Trace proofs
willow_getTraceProof returns the proof behind a
trace method’s response. The proof never
carries the trace itself. It carries the block, or the call, and the state its
run reads, so a verifier runs the block or the call again in its own EVM and
writes the trace with the same tracers Willow’s trace methods use. The
rules for every proof method
apply: the block is always named, the server verifies the proof with the
verifier’s own code before sending it, and refusals match the trace method’s.
The verifying client calls this method for every trace request an app makes. This page is the method reference, for anyone writing their own verifier.
Request
Section titled “Request”willow_getTraceProof takes [method, params]: the trace method’s name and
its params, exactly as they would be sent to the trace method.
{"jsonrpc":"2.0","id":1,"method":"willow_getTraceProof","params":["debug_traceTransaction",["0x7cc4da7212bad41a6a595c331464cdf9e4e8352123e41b429829b75ff23e16ef",{"tracer":"callTracer"}]]}| Method proven | Ethereum | Unichain |
|---|---|---|
debug_traceTransaction, debug_traceBlockByNumber, debug_traceBlockByHash | Under every tracer the trace methods run | Under callTracer, prestateTracer, and noopTracer |
trace_block, trace_transaction | Yes | Yes |
trace_replayBlockTransactions, trace_replayTransaction | Yes | Refused, as the trace methods refuse them |
debug_traceCall, trace_call | Yes, with state and block overrides | Refused, as the trace methods refuse them |
trace_filter | From a trace_block proof of each block (see trace_filter) | The same |
- A request is first refused as the trace method refuses it, with the same code
and message. What a proof does not cover is then refused with
-32601, in a message that nameswillow_getTraceProof. - On chains other than Ethereum and Unichain, the method is refused with
-32601. - It requires a key whose plan includes state methods, as the trace methods do, and is not served on the public path.
- It is served at any block Willow has verified, including Ethereum blocks the light client hasn’t confirmed yet, since the verifier anchors the block itself.
A block’s or a transaction’s traces
Section titled “A block’s or a transaction’s traces”For debug_traceBlockByNumber, debug_traceBlockByHash, trace_block, and
trace_replayBlockTransactions, the proof covers the block the request names.
For debug_traceTransaction, trace_transaction, and
trace_replayTransaction, it covers the block that holds the transaction, and
the state the block’s run reads up to and including that transaction.
Request (every transaction of Unichain block 63,764,357):
{"jsonrpc":"2.0","id":1,"method":"willow_getTraceProof","params":["trace_block",["0x3ccf785"]]}Response (truncated):
{ "id": 1, "jsonrpc": "2.0", "result": { "chainId": "0x82", "blockNumber": "0x3ccf785", "blockHash": "0x337b08c95e76e1d2193b70ff57d2736efd437a76d7db90a37a9a8682d814217e", "header": "0xf90279a036e19db7f810507a3b450fbffff5259375736035f76c5c02fa82c8…", "parent": "0xf90278a007aa4fa4b82ecfff29d3b9866c433d9cc12268146efe4bc50be2bb…", "ancestors": [], "transactions": [ "0x7ef90106a09dcc88e1e39380c0aacb37bd57bd3fcea05c38398b573c30a2cd…", … 3 more ], "receipts": [ "0x7ef9010e0182b48ab901000000000000000000000000000000000000000000…", … 3 more ], "witness": { "nodes": [ "0xf901f1a0b5d80f73088bbd5ab5a3944377b069d2a5588eb3d42952a0881077…", … 412 more ], "codes": [ "0x60a0806040526004361015610012575f80fd5b5f3560e01c908162fdd58e14…", … 19 more ] }, "algorithm": "willow-trace-v1" }}header: the block header’s RLP encoding, whose keccak256 isblockHash.parent: the parent block’s header. Its keccak256 must be the header’sparentHash, and its state root is the state the block runs over.ancestors: the headers before the parent, newest first, back to the oldest block whose hash the run reads (BLOCKHASH). Each must be the block its successor’sparentHashnames.transactions,receipts: every transaction and receipt of the block, in their EIP-2718 encodings, in block order. Together they must rebuild the header’stransactionsRootandreceiptsRoot.witness.nodes: the state and storage trie nodes the run reads, each found by its hash from the parent’s state root.witness.codes: the contract code the run executes, each found by its hash.algorithm:willow-trace-v1, how the block is run and its traces written.
The verifier verifies the headers and their links, the transactions and receipts against their roots, and that the block is the one asked for, or the one that holds the transaction asked for. It then runs the block itself, in its own EVM (on Unichain, as op-reth runs it), strictly over the witness: any account, slot, code, or block hash the run reads that the proof doesn’t hold fails verification. Each transaction it runs must match its receipt. It writes the trace with the tracers Willow’s trace methods use, and returns it as the trace method does. For the request above, the first of 40 traces:
[ { "action": { "callType": "call", "from": "0xdeaddeaddeaddeaddeaddeaddeaddeaddead0001", "gas": "0xee9c8", "input": "0x3db6be2b000007d0000dbba00000000000000009000000006af616ff000000…", "to": "0x4200000000000000000000000000000000000015", "value": "0x0" }, "blockHash": "0x337b08c95e76e1d2193b70ff57d2736efd437a76d7db90a37a9a8682d814217e", "blockNumber": 63764357, "result": { "gasUsed": "0x5c12", "output": "0x" }, "subtraces": 1, "traceAddress": [], "transactionHash": "0x7cc4da7212bad41a6a595c331464cdf9e4e8352123e41b429829b75ff23e16ef", "transactionPosition": 0, "type": "call" }, …]A call’s traces
Section titled “A call’s traces”debug_traceCall and trace_call are proven on Ethereum. The proof is a
call proof: the
named block and the witness of the state the call reads, under the request’s
state and block overrides, which the proof never carries. The verifier runs the
call over the witness as eth_call runs it, with the overrides laid over the
proven state, and writes its trace with the same tracers.
Request (a USDC transfer, traced with callTracer and its logs):
{"jsonrpc":"2.0","id":1,"method":"willow_getTraceProof","params":["debug_traceCall",[{"from":"0x28c6c06298d514db089934071355e5743bf21d60","to":"0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48","gas":"0x1000000","data":"0xa9059cbb0000000000000000000000006c3f9e1a2b7d4c58e0f1a9b3d2c4e6f8a1b3c5d700000000000000000000000000000000000000000000000000000000000f4240"},"0x192d1d3",{"tracer":"callTracer","tracerConfig":{"withLog":true}}]]}Response (truncated):
{ "id": 1, "jsonrpc": "2.0", "result": { "chainId": "0x1", "blockNumber": "0x192d1d3", "blockHash": "0xf1443dbc28ad1e2111fff76c14988e611d834d69b4a37dab9456f102c8303b86", "header": "0xf90280a06c3625e25cc761f1aff61bc9bd477a936c18869ffc04f5fb6d9cdf…", "witness": { "accounts": [ { "address": "0x28c6c06298d514db089934071355e5743bf21d60", "accountProof": ["#0", "#1", … 7 more], "balance": "0xb37d832b5a119d8", "codeHash": "0xc5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470", "nonce": "0x120a00b", "storageHash": "0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421", "storageProof": [] }, … 2 more ], "nodes": [ "0xf90211a0f66af329adec0478450131815054cc1e33a761761808814565ed66…", … 2 more ], "codes": { "0xcdfb7d322961af3acae7a8f7ee8b69c205b36f576cc5b077f170c7eb8ecbe3ea": "0x608060405234801561001057600080fd5b506004361061036d5760003560e0…", "0xd80d4b7c890cb9d6a4893e6b52bc34b56b25335cb13716e0d1d31383e6b41505": "0x60806040526004361061006d576000357c0100000000000000000000000000…" } }, "algorithm": "willow-trace-v1" }}The trace the verifier writes (truncated):
{ "from": "0x28c6c06298d514db089934071355e5743bf21d60", "to": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", "type": "CALL", "gas": "0x1000000", "gasUsed": "0x83bd", "input": "0xa9059cbb0000000000000000000000006c3f9e1a2b7d4c58e0f1a9b3d2c4e6…", "output": "0x08c379a0000000000000000000000000000000000000000000000000000000…", "error": "execution reverted", "revertReason": "Blacklistable: account is blacklisted", "value": "0x0", "calls": [ { "from": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", "to": "0x43506849d7c04f9138d1a2050bbf3a0c054402dd", "type": "DELEGATECALL", … } ]}A call that is invalid at the block (for example, one whose fee cap is below the block’s base fee) has no trace: the trace method refuses it, and no proof is served for it.
trace_filter
Section titled “trace_filter”trace_filter is proven block by block. The verifier requests a trace_block
proof of each block in the filter’s range (at most 16, as for trace_filter
itself), verifies each, filters the traces as Willow’s trace_filter filters
them, and anchors the range from its newest block through the blocks’
parentHash links. A willow_getTraceProof request for trace_filter itself
is refused with -32601.
Verification failures
Section titled “Verification failures”A verifier reports why a trace proof failed. The
verifying client reports these as
data.kind of WillowVerificationError:
| Kind | What failed |
|---|---|
header, wrong-block, wrong-chain | The header doesn’t hash to blockHash, or the block or chain is not the one asked for. |
parent | The parent or an ancestor is not the header its successor links to. |
transactions, receipts | The transactions or receipts don’t rebuild their roots. |
missing-read | The run read an account, slot, code, or block hash the proof doesn’t hold. |
disagrees | A transaction ran otherwise than its receipt records. |
account, slot, code, history | A call’s witness doesn’t verify against the state root. |
no-trace | The proof claims a trace for a call that is invalid at the block. |
limits, too-large | The witness, or the trace, is larger than one request may hold. |
algorithm | An algorithm the verifier doesn’t know. |
Sizes and units
Section titled “Sizes and units”A trace proof carries the whole block’s transactions and receipts and the state its run reads, so it is larger than the trace method’s response. In testing:
| Proof | JSON | Gzipped |
|---|---|---|
| A whole Ethereum block of 244 to 281 transactions | 12.7 to 15.4 MB | 5.1 to 6.3 MB |
| An early transaction of an Ethereum block | 1.1 MB | 0.29 MB |
| A Unichain block of 1 to 10 transactions | 53 to 606 KB | 26 to 231 KB |
| A call’s trace on Ethereum | 96 to 103 KB | 34 to 38 KB |
In WebAssembly, the verifier ran a whole Ethereum block in about 0.3 to 0.5 seconds, and verified a call’s trace in about 7 milliseconds.
willow_getTraceProof costs what the trace methods cost: 6 units, 3 units for
each request made to a paid provider, or its size in units, whichever is most
(see Units and pricing). Its size usually decides. With
gzip, in testing, a whole Ethereum block’s proof was about 1,250 to 1,540
units, an early transaction’s about 71, a Unichain block’s 6 to 56, and a
call’s trace about 9.