For AI agents: a documentation index is available at /llms.txt. Markdown versions of pages are available by appending .md to any documentation URL.
Skip to main content

TRACE methods

The TRACE API is a more concise alternative to the DEBUG API.

note

The TRACE API is not enabled by default for JSON-RPC. Enable it using the --rpc-http-api or --rpc-ws-api option.

trace_block​

Provides transaction processing of type trace for the specified block.

note

Your node must be an archive node, or the requested block must be within the number of blocks retained when using Bonsai (by default, 512 from the head of the chain).

Parameters

  • blockNumber: string - Hexadecimal integer representing a block number, or one of the string tags latest, earliest, pending, finalized, or safe, as described in block parameter.

    note

    pending returns the same value as latest.

Returns

  • List of trace objects for the block. Includes transaction traces (call, create, suicide) in execution order, then block and uncle reward traces. If revert reason is enabled with --revert-reason-enabled, the returned list items include the revert reason.

Example

curl -X POST http://127.0.0.1:8545/ \
  -H "Content-Type: application/json" \
  --data '{
    "jsonrpc": "2.0",
    "method": "trace_block",
    "params": [
      "0x6"
    ],
    "id": 1
  }'

trace_call​

Executes the given call and returns a number of possible traces for it.

note

When using Bonsai, the requested block must be within the number of blocks retained (by default, 512 from the head of the chain).

Parameters

  • call: object - Transaction call object.

    • from: data, 20 bytes - Address of the sender.

    • to: data, 20 bytes - Address of the action receiver.

    • gas: quantity, integer - Gas provided by the sender. eth_call consumes zero gas, but other executions might need this parameter. eth_estimateGas ignores this value.

    • gasPrice: quantity, integer - Gas price, in Wei, provided by the sender. The default is 0. Used only in non-EIP1559 transactions.

    • maxPriorityFeePerGas: quantity, integer - Maximum fee, in Wei, the sender is willing to pay per gas above the base fee. Can be used only in EIP1559 transactions. If used, must specify maxFeePerGas.

    • maxFeePerGas: quantity, integer - Maximum total fee (base fee + priority fee), in Wei, the sender is willing to pay per gas. Can be used only in EIP1559 transactions. If used, must specify maxPriorityFeePerGas.

    • maxFeePerBlobGas: quantity, integer - Maximum fee the sender is willing to pay per blob gas. Only used for blob transactions introduced in EIP-4844.

    • nonce: quantity, integer - Number of transactions made by the sender before this one. The default is the sender's nonce.

    • value: quantity, integer - Value transferred, in Wei.

    • data: data - Hash of the method signature and encoded parameters. For details, see Ethereum Contract ABI. Must be equal to input if both parameters are provided.

    • input: data - Hash of the method signature and encoded parameters. For details, see Ethereum Contract ABI. Must be equal to data if both parameters are provided.

    • accessList: array - List of addresses and storage keys that the transaction plans to access. Used only in non-FRONTIER transactions.

    • strict: boolean - Determines if the sender account balance is considered during gas estimation. If true, the sender's balance is checked against the transaction's gas parameters. This ensures the estimated gas reflects what the sender can actually afford. If false, the balance checks are skipped. The default is true.

    • blobVersionedHashes: array - List of references to blobs introduced in EIP-4844.

  • blockNumber: string - Hexadecimal integer representing a block number, or one of the string tags latest, earliest, pending, finalized, or safe, as described in block parameter.

    note

    pending returns the same value as latest.

  • options: array of strings - List of tracing options; tracing options are trace, vmTrace, and stateDiff. Specify any combination of the three options including none of them.

Returns

  • Object containing the trace results for the call, depending on the requested options.

    • output: data - Return value of the call.

    • stateDiff: object - State changes in the requested block, or null if stateDiff wasn't a requested option.

    • trace: array - Ordered list of trace objects, or an empty array if trace wasn't a requested option.

    • vmTrace: object - VM execution trace (code plus an ordered ops list), or null if vmTrace wasn't a requested option.

Example

