Block, state, and fee proofs
These methods return the proofs behind the standard methods that log,
transaction, and receipt proofs don’t cover: blocks, account state, calls, gas
estimates, and fees. Each result is self-sufficient, so a verifier builds the
standard response from the proven bytes alone. The block is then tied to
Ethereum, or on BNB Smart Chain to its validators, with
willow_getBlockAnchor. Traces are proven by willow_getTraceProof, described
in Trace proofs.
The verifying client calls these methods for every request an app makes and verifies the responses. This page is the method reference, for anyone writing their own verifier.
| Method | Params | Proves | Chains |
|---|---|---|---|
willow_getBlockProof | A block | eth_getBlockByNumber and eth_getBlockByHash, with hashes or full transactions, and eth_getBlockTransactionCountByNumber / ByHash | Every chain |
willow_getStateProof | An address, storage keys, a block, and {"code": bool} | eth_getBalance, eth_getTransactionCount, eth_getCode, eth_getStorageAt, and eth_getProof | The chains with state methods |
willow_getCallProof | A call object, a block, and optional state and block overrides | eth_call | Ethereum, Unichain, Robinhood Chain |
willow_getEstimateGasProof | A call object, a block, and optional state and block overrides | eth_estimateGas | Ethereum, Unichain, Robinhood Chain |
willow_getFeeProof | A block | eth_gasPrice, eth_maxPriorityFeePerGas, and eth_blobBaseFee | Ethereum, Base, OP Mainnet, Unichain, Ink, Arbitrum One, Robinhood Chain |
willow_getFeeHistoryProof | A block count, the newest block, and reward percentiles | eth_feeHistory | As willow_getFeeProof |
willow_getBlockAnchor | A block number, latest, or finalized (Ethereum and BNB Smart Chain) | The block’s hash, as Ethereum, or BNB Smart Chain’s validators, attest it | Every chain |
State, call, and estimate proofs require a key whose plan includes
state methods, as the standard state methods do,
and are not served on the public path. Block, fee, and fee-history proofs and
block anchors are also served without a key, on
https://api.willow.tech/v1/rpc/{chainId}/public.
Rules for every proof method
Section titled “Rules for every proof method”- The block is always named. Every result carries
chainIdandblockNumber(hexadecimal),blockHash, andheader, the block header’s RLP encoding. A verifier requires that the keccak256 ofheaderisblockHash, that the header decodes and carries that number, that the chain is the one asked for, and that the block is the one the request named, by number or by hash. - The block parameter takes a hexadecimal number, a tag, a block hash, or
an EIP-1898 object (
{"blockHash": …}or{"blockNumber": …}), except forwillow_getBlockAnchor, whose forms are below. Naming the block by hash means a reorg can’t put another block in its place, and the verifying client does so for every block it has already resolved. - Any verified block. On Ethereum, the proof methods are served at any block Willow has verified, including blocks the light client hasn’t confirmed yet, where the standard state methods are refused. The verifier anchors the block itself, so waiting would add nothing.
- Verified before sending. Willow’s server verifies every proof with the verifier’s own code before sending it, so a provider’s bad data is refused rather than passed on.
- Refusals match the standard method. A proof method is refused with the
same code and message as its standard method, so a router treats both the
same way. A proof method refused as unsupported on a chain (for example
willow_getCallProofon a chain where Willow does not execute calls) names itself in its-32601message. - Encoding. Binary data is
0xhex. Large responses are gzipped for requests that sendAccept-Encoding: gzip. - Versioned algorithms. A result that depends on a published algorithm
names it:
"formula": "willow-fee-v1","algorithm": "geth-v1.17.10-estimate"or"nitro-v3.12.2-estimate", or"algorithm": "willow-trace-v1". A verifier refuses a name it doesn’t know.
willow_getBlockProof
Section titled “willow_getBlockProof”Takes one block parameter, as eth_getBlockByNumber or eth_getBlockByHash
does, and returns the block’s header and every transaction. The same proof
serves the block with transaction hashes (false) and with full transactions
(true).
Request:
{"jsonrpc":"2.0","id":1,"method":"willow_getBlockProof","params":[{"blockHash":"0x2afce59c8f52e3f7ec60a9a0e57c080a835333de8a68283314bab946464bee16"}]}Response (truncated; an Ethereum block with 116 transactions):
{ "id": 1, "jsonrpc": "2.0", "result": { "blockHash": "0x2afce59c8f52e3f7ec60a9a0e57c080a835333de8a68283314bab946464bee16", "blockNumber": "0x192b3d7", "chainId": "0x1", "header": "0xf90286a0fdd9210c4e90db69e32d664c1cf4ec18c67f482768374025bd2d9959…", "transactions": [ "0x02f8b10103849502f900850134f92a7c8301026a9418084fba666a33d37592fa…", "0x02f8b201831ab5fe84861c4680848e2d83e182f02794a0b86991c6218b36c1d1…", … 114 more ], "withdrawals": "0xf90230e28408ec505b8309c611948e609ac80f4324e499a6efd24f221a2caa86…" }}transactions: every transaction’s consensus bytes (its EIP-2718 encoding), in block order. Together they must rebuild the header’stransactionsRoot, so none can be added, dropped, changed, or reordered.withdrawals: the block’s withdrawals as one RLP list, present when the header has awithdrawalsRoot. On Ethereum they must rebuildwithdrawalsRoot. On the OP Stack chains the list must be empty (0xc0), since from Isthmus theirwithdrawalsRootis the L2ToL1MessagePasser’s storage root.uncles: the uncle headers’ RLP encodings, in order, present when the block has uncles. Their RLP list must hash to the header’ssha3Uncles.receiptProofs(OP Stack chains): a receipt proof for each deposit transaction, in the form of transaction and receipt proofs. A deposit’snonceanddepositReceiptVersionare read from its receipt.unproven: present only for a block from before the Merge whose uncle headers Willow doesn’t hold. It lists the fields this proof can’t cover,sizeanduncles, and the verifier leaves them out of the block.
A Base block, with its deposits’ receipt proofs:
{ "id": 1, "jsonrpc": "2.0", "result": { "blockHash": "0x8c07cbc2061ddf440e67d449647978c22b7f44b8697db853eb9eec4d43907f6a", "blockNumber": "0x3574133", "chainId": "0x2105", "header": "0xf90279a0557f82a795b5e4fc9426590a6dc50c45685dd665286ee7951d52528a…", "receiptProofs": [ { "index": "0x0", "proof": [ "0xf851a04473f3b933afc6313a7a153b9475a89fe1bd39a26d1272688a1cb5ea25…", "0xf9011630b901127ef9010e0182b48ab901000000000000000000000000000000…" ], "value": "0x7ef9010e0182b48ab90100000000000000000000000000000000000000000000…" }, { "index": "0x1", "proof": [ "0xf851a04473f3b933afc6313a7a153b9475a89fe1bd39a26d1272688a1cb5ea25…", … 2 more ], "value": "0x7ef9010f018301306fb901000000000000000000000000000000000000000000…" } ], "transactions": [ "0x7ef90106a06ea29b5fc41c66af380be2adc0f7ac186831201ec1513a8ff39ff8…", … 6 more ], "withdrawals": "0xc0" }}Ethereum block 1,500,000, from a server without its uncle’s header:
{ "id": 1, "jsonrpc": "2.0", "result": { "blockHash": "0x83952d392f9b0059eea94b10d1a095eefb1943ea91595a16c6698757127d4e1c", "blockNumber": "0x16e360", "chainId": "0x1", "header": "0xf90218a027cc6d1022bd28ac1106505dafb86ad0167f11e473f6d14b7edc8175…", "transactions": [ "0xf86e8205dd850ba43b7400825208949d1e424358fa3376e995976e92437e0fb4…", … 4 more ], "unproven": ["size", "uncles"] }}The verifier renders the block with the same function Willow uses for the
headers it serves (see How Willow verifies data).
size is computed from the header, the transactions, the uncles, and the
withdrawals. Arbitrum One’s and Robinhood Chain’s l1BlockNumber, sendRoot,
and sendCount come from the header, and Base’s timestampMs from its
BaseTime deposit. With true, each transaction’s from is recovered from its
signature. totalDifficulty is not returned, because no block commits to it.
On the OP Stack chains, a deposit’s nonce from before Canyon is not in its
receipt, so the full form leaves it out.
A block number beyond the newest block Willow holds returns null, as
eth_getBlockByNumber does, and so does willow_getBlockReceiptsProof. A
block Willow doesn’t hold in full is refused as eth_getBlockByNumber with
true refuses it. In testing, an Ethereum block proof was 51 KB of JSON for a
block of 116 transactions and 370 KB for one of 347, and 2.5 to 25 KB on the
other chains.
willow_getStateProof
Section titled “willow_getStateProof”Takes [address, storageKeys, block, {"code": bool}]. The storage keys are a
list of at most 256, and may be empty. An absent block means latest. With
{"code": true}, the result also carries the account’s code.
Request (USDC on Ethereum, two of its storage slots, and its code):
{"jsonrpc":"2.0","id":1,"method":"willow_getStateProof","params":["0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",["0x07081a045c3dbf2e63b62a407ef205e7586e2629d2e2b95ff093308ca0ff3727","0x0"],{"blockHash":"0x8a27150df15c313310e346ad53e1e04825a7004e0e01096b5cf095e6c7d89552"},{"code":true}]}Response (truncated):
{ "id": 1, "jsonrpc": "2.0", "result": { "chainId": "0x1", "blockNumber": "0x192b4b5", "blockHash": "0x8a27150df15c313310e346ad53e1e04825a7004e0e01096b5cf095e6c7d89552", "header": "0xf90286a0cacbeb348fa34925df69d304c7c3aaf74eeaeba3ed487080d5f6485f…", "account": { "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", "accountProof": [ "0xf90211a08121535b79a42931a46b078696ad148c4cde0b402af5b476329010ee…", "0xf90211a05595744ee0fc5f13197e9d9a3184a895d37ff78a6a301538a65ee1ff…", … 7 more ], "balance": "0x0", "codeHash": "0xd80d4b7c890cb9d6a4893e6b52bc34b56b25335cb13716e0d1d31383e6b41505", "nonce": "0x1", "storageHash": "0xc75ab4dcfcdfd9f42598e57409e7ab347d0c0e18ce80e8616d04e1b3703e5346", "storageProof": [ { "key": "0x07081a045c3dbf2e63b62a407ef205e7586e2629d2e2b95ff093308ca0ff3727", "value": "0x8000000000000000000000000000000000000000000000000000000c3115cbc0", "proof": [ "0xf90211a0cc939fd63e9c4fc15b0a65e82f08897f3008df9adad4d6c2003c2167…", "0xf90211a0f01a4fffc505e4df7235edcc0d4ede015c490e37d3cf62e4daca64e1…", … 5 more ] }, { "key": "0x0", "value": "0xfcb19e6a322b27c06842a71e8c725399f049ae3a", "proof": [ "0xf90211a0cc939fd63e9c4fc15b0a65e82f08897f3008df9adad4d6c2003c2167…", "0xf90211a0397689f0d4af7d91ad5490a1bfd445e852d4f219ec1f73db8894e0cf…", … 6 more ] } ] }, "code": "0x60806040526004361061006d576000357c010000000000000000000000000000…" }}account: the EIP-1186 object for the address and keys asked for, exactly aseth_getProofreturns it. EachstorageProofentry’skeyis echoed as the request wrote it.code: present only with{"code": true}and only when the account has code. Its keccak256 must equalcodeHash.
The verifier verifies the account proof and each storage proof against the
header’s stateRoot, and the code against codeHash. From the one proof it
derives all five standard responses at that block:
{ "eth_getBalance": "0x0", "eth_getTransactionCount": "0x1", "eth_getCode": "0x60806040526004361061006d576000357c010000000000000000000000000000…", "eth_getStorageAt": [ "0x8000000000000000000000000000000000000000000000000000000c3115cbc0", "0x000000000000000000000000fcb19e6a322b27c06842a71e8c725399f049ae3a" ], "eth_getProof": { … }}An account with no entry in the state is proven absent. Its balance, nonce, and
storage are zero and its code is 0x, as the verifier derives for this
request:
{"jsonrpc":"2.0","id":1,"method":"willow_getStateProof","params":["0x6c3f9e1a2b7d4c58e0f1a9b3d2c4e6f8a1b3c5d7",["0x0"],{"blockHash":"0x8a27150df15c313310e346ad53e1e04825a7004e0e01096b5cf095e6c7d89552"},{"code":true}]}{ "eth_getBalance": "0x0", "eth_getTransactionCount": "0x0", "eth_getCode": "0x", "eth_getStorageAt": [ "0x0000000000000000000000000000000000000000000000000000000000000000" ]}In testing, a state proof was 9 to 26 KB of JSON.
willow_getCallProof
Section titled “willow_getCallProof”Takes [call, block, stateOverrides, blockOverrides], as eth_call does, on
Ethereum, Unichain, and Robinhood Chain; the overrides are optional. On the
other chains it is refused with -32601, as eth_call is.
The overrides are the caller’s own input, so the proof never carries them: the
verifier lays them over the proven state itself, as eth_call does. The
witness leaves out what they set. An account whose storage is replaced has no
slots in it, an account whose code is set has no code in it, and an account
whose nonce, balance, and code are all set has no proof in it unless the call
reads one of its slots that the override leaves.
Request (USDC’s balanceOf for one address):
{"jsonrpc":"2.0","id":1,"method":"willow_getCallProof","params":[{"to":"0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48","data":"0x70a0823100000000000000000000000028c6c06298d514db089934071355e5743bf21d60"},{"blockHash":"0x8a27150df15c313310e346ad53e1e04825a7004e0e01096b5cf095e6c7d89552"}]}Response (truncated):
{ "id": 1, "jsonrpc": "2.0", "result": { "chainId": "0x1", "blockNumber": "0x192b4b5", "blockHash": "0x8a27150df15c313310e346ad53e1e04825a7004e0e01096b5cf095e6c7d89552", "header": "0xf90286a0cacbeb348fa34925df69d304c7c3aaf74eeaeba3ed487080d5f6485f…", "witness": { "accounts": [ { "address": "0x0000000000000000000000000000000000000000", "accountProof": [ "#0", "0xf90211a0ddaccdd87e29604085aad75595201c2698e9d0d8a73bd22ab7fe3281…", … 7 more ], "balance": "0x2ff724df404d19689bb", "codeHash": "0xc5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470", "nonce": "0x0", "storageHash": "0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421", "storageProof": [] }, … 3 more ], "nodes": [ "0xf90211a08121535b79a42931a46b078696ad148c4cde0b402af5b476329010ee…", "0xf90211a0cc939fd63e9c4fc15b0a65e82f08897f3008df9adad4d6c2003c2167…" ], "codes": { "0xcdfb7d322961af3acae7a8f7ee8b69c205b36f576cc5b077f170c7eb8ecbe3ea": "0x608060405234801561001057600080fd5b506004361061036d5760003560e01c…", "0xd80d4b7c890cb9d6a4893e6b52bc34b56b25335cb13716e0d1d31383e6b41505": "0x60806040526004361061006d576000357c010000000000000000000000000000…" } }, "result": { "returned": "0x0000000000000000000000000000000000000000000000000000000c3115cbc0" } }}witness.accounts: one EIP-1186 object for each account the call read, with the storage slots it read. A proof node written"#i"iswitness.nodes[i].witness.nodes: trie nodes that more than one proof contains, such as the top of the state trie, sent once.witness.codes: each contract’s code that the call ran, once, keyed by its code hash.result: what the call came to:{"returned": data},{"reverted": data},{"halted": message}, or{"invalid": message}.
The verifier verifies every account, slot, and code against the header’s
stateRoot, then runs the call itself, in its own EVM, over that state alone,
under the request’s overrides: on Ethereum as reth runs it, on Unichain as
op-reth runs it, and on Robinhood Chain as Nitro runs it. Any account, slot,
code, or block hash the call reads that isn’t in the witness fails
verification. Its own outcome must equal result, and it returns its own
outcome as eth_call does:
{ "result": "0x0000000000000000000000000000000000000000000000000000000c3115cbc0"}A call that reverts carries the revert data:
{ "result": { "reverted": "0x08c379a000000000000000000000000000000000000000000000000000000000…" }}which the verifier returns as the error eth_call sends:
{ "error": { "code": 3, "message": "execution reverted: ERC20: transfer amount exceeds balance", "data": "0x08c379a000000000000000000000000000000000000000000000000000000000…" }}halted and invalid become -32000 errors with Willow’s eth_call
message.
A call that reads a block hash (the BLOCKHASH opcode) reads it from the
block’s own state: the block-hash history contract (EIP-2935,
0x0000F90827F1C53a10cb7A02335B175320002935), whose slots the witness carries,
and whose code the verifier pins. On Ethereum and Unichain it holds the last
8,191 blocks’ hashes. That contract exists on Ethereum from Prague on, so at
an earlier block a call that reads a block hash is refused with -32000. On
Robinhood Chain, BLOCKHASH reads ArbOS’s state, and ArbSys.arbBlockHash
reads Arbitrum’s history account at the same address, which holds the last
393,168 blocks’ hashes.
On Unichain and Robinhood Chain, the witness also carries the chain’s fee state that its EVM reads on every call (the L1 block attributes on Unichain, ArbOS’s pricing state on Robinhood Chain), proven like any other state. The block’s own fields, such as its number, time, and base fee, come from the anchored header.
The witness is read within the limits of Willow’s eth_call: 256 accounts,
8,192 storage slots, and trie nodes of at most 1,100 bytes, at most 64 per
proof. In testing, a call proof was 36 to 108 KB of JSON, and each recorded
call’s verified outcome equaled the standard eth_call response: calls with
state and block overrides and with gas prices on Ethereum, 12 calls on
Unichain, and 84 calls on Robinhood Chain.
willow_getEstimateGasProof
Section titled “willow_getEstimateGasProof”Takes [call, block, stateOverrides, blockOverrides], as eth_estimateGas
does, on Ethereum, Unichain, and Robinhood Chain. The overrides are optional
and are handled as for willow_getCallProof. On the
other chains it is refused with -32601, as eth_estimateGas is.
Request (a transfer of 1 wei):
{"jsonrpc":"2.0","id":1,"method":"willow_getEstimateGasProof","params":[{"from":"0x28c6c06298d514db089934071355e5743bf21d60","to":"0x4b1d5e7c9a3f2e6d8c0b1a2f3e4d5c6b7a8f9e01","value":"0x1"},{"blockHash":"0x8a27150df15c313310e346ad53e1e04825a7004e0e01096b5cf095e6c7d89552"}]}Response (truncated):
{ "id": 1, "jsonrpc": "2.0", "result": { "chainId": "0x1", "blockNumber": "0x192b4b5", "blockHash": "0x8a27150df15c313310e346ad53e1e04825a7004e0e01096b5cf095e6c7d89552", "header": "0xf90286a0cacbeb348fa34925df69d304c7c3aaf74eeaeba3ed487080d5f6485f…", "witness": { "accounts": [ { "address": "0x28c6c06298d514db089934071355e5743bf21d60", "accountProof": [ "#0", "0xf90211a04576fe625c7e4ef5ef0be118a541ae2190ec08ef7b9a3c9286c6e418…", … 7 more ], "balance": "0xb37d832b5a119d8", "codeHash": "0xc5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470", "nonce": "0x120a00b", "storageHash": "0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421", "storageProof": [] }, … 2 more ], "nodes": [ "0xf90211a08121535b79a42931a46b078696ad148c4cde0b402af5b476329010ee…" ], "codes": {} }, "algorithm": "geth-v1.17.10-estimate", "estimate": { "gas": "0x5208" } }}witness: the state that every run of the gas search read, in the form of a call proof’s witness.algorithm:geth-v1.17.10-estimateon Ethereum and Unichain, a line-for-line port of geth v1.17.10’s gas estimator (eth/gasestimator) over the chain’s own call runs, andnitro-v3.12.2-estimateon Robinhood Chain, a line-for-line port of Nitro v3.12.2’s gas estimation.estimate: what the search came to:{"gas": quantity},{"reverted": data}when the call reverts with all the gas it may have, or{"error": message}.
The verifier runs the same search over the witness alone and requires exactly
the same estimate. The search is deterministic over the state, so this proves
that the number is what the named algorithm returns at that block, not only
that it is enough gas. It then runs the call once with the gas found and requires it
to succeed. The standard response it returns:
{ "result": "0x5208"}A call that runs out of gas at the most gas it may have:
{ "algorithm": "geth-v1.17.10-estimate", "estimate": { "error": "gas required exceeds allowance (16777216)" }}{ "error": { "code": -32000, "message": "gas required exceeds allowance (16777216)" }}For a call that stops for another reason, the message uses the wording of
Willow’s eth_call, not geth’s exact text.
In testing, the estimates equaled geth’s eth_estimateGas exactly, at the same
block, for a plain transfer (21,000), a USDC transfer (63,054), a WETH deposit
(45,418), a Uniswap v2 swap (155,951), a contract creation (56,090), a call that
reverts, and one that runs out of gas. On Robinhood Chain, 16 recorded
estimates equaled the chain’s own eth_estimateGas exactly, and each verified
from its proof. An estimate proof was 23 to 229 KB of JSON.
willow_getFeeProof
Section titled “willow_getFeeProof”Takes one block parameter, latest when it is absent, and returns the headers
and bodies that the willow-fee-v1 formula reads at
that block, H:
- Ethereum: the headers of blocks H−3 through H, and a block proof of each,
in the form of
willow_getBlockProof. - Base, OP Mainnet, Unichain, and Ink: the header of H, and a block receipts proof of H, with its transactions and receipts.
- Arbitrum One and Robinhood Chain: the header of H alone.
Request:
{"jsonrpc":"2.0","id":1,"method":"willow_getFeeProof","params":[{"blockHash":"0x2afce59c8f52e3f7ec60a9a0e57c080a835333de8a68283314bab946464bee16"}]}Response (truncated):
{ "id": 1, "jsonrpc": "2.0", "result": { "blockHash": "0x2afce59c8f52e3f7ec60a9a0e57c080a835333de8a68283314bab946464bee16", "blockNumber": "0x192b3d7", "bodies": [ { "blockHash": "0x40dfffa82461d761ef772e5950dff517b6d4a7d849e03a03c167e98117130af0", "blockNumber": "0x192b3d4", "chainId": "0x1", "header": "0xf90288a05bac68916f7944f6e29e6751b169e421518ccb35aecad2ff99154ab5…", "transactions": [ "0x02f903700183031d0b808405e4bc72830746c4940000000aa232009084bd71a5…", … 164 more ], "withdrawals": "0xf90230e28408ec502b8309c5e1948e609ac80f4324e499a6efd24f221a2caa86…" }, … 3 more ], "chainId": "0x1", "formula": "willow-fee-v1", "headers": [ "0xf90288a05bac68916f7944f6e29e6751b169e421518ccb35aecad2ff99154ab5…", … 3 more ] }}formula:willow-fee-v1.blockNumber,blockHash: block H, the last header.headers: the headers’ RLP encodings, oldest first. Each must be the child of the one before it, byparentHash.bodies: one per header where the formula reads bodies, each verified against its header. Absent on Arbitrum One and Robinhood Chain.
On Robinhood Chain, the proof is one header:
{ "id": 1, "jsonrpc": "2.0", "result": { "blockHash": "0x82fb9ec96a5bfd01158828114d91812d3a9fae2c4be681c315d9410737fbbedf", "blockNumber": "0x6a87062", "chainId": "0x1237", "formula": "willow-fee-v1", "headers": [ "0xf90224a0bcebfc9ab09ee256175a2158fcfd37e50f2fa90e04fbb27840ed4cf2…" ] }}The verifier verifies the headers and bodies, anchors H, and computes the three standard responses at H. For the Ethereum proof above:
{ "baseFeePerGas": "0x2b069cb", "blockHash": "0x2afce59c8f52e3f7ec60a9a0e57c080a835333de8a68283314bab946464bee16", "blockNumber": "0x192b3d7", "eth_blobBaseFee": "0x27ee9d", "eth_gasPrice": "0x2660963", "eth_maxPriorityFeePerGas": "0xc", "formula": "willow-fee-v1", "nextBaseFeePerGas": "0x2660957"}In testing, an Ethereum fee proof was 890 KB of JSON (222 KB gzipped), since it carries four whole blocks. On the OP Stack chains it was 4 to 77 KB, and on Arbitrum One and Robinhood Chain about 1.3 KB.
willow_getFeeHistoryProof
Section titled “willow_getFeeHistoryProof”Takes [blockCount, newestBlock, rewardPercentiles], as eth_feeHistory does.
A count above 1,024 is cut to 1,024, as geth cuts it. Reward percentiles are at
most 100 values from 0 to 100, in increasing order. With reward percentiles, on
every chain except Arbitrum One and Robinhood Chain, one proof covers at most 16
blocks; a larger count is refused with -32602, and the verifying client
splits it into proofs of 16.
Request (four Base blocks, with rewards at the 10th, 50th, and 90th percentiles):
{"jsonrpc":"2.0","id":1,"method":"willow_getFeeHistoryProof","params":["0x4","0x3574133",[10.0,50.0,90.0]]}Response (truncated):
{ "id": 1, "jsonrpc": "2.0", "result": { "blockHash": "0x8c07cbc2061ddf440e67d449647978c22b7f44b8697db853eb9eec4d43907f6a", "blockNumber": "0x3574133", "bodies": [ { "blockHash": "0xb449aa4378e3f6163612cf1c9a70a16d09f10e7f713ae031f615b6757883e516", "blockNumber": "0x3574130", "chainId": "0x2105", "header": "0xf90279a0ae2a9b960866c2b6fad7e6170a4c0a6af2adb0fc577d2e46b89e1db9…", "receipts": [ "0x7ef9010e0182b48ab90100000000000000000000000000000000000000000000…", … 8 more ], "transactions": [ "0x7ef90106a0e1798bb717a7384496624427ccc5fcd4c52b647ea65869fecd7a03…", … 8 more ] }, … 3 more ], "chainId": "0x2105", "formula": "willow-fee-v1", "headers": [ "0xf90279a0ae2a9b960866c2b6fad7e6170a4c0a6af2adb0fc577d2e46b89e1db9…", … 3 more ] }}The fields are those of willow_getFeeProof. headers covers the requested
range, oldest first, and bodies holds a block receipts proof of each block,
only when reward percentiles are requested (never on Arbitrum One and Robinhood
Chain, where the rewards are zero). The verifier computes eth_feeHistory from
them, as described in Fee formula:
{ "baseFeePerBlobGas": ["0x1", "0x1", "0x1", "0x1", "0x1"], "baseFeePerGas": ["0x4c4b40", "0x4c4b40", "0x4c4b40", "0x4c4b40", "0x4c4b40"], "blobGasUsedRatio": [0.0, 0.0, 0.0, 0.0], "gasUsedRatio": [0.0231353, 0.050149375, 0.07197315, 0.03608955], "oldestBlock": "0x3574130", "reward": [ ["0x0", "0xf4240", "0x118c30"], ["0x186a0", "0x1e8480", "0x2018e5"], ["0x66a64", "0x21992f", "0x2bde780"], ["0x0", "0x0", "0x0"] ]}willow_getBlockAnchor
Section titled “willow_getBlockAnchor”Takes one block: a block number, latest, or, on Ethereum and BNB Smart
Chain, finalized. Any other tag is refused with -32602, as is finalized
on an L2. The result is the data that ties the block’s hash to Ethereum (on BNB
Smart Chain, to its validators), and blockNumber names the block chosen. The
verifier passes it, with the block’s number and the hash its proof ended at, to
the anchor module that the browser verifier
uses, which returns the hash attested for that block and the level it reached.
A different hash fails verification. The anchor module holds three light
clients: Ethereum’s, which anchors Ethereum and the L2s that settle on it;
Sepolia’s, which anchors the six testnets; and one of BNB Smart Chain’s
validator set.
Request:
{"jsonrpc":"2.0","id":1,"method":"willow_getBlockAnchor","params":["latest"]}Response (update.data collapsed):
{ "id": 1, "jsonrpc": "2.0", "result": { "blockNumber": "0x192b489", "proof": { "kind": "head" }, "update": { "data": { … }, "version": "fulu" } }}update: an Ethereum light-client finality update, as a beacon API sends it. The light client verifies its sync committee signature, so it fixes a signed head and a finalized block.proof(Ethereum): how the block reaches that head.{"kind": "head"}is the head itself.{"kind": "history", "proof": …}is aneth_getProofof Ethereum’s block-hash history contract at the head, for the last 8,191 blocks.{"kind": "beacon", "witness": …}reaches older blocks from the Merge on through the beacon state’s block roots: the period’s roots, committed to by the finalized state’shistorical_summariesfrom Capella on and by itshistorical_rootsfrom the Merge to Capella.{"kind": "accumulator", "hash", "totalDifficulty", "branch", "epochBranch"}proves a block before the Merge (blocks 0 to 15,537,393) by its record in EIP-7643’s historical hashes accumulator, whose root the verifier pins. It needs no light client.
latest on Ethereum is the light client’s signed head (path head, level
signed). finalized is the head’s finalized block (path history, level
final):
{ "id": 1, "jsonrpc": "2.0", "result": { "blockNumber": "0x192b435", "proof": { "kind": "history", "proof": { … } }, "update": { "data": { … }, "version": "fulu" } }}On an L2, the result also carries l1, a witness of the Ethereum state it
reads (the chain’s contracts and their code), headers, the L2 block-hash
history proofs in proofs, and either the claim on Ethereum that covers the
block (a dispute game on the OP Stack chains, an assertion on Arbitrum One and
Robinhood Chain) or signed, a block its sequencer signed. A block further
below the claimed block than the chain’s block-hash history reaches is
anchored through descent, the headers from the claimed block down to it,
each linked to the next by parentHash. On the six testnets, update is a
Sepolia light-client update, and the claims are on Sepolia. latest on an L2
is the newest block its sequencer signed, with that block’s header alone:
{ "id": 1, "jsonrpc": "2.0", "result": { "blockNumber": "0x3573e85", "headers": [ "0xf90279a0f506c530a6573924f1104afdd760e8e51e125db0b977e10967734c33…" ], "l1": { … }, "proofs": [], "signed": { "message": "0x0c76888dd218993c7e81225712f18032a193a5af44909c20f648464b065c6675…", "version": 3 }, "update": { "data": { … }, "version": "fulu" } }}On BNB Smart Chain, the result is parlia: the block’s header and the
headers up to a block that BNB’s validators voted final, linked by
parentHash, with the vote attestation that finalizes it. latest and
finalized are BNB Smart Chain’s newest finalized block. Block 133,520,287:
{ "id": 1, "jsonrpc": "2.0", "result": { "blockNumber": "0x7f55b9f", "parlia": { "attestation": "0xf8b5831fffffb86087e88e8c1ab15f0ef6e17444d7611b0ac110a1cdcd51d9cf…", "headers": [ "0xf9037ca0bae4c07bbe09e37856ed706d8e6b053302d670560a95c2953b941471…" ] } }}The verifier requires the headers to link, and the attestation to be signed
by at least two thirds of the validator set that seals the block after the
finalized one. Its light client follows that set from a pinned epoch block. A
block not yet voted final can be anchored as signed by its header alone,
sealed by a validator of the set, for 10 minutes.
The levels, and which blocks can be anchored, are described in
Anchoring. In testing, Ethereum’s
latest anchor was about 5 KB of JSON and finalized about 17 KB, and an L2’s
latest was 68 to 147 KB (27 to 57 KB gzipped). Willow’s server verifies every
anchor with the same code before serving it. The first anchor of an old L2
block can take longer, while its claim is found and its headers are collected.
The light clients start from two more methods, also served without a key:
- On Ethereum’s route,
willow_lightClientBootstrap [blockRoot]returns the beacon API’s bootstrap for that block root, andwillow_lightClientUpdates [startPeriod, count]the best update for each of up to 16 sync committee periods, both as the beacon API sends them. - On each testnet’s route, the same two methods serve Sepolia’s light client.
- On BNB Smart Chain’s route,
willow_lightClientBootstrap [blockHash]returns an epoch block’s header, andwillow_lightClientUpdates [fromEpoch, count]one update for each of up to 64 epochs: the epoch block’s header, the headers to the block finalized after it, and the attestation that finalizes it.
| Method | Units |
|---|---|
willow_getBlockProof, willow_getFeeProof, willow_getFeeHistoryProof | By size, at least 1, on every plan |
willow_getStateProof | 3, as a read |
willow_getCallProof | 3, as eth_call |
willow_getEstimateGasProof | 3, as eth_estimateGas |
willow_getBlockAnchor, willow_lightClientBootstrap, willow_lightClientUpdates | 0 |
The state, call, and estimate proofs cost their minimum, 3 units for each
request made to a paid provider, or their size in units, whichever is most, as
their standard methods do. Requests to Willow’s own nodes and to free public
providers are not counted. A proof costs what its standard method costs, apart
from the proof’s own bytes where it is large. willow_getTraceProof is priced as the trace methods are
(see Trace proofs). See
Units and pricing.