BNB Smart Chain · debug

debug_traceBlockByNumber

Replays a block and returns traces for all transactions.

Replays the block identified by the given number and returns a trace for every transaction in the block. The parent block must be present in the client's database. The genesis block (block 0) cannot be traced because it has no parent state to replay from; clients MUST return an error for this input. When no tracer is specified (or the tracer field is absent), the opcode (struct) logger is used and each entry conforms to OpcodeBlockTransactionTrace, whose result field conforms to OpcodeTransactionTrace. When a named tracer is specified via the tracer field in TraceConfig (e.g. "callTracer", "prestateTracer"), the result field of each entry contains tracer-specific output. Defining the output schemas of named tracers is outside the scope of this specification. The response is an array ordered by transaction index within the block. Each entry includes the transaction hash paired with its trace result. If a timeout is configured and reached before tracing completes, the client MUST return an error; no partial results are returned. Clients that do not support execution timeouts MAY ignore the timeout field.

Parameters

Block required

Schema

{
  "title": "Block number or tag",
  "oneOf": [
    {
      "type": "string",
      "title": "Block number",
      "pattern": "^0x(0|[1-9a-f][0-9a-f]*)$"
    },
    {
      "type": "string",
      "title": "Block tag",
      "description": "`earliest`: The lowest numbered block the client has available; `finalized`: The most recent crypto-economically secure block, cannot be re-orged outside of manual intervention driven by community coordination; `safe`: The most recent block that is safe from re-orgs under honest majority and certain synchronicity assumptions; `latest`: The most recent block in the canonical chain observed by the client, this block may be re-orged out of the canonical chain even under healthy/normal conditions; `pending`: A sample next block built by the client on top of `latest` and containing the set of transactions usually taken from local mempool. Before the merge transition is finalized, any call querying for `finalized` or `safe` block MUST be responded to with `-39001: Unknown block` error",
      "enum": [
        "earliest",
        "finalized",
        "safe",
        "latest",
        "pending"
      ]
    }
  ]
}

TraceConfig

Schema

{
  "type": "object",
  "title": "Trace configuration",
  "description": "Configuration object accepted by debug_traceBlockByNumber and debug_traceTransaction.\nWhen the tracer field is absent or empty, the opcode (struct) logger is used and the result conforms to OpcodeTransactionTrace. The fields enableMemory, disableStack, disableStorage, enableReturnData, and limit only apply to the opcode logger and are ignored when a named tracer is set.\nWhen the tracer field is set to a named tracer (e.g. \"callTracer\", \"prestateTracer\"), the result format is tracer-specific. Defining the output schemas of named tracers is outside the scope of this specification.",
  "properties": {
    "debug": {
      "type": "boolean",
      "title": "debug print",
      "description": "Opcode logger only. When true, the client may print the trace output to its internal log during execution. Has no effect on the JSON-RPC response. Ignored when tracer is set. Default: false."
    },
    "disableStack": {
      "type": "boolean",
      "title": "disable stack capture",
      "description": "Opcode logger only. Setting to true disables stack capture in structLogs. When true, the stack field is omitted from each StructLog entry. Ignored when tracer is set. Default: false."
    },
    "disableStorage": {
      "type": "boolean",
      "title": "disable storage capture",
      "description": "Opcode logger only. Setting to true disables storage capture in structLogs. When true, the storage field is omitted from each StructLog entry. Ignored when tracer is set. Default: false."
    },
    "enableMemory": {
      "type": "boolean",
      "title": "enable memory capture",
      "description": "Opcode logger only. Setting to true enables memory capture in structLogs. When false (default), the memory field is omitted from each StructLog entry. Ignored when tracer is set. Default: false."
    },
    "enableReturnData": {
      "type": "boolean",
      "title": "enable return data capture",
      "description": "Opcode logger only. Setting to true enables return data capture in structLogs. When false (default), the returnData field is omitted from each StructLog entry. Ignored when tracer is set. Default: false."
    },
    "limit": {
      "type": "integer",
      "title": "step limit",
      "description": "Opcode logger only. Maximum number of opcode steps to capture. Zero means no limit. When the limit is reached, execution continues but no further StructLog entries are recorded. Ignored when tracer is set. Default: 0 (unlimited)."
    },
    "timeout": {
      "type": "string",
      "title": "execution timeout",
      "description": "Optional duration string specifying a timeout for trace execution. Clients that do not support execution timeouts (e.g. streaming implementations) MAY ignore this field. When supported and the timeout is reached, the client MUST return an error; no partial results are returned. Accepts Go duration strings (e.g. \"5s\", \"300ms\", \"2m\")."
    },
    "tracer": {
      "type": "string",
      "title": "tracer name",
      "description": "The name of a built-in or custom tracer to use. When absent or empty, the opcode (struct) logger is used.\nExample built-in tracer names in go-ethereum include: 4byteTracer, callTracer, prestateTracer, noopTracer, bigramTracer, evmdisTracer, opcountTracer, trigramTracer, unigramTracer.\nClients may support different sets of named tracers.\nCustom JavaScript tracers may also be supplied as an expression string."
    },
    "tracerConfig": {
      "type": "object",
      "title": "tracer configuration",
      "description": "An optional tracer-specific configuration object passed to the named tracer. Only applicable when the tracer field is set. The fields accepted here depend on the named tracer in use."
    }
  }
}

