debug_traceBlockByHash | BNB Chain

BNB API method that traces the execution of a block. This method can be used to debug and analyze smart contracts and transactions on the BNB blockchain. It provides a detailed trace of the execution of a block, including information on all the transactions and calls that interacted with the block, as well as the gas used, memory, storage operations, and other performance metrics for each operation.

📘

Learn how to deploy a node with the debug and trace API methods enabled.

👍

Get you own node endpoint today

Start for free and get your app to production levels immediately. No credit card required.

You can sign up with your GitHub, X, Google, or Microsoft account.

Parameters

• hash — the hash of the block to be traced.
• 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.

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_traceBlockByHash code examples

const { Web3, Web3PluginBase } = require('web3');
const NODE_URL = "CHAINSTACK_NODE_URL";
const web3 = new Web3(NODE_URL);

// Define the TraceBlockPlugin class
class TraceBlockPlugin extends Web3PluginBase {
    pluginNamespace = 'trace';

    async traceBlockByHash(blockHash, tracer) {
        return this.requestManager.send({
            method: 'debug_traceBlockByHash',
            params: [blockHash, tracer],
        });
    }
}

// Register the plugin
web3.registerPlugin(new TraceBlockPlugin());

// Function to trace block by hash using the custom plugin
async function traceBlockByHash(blockHash) {
    const tracer = { tracer: '4byteTracer' }; // Or any other tracer you want to use
    try {
        const result = await web3.trace.traceBlockByHash(blockHash, tracer);
        console.log(result);
    } catch (error) {
        console.error("Error tracing block by hash:", error);
    }
}

// Call the function with a specific block hash
traceBlockByHash("0x0e77e2cf5a6999f616b56f1378b6c7b127b5a4e20cb2e12611d808af0979dacf");

const ethers = require('ethers');
const NODE_URL = "CHAINSTACK_NODE_URL";
const provider = new ethers.JsonRpcProvider(NODE_URL);

const traceBlockByHash = async (blockHash) => {

  // Specify the type of tracer: 4byteTracer, callTracer, or prestateTracer
  const tracer = { tracer: '4byteTracer' };
  const traces = await provider.send("debug_traceBlockByHash", [blockHash, tracer]);
  console.log(traces);
};

traceBlockByHash("0x0e77e2cf5a6999f616b56f1378b6c7b127b5a4e20cb2e12611d808af0979dacf")

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

block_hash = "0x0e77e2cf5a6999f616b56f1378b6c7b127b5a4e20cb2e12611d808af0979dacf"

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

Use case

One practical use case for debug_traceBlockByHash with the 4byteTracer tracer would be for auditing or analysis purposes of a blockchain.

For example, if there are token contracts on the blockchain and the transfer function of these contracts is used to send tokens between users, a developer could use the debug_traceBlockByHash method with the 4byteTracer tracer to trace the transactions in a given block and count how many times the transfer function was called.

Try the debug_traceBlockByHash RPC method yourself