debug_traceTransaction: Full Execution Traces

What debug_traceTransaction does

The node replays the block containing your transaction from the start, up to and through your transaction, with tracing hooks enabled. Because it re-executes real historical state, the results are exact rather than estimated: actual gas per call frame, actual reverts, the actual call tree.

The shape of the response is decided by the tracer option. With no tracer you get the raw opcode-level struct logger, one entry per EVM step with stack, memory and gas, which for a complex DeFi transaction runs to hundreds of megabytes. In practice you always pass a named tracer: callTracer for the call tree, prestateTracer for the state the transaction read (or, with diffMode, how it changed state), 4byteTracer for selector statistics.

Geth defines this interface, and Nethermind, Erigon and Reth implement it with the same named tracers. Parity-style clients additionally expose the alternative trace_transaction and trace_replayTransaction family. Either way the debug namespace must be enabled on the node, which is exactly what shared public endpoints do not do.

Parameters

What it returns

Depends on the tracer. callTracer returns one nested frame per call: type (CALL, DELEGATECALL, STATICCALL, CREATE, SELFDESTRUCT), from, to, value, gas, gasUsed, input, output, and a calls array of child frames; failed frames add error and, when decodable, revertReason.

prestateTracer returns per-address balance, nonce, code and the storage slots the transaction touched. The default struct logger returns gas, failed, returnValue and the structLogs opcode array.

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "type": "CALL",
    "from": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
    "to": "0x7a250d5630b4cf539739df2c5dacb4c659f2488d",
    "value": "0x2386f26fc10000",
    "gas": "0x2e253",
    "gasUsed": "0x1f4e2",
    "input": "0x7ff36ab5...",
    "output": "0x...",
    "calls": [
      {
        "type": "CALL",
        "from": "0x7a250d5630b4cf539739df2c5dacb4c659f2488d",
        "to": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
        "gasUsed": "0x5da6",
        "input": "0xd0e30db0",
        "calls": []
      }
    ]
  }
}

A trimmed callTracer result for a router swap: the top frame is the user's call, child frames are the internal calls it made. Hash and values are illustrative.

import { WebSocketProvider } from "ethers";

// Inside a BLAZED.sh container the node is one local socket away
const provider = new WebSocketProvider("ws://blazed_infra_eth-execution:8545");

// ethers has no wrapper for debug_*; use provider.send
const trace = await provider.send("debug_traceTransaction", [
  "0x16897e492b2e023d8f07be9e925f2c15a91000ef11a01fc71e70f75050f1e03c",
  { tracer: "callTracer", tracerConfig: { withLog: true } },
]);
console.log(trace.calls.length, "internal calls");

Gotchas and common errors

What debug_traceTransaction costs on BLAZED.sh

debug_traceTransaction costs 1 credit per call on BLAZED.sh; the heavy Parity-style replay methods trace_replayTransaction and trace_replayBlockTransactions are the ones billed at 4 credits. What you actually watch with tracing is the response-size surcharge: responses over 100KB add 50 credits per MB, and tracing is the method family that can genuinely hit it. A callTracer result for a typical swap stays in the kilobytes; a full struct-log trace can be thousands of times larger and cost accordingly, one more reason to always pass a named tracer.

debug_traceTransaction: frequently asked questions