Result

Block trace

Schema

{
  "type": "array",
  "title": "Array of per-transaction traces",
  "description": "An array of trace entries ordered by transaction index within the block. When no named tracer is set, each entry conforms to OpcodeBlockTransactionTrace. When a named tracer is set, the result field of each entry contains tracer-specific output not defined by this specification, but the txHash field is always present.",
  "items": {
    "anyOf": [
      {
        "type": "object",
        "title": "Opcode tracer entry",
        "description": "Returned when no named tracer is specified.",
        "properties": {
          "result": {
            "type": "object",
            "title": "opcode transaction trace",
            "description": "The opcode trace for this transaction.",
            "properties": {
              "failed": {
                "type": "boolean",
                "title": "failed",
                "description": "Whether the transaction execution failed (reverted or ran out of gas)."
              },
              "gas": {
                "type": "integer",
                "title": "gas used",
                "description": "Total amount of gas consumed by the transaction."
              },
              "returnValue": {
                "type": "string",
                "title": "return value",
                "description": "The data returned by the transaction. 0x-prefixed hex-encoded bytes. MUST be \"0x\" (not an empty string) when no data was returned.",
                "pattern": "^0x[0-9a-f]*$"
              },
              "structLogs": {
                "type": "array",
                "title": "opcode execution logs",
                "description": "The ordered sequence of opcode execution steps. Will be empty for simple ETH transfers between externally owned accounts that execute no EVM code.",
                "items": {
                  "type": "object",
                  "title": "Opcode execution log entry",
                  "description": "A single step in the EVM execution trace produced by the opcode (struct) logger. One entry is emitted per opcode executed.",
                  "properties": {
                    "depth": {
                      "type": "integer",
                      "title": "call depth",
                      "description": "The call stack depth at this execution step. Starts at 1 for the outermost call."
                    },
                    "error": {
                      "type": "string",
                      "title": "execution error",
                      "description": "The error encountered during execution of this opcode, if any. This field MUST be absent when no error occurred. Clients MUST NOT include this field as null or as an empty string when there is no error."
                    },
                    "gas": {
                      "type": "integer",
                      "title": "remaining gas",
                      "description": "The amount of gas remaining before executing this opcode."
                    },
                    "gasCost": {
                      "type": "integer",
                      "title": "gas cost",
                      "description": "The gas cost computed for this opcode step — the amount that will be deducted from the remaining gas assuming successful execution. Includes dynamic costs such as memory expansion and storage access charges (e.g. cold vs. warm SLOAD/SSTORE)."
                    },
                    "memory": {
                      "type": "array",
                      "title": "EVM memory",
                      "description": "The contents of EVM memory at this step, divided into 32-byte chunks. Each element is a 0x-prefixed, zero-padded 32-byte hex word representing a consecutive 32-byte memory slot starting at offset (index * 32). This field is absent (not null) when enableMemory is false.",
                      "items": {
                        "type": "unknown"
                      }
                    },
                    "op": {
                      "type": "string",
                      "title": "opcode name",
                      "description": "The name of the EVM opcode executed at this step (e.g. \"PUSH1\", \"SSTORE\")."
                    },
                    "pc": {
                      "type": "integer",
                      "title": "program counter",
                      "description": "The program counter position of this opcode in the contract bytecode."
                    },
                    "refund": {
                      "type": "integer",
                      "title": "gas refund counter",
                      "description": "The accumulated gas refund counter at this execution step. Clients MUST include this field at every step when it is non-zero. Clients SHOULD include this field at every step even when zero."
                    },
                    "returnData": {
                      "type": "string",
                      "title": "return data",
                      "description": "The return data from the most recent call at this step. This field is absent when enableReturnData is false.",
                      "pattern": "^0x[0-9a-f]*$"
                    },
                    "stack": {
                      "type": "array",
                      "title": "EVM stack",
                      "description": "The contents of the EVM stack at this step, ordered from bottom (index 0) to top (last element). Each value is a 0x-prefixed uint256 quantity. This field is absent when disableStack is true.",
                      "items": {
                        "type": "unknown"
                      }
                    },
                    "storage": {
                      "type": "object",
                      "title": "contract storage",
                      "description": "A cumulative snapshot of all storage slots accessed or modified by the current contract up to and including this step. Keys are 0x-prefixed, zero-padded 32-byte storage slot indices; values are the 32-byte stored values reflecting the post-execution state of the opcode at this step (i.e., for SSTORE, the value reflects the new value just written).\nThis field is only populated at SLOAD and SSTORE opcodes. At all other opcodes, this field MUST be absent (not an empty object). This field is absent when disableStorage is true."
                    }
                  },
                  "required": [
                    "pc",
                    "op",
                    "gas",
                    "gasCost",
                    "depth"
                  ]
                }
              }
            },
            "required": [
              "gas",
              "failed",
              "returnValue",
              "structLogs"
            ]
          },
          "txHash": {
            "type": "string",
            "title": "transaction hash",
            "description": "The hash of the transaction this trace entry corresponds to.",
            "pattern": "^0x[0-9a-f]{64}$"
          }
        },
        "required": [
          "txHash",
          "result"
        ]
      },
      {
        "type": "object",
        "title": "Named tracer entry",
        "description": "Returned when a named tracer is specified. The result field contains tracer-specific output not defined by this specification.",
        "properties": {
          "result": {
            "description": "Named tracer output. The schema is unspecified and may be any valid JSON value."
          },
          "txHash": {
            "type": "string",
            "title": "32 byte hex value",
            "pattern": "^0x[0-9a-f]{64}$"
          }
        },
        "required": [
          "txHash",
          "result"
        ]
      }
    ]
  }
}

