debug_traceBlockByHash

The debug_traceBlockByHash method returns a full trace of all invoked opcodes of all transactions included in the specified block, identified by its hash. This method provides comprehensive opcode-level execution information for analyzing and debugging every transaction within a specified block, making it ideal for deep investigation of blockchain state transitions.

Use Cases

Debug complex transaction failures and interactions within a specific known block
Analyze execution patterns across multiple transactions in a precisely identified block
Investigate gas usage optimization across transactions in historical blocks
Perform security auditing of deployed contracts in production environments
Verify correct transaction behavior and execution flow in specific important blocks
Understand complex multi-contract interactions across a series of transactions
Analyze historical blocks by their hash to investigate network behavior
Trace exact execution of transactions for block validation or bug hunting
Identify patterns in transaction execution within the same block context
Investigate MEV (Miner Extractable Value) transaction ordering effects
Debug failed transactions in the context of their block environment

Method Details

This method traces the execution of all transactions in a block, identified by its hash, 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:

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.

Differences from Other Block Tracing Methods

While all three block tracing methods provide similar information:

debug_traceBlockByHash accepts a block hash for precise block identification
debug_traceBlockByNumber uses a block number or tag (e.g., "latest")
debug_traceBlock requires an RLP-encoded block as input
All methods return identical trace formats
This method is ideal when you know the exact block hash you want to investigate

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 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)
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
For regular block information without tracing, use eth_getBlockByHash