debug_traceBlockByNumber | Ethereum

​

Parameters

• quantity or tag — the integer of a block encoded as hexadecimal or the string with:
  • latest — the most recent block in the blockchain and the current state of the blockchain at the most recent block. A chain reorganization is to be expected.
  • safe — the block that received justification from the beacon chain. Although this block could be involved in a chain reorganization, it would necessitate either a coordinated attack by the majority of validators or an instance of severe propagation latency.
  • finalized — the block accepted as canonical by more than 2/3 of the validators. A chain reorganization is extremely unlikely, and it would require at least 1/3 of the staked ETH to be burned.
  • earliest — the earliest available or genesis block
  • pending — the pending state and transactions block. The current state of transactions that have been broadcast to the network but have not yet been included in a block.

• tracer — an object identifying the type of tracer and its configuration:
  • 4byteTracer — tracer that captures the function signatures and call data sizes for all functions executed during a transaction, creating a map that links each selector and size combination to the number of times it occurred. This provides valuable information about the frequency and usage of each function within the transaction.
  • callTracer — tracer that captures information on all call frames executed during a transaction. The resulting nested list of call frames is organized into a tree structure that reflects the way the Ethereum Virtual Machine works and can be used for debugging and analysis purposes.
  • prestateTracer — tracer with two modes: prestate and diff, where the former returns the accounts needed to execute a transaction, and the latter returns the differences between the pre and post-states of the transaction. The tracer operates by re-executing the transaction and tracking every state change made, resulting in an object with the account addresses as keys and the corresponding trie leaves as values.
  • flatCallTracer — tracer that returns call traces in the flat, Parity-style format used by the trace_* namespace, as a flattened list of call frames rather than a nested tree.
  • muxTracer — tracer that runs several native tracers in a single pass, configured via a tracerConfig object keyed by tracer name, returning each tracer’s output under its own key.
  • erc7562Tracer — tracer that enforces the ERC-7562 account-abstraction validation rules, tracking opcode and storage access during the validation phase of an ERC-4337 user operation.

​

Response types

​

4byteTracer response

• object — the 4byteTracer traces object:
  • result — a map of the function signature, the call data size, and how many times the function was called.

​

callTracer response

• object — the callTracer traces object:
  • from — the address of the sender who initiated the transaction.
  • gas — the units of gas included in the transaction by the sender.
  • gasused — the total used gas by the call, encoded as hexadecimal.
  • to — the address of the recipient of the transaction if it was a transaction to an address. For contract creation transactions, this field is null.
  • input — the optional input data sent with the transaction, usually used to interact with smart contracts.
  • output — the return value of the call, encoded as a hexadecimal string.
  • error — an error message in case the execution failed.
  • revertReason — the reason why the transaction was reverted, returned by the smart contract if any.
  • calls — a list of sub-calls made by the contract during the call, each represented as a nested call frame object.

​

prestateTracer response

• object — the prestateTracer traces object:
• smart contract address — the address of the smart contract associated with the result.
• balance — the balance of the contract, expressed in Wei and encoded as a hexadecimal string.
• code — the bytecode of the contract, encoded as a hexadecimal string.
• nonce — the nonce of the account associated with the contract, represented as an unsigned integer.
• storage — a map of key-value pairs representing the storage slots of the contract. The keys and values are both encoded as hexadecimal strings.

​

debug_traceBlockByNumber code examples

const ethers = require("ethers");

// Create a ChainstackProvider instance for Ethereum mainnet
const chainstack = new ethers.ChainstackProvider("mainnet");

const traceBlockByNumber = async (block) => {
  // Specify the type of tracer: 4byteTracer, callTracer, prestateTracer, or muxTracer
  const tracer = { tracer: "callTracer" };
  const traces = await chainstack.send("debug_traceBlockByNumber", [
    block,
    tracer,
  ]);
  console.log(traces);
};

traceBlockByNumber("latest");

from web3 import Web3  
node_url = "CHAINSTACK_NODE_URL" 
web3 = Web3.HTTPProvider(node_url)

block = "latest"

# Specify the type of tracer: 4byteTracer, callTracer, prestateTracer, or muxTracer
tracer = { "tracer": 'callTracer' }
block_traces = web3.provider.make_request('debug_traceBlockByNumber', [block, tracer])
print(block_traces)

​

Use case

const ethers = require("ethers");

// Create a ChainstackProvider instance for Ethereum mainnet
const chainstack = new ethers.ChainstackProvider("mainnet");

async function getAverageGasUsed(block) {

    const tracer = { tracer: "callTracer" };
    const traceResult = await chainstack.send("debug_traceBlockByNumber", [
      block,
      tracer,
    ]);
    let totalGasUsed = 0;
    let transactionCount = 0;

    for (let obj of traceResult) {
      const gasUsed = obj.result.gasUsed;
      const decimalGas = parseInt(gasUsed, 16);
      totalGasUsed += decimalGas;
      transactionCount++;
    }

    const averageGasUsed = totalGasUsed / transactionCount;
    console.log(`Transaction in this block: ${transactionCount}`)
    console.log(`Average units of gas used per transaction: ${Math.round(averageGasUsed)}`);
    
}

getAverageGasUsed("latest");