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

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: tag - 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

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.

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

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.

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

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 calls to other contracts, excluding precompiled contracts. Each item in the list is an object with the following fields.

  • action: object - Transaction details.

    • callType: string - Whether the transaction is call or create.

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

    • gas: quantity - Gas provided by sender.

    • input: data - Transaction data.

    • to: data, 20 bytes - Target of the transaction.

    • value: quantity - Value transferred in the transaction.

  • result: object - Transaction result.

    • gasUsed: quantity - Gas used by the transaction. Includes any refunds of unused gas.

    • 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.

  • subtraces: integer - Traces of contract calls made by the transaction.

  • traceAddress: array - Tree list address of where the call occurred, address of the parents, and order of the current sub call.

  • type: string - Whether the transaction is a CALL or CREATE series operation.

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​

An object containing the following fields.

  • 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":{
    }
  }
}