debug_traceBlockByNumber: Trace Every Transaction in a Block

What debug_traceBlockByNumber does

The node loads the state of the parent block and replays every transaction in order with tracing hooks attached. Doing that once for the whole block is dramatically cheaper than issuing debug_traceTransaction for each transaction separately, because the expensive part, reconstructing and warming the state, happens once instead of two hundred times.

The options object is the same one debug_traceTransaction takes, and the same rules apply: name a tracer, or receive an opcode-level struct log for every transaction in the block. callTracer is the usual choice, with tracerConfig.onlyTopCall when you want the shape of the block rather than the interior of every call.

The response is an array in block order, one entry per transaction, each pairing the transaction hash with its trace result. A transaction whose trace failed carries an error instead, so a partial failure does not sink the whole response. Its siblings are debug_traceBlockByHash, which pins a specific block and is the reorg-safe choice, and the Parity-style trace_block and trace_replayBlockTransactions.

Parameters

What it returns

An array with one entry per transaction, in the order they were executed, each holding the transaction hash and the trace produced by your chosen tracer. Entries whose tracing failed carry an error field instead of a result, which is worth checking rather than assuming a uniform array.

Sizes are the defining characteristic. A busy mainnet block traced with callTracer runs to megabytes; the same block with the default struct logger is orders of magnitude larger and will usually hit a timeout before it finishes serializing.

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    {
      "txHash": "0x20f83f863231a8e1c97f14d1b2e9379d389c57d3bb82d265cd6e5d806378ba9b",
      "result": {
        "type": "CALL",
        "from": "0xca112ee75e517fdbad2a7450c65cdaab8256d9a2",
        "to": "0x3f2b113d180ecb1457e450b9efcac3df1dd29ad3",
        "gasUsed": "0x317fa",
        "input": "0x3c83980f...",
        "output": "0x"
      }
    },
    {
      "txHash": "0x2efde06bb1dcf26741f3a7c1385d5a62ad2554523322e9dd53f1635ba6add6d1",
      "result": { "type": "CALL", "gasUsed": "0x8238e", "…": "…" }
    }
  ]
}

Two entries out of 209, with onlyTopCall keeping each one to a single frame. Drop that option and every entry grows a nested calls tree; the block goes from a readable summary to megabytes of JSON.

import { WebSocketProvider } from "ethers";

// inside a BLAZED.sh container the node is one local socket away
const provider = new WebSocketProvider("ws://eth:8545");

// trace the head block: one request instead of one per transaction
const head = await provider.getBlockNumber();
const traces = await provider.send("debug_traceBlockByNumber", [
  "0x" + head.toString(16),
  { tracer: "callTracer", timeout: "60s" },
]);

const failed = traces.filter((t) => t.result?.error);
console.log(traces.length, "transactions,", failed.length, "reverted");

// walk one call tree
const count = (frame) => 1 + (frame.calls ?? []).reduce((n, c) => n + count(c), 0);
console.log("frames in tx 0:", count(traces[0].result));

Gotchas and common errors

What debug_traceBlockByNumber costs on BLAZED.sh

debug_traceBlockByNumber costs 1 credit per call on BLAZED.sh, the same as any standard method; the 4-credit rate is reserved for txpool_content and the two trace_replay methods. What makes this call expensive is the size surcharge: responses over 100KB add 50 credits per MB, and a whole-block callTracer response is measured in megabytes, so this is the method where that rule genuinely bites. onlyTopCall is not just a speed knob, it is a billing one. It is also the workload where a co-located node matters most, since multi-megabyte responses over a local socket never touch the public internet.

debug_traceBlockByNumber: frequently asked questions