Skip to content

How Willow verifies data

On every chain, Willow verifies each block against its block hash before any data from it is stored or served. This page describes the verification performed on each chain. The verification is identical whether or not a proof is requested; a proof enables independent verification.

  • The header’s fields must hash to the block hash (keccak256 of the header’s RLP encoding). The header served is rebuilt from those fields. Its hash and size (and, on Arbitrum One, Robinhood Chain, Arbitrum Sepolia, and Robinhood Chain Testnet, l1BlockNumber, sendRoot, and sendCount) are computed from the verified data. totalDifficulty is not served, because no block commits to it. BNB Smart Chain’s nodes report size inconsistently (BNB Chain’s geth reports one byte less once a block is a few minutes old, and reth-bsc counts blob sidecars); Willow serves the length of the block’s encoding with its withdrawals list, which geth reports for a new block.
  • The block is fetched with its full transactions. Each transaction is encoded to its consensus bytes, and together they must reconstruct the header’s transactionsRoot. A transaction’s hash is the keccak256 of those bytes, so the transaction hashes served in blocks, receipts, and logs are all verified.
  • Withdrawals must reconstruct the header’s withdrawalsRoot (on the OP Stack chains, the list must be empty). Ethereum blocks before the Merge must have uncles that hash to the header’s sha3Uncles. Every other block must have none.
  • The block’s receipts are fetched with eth_getBlockReceipts by block hash, and must reconstruct the header’s receiptsRoot.
  • The logs served are derived from those verified receipts. Each log’s address, topics, data, logIndex, transactionIndex, transactionHash, blockNumber, and blockHash are taken from the verified data, and blockTimestamp from the verified header.

The proving programs verify their inputs the same way.

A block that fails verification is fetched again from Willow’s other providers. If none of them serves it in a verifiable form, the block is never served. The chain halts at the previous block, requests for later blocks are refused with -32000, and /v1/rpc/health reports the chain as unhealthy, with stalledAtBlock and lastVerifyError.

Willow stores each block’s transaction and receipt bytes, and each transaction’s sender (recovered from its signature, for a signed transaction). Every other field is computed from these at request time. Each field served belongs to one of three categories, and two fields are not served at all:

  • Committed: contained in the block’s consensus bytes, and therefore verified against the block hash. For example, a signed transaction’s nonce, gas, to, value, input, and signature, and a receipt’s status, cumulativeGasUsed, logsBloom, and logs. An Ethereum receipt before Byzantium (block 4,370,000) commits root, the post-state root, instead of status, so Willow serves root. The status that some providers return for those receipts is computed by replaying the block and cannot be verified from it.
  • Derived: computed from committed data, as nodes compute it. For example, hash, from, the gasPrice of a fee-market transaction, gasUsed, contractAddress, effectiveGasPrice, the blob gas fields, logIndex, the OP Stack L1 fee fields (from the block’s L1 info deposit), and Nitro’s l1BlockNumber.
  • Passed through: an OP Stack deposit’s nonce from before the Canyon upgrade, since receipts before Canyon don’t carry it. No block data determines it, so it is served as the provider reported it. It is the only field in this category.
  • Not served: Arbitrum Nitro’s receipt fields gasUsedForL1 and timeboosted. No block data determines them, so Willow leaves them out of every receipt it serves.

Before a block’s full form is served, its computed transactions and receipts must equal the provider’s, field for field. If a derived field disagrees with every provider, the block is stored without its full form: its header and logs are still served, the full-block methods refuse it with -32000, and /v1/rpc/health counts it in fullBlocks.skipped.

Blocks are added in order, and each new block must link to the previous one by its parent hash, so data from two different forks cannot be mixed. When a chain reorganizes, Willow rolls back to the common ancestor and reads the new blocks.

Parent-hash links keep the blocks of one fork together, but do not establish which fork is canonical. Willow verifies canonicality independently rather than accepting it from its providers. /v1/rpc/health reports the result on every chain (canonicalStatus).

On Ethereum, canonicality is verified against Helios, a light client that follows Ethereum’s sync committee. A block is served as soon as it is verified as above. Helios trails the newest block by a slot or two and confirms it shortly after. If the providers’ chain contradicts a block Helios verified, Willow rolls back to the newest block Helios confirmed, and serves nothing above it until the providers agree with Helios again. It never rolls back below a block that matched Helios’s finalized block. The finalized tag is Helios’s finalized block. Helios has no safe block of its own, so safe is refused on Ethereum.

