Debug Tracing Overview

Requirements

The examples in this guide call the debug JSON-RPC endpoints directly with curl — no SDK or additional libraries are required. Optionally install jq to pretty-print the JSON responses:

# macOS
brew install jq

# Debian/Ubuntu
sudo apt-get install jq

Debug tracing is your primary tool for understanding EVM transaction execution on Sei. This comprehensive system allows you to analyze transaction flow, optimize gas usage, debug smart contract interactions, and troubleshoot production issues.

What You Can Trace

Transaction Execution

Step-by-step opcode execution
Contract call hierarchy
Gas consumption breakdown
State changes and storage access

Contract Interactions

Cross-contract calls and returns
Event emission analysis
Precompile usage tracking
External library calls

Performance Analysis

Gas optimization opportunities
Bottleneck identification
Cache hit/miss patterns
State access efficiency

Security Analysis

Suspicious operation detection
Reentrancy pattern analysis
Access control verification
Vulnerability scanning

Available Tracing Methods

Method	Purpose	Use Case
`debug_traceTransaction`	Trace specific transaction	Debugging failed transactions
`debug_traceBlockByNumber`	Trace entire block	Block-level analysis
`debug_traceCall`	Simulate and trace	Testing before execution
`debug_traceStateAccess`	State access patterns	Performance optimization
`debug_traceTransactionProfile`	Trace plus timing/store-access profiling	Latency breakdown and DB-access analysis

Transaction Analysis Example

Tracing an ERC-20 transfer transaction:

Transaction Details
Basic Trace
Gas Analysis

# Real transaction on Sei mainnet
TRANSACTION_HASH="0x75b7ba10248e90db85b224eae587db1728520b6f72c795b9185064f444cee7c3"

# Transaction details

curl -X POST -H "Content-Type: application/json" \
 --data '{
"jsonrpc": "2.0",
"method": "eth_getTransactionByHash",
"params": ["'$TRANSACTION_HASH'"],
"id": 1
}' \
 https://evm-rpc.sei-apis.com

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "blockHash": "0xbc229fe41605ba2b46fcd7aa7ce328dc2f6da78385dfea84ca8dbef7b4325462",
    "blockNumber": "0x97aefcf",
    "from": "0x4cbee7ad42d33e9d3b41e8b6faca2f6f173c8a94",
    "gas": "0x66f24",
    "gasPrice": "0x565dd756",
    "maxFeePerGas": "0x565dd756",
    "maxPriorityFeePerGas": "0x5e679d6",
    "hash": "0x75b7ba10248e90db85b224eae587db1728520b6f72c795b9185064f444cee7c3",
    "input": "0x733214a3e5f551789f7ee58322679a2b141e64533098b8ba41d9e10cf8061a18a777d6ce00000000000000000000000000000000000000000000000000000000000000c000000000000000000000000000000000000000000000000000000000000001000000000000000000000000004cbee7ad42d33e9d3b41e8b6faca2f6f173c8a940000000000000000000000000000000000000000000000000dd26083bfc745570000000000000000000000000000000000000000000000000000000000000160000000000000000000000000000000000000000000000000000000000000000f6a756d7065722e65786368616e67650000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000002a30783030303030303030303030303030303030303030303030303030303030303030303030303030303000000000000000000000000000000000000000000000000000000000000000000000fde9ce4e17b650efdca13d524f132876700d806f000000000000000000000000fde9ce4e17b650efdca13d524f132876700d806f0000000000000000000000003894085ef7ff0f0aedf52e2a2704928d1ec074f10000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000004faaa00000000000000000000000000000000000000000000000000000000000000e0000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000001642646478b0000000000000000000000003894085ef7ff0f0aedf52e2a2704928d1ec074f1000000000000000000000000000000000000000000000000000000000004faaa000000000000000000000000eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee0000000000000000000000000000000000000000000000000dd26083bfc745570000000000000000000000001231deb6f5749ef6ce6943a275a1d3e7486f4eae00000000000000000000000000000000000000000000000000000000000000c00000000000000000000000000000000000000000000000000000000000000070023894085ef7ff0f0aedf52e2a2704928d1ec074f101ffff015cfa8db453c9904511c4ea9eb0bfc903e36b9f5f01fde9ce4e17b650efdca13d524f132876700d806f01e30fedd158a2e3b13e9badaeabafc5516e95e8c701ffff02001231deb6f5749ef6ce6943a275a1d3e7486f4eae0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
    "nonce": "0x4",
    "to": "0x1231deb6f5749ef6ce6943a275a1d3e7486f4eae",
    "transactionIndex": "0x14",
    "value": "0x0",
    "type": "0x2",
    "accessList": [],
    "chainId": "0x531",
    "v": "0x0",
    "r": "0x3a107aca9cd554a9171a65ea2e8ef56ebeca8cfdc17f4bbecfb0f86837ca90d6",
    "s": "0x426134cf65b701bc8d43162f78bcf787319ff17cc6293188bcbb30fd99feb60",
    "yParity": "0x0"
  }
}

