> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chainstack.com/llms.txt
> Use this file to discover all available pages before exploring further.
# debug_traceBlockByHash | Ethereum
> Ethereum API method that traces the execution of a block. debug_traceBlockByHash JSON-RPC method available on the Ethereum blockchain via Chainstack.
Ethereum API method that traces the execution of a block. This method can be used to debug and analyze smart contracts and transactions on the Ethereum 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](/docs/debug-and-trace-apis#ethereum) with the debug and trace API methods enabled.
## 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.
* `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_traceBlockByHash` code examples
Learn more about the `ChainstackProvider` in `ethers.js`: [ethers ChainstackProvider Documentation](/reference/ethersjs-chainstackprovider).
```javascript ethers.js theme={"system"}
const ethers = require("ethers");
// Create a ChainstackProvider instance for Ethereum mainnet
const chainstack = new ethers.ChainstackProvider("mainnet");
const traceBlockByHash = async (blockHash) => {
// Specify the type of tracer: 4byteTracer, callTracer, prestateTracer, or muxTracer
const tracer = { tracer: "4byteTracer" };
const traces = await chainstack.send("debug_traceBlockByHash", [
blockHash,
tracer,
]);
console.log(traces);
};
traceBlockByHash(
"0x4725335feac695de65deb8662235f52692522d4f623a81468cc6479b43dc9782"
);
```
```python web3.py theme={"system"}
from web3 import Web3
node_url = "CHAINSTACK_NODE_URL"
web3 = Web3.HTTPProvider(node_url)
block_hash = "0x4725335feac695de65deb8662235f52692522d4f623a81468cc6479b43dc9782"
# Specify the type of tracer: 4byteTracer, callTracer, prestateTracer, or muxTracer
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.
The following is an implementation of this logic using ethers.js:
```javascript index.js theme={"system"}
const ethers = require("ethers");
// Create a ChainstackProvider instance for Ethereum mainnet
const chainstack = new ethers.ChainstackProvider("mainnet");
async function traceTransferFunction(blockHash) {
try {
// Specify the type of tracer: 4byteTracer, callTracer, prestateTracer, or muxTracer
const tracer = { tracer: "4byteTracer" };
const response = await chainstack.send("debug_traceBlockByHash", [
blockHash,
tracer,
]);
let sum = 0;
for (let obj of response) {
for (let key in obj.result) {
const signature = key.split('-')[0];
// Look for transfer function signatures
if (signature === "0xa9059cbb") {
const timesCalled = obj.result[key]
sum += timesCalled
}
}
}
console.log(`In this block the transfer function was called ${sum} times!`)
} catch (err) {
console.error(`Error in traceBlockByHash: ${err.message}`);
}
}
traceTransferFunction("0x4725335feac695de65deb8662235f52692522d4f623a81468cc6479b43dc9782");
```
This code calls the `debug_traceBlockByHash` method directly through the provider's `send` method to trace a block, since ethers.js does not expose a dedicated helper for it. The call uses the `4byteTracer` to identify the functions called in the block.
Then, the `traceTransferFunction` function is defined, which takes a block hash as an argument. This function sends the `debug_traceBlockByHash` request with the provided block hash and uses a loop to iterate over the results.
Inside the loop, the function checks for the `transfer` function from the ERC-20 standard with signature `0xa9059cbb` and counts how many times it was called in that block by adding up the times it was called in each trace.
Finally, the function logs the number of times the transfer function was called in that block. The code also has error handling in case anything goes wrong with the tracing process.
## OpenAPI
````yaml openapi/ethereum_node_api/debug_and_trace/debug_traceBlockByHash.json POST /0a9d79d93fb2f4a4b1e04695da2b77a7
openapi: 3.0.0
info:
title: Polygon Node API
version: 1.0.0
description: This is an API for interacting with a Chainstack node.
servers:
- url: https://nd-422-757-666.p2pify.com
security: []
paths:
/0a9d79d93fb2f4a4b1e04695da2b77a7:
post:
tags:
- upload
summary: debug_traceBlockByHash
operationId: traceBlockByHash
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
id:
type: integer
default: 1
jsonrpc:
type: string
default: '2.0'
method:
type: string
default: debug_traceBlockByHash
params:
type: array
items:
anyOf:
- type: string
title: Block Hash
description: The block hash.
- type: object
title: Tracer type
properties:
tracer:
type: string
description: The type of tracer.
default:
- >-
0x66103840578be3bc9c865e0961c4a4de31b5df7a45dcd13ffe2679ff9c7315d8
- tracer: 4byteTracer
responses:
'200':
description: The block traces.
content:
application/json:
schema:
type: object
properties:
jsonrpc:
type: string
id:
type: integer
result:
type: object
````