debug_traceCall: Trace a Transaction You Never Sent

What debug_traceCall does

The mechanics are eth_call's. State changes are discarded, no gas is paid, and the call runs as whatever from address you give it. What changes is the output: instead of the return data, you get whatever the tracer you named produces, so a callTracer run returns the nested tree of internal calls with per-frame gas and revert reasons.

The two override objects are what make the method powerful. stateOverrides patches balances, nonces, code and individual storage slots for the duration of the call, so you can simulate a swap as if an approval already existed or as if your address held tokens it does not. blockOverrides patches the environment itself: block number, timestamp, base fee, coinbase. Together they let you trace a transaction against a world that does not exist yet, which is exactly what a searcher needs before committing to a bundle.

Compared with eth_estimateGas or a plain eth_call, this is the method that tells you why. A call that returns 0x, a swap that reverts with an unrecognised selector, a router that silently takes a different path than you expected: all of them become obvious the moment you can see the call tree instead of the final return value.

Parameters

What it returns

Whatever the chosen tracer emits, in the same shape debug_traceTransaction returns. callTracer gives one nested frame per call with type, from, to, value, gas, gasUsed, input, output and a calls array, plus error and revertReason on failing frames. prestateTracer gives the state the call read, or with diffMode the state it would have changed.

With no tracer named you get the opcode-level struct logger, which for anything but a trivial call is an enormous response. Naming a tracer is effectively mandatory.

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "type": "CALL",
    "from": "0x0000000000000000000000000000000000000000",
    "to": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    "value": "0x0",
    "gas": "0x2faf080",
    "gasUsed": "0x2b8c",
    "input": "0x70a08231000000000000000000000000d8da6bf26964af9d7eed9e03e53415d37aa96045",
    "output": "0x00000000000000000000000000000000000000000000000000000000023781bc",
    "calls": [
      {
        "type": "DELEGATECALL",
        "from": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
        "to": "0x43506849d7c04f9138d1a2050bbf3a0c054402dd",
        "gasUsed": "0x1f9a",
        "input": "0x70a08231000000000000000000000000d8da6bf26964af9d7eed9e03e53415d37aa96045",
        "output": "0x00000000000000000000000000000000000000000000000000000000023781bc"
      }
    ]
  }
}

A balanceOf call traced with callTracer, gas figures illustrative. The child frame is the giveaway that USDC is a proxy: the token address delegates to its implementation contract, something a plain eth_call would never have shown you.

import { WebSocketProvider } from "ethers";

// inside a BLAZED.sh container the node is one local socket away
const provider = new WebSocketProvider("ws://eth:8545");

const trace = await provider.send("debug_traceCall", [
  {
    from: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    to: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    data: "0xa9059cbb" + "…", // transfer(address,uint256) calldata
  },
  "latest",
  {
    tracer: "callTracer",
    tracerConfig: { withLog: true },
    // pretend the sender is funded, without funding it
    stateOverrides: {
      "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045": { balance: "0xde0b6b3a7640000" },
    },
  },
]);

console.log(trace.error ?? "ok", trace.calls?.length ?? 0, "internal calls");

Gotchas and common errors

What debug_traceCall costs on BLAZED.sh

debug_traceCall costs 1 credit per call on BLAZED.sh, the same as a plain eth_call, and the same as debug_traceTransaction; only the Parity-style replay methods carry the 4-credit rate. The variable that moves your bill is response size, since anything over 100KB adds 50 credits per MB, and an untraced-by-default struct log is the one shape that reliably crosses it. Keep a named tracer on every request and the surcharge stays theoretical. What co-location buys here is the round-trip: pre-flight simulation only helps if the answer arrives while the opportunity is still there, which is what a sub-10ms local call gives you.

debug_traceCall: frequently asked questions