debug_traceBlock

The debug_traceBlock method returns a full trace of all invoked opcodes of all transactions included in the specified block. This method provides comprehensive low-level execution information essential for debugging, security analysis, and optimizing transaction behavior across multiple contracts within a single block context.

Use Cases

Debug complex transactions and interactions within a specific block context
Analyze smart contract execution flow across multiple transactions
Optimize gas usage by identifying inefficient patterns across transactions
Perform security auditing of deployed contracts in real-world conditions
Verify transaction behavior matches expected outcomes and specifications
Understand complex multi-contract interactions in production environments
Analyze virtual machine execution patterns for research and optimization
Investigate transaction failures at the opcode level
Verify correctness of complex execution paths in smart contracts
Identify gas usage patterns in production environments
Debug and analyze the exact execution of transactions within historical blocks
Trace all internal calls across a complete block of operations

Method Details

This method traces the execution of all transactions in a block at the opcode level.

Response Example (Simplified)

1{
2	"jsonrpc": "2.0",
3	"id": 1,
4	"result": [
5		{
6			"gas": 21000,
7			"failed": false,
8			"returnValue": "",
9			"structLogs": [
10				{
11					"pc": 0,
12					"op": "PUSH1",
13					"gas": 68232,
14					"gasCost": 3,
15					"depth": 1,
16					"stack": [],
17					"memory": [],
18					"storage": {}
19				},
20				{
21					"pc": 2,
22					"op": "MSTORE",
23					"gas": 68229,
24					"gasCost": 12,
25					"depth": 1,
26					"stack": ["0x60", "0x40"],
27					"memory": [
28						"0000000000000000000000000000000000000000000000000000000000000000",
29						"0000000000000000000000000000000000000000000000000000000000000000"
30					],
31					"storage": {}
32				}
33				// ... more operations
34			]
35		}
36		// Additional transaction traces...
37	]
38}

Response with callTracer

When using the callTracer option, the response is formatted as a call graph for each transaction:

1{
2	"jsonrpc": "2.0",
3	"id": 1,
4	"result": [
5		{
6			"type": "CALL",
7			"from": "0x1923f626bb8dc025849e00f99c25fe2b2f7fb0db",
8			"to": "0xdac17f958d2ee523a2206206994597c13d831ec7",
9			"value": "0x0",
10			"gas": "0x13458",
11			"gasUsed": "0x8fc",
12			"input": "0xa9059cbb0000000000000000000000001f9840a85d5af5bf1d1762f925bdaddc4201f984000000000000000000000000000000000000000000000002b5e3af16b1880000",
13			"output": "0x0000000000000000000000000000000000000000000000000000000000000001",
14			"calls": [
15				{
16					"type": "STATICCALL",
17					"from": "0xdac17f958d2ee523a2206206994597c13d831ec7",
18					"to": "0x1f9840a85d5af5bf1d1762f925bdaddc4201f984",
19					"gas": "0x8fc",
20					"gasUsed": "0x54b",
21					"input": "0x70a08231000000000000000000000000dac17f958d2ee523a2206206994597c13d831ec7",
22					"output": "0x0000000000000000000000000000000000000000000000000000000000000000"
23				}
24			]
25		}
26		// Additional call traces...
27	]
28}

Available Tracers

Geth provides several built-in tracers that format the output in different ways:

Default tracer: Detailed opcode-level execution logs
callTracer: Focuses on call hierarchy between contracts
prestateTracer: Shows contract state before execution
4byteTracer: Tracks function selector usage statistics
noopTracer: Minimal tracer for performance testing
opCountTracer: Counts occurrences of each opcode

You can also use JavaScript-based custom tracers for specialized analysis.

Working with RLP-encoded Blocks

This method requires an RLP-encoded block as input:

You can obtain an RLP-encoded block from eth_getBlockByHash with the second parameter set to false
The encoding includes all block header fields and transaction data in binary format
For testing purposes, you can use a known block RLP from the network
Tools like web3.js or ethers.js can help extract and encode blocks properly
Manually extracted blocks ensure you're analyzing the exact state you need

Differences from debug_traceBlockByNumber and debug_traceBlockByHash

While all three methods provide block-level transaction traces:

debug_traceBlock accepts an RLP-encoded block as input
debug_traceBlockByNumber accepts a block number or tag (e.g., "latest")
debug_traceBlockByHash accepts a block hash
All methods return identical trace formats
This method is useful when you already have the RLP-encoded block data

Performance Considerations

Tracing entire blocks is extremely resource-intensive, especially for blocks with many transactions
Response size can be very large for blocks with complex transactions
Consider using the disableMemory, disableStack, or disableStorage options for better performance
For call graph analysis only, the callTracer is much more efficient
JavaScript tracers may require longer timeouts for complex blocks
Queries against historical blocks require an archive node
Tracing blocks with many transactions may time out on public nodes
For high-volume blocks, consider tracing individual transactions instead
Response time increases with block size and transaction complexity
For blocks with complex transactions, specialized tracers are recommended

Important Notes

This method requires debug APIs to be enabled on the node (--http.api=eth,debug,net,web3)
Not all Ethereum clients support this method (primarily Geth with debug APIs enabled)
The RLP-encoded block parameter must be properly formatted for the method to work
For older blocks, an archive node is required to access historical state
The method provides detailed traces for all transactions in the block, which can result in very large responses
Different Ethereum clients may produce slightly different trace formats
The output format depends on the tracer used and may change between client versions
Memory and stack values are represented in hex and may need decoding

1curl https://sonic.therpc.io \
2  -X POST \
3  -H 'Content-Type: application/json' \
4  -d '{"jsonrpc":"2.0","id":1,"method":"debug_traceBlock","params":["0xf90213a01e77d8f1267348b516ebc4f4da1e2aa59f85f0cbd853949500ffac8bfc38ba14a01dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347942a65aca4d5fc5b5c859090a6c34d164135398226a00b5e4386680f43c224c5c037efc0b645c8e1c3f6b30da0eec07272b4e6f8cd89a056e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421a056e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421b901000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000086057a418a7c3e83061a80832fefd880845622efdc96d583010202844765746885676f312e35856c696e7578a03fbea7af642a4e20cd93a945a1f5e23bd72fc5261153e09102cf718980aeff38886af23caae95692ef",{"disableStorage":false,"disableMemory":false,"disableStack":false,"tracer":"callTracer","timeout":"10s"}]}'