Skip to main content
Version: Next

debug_traceTransaction

Executes the transaction identified by the given hash in the exact manner it was executed on the network, replaying all prior transactions in the same block as necessary to reconstruct the correct pre-execution state. When no tracer is specified (or the tracer field is absent), the opcode (struct) logger is used and the result conforms to OpcodeTransactionTrace. When a named tracer is specified via the tracer field in TraceConfig (e.g. "callTracer", "prestateTracer"), the result contains tracer-specific output. Defining the output schemas of named tracers is outside the scope of this specification.

Replays a transaction and returns its trace.

Parameters (by position)​

Transaction hash string required

TraceConfig object

Configuration object accepted by debug_traceBlockByNumber and debug_traceTransaction. When the tracer field is absent or empty, the opcode (struct) logger is used and the result conforms to OpcodeTransactionTrace. The fields enableMemory, disableStack, disableStorage, enableReturnData, and limit only apply to the opcode logger and are ignored when a named tracer is set. When the tracer field is set to a named tracer (e.g. "callTracer", "prestateTracer"), the result format is tracer-specific. Defining the output schemas of named tracers is outside the scope of this specification.

Show TraceConfig object

TraceConfig fields​

  • debug boolean

    Opcode logger only. When true, the client may print the trace output to its internal log during execution. Has no effect on the JSON-RPC response. Ignored when tracer is set. Default: false.

  • disableStack boolean

    Opcode logger only. Setting to true disables stack capture in structLogs. When true, the stack field is omitted from each StructLog entry. Ignored when tracer is set. Default: false.

  • disableStorage boolean

    Opcode logger only. Setting to true disables storage capture in structLogs. When true, the storage field is omitted from each StructLog entry. Ignored when tracer is set. Default: false.

  • enableMemory boolean

    Opcode logger only. Setting to true enables memory capture in structLogs. When false (default), the memory field is omitted from each StructLog entry. Ignored when tracer is set. Default: false.

  • enableReturnData boolean

    Opcode logger only. Setting to true enables return data capture in structLogs. When false (default), the returnData field is omitted from each StructLog entry. Ignored when tracer is set. Default: false.

  • limit integer

    Opcode logger only. Maximum number of opcode steps to capture. Zero means no limit. When the limit is reached, execution continues but no further StructLog entries are recorded. Ignored when tracer is set. Default: 0 (unlimited).

    Range: >= 0

  • timeout string

    Optional duration string specifying a timeout for trace execution. Clients that do not support execution timeouts (e.g. streaming implementations) MAY ignore this field. When supported and the timeout is reached, the client MUST return an error; no partial results are returned. Accepts Go duration strings (e.g. "5s", "300ms", "2m").

  • tracer string

    The name of a built-in or custom tracer to use. When absent or empty, the opcode (struct) logger is used. Example built-in tracer names in go-ethereum include: 4byteTracer, callTracer, prestateTracer, noopTracer, bigramTracer, evmdisTracer, opcountTracer, trigramTracer, unigramTracer. Clients may support different sets of named tracers. Custom JavaScript tracers may also be supplied as an expression string.

  • tracerConfig object

    An optional tracer-specific configuration object passed to the named tracer. Only applicable when the tracer field is set. The fields accepted here depend on the named tracer in use.

    Show tracerConfig object

    tracerConfig fields​

    An optional tracer-specific configuration object passed to the named tracer. Only applicable when the tracer field is set. The fields accepted here depend on the named tracer in use.

  • additionalProperties true

Result​

Transaction trace object or unknown

Show Option 1 Opcode tracer result object

Opcode tracer result fields​

Returned when no named tracer is specified.

Transaction trace object

Returned when no named tracer is specified.

Show Transaction trace object