# Trace the transaction execution
curl -X POST -H "Content-Type: application/json" \
  --data '{
    "jsonrpc": "2.0",
    "method": "debug_traceTransaction",
    "params": [
      "'$TRANSACTION_HASH'",
      {
        "tracer": "callTracer",
        "tracerConfig": {
          "withLog": true
        }
      }
    ],
    "id": 1
  }' \
  https://evm-rpc.sei-apis.com

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "from": "0x4cbee7ad42d33e9d3b41e8b6faca2f6f173c8a94",
    "gas": "0x66f24",
    "gasUsed": "0x40f98",
    "to": "0x1231deb6f5749ef6ce6943a275a1d3e7486f4eae",
    "input": "0x733214a3e5f551789f7ee58322679a2b141e64533098b8ba41d9e10cf8061a18a777d6ce00000000000000000000000000000000000000000000000000000000000000c000000000000000000000000000000000000000000000000000000000000001000000000000000000000000004cbee7ad42d33e9d3b41e8b6faca2f6f173c8a940000000000000000000000000000000000000000000000000dd26083bfc745570000000000000000000000000000000000000000000000000000000000000160000000000000000000000000000000000000000000000000000000000000000f6a756d7065722e65786368616e67650000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000002a30783030303030303030303030303030303030303030303030303030303030303030303030303030303000000000000000000000000000000000000000000000000000000000000000000000fde9ce4e17b650efdca13d524f132876700d806f000000000000000000000000fde9ce4e17b650efdca13d524f132876700d806f0000000000000000000000003894085ef7ff0f0aedf52e2a2704928d1ec074f10000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000004faaa00000000000000000000000000000000000000000000000000000000000000e0000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000001642646478b0000000000000000000000003894085ef7ff0f0aedf52e2a2704928d1ec074f1000000000000000000000000000000000000000000000000000000000004faaa000000000000000000000000eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee0000000000000000000000000000000000000000000000000dd26083bfc745570000000000000000000000001231deb6f5749ef6ce6943a275a1d3e7486f4eae00000000000000000000000000000000000000000000000000000000000000c00000000000000000000000000000000000000000000000000000000000000070023894085ef7ff0f0aedf52e2a2704928d1ec074f101ffff015cfa8db453c9904511c4ea9eb0bfc903e36b9f5f01fde9ce4e17b650efdca13d524f132876700d806f01e30fedd158a2e3b13e9badaeabafc5516e95e8c701ffff02001231deb6f5749ef6ce6943a275a1d3e7486f4eae0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
    "calls": [
      {
        "from": "0x1231deb6f5749ef6ce6943a275a1d3e7486f4eae",
        "gas": "0x5d03f",
        "gasUsed": "0x3b0cc",
        "to": "0x31a9b1835864706af10103b31ea2b79bdb995f5f",
        "input": "0x733214a3e5f551789f7ee58322679a2b141e64533098b8ba41d9e10cf8061a18a777d6ce00000000000000000000000000000000000000000000000000000000000000c000000000000000000000000000000000000000000000000000000000000001000000000000000000000000004cbee7ad42d33e9d3b41e8b6faca2f6f173c8a940000000000000000000000000000000000000000000000000dd26083bfc745570000000000000000000000000000000000000000000000000000000000000160000000000000000000000000000000000000000000000000000000000000000f6a756d7065722e65786368616e67650000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000002a30783030303030303030303030303030303030303030303030303030303030303030303030303030303000000000000000000000000000000000000000000000000000000000000000000000fde9ce4e17b650efdca13d524f132876700d806f000000000000000000000000fde9ce4e17b650efdca13d524f132876700d806f0000000000000000000000003894085ef7ff0f0aedf52e2a2704928d1ec074f10000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000004faaa00000000000000000000000000000000000000000000000000000000000000e0000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000001642646478b0000000000000000000000003894085ef7ff0f0aedf52e2a2704928d1ec074f1000000000000000000000000000000000000000000000000000000000004faaa000000000000000000000000eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee0000000000000000000000000000000000000000000000000dd26083bfc745570000000000000000000000001231deb6f5749ef6ce6943a275a1d3e7486f4eae00000000000000000000000000000000000000000000000000000000000000c00000000000000000000000000000000000000000000000000000000000000070023894085ef7ff0f0aedf52e2a2704928d1ec074f101ffff015cfa8db453c9904511c4ea9eb0bfc903e36b9f5f01fde9ce4e17b650efdca13d524f132876700d806f01e30fedd158a2e3b13e9badaeabafc5516e95e8c701ffff02001231deb6f5749ef6ce6943a275a1d3e7486f4eae0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
        "calls": [
          {
            "from": "0x1231deb6f5749ef6ce6943a275a1d3e7486f4eae",
            "gas": "0x5aa48",
            "gasUsed": "0xa724",
            "to": "0x3894085ef7ff0f0aedf52e2a2704928d1ec074f1",
            "input": "0x23b872dd0000000000000000000000004cbee7ad42d33e9d3b41e8b6faca2f6f173c8a940000000000000000000000001231deb6f5749ef6ce6943a275a1d3e7486f4eae000000000000000000000000000000000000000000000000000000000004faaa",
            "output": "0x0000000000000000000000000000000000000000000000000000000000000001",
            "calls": [
              {
                "from": "0x3894085ef7ff0f0aedf52e2a2704928d1ec074f1",
                "gas": "0x54283",
                "gasUsed": "0x4ad6",
                "to": "0x0000000000000000000000000000000000001001",
                "input": "0x5c05961b0000000000000000000000004cbee7ad42d33e9d3b41e8b6faca2f6f173c8a940000000000000000000000001231deb6f5749ef6ce6943a275a1d3e7486f4eae0000000000000000000000000000000000000000000000000000000000000080000000000000000000000000000000000000000000000000000000000004faaa00000000000000000000000000000000000000000000000000000000000000446962632f4341364642464146333939343734413036323633453130443043453541454242453135313839443644344232444439414445363130303745363845423944423000000000000000000000000000000000000000000000000000000000",
                "output": "0x0000000000000000000000000000000000000000000000000000000000000001",
                "value": "0x0",
                "type": "CALL"
              }
            ],
            "logs": [
              {
                "address": "0x3894085ef7ff0f0aedf52e2a2704928d1ec074f1",
                "topics": [
                  "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
                  "0x0000000000000000000000004cbee7ad42d33e9d3b41e8b6faca2f6f173c8a94",
                  "0x0000000000000000000000001231deb6f5749ef6ce6943a275a1d3e7486f4eae"
                ],
                "data": "0x000000000000000000000000000000000000000000000000000000000004faaa",
                "position": "0x1"
              }
            ],
            "value": "0x0",
            "type": "CALL"
          },
          ...
        ]
      }
    ]
  }
}

