trace_replayTransaction: Flat Traces, VM Traces and State Diffs

What trace_replayTransaction does

You choose what you get with the second parameter, an array of trace types. "trace" returns the flat action list. "stateDiff" returns, per touched address, the before and after value of balance, nonce, code and each storage slot. "vmTrace" returns the opcode-level execution. You can request any combination, and the ones you leave out come back as null, so asking for everything by reflex is the easiest way to make this call far more expensive than it needs to be.

The flat format is the real difference from the Geth family. Instead of a nested tree of frames, you get a list where each entry carries a traceAddress array describing its position in the call hierarchy: [] is the root, [0] its first child, [0, 1] the second child of that. Reconstructing a tree from those paths is mechanical, but it is not the same data shape, so a pipeline built on callTracer cannot consume these traces without a converter.

Client support splits along the same line. Erigon, Nethermind and Reth implement the trace namespace; Geth does not implement it at all and answers "method not found", offering only its own debug namespace. That is the first thing to check when this method fails, before looking at anything else.

Parameters

What it returns

An object with output (the transaction's return data), trace (the flat action list, each entry holding action, result, subtraces, traceAddress and type), stateDiff and vmTrace. Any type you did not request is null.

In stateDiff, each changed value is expressed as a transition object with the value before and after; slots the transaction only read are absent, and newly created entries are marked as such. This is the cleanest available answer to "what did this transaction change", and it is why the method exists despite costing more than the debug equivalents.

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "output": "0x0000000000000000000000000000000000000000000000000000000000000001",
    "vmTrace": null,
    "trace": [
      {
        "type": "call",
        "action": {
          "callType": "call",
          "from": "0xdc4239109ce3a991673d29b26d84d487ad2cb19b",
          "to": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
          "gas": "0x11c9d",
          "input": "0xa9059cbb...",
          "value": "0x0"
        },
        "result": { "gasUsed": "0xf328", "output": "0x…01" },
        "subtraces": 1,
        "traceAddress": []
      }
    ],
    "stateDiff": {
      "0xdc4239109ce3a991673d29b26d84d487ad2cb19b": {
        "balance": { "*": { "from": "0x1bc16d674ec80000", "to": "0x1bc0f8e0e3b5c8a1" } },
        "nonce": { "*": { "from": "0xa", "to": "0xb" } },
        "code": "=",
        "storage": {}
      }
    }
  }
}

Trimmed to one trace entry and one diffed account. In stateDiff, "=" means unchanged and "*" wraps a from/to transition; the sender's nonce increments and the balance drops by the fee. traceAddress [] marks the root call, and subtraces counts its direct children, here the proxy's delegatecall.

import { WebSocketProvider } from "ethers";

// trace_* needs Erigon, Nethermind or Reth; Geth does not implement it
const provider = new WebSocketProvider("ws://eth:8545");

const replay = await provider.send("trace_replayTransaction", [
  "0x1433cd18789195b1f14d55426174f0981ae3ee4256e30804a6d7e1fd286fe840",
  ["trace", "stateDiff"], // leave out vmTrace unless you truly need opcodes
]);

// flat traces carry their position instead of nesting
for (const t of replay.trace) {
  const depth = "  ".repeat(t.traceAddress.length);
  console.log(`${depth}${t.type} ${t.action.to ?? ""} gas=${t.result?.gasUsed}`);
}

// every account the transaction touched
console.log(Object.keys(replay.stateDiff));

Gotchas and common errors

What trace_replayTransaction costs on BLAZED.sh

trace_replayTransaction is one of three methods priced at 4 credits per call on BLAZED.sh rather than the standard 1, alongside trace_replayBlockTransactions and txpool_content. The response-size surcharge applies on top: over 100KB, responses add 50 credits per MB, which a trace-and-stateDiff replay rarely reaches and a vmTrace replay reaches immediately. Where the same answer is available from debug_traceTransaction, which costs 1 credit, the debug family is the cheaper route; pay the 4 when you specifically want flat traces or a state diff.

trace_replayTransaction: frequently asked questions