Skip to content

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.

MethodParamsProvesChains
willow_getBlockProofA blocketh_getBlockByNumber and eth_getBlockByHash, with hashes or full transactions, and eth_getBlockTransactionCountByNumber / ByHashEvery chain
willow_getStateProofAn address, storage keys, a block, and {"code": bool}eth_getBalance, eth_getTransactionCount, eth_getCode, eth_getStorageAt, and eth_getProofThe chains with state methods
willow_getCallProofA call object, a block, and optional state and block overrideseth_callEthereum, Unichain, Robinhood Chain
willow_getEstimateGasProofA call object, a block, and optional state and block overrideseth_estimateGasEthereum, Unichain, Robinhood Chain
willow_getFeeProofA blocketh_gasPrice, eth_maxPriorityFeePerGas, and eth_blobBaseFeeEthereum, Base, OP Mainnet, Unichain, Ink, Arbitrum One, Robinhood Chain
willow_getFeeHistoryProofA block count, the newest block, and reward percentileseth_feeHistoryAs willow_getFeeProof
willow_getBlockAnchorA block number, latest, or finalized (Ethereum and BNB Smart Chain)The block’s hash, as Ethereum, or BNB Smart Chain’s validators, attest itEvery 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.

  • The block is always named. Every result carries chainId and blockNumber (hexadecimal), blockHash, and header, the block header’s RLP encoding. A verifier requires that the keccak256 of header is blockHash, 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 for willow_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_getCallProof on a chain where Willow does not execute calls) names itself in its -32601 message.
  • Encoding. Binary data is 0x hex. Large responses are gzipped for requests that send Accept-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.

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’s transactionsRoot, so none can be added, dropped, changed, or reordered.
  • withdrawals: the block’s withdrawals as one RLP list, present when the header has a withdrawalsRoot. On Ethereum they must rebuild withdrawalsRoot. On the OP Stack chains the list must be empty (0xc0), since from Isthmus their withdrawalsRoot is 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’s sha3Uncles.
  • receiptProofs (OP Stack chains): a receipt proof for each deposit transaction, in the form of transaction and receipt proofs. A deposit’s nonce and depositReceiptVersion are 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, size and uncles, 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.

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 as eth_getProof returns it. Each storageProof entry’s key is echoed as the request wrote it.
  • code: present only with {"code": true} and only when the account has code. Its keccak256 must equal codeHash.

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.

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" is witness.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.

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-estimate on 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, and nitro-v3.12.2-estimate on 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.

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, by parentHash.
  • 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.

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"]
]
}

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 an eth_getProof of 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’s historical_summaries from Capella on and by its historical_roots from 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, and willow_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, and willow_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.
MethodUnits
willow_getBlockProof, willow_getFeeProof, willow_getFeeHistoryProofBy size, at least 1, on every plan
willow_getStateProof3, as a read
willow_getCallProof3, as eth_call
willow_getEstimateGasProof3, as eth_estimateGas
willow_getBlockAnchor, willow_lightClientBootstrap, willow_lightClientUpdates0

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.