Transaction trace fields​

  • failed boolean required

    Whether the transaction execution failed (reverted or ran out of gas).

  • gas integer required

    Total amount of gas consumed by the transaction.

    Range: >= 0

  • returnValue string required

    The data returned by the transaction. 0x-prefixed hex-encoded bytes. MUST be "0x" (not an empty string) when no data was returned.

    Match pattern: ^0x[0-9a-f]*$

  • structLogs array<object> required

    The ordered sequence of opcode execution steps. Will be empty for simple ETH transfers between externally owned accounts that execute no EVM code.

    Show structLogs object

    structLogs fields​

    The ordered sequence of opcode execution steps. Will be empty for simple ETH transfers between externally owned accounts that execute no EVM code.

    • depth integer required

      The call stack depth at this execution step. Starts at 1 for the outermost call.

      Range: >= 1

    • error string

      The error encountered during execution of this opcode, if any. This field MUST be absent when no error occurred. Clients MUST NOT include this field as null or as an empty string when there is no error.

    • gas integer required

      The amount of gas remaining before executing this opcode.

      Range: >= 0

    • gasCost integer required

      The gas cost computed for this opcode step — the amount that will be deducted from the remaining gas assuming successful execution. Includes dynamic costs such as memory expansion and storage access charges (e.g. cold vs. warm SLOAD/SSTORE).

      Range: >= 0

    • memory array<string>

      The contents of EVM memory at this step, divided into 32-byte chunks. Each element is a 0x-prefixed, zero-padded 32-byte hex word representing a consecutive 32-byte memory slot starting at offset (index * 32). This field is absent (not null) when enableMemory is false.

      Match pattern: ^0x[0-9a-f]{64}$

    • op string required

      The name of the EVM opcode executed at this step (e.g. "PUSH1", "SSTORE").

    • pc integer required

      The program counter position of this opcode in the contract bytecode.

      Range: >= 0

    • refund integer

      The accumulated gas refund counter at this execution step. Clients MUST include this field at every step when it is non-zero. Clients SHOULD include this field at every step even when zero.

      Range: >= 0

    • returnData string

      The return data from the most recent call at this step. This field is absent when enableReturnData is false.

      Match pattern: ^0x[0-9a-f]*$

    • stack array<string>

      The contents of the EVM stack at this step, ordered from bottom (index 0) to top (last element). Each value is a 0x-prefixed uint256 quantity. This field is absent when disableStack is true.

      Match pattern: ^0x(0|[1-9a-f][0-9a-f]{0,63})$

    • storage object

      A cumulative snapshot of all storage slots accessed or modified by the current contract up to and including this step. Keys are 0x-prefixed, zero-padded 32-byte storage slot indices; values are the 32-byte stored values reflecting the post-execution state of the opcode at this step (i.e., for SSTORE, the value reflects the new value just written). This field is only populated at SLOAD and SSTORE opcodes. At all other opcodes, this field MUST be absent (not an empty object). This field is absent when disableStorage is true.

      Show storage object

      storage fields​

      A cumulative snapshot of all storage slots accessed or modified by the current contract up to and including this step. Keys are 0x-prefixed, zero-padded 32-byte storage slot indices; values are the 32-byte stored values reflecting the post-execution state of the opcode at this step (i.e., for SSTORE, the value reflects the new value just written). This field is only populated at SLOAD and SSTORE opcodes. At all other opcodes, this field MUST be absent (not an empty object). This field is absent when disableStorage is true.

    • additionalProperties true

  • additionalProperties true

Show Option 2 Named tracer result

Named tracer result fields​

Returned when a named tracer is specified via the tracer field. The format is tracer-specific and not defined by this specification. Named tracers may return any JSON value (object, array, integer, etc.).

Errors​

Error code: 4444

  • code

    4444

  • message

    Pruned history unavailable

Examples​

debug_traceTransaction example (opcode tracer)

Request​

{
  "params": [
    "0xdd8cf045113754c306ba9ac8ac8786235e33bc5c087678084ef260a2a583f127",
    {
      "disableStack": false,
      "disableStorage": false,
      "enableMemory": false,
      "enableReturnData": false
    }
  ]
}

Response​

{
  "failed": false,
  "gas": 26916,
  "returnValue": "0x",
  "structLogs": [
    {
      "depth": 1,
      "gas": 68612,
      "gasCost": 3,
      "op": "PUSH1",
      "pc": 0,
      "stack": [
        "0x60"
      ]
    },
    {
      "depth": 1,
      "gas": 68609,
      "gasCost": 3,
      "op": "PUSH1",
      "pc": 2,
      "stack": [
        "0x60",
        "0x40"
      ]
    },
    {
      "depth": 1,
      "gas": 68606,
      "gasCost": 12,
      "op": "MSTORE",
      "pc": 4,
      "stack": []
    }
  ]
}

debug_traceTransaction example (callTracer)

Request​

{
  "params": [
    "0xdd8cf045113754c306ba9ac8ac8786235e33bc5c087678084ef260a2a583f127",
    {
      "tracer": "callTracer",
      "tracerConfig": {
        "onlyTopCall": false,
        "withLog": true
      }
    }
  ]
}

Response​

{
  "from": "0xfe3b557e8fb62b89f4916b721be55ceb828dbd73",
  "gas": "0x1a49e",
  "gasUsed": "0x1a49e",
  "input": "0x",
  "output": "0x",
  "to": "0x0100000000000000000000000000000000000000",
  "type": "CALL",
  "value": "0x0"
}
Request