Trace methods

These methods trace transactions, blocks, and calls to inspect low-level execution.

debug_standardTraceBlockToFile

Generates files containing the block trace. A separate file is generated for each transaction in the block.

You can also specify a trace file for a specific transaction in a block.

Use debug_standardTraceBadBlockToFile to view the trace for an invalid block.

Parameters

• blockHash: string - Block hash.

• options: object - (Optional) Request options object (all fields optional).

  • txHash: string - Transaction hash; if omitted, a trace file is generated for each transaction in the block.

  • disableMemory: boolean - true disables memory capture. The default is true.

  • disableStack: boolean - true disables stack capture. The default is false.

  • disableStorage: boolean - true disables storage capture. The default is false.

  • opcodes: array of strings - List of opcode names to trace; if omitted or empty, all opcodes are traced.

  • enableReturnData: boolean - true enables return data capture. The default is false.

Returns

• Location of the generated trace files.

Example

curl HTTP request

curl -X POST http://127.0.0.1:8545/ \
  -H "Content-Type: application/json" \
  --data '{
    "jsonrpc": "2.0",
    "method": "debug_standardTraceBlockToFile",
    "params": [
      "0x2dc0b6c43144e314a86777b4bd4f987c0790a6a0b21560671d221ed81a23f2dc",
      {
        "txHash": "0x4ff04c4aec9517721179c8dd435f47fbbfc2ed26cd4926845ab687420d5580a6",
        "disableMemory": false
      }
    ],
    "id": 1
  }'

wscat WS request

{
  "jsonrpc": "2.0",
  "method": "debug_standardTraceBlockToFile",
  "params": [
    "0x2dc0b6c43144e314a86777b4bd4f987c0790a6a0b21560671d221ed81a23f2dc",
    {
      "txHash": "0x4ff04c4aec9517721179c8dd435f47fbbfc2ed26cd4926845ab687420d5580a6",
      "disableMemory": false
    }
  ],
  "id": 1
}

JSON result

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    "/Users/me/mynode/sepolia/data/traces/block_0x2dc0b6c4-4-0x4ff04c4a-1612820117332"
  ]
}

---

debug_standardTraceBadBlockToFile

Generates files containing the block trace of invalid blocks. A separate file is generated for each transaction in the block.

Use debug_standardTraceBlockToFile to view the trace for a valid block.

Parameters

• blockHash: string - Block hash.

• options: object - (Optional) Request options object (all fields optional).

  • txHash: string - Transaction hash; if omitted, a trace file is generated for each transaction in the block.

  • disableMemory: boolean - true disables memory capture. The default is true.

  • disableStack: boolean - true disables stack capture. The default is false.

  • disableStorage: boolean - true disables storage capture. The default is false.

  • opcodes: array of strings - List of opcode names to trace; if omitted or empty, all opcodes are traced.

  • enableReturnData: boolean - true enables return data capture. The default is false.

Returns

• Location of the generated trace files.

Example

curl HTTP request

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

wscat WS request

{
  "jsonrpc": "2.0",
  "method": "debug_standardTraceBadBlockToFile",
  "params": [
    "0x53741e9e94791466d117c5f9e41a2ed1de3f73d39920c621dfc2f294e7779baa"
  ],
  "id": 1
}

JSON result

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    "/Users/me/mynode/sepolia/data/traces/block_0x53741e9e-0-0x407ec43d-1600951088172"
  ]
}

---

debug_traceTransaction

Remix uses debug_traceTransaction to implement debugging. Use the Debugger tab in Remix instead of calling debug_traceTransaction directly.

Reruns the transaction with the same state as when the transaction executed.

Parameters

• transactionHash: string - Transaction hash.

• options: object - (Optional) Request options object (all fields optional).

  • disableStorage: boolean - true disables storage capture. The default is false.

  • enableMemory: boolean - true enables memory capture. The default is false. If specified, enableMemory takes precedence over disableMemory.

  • disableMemory: boolean - true disables memory capture. The default is true.

  • disableStack : boolean - true disables stack capture. The default is false.

  • opcodes: array of strings - List of opcode names to trace; if omitted or empty, all opcodes are traced.

  • enableReturnData: boolean - true enables return data capture. The default is false.

Returns