curl -X POST http://127.0.0.1:8545/ \
  -H "Content-Type: application/json" \
  --data '{
    "jsonrpc": "2.0",
    "method": "trace_call",
    "params": [
      {
        "from": "0xfe3b557e8fb62b89f4916b721be55ceb828dbd73",
        "to": "0x0010000000000000000000000000000000000000",
        "gas": "0xfffff2",
        "gasPrice": "0xef",
        "value": "0x0",
        "data": "0x0000000000000000000000000000000000000000000000000000000000000001000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000002",
        "nonce": "0x0"
      },
      [
        "trace"
      ],
      "latest"
    ],
    "id": 1
  }'

trace_callMany​

Performs multiple call traces on top of the same block. You can trace dependent transactions.

note

When using Bonsai, the requested block must be within the number of blocks retained (by default, 512 from the head of the chain).

Parameters

  • options: array of strings - List of tracing options; tracing options are trace, vmTrace, and stateDiff. Specify any combination of the three options including none of them.

  • blockNumber: string - Hexadecimal integer representing a block number, or one of the string tags latest, earliest, pending, finalized, or safe, as described in block parameter.

    note

    pending returns the same value as latest.

Returns

  • List of objects containing the trace results for each call, in the order the calls were specified, one object per call, depending on the requested options.

    • output: data - Return value of the call.

    • stateDiff: object - State changes in the requested block, or null if stateDiff wasn't a requested option.

    • trace: array - Ordered list of trace objects, or an empty array if trace wasn't a requested option.

    • vmTrace: object - VM execution trace (code plus an ordered ops list), or null if vmTrace wasn't a requested option.

Example

curl -X POST http://127.0.0.1:8545/ \
  -H "Content-Type: application/json" \
  --data '{
    "jsonrpc": "2.0",
    "method": "trace_callMany",
    "params": [
      [
        [
          {
            "from": "0x407d73d8a49eeb85d32cf465507dd71d507100c1",
            "to": "0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b",
            "value": "0x186a0"
          },
          [
            "trace"
          ]
        ],
        [
          {
            "from": "0x407d73d8a49eeb85d32cf465507dd71d507100c1",
            "to": "0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b",
            "value": "0x186a0"
          },
          [
            "trace"
          ]
        ]
      ],
      "latest"
    ],
    "id": 1
  }'

trace_filter​

Returns traces matching the specified filter. The maximum number of blocks you can supply to trace_filter is 1000 by default. You can adjust this limit using the --rpc-max-trace-filter-range option.

note

Your node must be an archive node, or the requested blocks must be within the number of blocks retained when using Bonsai (by default, 512 from the head of the chain).

Parameters

  • traceFilterOptions: object - Trace filter options object.

  • fromBLock: String | Tag - Trace starts at this block.

  • toBlock: String | Tag - Trace stops at this block.

  • fromAddress: string - Include only traces sent from this address.

  • toAddress: string - Include only traces with this destination address.

  • after: quantity - The offset trace number.

  • count: integer - Number of traces to display in a batch.

Returns

Example

curl -X POST http://127.0.0.1:8545/ \
  -H "Content-Type: application/json" \
  --data '{
    "jsonrpc": "2.0",
    "method": "trace_filter",
    "params": [
      {
        "fromBlock": "0x1",
        "toBlock": "0x21",
        "after": 2,
        "count": 2,
        "fromAddress": [
          "0xfe3b557e8fb62b89f4916b721be55ceb828dbd73"
        ]
      }
    ],
    "id": 415
  }'

trace_get​

Returns a trace at the given position.

note

Your node must be an archive node, or the requested transaction must be contained in a block within the number of blocks retained when using Bonsai (by default, 512 from the head of the chain).

Parameters

  • transaction: string - Transaction hash.

  • indexPositions: array - Index positions of the traces.

Returns

  • List of trace objects at the requested positions, in the order specified.

Example

curl -X POST http://127.0.0.1:8545/ \
  -H "Content-Type: application/json" \
  --data '{
    "jsonrpc": "2.0",
    "method": "trace_get",
    "params": [
      "0x17104ac9d3312d8c136b7f44d4b8b47852618065ebfa534bd2d3b5ef218ca1f3",
      [
        "0x0"
      ]
    ],
    "id": 1
  }'

trace_rawTransaction​

Traces a call to eth_sendRawTransaction without making the call, returning the traces.

note

When using Bonsai, the requested transaction must be contained in a block within the number of blocks retained (by default, 512 from the head of the chain).

