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.

​

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");

​

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.