Debug and trace APIs

Overview

Debug and trace APIs allow Web3 developers to monitor, trace, and debug the activities that occur within blockchain networks. They provide detailed information about transactions, blocks, and smart contracts execution making it easier to identify and resolve issues within decentralized applications.

By using debug and trace APIs, developers can build more reliable and secure DApps with improved user experience and thus contribute to the overall health of a network.

📘

Historical states limitations

To debug and trace transactions, you need to have historical states on the node. Full nodes of different protocols can store different amount of historical states. At the same time, archive nodes keep historical states for the entire chain.

Protocols with debug and trace APIs

Ethereum

Elastic nodes

To enable debug and trace APIs on your elastic Ethereum node, you must have the Growth plan or higher and deploy the node in the archive mode. Your node will run the Erigon client and will expose the debug_* and trace_* methods. Learn how to deploy your elastic Ethereum node with debug and trace APIs enabled.

Dedicated nodes

To enable debug and trace APIs on your dedicated Ethereum node, you must have the Growth plan or higher. Dedicated nodes can be deployed either as the Geth or Erigon client implementation for the full and archive modes respectively, however, they slightly differ from each other:

• With a node running on Geth, only debug_*namespace is exposed.
• With a node running on Erigon, both debug_* and trace_*namespaces are exposed.

Learn how to deploy your dedicated Ethereum node run on different clients with debug and trace APIs enabled.

For the full list of the available debug and trace API methods, see:

• Geth: debug namespace
• Erigon: RPC implementation status

Polygon

Elastic nodes

To enable debug and trace APIs on your elastic Polygon node, you must have the Growth plan or higher and deploy the node in the archive mode. Your node will run the Erigon client and will expose the debug_* and trace_* methods.

Dedicated nodes

To enable debug and trace APIs on your dedicated Polygon node, you must have the Growth plan or higher. Dedicated nodes can be deployed either as the Bor or Erigon client implementation for the full and archive modes respectively, however, they slightly differ from each other:

• With a node running on Bor, only debug_*namespace is exposed.
• With a node running on Erigon, both debug_* and trace_*namespaces are exposed.

For the full list of the available debug and trace API methods, see: Erigon: RPC implementation status

BNB Smart Chain

Elastic nodes

To enable debug and trace APIs on your elastic BNB Smart Chain node, you must have the Growth plan or higher and deploy the node in the archive mode. Your node will run the Erigon client and will expose the debug_* and trace_* methods.

Dedicated nodes

To enable debug and trace APIs on your dedicated BNB Smart Chain node, you must have the Growth plan or higher. Dedicated nodes can be deployed either as the Geth or Erigon client implementation for the full and archive modes respectively, however, they slightly differ from each other:

• With a node running on Geth, only debug_*namespace is exposed.
• With a node running on Erigon, both debug_* and trace_*namespaces are exposed.

For the full list of the available debug and trace API methods, see:

• Geth: debug namespace
• Erigon: RPC implementation status

Avalanche

To enable debug and trace APIs on your elastic Avalanche node, you must have the Growth plan or higher and deploy the node in the archive mode. Your node will run the AvalancheGo client, which is the Go language implementation of an Avalanche node. Avalanche offers an API interface identical to Geth's API, but with a limited set of services that include debug_trace*.

For a full list of the Geth debug API methods, see the Debug namespace section of the Geth documentation.

You can deploy a dedicated Avalanche node starting from the Growth plan.

Arbitrum

Elastic nodes

To enable debug and trace APIs on your elastic Arbitrum node, you must have the Growth plan or higher and deploy the node in the archive mode.

Dedicated nodes

To enable debug and trace APIs on your dedicated Arbitrum node, you must have the Growth plan or higher.

Avalaible methods

Both elastic and dedicated Arbitrum nodes with debug and trace APIs enabled will expose the debug_* and arbtrace_* methods.

Blocks older than 22,207,815th were added to the chain before Nitro migration and cannot be queried with Geth methods. Starting from block 22,207,815, Arbitrum migrated to Nitro which made Geth debug_* methods available for newer blocks.

Use the following methods for calling on blocks prior to 22,207,815:

• arbtrace_call
• arbtrace_callMany
• arbtrace_replayBlockTransactions
• arbtrace_replayTransaction
• arbtrace_transaction
• arbtrace_get
• arbtrace_block
• arbtrace_filter

For the full list of the available debug_* namespace methods, see Geth documentation.

zkSync Era

To enable debug and trace APIs on your zkSync Era node, you must deploy an elastic node in the archive mode. The node will expose the debug_* API methods. An elastic debug and trace node for zkSync Era is available starting from the Growth plan.

