debug_traceBlockByNumber

The debug_traceBlockByNumber method returns a full trace of all invoked opcodes of all transactions included in the specified block, identified by its block number. This method provides detailed low-level execution information useful for debugging and analyzing transaction behavior.

Use Cases

• Debugging failed transactions in a specific block
• Analyzing smart contract execution flow
• Gas usage optimization and profiling
• Security auditing of deployed contracts
• Transaction behavior verification
• Understanding complex contract interactions
• Analyzing historical blocks by their number
• Monitoring transaction execution patterns
• Finding edge cases in contract design
• Verifying deterministic execution across nodes

Method Details

This method traces the execution of all transactions in a block, identified by its number, 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": {}
				}
				// Many more opcode logs...
			]
		}
		// Additional transaction traces...
	]
}

Using callTracer Format

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

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

Block Number Tag Options

The blockNumber parameter accepts several special tags:

• latest: Most recent block that has been confirmed by the network
• earliest: Genesis block (block 0)
• pending: Pending block with transactions in the mempool (not yet mined)

Custom Tracers

The debug_traceBlockByNumber method supports several built-in tracers:

• callTracer: Captures the call graph of each transaction execution.
• prestateTracer: Captures the pre-state of the contracts involved.
• 4byteTracer: Collects function selectors (first 4 bytes of calldata).
• noopTracer: Simply traces without collecting data (for performance testing).

Important Notes

• This method is computationally intensive and may take time to complete
• Requires debug APIs to be enabled on the Ethereum node
• Not all Ethereum clients support this method
• The response can be very large for blocks with complex transactions
• Consider using trace options to reduce response size if needed
• Specifying a block far in the past may require an archive node
• For regular block information without tracing, use eth_getBlockByNumber
• Different clients may expose different tracer options
• Custom tracers can significantly improve performance for specific analysis needs
• Historical traces might not be available beyond certain block ages on some nodes

See also

• debug_traceBlock - Trace transactions in a block using RLP-encoded block
• debug_traceBlockByHash - Trace transactions in a block using block hash
• debug_traceTransaction - Trace a single transaction by hash