• Trace object.

  • gas: integer - Gas used by the transaction.

  • failed: boolean - True if transaction failed, otherwise, false.

  • returnValue: string - Bytes returned from transaction execution (without a 0x prefix).

  • structLogs: array - Array of structured log objects.

    • pc: integer - Current program counter.

    • op: string - Current opcode.

    • gas: integer - Gas remaining.

    • gasCost: integer - Cost in wei of each gas unit.

    • depth: integer - Execution depth.

    • exceptionalHaltReasons: array - One or more strings representing an error condition causing the EVM execution to terminate, such as running out of gas or attempting to execute an unknown instruction.

    • stack: array of 32 byte arrays - EVM execution stack before executing current operation.

    • memory: array of 32 byte arrays - Memory space of the contract before executing current operation.

    • storage: object - Storage entries changed by the current transaction.

    • returnData: data - EVM return data produced by the current opcode, as a hex string.

Example

curl HTTP request

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

wscat WS request

{
  "jsonrpc": "2.0",
  "method": "debug_traceTransaction",
  "params": [
    "0x2cc6c94c21685b7e0f8ddabf277a5ccf98db157c62619cde8baea696a74ed18e",
    {
      "disableStorage": true,
      "enableReturnData": true
    }
  ],
  "id": 1
}

JSON result

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "gas": 21000,
    "failed": false,
    "returnValue": "",
    "structLogs": [
      {
        "pc": 100,
        "op": "STATICCALL",
        "gas": 78000,
        "gasCost": 500,
        "depth": 1,
        "stack": [],
        "returnData": "0x0000000000000000000000000000000000000000000000000000000000000001"
      }
    ]
  }
}

---

debug_traceBlock

Returns full trace of all invoked opcodes of all transactions included in the block.

Parameters

• block: string - RLP of the block.

• options: object - (Optional) Request options object (all fields optional).

  • disableStorage: boolean - true disables storage capture. The default is false.

  • enableMemory: boolean - true enables memory capture. The default is false. If specified, enableMemory takes precedence over disableMemory.

  • disableMemory: boolean - true disables memory capture. The default is true.

  • disableStack : boolean - true disables stack capture. The default is false.

  • opcodes: array of strings - List of opcode names to trace; if omitted or empty, all opcodes are traced.

  • enableReturnData: boolean - true enables return data capture. The default is false.

Returns

• Trace object.

  • gas: integer - Gas used by the transaction.

  • failed: boolean - True if transaction failed, otherwise, false.

  • returnValue: string - Bytes returned from transaction execution (without a 0x prefix).

  • structLogs: array - Array of structured log objects.

    • pc: integer - Current program counter.

    • op: string - Current opcode.

    • gas: integer - Gas remaining.

    • gasCost: integer - Cost in wei of each gas unit.

    • depth: integer - Execution depth.

    • exceptionalHaltReasons: array - One or more strings representing an error condition causing the EVM execution to terminate, such as running out of gas or attempting to execute an unknown instruction.

    • stack: array of 32 byte arrays - EVM execution stack before executing current operation.

    • memory: array of 32 byte arrays - Memory space of the contract before executing current operation.

    • storage: object - Storage entries changed by the current transaction.

    • returnData: data - EVM return data produced by the current opcode, as a hex string.

Example

curl HTTP request

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

wscat WS request

{
  "jsonrpc": "2.0",
  "method": "debug_traceBlock",
  "params": [
    "0xf90277f90208a05a41d0e66b4120775176c09fcf39e7c0520517a13d2b57b18d33d342df038bfca01dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d4934794e6a7a1d47ff21b6321162aea7c6cb457d5476bcaa00e0df2706b0a4fb8bd08c9246d472abbe850af446405d9eba1db41db18b4a169a04513310fcb9f6f616972a3b948dc5d547f280849a87ebb5af0191f98b87be598a0fe2bf2a941abf41d72637e5b91750332a30283efd40c424dc522b77e6f0ed8c4b9010000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000860153886c1bbd82b44382520b8252088455c426598b657468706f6f6c2e6f7267a0b48c515a9dde8d346c3337ea520aa995a4738bb595495506125449c1149d6cf488ba4f8ecd18aab215f869f86780862d79883d2000825208945df9b87991262f6ba471f09758cde1c0fc1de734827a69801ca088ff6cf0fefd94db46111149ae4bfc179e9b94721fffd821d38d16464b3f71d0a045e0aff800961cfce805daef7016b9b675c137a6a41a548f7b60a3484c06a33ac0"
  ],
  "id": 1
}