# Analyze gas usage patterns
curl -X POST -H "Content-Type: application/json" \
  --data '{
    "jsonrpc": "2.0",
    "method": "debug_traceTransaction",
    "params": [
      "0x75b7ba10248e90db85b224eae587db1728520b6f72c795b9185064f444cee7c3",
      {
        "tracer": "{gasUsed: 0, operations: {}, step: function(log, db) { var op = log.op.toString(); var cost = log.getCost(); this.gasUsed += cost; if (!this.operations[op]) { this.operations[op] = { count: 0, totalGas: 0 }; } this.operations[op].count++; this.operations[op].totalGas += cost; }, fault: function(log, db) {}, result: function(ctx, db) { return { totalGas: this.gasUsed, operations: this.operations, efficiency: this.gasUsed / ctx.gasUsed }; }}"
      }
    ],
    "id": 1
  }' \
  https://evm-rpc.sei-apis.com

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "totalGas": 6346011,
    "operations": {
      "PUSH1": {
        "count": 1476,
        "totalGas": 4428
      },
      "MSTORE": {
        "count": 342,
        "totalGas": 1690
      },
      "CALLDATASIZE": {
        "count": 41,
        "totalGas": 82
      },
      "PUSH2": {
        "count": 1400,
        "totalGas": 4200
      },

      ...


      "STOP": {
        "count": 5,
        "totalGas": 0
      },
      "LOG2": {
        "count": 2,
        "totalGas": 5578
      },
      "LOG4": {
        "count": 1,
        "totalGas": 2899
      },
      "LOG1": {
        "count": 1,
        "totalGas": 2542
      }
    },
    "efficiency": 23.84499278564343
  }
}

