Skip to content

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.

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 provenEthereumUnichain
debug_traceTransaction, debug_traceBlockByNumber, debug_traceBlockByHashUnder every tracer the trace methods runUnder callTracer, prestateTracer, and noopTracer
trace_block, trace_transactionYesYes
trace_replayBlockTransactions, trace_replayTransactionYesRefused, as the trace methods refuse them
debug_traceCall, trace_callYes, with state and block overridesRefused, as the trace methods refuse them
trace_filterFrom 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 names willow_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.

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 is blockHash.
  • parent: the parent block’s header. Its keccak256 must be the header’s parentHash, 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’s parentHash names.
  • transactions, receipts: every transaction and receipt of the block, in their EIP-2718 encodings, in block order. Together they must rebuild the header’s transactionsRoot and receiptsRoot.
  • 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"
},
…
]

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 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.

A verifier reports why a trace proof failed. The verifying client reports these as data.kind of WillowVerificationError:

KindWhat failed
header, wrong-block, wrong-chainThe header doesn’t hash to blockHash, or the block or chain is not the one asked for.
parentThe parent or an ancestor is not the header its successor links to.
transactions, receiptsThe transactions or receipts don’t rebuild their roots.
missing-readThe run read an account, slot, code, or block hash the proof doesn’t hold.
disagreesA transaction ran otherwise than its receipt records.
account, slot, code, historyA call’s witness doesn’t verify against the state root.
no-traceThe proof claims a trace for a call that is invalid at the block.
limits, too-largeThe witness, or the trace, is larger than one request may hold.
algorithmAn algorithm the verifier doesn’t know.

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:

ProofJSONGzipped
A whole Ethereum block of 244 to 281 transactions12.7 to 15.4 MB5.1 to 6.3 MB
An early transaction of an Ethereum block1.1 MB0.29 MB
A Unichain block of 1 to 10 transactions53 to 606 KB26 to 231 KB
A call’s trace on Ethereum96 to 103 KB34 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.