JSON result

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "gas": 21000,
    "failed": false,
    "returnValue": "",
    "structLogs": [
      {
        "pc": 0,
        "op": "STOP",
        "gas": 0,
        "gasCost": 0,
        "depth": 1,
        "stack": []
      }
    ]
  }
}

---

debug_traceBlockByHash

Returns full trace of all invoked opcodes of all transactions included in the block.

Parameters

• blockHash: string - Block hash.

• options: object - (Optional) Request options object (all fields optional).

  • disableStorage: boolean - true disables storage capture. The default is false.

  • enableMemory: boolean - true enables memory capture. The default is false. If specified, enableMemory takes precedence over disableMemory.

  • disableMemory: boolean - true disables memory capture. The default is true.

  • disableStack : boolean - true disables stack capture. The default is false.

  • opcodes: array of strings - List of opcode names to trace; if omitted or empty, all opcodes are traced.

  • enableReturnData: boolean - true enables return data capture. The default is false.

Returns

• List of trace objects.

  • gas: integer - Gas used by the transaction.

  • failed: boolean - True if transaction failed, otherwise, false.

  • returnValue: string - Bytes returned from transaction execution (without a 0x prefix).

  • structLogs: array - Array of structured log objects.

    • pc: integer - Current program counter.

    • op: string - Current opcode.

    • gas: integer - Gas remaining.

    • gasCost: integer - Cost in wei of each gas unit.

    • depth: integer - Execution depth.

    • exceptionalHaltReasons: array - One or more strings representing an error condition causing the EVM execution to terminate, such as running out of gas or attempting to execute an unknown instruction.

    • stack: array of 32 byte arrays - EVM execution stack before executing current operation.

    • memory: array of 32 byte arrays - Memory space of the contract before executing current operation.

    • storage: object - Storage entries changed by the current transaction.

    • returnData: data - EVM return data produced by the current opcode, as a hex string.

Example

curl HTTP request

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

wscat WS request

{
  "jsonrpc": "2.0",
  "method": "debug_traceBlockByHash",
  "params": [
    "0xaceb3b2c9b25b0589230873921eb894b28722011b8df63977145517d754875a5"
  ],
  "id": 1
}

JSON result

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    {
      "gas": 21000,
      "failed": false,
      "returnValue": "",
      "structLogs": [
        {
          "pc": 0,
          "op": "STOP",
          "gas": 0,
          "gasCost": 0,
          "depth": 1,
          "stack": []
        }
      ]
    }
  ]
}

---

debug_traceBlockByNumber

Returns full trace of all invoked opcodes of all transactions included in the block.

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: object - (Optional) Request options object (all fields optional).

  • disableStorage: boolean - true disables storage capture. The default is false.

  • enableMemory: boolean - true enables memory capture. The default is false. If specified, enableMemory takes precedence over disableMemory.

  • disableMemory: boolean - true disables memory capture. The default is true.

  • disableStack : boolean - true disables stack capture. The default is false.

  • opcodes: array of strings - List of opcode names to trace; if omitted or empty, all opcodes are traced.

  • enableReturnData: boolean - true enables return data capture. The default is false.

Returns

• List of trace objects.

  • gas: integer - Gas used by the transaction.

  • failed: boolean - True if transaction failed, otherwise, false.

  • returnValue: string - Bytes returned from transaction execution (without a 0x prefix).

  • structLogs: array - Array of structured log objects.

    • pc: integer - Current program counter.

    • op: string - Current opcode.

    • gas: integer - Gas remaining.

    • gasCost: integer - Cost in wei of each gas unit.

    • depth: integer - Execution depth.

    • exceptionalHaltReasons: array - One or more strings representing an error condition causing the EVM execution to terminate, such as running out of gas or attempting to execute an unknown instruction.

    • stack: array of 32 byte arrays - EVM execution stack before executing current operation.

    • memory: array of 32 byte arrays - Memory space of the contract before executing current operation.

    • storage: object - Storage entries changed by the current transaction.

    • returnData: data - EVM return data produced by the current opcode, as a hex string.

