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)

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				// Many more opcode logs...
34			]
35		}
36		// Additional transaction traces...
37	]
38}

Using callTracer Format

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

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		// Additional call traces...
17	]
18}

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