Parameters

  • data - string - Raw transaction data.

  • options: array of strings - List of tracing options; tracing options are trace, vmTrace, and stateDiff. Specify any combination of the three options including none of them.

Returns

  • Object containing the trace results for the transaction, depending on the requested options.

    • output: data - Return value of the transaction.

    • from: data, 20 bytes - Address of the transaction sender.

    • stateDiff: object - State changes in the requested block, or null if stateDiff wasn't a requested option.

    • trace: array - Ordered list of trace objects, or an empty array if trace wasn't a requested option.

    • vmTrace: object - VM execution trace (code plus an ordered ops list), or null if vmTrace wasn't a requested option.

Example

curl -X POST http://127.0.0.1:8545/ \
  -H "Content-Type: application/json" \
  --data '{
    "jsonrpc": "2.0",
    "method": "trace_rawTransaction",
    "params": [
      "0xd46e8dd67c5d32be8d46e8dd67c5d32be8058bb8eb970870f072445675058bb8eb970870f072445675",
      [
        "trace"
      ]
    ],
    "id": 1
  }'

trace_replayBlockTransactions​

Provides transaction processing tracing per block.

note

When using Bonsai, the requested block must be within the number of blocks retained (by default, 512 from the head of the chain).

Parameters

  • blockNumber: string - Hexadecimal integer representing a block number, or one of the string tags latest, earliest, pending, finalized, or safe, as described in block parameter.

    note

    pending returns the same value as latest.

  • options: array of strings - List of tracing options; tracing options are trace, vmTrace, and stateDiff. Specify any combination of the three options including none of them.

Returns

  • List of transaction trace objects containing one object per transaction, in transaction execution order; if revert reason is enabled with --revert-reason-enabled, the trace list items in the returned transaction trace object include the revert reason.

Example

curl -X POST http://127.0.0.1:8545/ \
  -H "Content-Type: application/json" \
  --data '{
    "jsonrpc": "2.0",
    "method": "trace_replayBlockTransactions",
    "params": [
      "0x12",
      [
        "trace",
        "vmTrace",
        "stateDiff"
      ]
    ],
    "id": 1
  }'

trace_transaction​

Provides transaction processing of type trace for the specified transaction.

note

Your node must be an archive node, or the requested transaction must be contained in a block within the number of blocks retained when using Bonsai (by default, 512 from the head of the chain).

Parameters

  • transaction: string - Transaction hash.

Returns

Example

curl -X POST http://127.0.0.1:8545/ \
  -H "Content-Type: application/json" \
  --data '{
    "jsonrpc": "2.0",
    "method": "trace_transaction",
    "params": [
      "0x4c253746668dca6ac3f7b9bc18248b558a95b5fc881d140872c2dff984d344a7"
    ],
    "id": 1
  }'

Trace types​

trace​

An ordered list of trace objects produced during execution, excluding precompiled-contract calls that do not execute. Each item is an object with the following fields. The action and result shapes depend on the trace type.

  • action: object - Details of the traced operation. Fields present depend on type. Unused action fields are omitted from the JSON.

    • callType: string - CALL-family variant: call, callcode, delegatecall, or staticcall. Present only on call traces. Contract creation is indicated by type: "create", not by callType.

    • from: data, 20 bytes - Address of the caller or creator. Present on call and create traces.

    • gas: quantity - Gas provided for this operation. Present on call and create traces.

    • input: data - Call data. Present on call traces.

    • to: data, 20 bytes - Call target. Present on call traces.

    • value: quantity - Value transferred. Present on call, create, and reward traces.

    • init: data - Contract initialization bytecode. Present on create traces.

    • creationMethod: string - Creation opcode (create or create2). Present on some create traces.

    • address: data, 20 bytes - Contract that self-destructed. Present on suicide traces.

    • balance: quantity - Balance transferred on self-destruct. Present on suicide traces.

    • refundAddress: data, 20 bytes - Recipient of the self-destructed balance. Present on suicide traces.

    • author: data, 20 bytes - Reward recipient. Present on reward traces (trace_block only).

    • rewardType: string - Reward kind: block or uncle. Present on reward traces (trace_block only).

  • result: object - Execution result for successful call and create traces. Omitted when error is present. null for suicide and reward traces.

    • gasUsed: quantity - Gas used by this trace, including unused-gas refunds.

    • output: data - Return value of the contract call. Contains only the actual value sent by a RETURN operation. If a RETURN was not executed, the output is empty bytes. Present on call traces.

    • code: data - Deployed bytecode. Present on create traces.

    • address: data, 20 bytes - Created contract address. Present on create traces.

  • error: string - Error that caused this trace to fail, for example Reverted. Present only on failed traces. When this field is present, result is omitted from the JSON.

  • subtraces: integer - Number of child traces.

  • traceAddress: array - Path of this trace in the call tree. Empty for the top-level trace.

  • type: string - Trace kind: call, create, suicide, or reward. reward appears only in trace_block results.

