Version: Next

debug_traceBlockByHash

Replays the block identified by the given hash and returns a trace for every transaction in the block. The parent block must be present in the client's database. The genesis block (block 0) cannot be traced because it has no parent state to replay from; clients MUST return an error for this input. When no tracer is specified (or the tracer field is absent), the opcode (struct) logger is used and each entry conforms to OpcodeBlockTransactionTrace, whose result field conforms to OpcodeTransactionTrace. When a named tracer is specified via the tracer field in TraceConfig (e.g. "callTracer", "prestateTracer"), the result field of each entry contains tracer-specific output. Defining the output schemas of named tracers is outside the scope of this specification. The response is an array ordered by transaction index within the block. Each entry includes the transaction hash paired with its trace result. If a timeout is configured and reached before tracing completes, the client MUST return an error; no partial results are returned. Clients that do not support execution timeouts MAY ignore the timeout field. Clients MUST return an error if no block with the given hash is found.

Replays a block and returns traces for all transactions.

Parameters (by position)

Block 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

Block trace object or object

Show Option 1 Opcode tracer entry object

`Opcode tracer entry` fields

Returned when no named tracer is specified.

Block trace array<object>

Returned when no named tracer is specified.

Show Block trace object

`Block trace` fields

result object required

The opcode trace for this transaction.
Show result object
result fields
The opcode trace for this transaction.

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
txHash string required

The hash of the transaction this trace entry corresponds to.

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

Show Option 2 Named tracer entry object

`Named tracer entry` fields

Returned when a named tracer is specified. The result field contains tracer-specific output not defined by this specification.

Block trace array<object>

Returned when a named tracer is specified. The result field contains tracer-specific output not defined by this specification.

Show Block trace object

`Block trace` fields

txHash string required

32 byte hex value

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

Errors

Error code: 4444

code

4444
message

Pruned history unavailable

Examples

debug_traceBlockByHash example (opcode tracer)

Request

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

Response

[
  {
    "result": {
      "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": []
        }
      ]
    },
    "txHash": "0xdd8cf045113754c306ba9ac8ac8786235e33bc5c087678084ef260a2a583f127"
  }
]

Request

Server URL:

debug_traceBlockByHash

Parameters (by position)

`TraceConfig` fields

`tracerConfig` fields

Result

`Opcode tracer entry` fields

`Block trace` fields

`result` fields

`structLogs` fields

`storage` fields

`Named tracer entry` fields

`Block trace` fields

Errors

Examples

Request

Response

Parameters (by position)​

TraceConfig fields​

tracerConfig fields​

Result​

Opcode tracer entry fields​

Block trace fields​

result fields​

structLogs fields​

storage fields​

Named tracer entry fields​

Block trace fields​

Errors​

Examples​

Request​

Response​

Parameters (by position)

`TraceConfig` fields

`tracerConfig` fields

Result

`Opcode tracer entry` fields

`Block trace` fields

`result` fields

`structLogs` fields

`storage` fields

`Named tracer entry` fields

`Block trace` fields

Errors

Examples

Request

Response