Debugging Failed Transactions

Steps to analyze and resolve transaction failures:

Step 1: Identify the Problem

# Get transaction receipt
FAILED_TX="0xb2a6f4f7f37d8df728968126c05d1a8b0391003cf375ed5abb1b5e02fe66c717"

curl -X POST -H "Content-Type: application/json" \
  --data '{
    "jsonrpc": "2.0",
    "method": "eth_getTransactionReceipt",
    "params": ["'$FAILED_TX'"],
    "id": 1
  }' \
  https://evm-rpc.sei-apis.com

Step 2: Trace the Execution

# Trace to see where it failed
curl -X POST -H "Content-Type: application/json" \
  --data '{
    "jsonrpc": "2.0",
    "method": "debug_traceTransaction",
    "params": [
      "'$FAILED_TX'",
      {
        "tracer": "callTracer",
        "tracerConfig": {
          "withLog": true
        }
      }
    ],
    "id": 1
  }' \
  https://evm-rpc.sei-apis.com

Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "from": "0x2c80b1b0473bb765ef536d2526ec63195794d945",
    "gas": "0xc3500",
    "gasUsed": "0x2863d",
    "to": "0xd1efe48b71acd98db16fcb9e7152b086647ef544",
    "input": "0x414bf3890000000000000000000000003894085ef7ff0f0aedf52e2a2704928d1ec074f1000000000000000000000000e30fedd158a2e3b13e9badaeabafc5516e95e8c70000000000000000000000000000000000000000000000000000000000000bb80000000000000000000000002c80b1b0473bb765ef536d2526ec63195794d94500000000000000000000000000000000000000000000000000000000688a24580000000000000000000000000000000000000000000000000000000031aba85500000000000000000000000000000000000000000000009556d1a971e567965b0000000000000000000000000000000000000000000000000000000000000000",
    "output": "0x08c379a000000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000013546f6f206c6974746c6520726563656976656400000000000000000000000000",
    "error": "execution reverted",
    "revertReason": "Too little received",
    "calls": [
      ...
    ]
  }
}

Step 3: Fix and Test

# Simulate the fix with debug_traceCall
curl -X POST \
  -H "Content-Type: application/json" \
  --data '{
    "jsonrpc": "2.0",
    "method": "debug_traceCall",
    "params": [
      {
        "from": "0x2c80b1b0473bb765ef536d2526ec63195794d945",
        "to": "0xd1efe48b71acd98db16fcb9e7152b086647ef544",
        "gas": "0xc3500",
        "gasPrice": "0x2127ddd32",
        "value": "0x0"
      },
      "0x98a87cc",
      {
        "tracer": "callTracer",
        "tracerConfig": {
          "onlyTopCall": false,
          "withLog": true
        }
      }
    ],
    "id": 1
  }' \
  https://evm-rpc.sei-apis.com

Common Debugging Scenarios

Transaction Reverted

Problem: Transaction failed with revert Solution: Use callTracer to find the exact revert reason

Out of Gas

Problem: Transaction ran out of gas Solution: Use gas analysis tracer to optimize gas usage

Unexpected Behavior

Problem: Transaction succeeded but wrong result Solution: Use opcode tracer for step-by-step analysis

Slow Performance

Problem: Transaction uses too much gas Solution: Use state access tracer to find inefficiencies

Quick Reference

Essential Commands

# Trace transaction
debug_traceTransaction(hash, {tracer: "callTracer"})

# Trace block
debug_traceBlockByNumber("latest", {tracer: "callTracer"})

# Simulate call
debug_traceCall(tx, "latest", {tracer: "callTracer"})

# State access
debug_traceStateAccess(hash)

Common Tracers

callTracer: Contract call hierarchy
opcodeTracer: Opcode-level execution
Custom JS: Custom analysis logic

Pre-Baked Trace Cache

RPC nodes can optionally pre-compute and cache debug_trace* results in the background so that trace requests are served from a local on-disk cache instead of re-executing the block live on every call. This is an opt-in feature configured through new [evm] fields in app.toml and is recommended for RPC nodes only. When enabled, a background worker re-executes each committed block with the configured tracers and stores the results in a Pebble database at <home>/data/trace_db. The following methods serve from this cache on hit, and otherwise fall through to live re-execution:

debug_traceTransaction
debug_traceBlockByNumber and debug_traceBlockByHash

When the cache is used

A request is only served from cache when trace baking is enabled and the request uses a bakeable tracer configuration:

The tracer is one of callTracer, prestateTracer, or flatCallTracer.
No custom tracerConfig is supplied. A per-call tracerConfig (for example {"withLog": true}) is not part of the cache key, so any custom tracer config makes the request un-bakeable and it falls through to live re-execution.

Requests that use the struct logger (no tracer), a JavaScript tracer, or any other named tracer are always executed live.

Configuration

Trace baking is controlled by these [evm] fields in app.toml:

Field	Default	Description
`trace_bake_enabled`	`false`	Enables the background trace-baking worker that caches results at `<home>/data/trace_db`. RPC nodes only.
`trace_bake_workers`	`1`	Number of re-execution worker goroutines.
`trace_bake_queue_size`	`4096`	Bounds the in-flight height queue. Heights are dropped when the queue is full so consensus never blocks; dropped blocks fall through to live re-execution.
`trace_bake_tracers`	`["callTracer"]`	Which tracers to bake per block. Eligible values: `callTracer`, `prestateTracer`, `flatCallTracer`.
`trace_bake_window_blocks`	`0`	Rolling prune window: blocks older than `(latest - window)` are pruned. `0` disables pruning, so the cache grows forever.
`trace_bake_use_snapshot`	`false`	Uses in-memory memiavl snapshots as the state backend for trace baking when the store backend supports snapshots.
`trace_bake_snapshot_window`	`64`	Number of recent memiavl snapshots to retain for trace baking.

Enabling trace baking adds a persistent on-disk store at <home>/data/trace_db and increases disk usage. The store’s write-ahead log is flushed when the node shuts down cleanly.

Removed legacy trace filters

The legacy *ExcludeTraceFail endpoints have been removed. Use debug_traceBlockByNumber or debug_traceBlockByHash for block tracing and eth_getTransactionReceipt for EVM receipts. There is no block or filter method for discovering synthetic logs from Cosmos-originated transactions. If you already know a synthetic transaction hash, enable sei_getTransactionReceipt to retrieve its receipt and logs.

Next Steps

JavaScript Tracers - Custom analysis scripts
Troubleshooting - Common issues and solutions

Start with callTracer for general debugging, then use specialized tracers for specific analysis needs.

Overview

Essentials

seid CLI

Frontend Development

Smart Contracts

sei-js Library

Videos

Ecosystem Tutorials

Reference

Hardware Wallets

Debug Tracing Overview

Requirements

What You Can Trace

Transaction Execution

Contract Interactions

Performance Analysis

Security Analysis

Available Tracing Methods

Transaction Analysis Example

Debugging Failed Transactions

Step 1: Identify the Problem

Step 2: Trace the Execution

Step 3: Fix and Test

Common Debugging Scenarios

Transaction Reverted

Out of Gas

Unexpected Behavior

Slow Performance

Quick Reference

Essential Commands

Common Tracers

Pre-Baked Trace Cache

When the cache is used

Configuration

Removed legacy trace filters

Next Steps

​Requirements

​What You Can Trace

​Transaction Execution

​Contract Interactions

​Performance Analysis

​Security Analysis

​Available Tracing Methods

​Transaction Analysis Example

​Debugging Failed Transactions

​Step 1: Identify the Problem

​Step 2: Trace the Execution

​Step 3: Fix and Test

​Common Debugging Scenarios

​Transaction Reverted

​Out of Gas

​Unexpected Behavior

​Slow Performance

​Quick Reference

​Essential Commands

​Common Tracers

​Pre-Baked Trace Cache

​When the cache is used

​Configuration

​Removed legacy trace filters

​Next Steps

Requirements

What You Can Trace

Transaction Execution

Contract Interactions

Performance Analysis

Security Analysis

Available Tracing Methods

Transaction Analysis Example

Debugging Failed Transactions

Step 1: Identify the Problem

Step 2: Trace the Execution

Step 3: Fix and Test

Common Debugging Scenarios

Transaction Reverted

Out of Gas

Unexpected Behavior

Slow Performance

Quick Reference

Essential Commands

Common Tracers

Pre-Baked Trace Cache

When the cache is used

Configuration

Removed legacy trace filters

Next Steps