For the full list of the available debug and trace API methods, see Debug namespace.

Optimism

To enable debug and trace APIs on your Optimism node, you must deploy a dedicated node in the full or archive mode. The node will expose the debug_* API methods. A dedicated debug and trace node for Optimism is available starting from the Growth plan.

For the full list of the available debug and trace API methods, see Debug namespace.

Gnosis Chain

To enable debug and trace APIs on your Gnosis Chain node, you must deploy a dedicated node in the full or archive mode. The node will expose the debug_* and trace_* API methods. A dedicated debug and trace node for Gnosis Chain is available starting from the Growth plan.

For the full list of the available debug and trace API methods, see Nethermind documentation.

Fantom

To enable debug and trace APIs on your Fantom node, you must deploy a dedicated node in the full or archive mode. The node will expose the debug_* API methods. A dedicated debug and trace node for Fantom is available starting from the Growth plan.

For the full list of the available debug and trace API methods, see Debug namespace.

Harmony

To enable debug and trace APIs on your Harmony node, you must deploy a dedicated node in the full or archive mode. The node will expose the debug_* API methods. A dedicated debug and trace node for Harmony is available starting from the Growth plan.

For the full list of the available debug and trace API methods, see Debug namespace.

Fuse

To enable debug and trace APIs on your Fuse node, you must deploy a dedicated node in the full or archive mode. The node will expose the debug_* and trace_* API methods. A dedicated debug and trace node for Fuse is available starting from the Growth plan.

For the full list of the available debug and trace API methods, see Nethermind documentation.

Usage examples

You can debug and trace transactions by replaying them in the Ethereum Virtual Machine to get the execution details in the exact same way as they happened on the chain.

debug_traceBlockByNumber

Trace all transactions included in a block with debug_traceBlockByNumber in block 14,976,695:

curl 'YOUR_CHAINSTACK_ENDPOINT' \
-H 'Content-Type: application/json' \
-d '{"id": 1, "method": "debug_traceBlockByNumber", "params": ["0xE486B7", {"tracer": "callTracer"}]}'

where

• 0xE486B7 — the number of the block to get the traces of included transactions. For Geth, you need to provide the block number in hex.
• YOUR_CHAINSTACK_ENDPOINT — your Chainstack node HTTPS endpoint. See View node access and credentials.

See a reverted transaction in the output:

"calls": [
  {
    "type": "DELEGATECALL",
    "from": "0x68b3465833fb72a70ecdf485e0e4c7bd8665fc45",
    "to": "0x68b3465833fb72a70ecdf485e0e4c7bd8665fc45",
    "gas": "0x38ed0",
    "gasUsed": "0x31147",
    "input": "0x472b43f30000000000000000000000000000000000000000000000000429d069189e00000000000000000000000000000000000000000000000000160d962fcdfd0bb02400000000000000000000000000000000000000000000000000000000000000800000000000000000000000000b5ec97d9a8a9941a28a88084a1f670c62bd8bf40000000000000000000000000000000000000000000000000000000000000002000000000000000000000000c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2000000000000000000000000b00b2e950d7ef8bdc49377c49676d1550deab982",
     "error": "execution reverted"

trace_block

Trace all transactions included in a block with trace_block in block 14,976,695:

curl 'YOUR_CHAINSTACK_ENDPOINT' \
-H 'Content-Type: application/json' \
-d '{"id": 1, "method": "trace_block", "params": ["14976695"]}'

where

• 14976695 — the number of the block to get the traces of included transactions
• YOUR_CHAINSTACK_ENDPOINT — your Chainstack node HTTPS endpoint. See View node access and credentials.

See a reverted transaction in the output:

"action": {
  "from": "0x68b3465833fb72a70ecdf485e0e4c7bd8665fc45",
  "callType": "delegatecall",
  "gas": "0x38ed0",
  "input": "0x472b43f30000000000000000000000000000000000000000000000000429d069189e00000000000000000000000000000000000000000000000000160d962fcdfd0bb02400000000000000000000000000000000000000000000000000000000000000800000000000000000000000000b5ec97d9a8a9941a28a88084a1f670c62bd8bf40000000000000000000000000000000000000000000000000000000000000002000000000000000000000000c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2000000000000000000000000b00b2e950d7ef8bdc49377c49676d1550deab982",
  "to": "0x68b3465833fb72a70ecdf485e0e4c7bd8665fc45",
  "value": "0x429d069189e0000"
  },
  "blockHash": "0x03a83bf066e81498804f26caf5d49e47820f6a0e92fd1c9cb7dc3b87bf46cf0f",
  "blockNumber": 14976695,
  "error": "Reverted"