debug_traceBlockByNumber

The debug_traceBlockByNumber method returns the traces of all transactions in a block identified by block number. Similar to debug_traceBlockByHash but uses block number for identification, this method is particularly useful when working with sequential block analysis or when you know the block height but not its hash.

This method provides comprehensive transaction trace data for all transactions within the specified block, including detailed execution information such as opcode-level traces, gas consumption, internal calls, and state changes. It's essential for debugging multiple transactions in a block, analyzing block-level gas usage patterns, identifying failed transactions, and building comprehensive blockchain analytics tools that process blocks sequentially.

This method is available only on the full archive node.

Parameters

parameter	type	description
blockNumber	string (required)	Block number in hex format (e.g., '0x10d4f') or one of the string tags: 'latest' for the most recent block, 'earliest' for the genesis block, or 'pending' for pending state/transactions
traceConfig	object (optional)	Configuration object to customize the trace output. Optional fields: 'tracer' (string, e.g., 'callTracer' or 'prestateTracer'), 'timeout' (string, e.g., '10s'), 'disableStorage' (boolean), 'disableMemory' (boolean), 'disableStack' (boolean), 'enableMemory' (boolean), 'enableReturnData' (boolean)

Return Object

The method returns an array of trace objects for all transactions in the block:

result - array: An array where each element corresponds to a transaction in the block. Each element contains a trace object with the structure determined by the tracer configuration. With the default tracer, each trace includes gas used, failed status, return value, and an array of structLogs showing opcode execution. With 'callTracer', each trace shows the call tree structure with type, from, to, value, gas, gasUsed, input, output, and nested calls array.

Request Example

Request

Response Example

Response