On the L2s, canonicality is verified against the chain’s sequencer, which signs every block it produces. On the OP Stack chains (Base, OP Mainnet, Unichain, Ink, World Chain, Soneium, Zora, Base Sepolia, OP Sepolia, Unichain Sepolia, and Ink Sepolia), the signed blocks come from the OP Stack’s peer-to-peer network, and Willow verifies each signature against the chain’s unsafe block signer, the key specified in the chain’s SystemConfig contract on its L1. On Arbitrum One, Robinhood Chain, Arbitrum Sepolia, and Robinhood Chain Testnet, the signed block hashes come from the chain’s sequencer feed, and the signing key must be a batch poster or sequencer in the chain’s SequencerInbox contract on its L1. The L1 is Ethereum, or Sepolia for the testnets. Both contracts are read through Helios, a light client of that L1, so the keys are obtained from verified L1 state rather than from a provider, and they are read again every five minutes.

A block is served only once the sequencer has signed it, or has signed a later block that links back to it by parent hash. A block the sequencer did not sign is never stored or served, even if it is internally consistent (for example, a forged block from a compromised provider). The chain then halts at the newest signed block it holds, and /v1/rpc/health reports it as unhealthy until the providers serve the signed chain again. If signed blocks stop arriving, the chain halts in the same way instead of serving unsigned blocks. If the sequencer signs a different block at a height already served, Willow rolls back below that height and reads the new blocks.

The signature is the sequencer’s attestation to its newest blocks, which is the furthest extent to which any L2 can be verified at its tip. It does not establish that the sequencer posts those blocks to Ethereum. The finalized and safe tags establish that.

On BNB Smart Chain, every block is verified against the chain’s validators before it is stored or served. BNB Smart Chain settles nowhere else, so Willow follows its validator set itself, as a light client does, from a block hash pinned in Willow’s code:

  • Each header must carry a valid seal (the producing validator’s signature in extraData) by a validator in the current set, and miner must be that validator. Its difficulty must match whether it was that validator’s turn, and no validator may seal more than its share of recent blocks.
  • Every epoch block names the next validator set (with each validator’s BLS vote key). It is sealed by the current set, and the new set takes over a fixed number of blocks later, as the chain’s own rules specify.
  • Each vote attestation in a header (the validators’ fast-finality votes) must carry an aggregate BLS signature by at least two thirds of the validators over a recent block. safe is the newest block voted that way, and finalized the newest block that two consecutive votes made final.

A block is served only once a verified header links back to it by parent hash. At the tip, that header is signed by one validator: like a sequencer’s signature on an L2, it attests to the newest block but is not final. A block at or below safe was voted for by at least two thirds of the validators. Willow does not re-execute blocks: their state and receipts are those its providers computed, verified against the header’s roots as above.

Older blocks are linked by parent hash, block by block, to blocks Willow already holds, on Ethereum down to genesis. On Base, OP Mainnet, Unichain, Ink, Arbitrum One, and Robinhood Chain, a fetched range can instead link to a block hash the chain committed on Ethereum: an OP Stack output root whose dispute game resolved, or a confirmed Arbitrum assertion. These are read from Ethereum blocks and state that Willow verified, not taken from a provider. See History.

On Base, OP Mainnet, Unichain, Ink, Arbitrum One, and Robinhood Chain, finalized is the newest block whose transactions were posted to Ethereum in a block that the Ethereum light client verified as finalized. Willow reads the posted batches from verified Ethereum blocks, verifies the batch data against the hashes committed on Ethereum, derives the chain’s blocks from it under the chain’s own rules, and serves the tag only when every block up to it matches the derived blocks.

  • On Base, OP Mainnet, Unichain, and Ink, this covers every transaction and every header field set by the derivation.
  • On Arbitrum One and Robinhood Chain, it covers every transaction the sequencer posted, the deposits and retryable tickets from Ethereum, and each block’s timestamp, Ethereum block, and poster. ArbOS’s own transactions are verified by type, and a transaction sent through the delayed inbox that ArbOS rejected may be missing from its block.

safe on Base, OP Mainnet, Unichain, and Ink is defined in the same way, but up to the newest Ethereum block the light client verified rather than the finalized one. It is refused on Arbitrum One and Robinhood Chain.

Willow does not re-execute L2 blocks: the state and receipts are those its providers computed, verified as described above. Either tag is refused while it cannot be verified. This includes the period until every one of Willow’s providers has the same block at or below its own safe block (for up to ten minutes in the interim, the tag is the newest earlier block they all have), and any period in which the providers dispute the sequencer-signed blocks Willow stores or signed blocks stop arriving. /v1/rpc/health/finality reports on both tags.

On World Chain, Soneium, Zora, and the testnets, finalized and safe are refused.

Because every log is verified against its block before it is served, a proof generated later for the same blocks confirms the logs that were previously served.