Example

curl HTTP request

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

wscat WS request

{
  "jsonrpc": "2.0",
  "method": "debug_traceBlockByNumber",
  "params": [
    "0x7224",
    {
      "disableStorage": true
    }
  ],
  "id": 1
}

JSON result

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    {
      "gas": 21000,
      "failed": false,
      "returnValue": "",
      "structLogs": [
        {
          "pc": 0,
          "op": "STOP",
          "gas": 0,
          "gasCost": 0,
          "depth": 1,
          "stack": []
        }
      ]
    }
  ]
}

---

debug_traceCall

Performs an eth_call within the execution environment of a given block, using the final state of its parent block as the base, and provides a detailed trace of the executed opcodes.

Each options entry specifies a state that will be temporarily overridden before executing the call. This allows you to test, analyze, and debug smart contracts more efficiently by allowing temporary state changes without affecting the actual blockchain state.

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: object - (Optional) Request options object (all fields optional).

  • disableStorage: boolean - true disables storage capture. The default is false.

  • enableMemory: boolean - true enables memory capture. The default is false. If specified, enableMemory takes precedence over disableMemory.

  • disableMemory: boolean - true disables memory capture. The default is true.

  • disableStack : boolean - true disables stack capture. The default is false.

  • opcodes: array of strings - List of opcode names to trace; if omitted or empty, all opcodes are traced.

  • enableReturnData: boolean - true enables return data capture. The default is false.

  • stateOverrides: object - Address-to-state mapping.

    • balance: quantity - Temporary account balance for the call execution.

    • nonce: quantity - Temporary nonce value for the call execution.

    • code: binary - Bytecode to inject into the account.

    • movePrecompileToAddress: data, 20 bytes - Address to which the precompile address should be moved.

    • state: quantity - key:value pairs to override all slots in the account storage. You cannot set both the state and stateDiff options simultaneously.

    • stateDiff: quantity - key:value pairs to override individual slots in the account storage. You cannot set both the state and stateDiff options simultaneously.

Returns

• List of trace objects.

  • gas: integer - Gas used by the transaction.

  • failed: boolean - True if transaction failed, otherwise, false.

  • returnValue: string - Bytes returned from transaction execution (without a 0x prefix).

  • structLogs: array - Array of structured log objects.

    • pc: integer - Current program counter.

    • op: string - Current opcode.

    • gas: integer - Gas remaining.

    • gasCost: integer - Cost in wei of each gas unit.

    • depth: integer - Execution depth.

    • exceptionalHaltReasons: array - One or more strings representing an error condition causing the EVM execution to terminate, such as running out of gas or attempting to execute an unknown instruction.

    • stack: array of 32 byte arrays - EVM execution stack before executing current operation.

    • memory: array of 32 byte arrays - Memory space of the contract before executing current operation.

    • storage: object - Storage entries changed by the current transaction.

    • returnData: data - EVM return data produced by the current opcode, as a hex string.

Example

curl HTTP request

curl -X POST http://127.0.0.1:8545/ \
  -H "Content-Type: application/json" \
  --data '{
    "jsonrpc": "2.0",
    "method": "debug_traceCall",
    "params": [
      {
        "from": "",
        "to": "",
        "gas": "0xfffff2",
        "gasPrice": "0xef",
        "value": "0x0",
        "data": ""
      },
      "latest",
      {
        "disableMemory": true,
        "disableStack": true,
        "disableStorage": true
      }
    ],
    "id": 1
  }'

wscat WS request

{
  "jsonrpc": "2.0",
  "method": "debug_traceCall",
  "params": [{"0xfe3b557e8fb62b89f4916b721be55ceb828dbd73","0x0050000000000000000000000000000000000000", "0xfffff2","0xef","0x0","0x0000000000000000000000000030000000000000000000000000000000000000f000000000000000000000000000000000000000000000000000000000000001"},"latest",{"disableMemory":true,"disableStack":true,"disableStorage":true}],
  "id": 1
}

JSON result

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    {
      "gas": 21000,
      "failed": false,
      "returnValue": "",
      "structLogs": [
        {
          "pc": 0,
          "op": "STOP",
          "gas": 0,
          "gasCost": 0,
          "depth": 1
        }
      ]
    }
  ]
}