Example​

"trace":[
  {
    "action":{
      "callType":"call",
      "from":"0xfe3b557e8fb62b89f4916b721be55ceb828dbd73",
      "gas":"0xffadea",
      "input":"0x",
      "to":"0x0100000000000000000000000000000000000000",
      "value":"0x0"
    },
    "result":{
      "gasUsed":"0x1e",
      "output":"0x"
    },
    "subtraces":0,
    "traceAddress":[
    ],
    "type":"call"
  }
]

vmTrace​

The vmTrace field is an object with a code property and a nested ops list. The field itself is not a list.

  • code: data - Code executed by the EVM.

  • ops: array - Sequence of EVM operations (opcodes) executed in the transaction.

    • cost: quantity - Gas cost of the opcode. Includes memory expansion costs but not gas refunds. For precompiled contract calls, reports only the actual cost.

    • ex: object - Executed operations.

      • mem: object - Memory read or written by the operation.

      • push: array - Adjusted stack items. For swap, includes all intermediate values and the result. Otherwise, is the value pushed onto the stack.

      • store: object - Account storage written by the operation.

      • used: quantity - Remaining gas taking into account the all but 1/64th rule for calls.

    • pc: quantity - Program counter.

    • sub: object - Sub call operations.

vmTrace only reports actual data returned from a RETURN opcode and does not return the contents of the reserved output space for the call operations. As a result:

  • vmTrace reports null when a call operation ends because of a STOP, HALT, REVERT, running out of instructions, or any exceptional halts.
  • When a RETURN operation returns data of a different length to the space reserved by the call, vmTrace reports only the data passed to the RETURN operation and does not include pre-existing memory data or trim the returned data.

For out of gas operations, vmTrace reports the operation that caused the out of gas exception, including the calculated gas cost. vmTrace does not report ex values because the operation is not executed.

Example​

"vmTrace":{
  "code":"0x7f3940be4289e4c3587d88c1856cc95352461992db0a584c281226faefe560b3016000527f14c4d2c102bdeb2354bfc3dc96a95e4512cf3a8461e0560e2272dbf884ef3905601052600851",
  "ops":[
    {
    "cost":3,
    "ex":{
      "mem":null,
      "push":[
        "0x8"
      ],
      "store":null,
      "used":16756175
    },
    "pc":72,
    "sub":null
    },
    ...
  ]
}

stateDiff​

State changes in the requested block for each transaction represented as a map of accounts to an object. Besu lists the balance, code, nonce, and storage changes from immediately before the transaction to after the transaction.

  • balance: string or object - Change of balance.

  • code: string or object - Change to the account's code.

  • nonce: string or object - Change of nonce.

  • storage: object - Map of each changed storage slot key to its diff value.


Each of the balance, code, and nonce values, and each changed storage slot in storage, uses one of the following notations, depending on the type of change:

  • "=" - The value didn't change.

  • {"+": <value>} - The value didn't exist before the transaction and now has the specified value.

  • {"-": <value>} - The value existed before the transaction and was deleted.

  • {"*": {"from": <value>, "to": <value>}} - The value changed from one value to another.

An absent value is distinct from zero when creating accounts or clearing storage.

Example​

"stateDiff":{
  "0xfe3b557e8fb62b89f4916b721be55ceb828dbd73":{
    "balance":{
      "*":{
        "from":"0xffffffffffffffffffffffffffffffffc3e12a20b",
        "to":"0xffffffffffffffffffffffffffffffffc3dc5f091"
      }
    },
    "code":"=",
    "nonce":{
      "*":{
        "from":"0x14",
        "to":"0x15"
      }
    },
    "storage":{
    }
  }
}