Example request

Endpoint: https://your-bsc-node.azxa.io

JSON-RPC

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "debug_traceBlockByNumber",
  "params": [
    "0x3",
    {
      "disableStack": false,
      "disableStorage": false,
      "enableMemory": false,
      "enableReturnData": false
    }
  ]
}

Example response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    {
      "result": {
        "failed": false,
        "gas": 26916,
        "returnValue": "0x",
        "structLogs": [
          {
            "depth": "…",
            "gas": "…",
            "gasCost": "…",
            "op": "…",
            "pc": "…",
            "stack": "…"
          },
          {
            "depth": "…",
            "gas": "…",
            "gasCost": "…",
            "op": "…",
            "pc": "…",
            "stack": "…"
          },
          {
            "depth": "…",
            "gas": "…",
            "gasCost": "…",
            "op": "…",
            "pc": "…",
            "stack": "…"
          }
        ]
      },
      "txHash": "0xdd8cf045113754c306ba9ac8ac8786235e33bc5c087678084ef260a2a583f127"
    }
  ]
}

Test fixture

Fixture: trace-block-invalid-number

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "debug_traceBlockByNumber",
  "params": [
    "3"
  ]
}

Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "invalid argument 0: hex string without 0x prefix"
  }
}

cURL

curl -X POST https://your-bsc-node.azxa.io \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"debug_traceBlockByNumber","params":["0x3",{"disableStack":false,"disableStorage":false,"enableMemory":false,"enableReturnData":false}]}'