> ## Documentation Index
> Fetch the complete documentation index at: https://seilabs-docs-remove-retired-sei-rpcs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Debug Tracing Overview

> Comprehensive guide to debugging and tracing EVM transactions on Sei. Learn to analyze transaction execution, optimize gas usage, and troubleshoot smart contracts with real examples and end-to-end workflows.

## 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`](https://jqlang.github.io/jq/) to pretty-print the JSON responses:

```bash theme={"dark"}
# 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:

<Tabs>
  <Tab title="Transaction Details">
    ```bash theme={"dark"}
    # 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:**

    ```json theme={"dark"}
    {
      "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"
      }
    }
    ```
  </Tab>

  <Tab title="Basic Trace">
    ```bash theme={"dark"}
    # 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:**

    ```json theme={"dark"}
    {
      "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"
              },
              ...
            ]
          }
        ]
      }
    }
    ```
  </Tab>

  <Tab title="Gas Analysis">
    ```bash theme={"dark"}
    # 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:**

    ```json theme={"dark"}
    {
      "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
      }
    }
    ```
  </Tab>
</Tabs>

## Debugging Failed Transactions

Steps to analyze and resolve transaction failures:

### Step 1: Identify the Problem

```bash theme={"dark"}
# 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

```bash theme={"dark"}
# 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

```json theme={"dark"}
{
  "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

```bash theme={"dark"}
# 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

```bash theme={"dark"}
# 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.                                                                                             |

<Warning>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.</Warning>

## Removed legacy trace filters

<Note>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.</Note>

## Next Steps

1. **[JavaScript Tracers](/evm/tracing/javascript-tracers)** - Custom analysis scripts
2. **[Troubleshooting](/evm/tracing/troubleshooting)** - Common issues and solutions

<Info>Start with `callTracer` for general debugging, then use specialized tracers for specific analysis needs.</Info>