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)

{
	"jsonrpc": "2.0",
	"id": 1,
	"result": [
		{
			"gas": 21000,
			"failed": false,
			"returnValue": "",
			"structLogs": [
				{
					"pc": 0,
					"op": "PUSH1",
					"gas": 68232,
					"gasCost": 3,
					"depth": 1,
					"stack": [],
					"memory": [],
					"storage": {}
				},
				{
					"pc": 2,
					"op": "MSTORE",
					"gas": 68229,
					"gasCost": 12,
					"depth": 1,
					"stack": ["0x60", "0x40"],
					"memory": [
						"0000000000000000000000000000000000000000000000000000000000000000",
						"0000000000000000000000000000000000000000000000000000000000000000"
					],
					"storage": {}
				}
				// ... more operations
			]
		}
		// Additional transaction traces...
	]
}

Response with callTracer

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

{
	"jsonrpc": "2.0",
	"id": 1,
	"result": [
		{
			"type": "CALL",
			"from": "0x1923f626bb8dc025849e00f99c25fe2b2f7fb0db",
			"to": "0xdac17f958d2ee523a2206206994597c13d831ec7",
			"value": "0x0",
			"gas": "0x13458",
			"gasUsed": "0x8fc",
			"input": "0xa9059cbb0000000000000000000000001f9840a85d5af5bf1d1762f925bdaddc4201f984000000000000000000000000000000000000000000000002b5e3af16b1880000",
			"output": "0x0000000000000000000000000000000000000000000000000000000000000001",
			"calls": [
				{
					"type": "STATICCALL",
					"from": "0xdac17f958d2ee523a2206206994597c13d831ec7",
					"to": "0x1f9840a85d5af5bf1d1762f925bdaddc4201f984",
					"gas": "0x8fc",
					"gasUsed": "0x54b",
					"input": "0x70a08231000000000000000000000000dac17f958d2ee523a2206206994597c13d831ec7",
					"output": "0x0000000000000000000000000000000000000000000000000000000000000000"
				}
			]
		}
		// Additional call traces...
	]
}

Available Tracers

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

1. Default tracer: Detailed opcode-level execution logs
2. callTracer: Focuses on call hierarchy between contracts
3. prestateTracer: Shows contract state before execution
4. 4byteTracer: Tracks function selector usage statistics
5. noopTracer: Minimal tracer for performance testing
6. 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

See also

• debug_traceBlockByNumber - Trace block transactions by number
• debug_traceBlockByHash - Trace block transactions by hash
• debug_traceTransaction - Trace a single transaction
• debug_traceCall - Trace a call without creating a transaction
• eth_getBlockByHash - Get block by hash