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.
Block verification
Section titled “Block 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
hashandsize(and, on Arbitrum One, Robinhood Chain, Arbitrum Sepolia, and Robinhood Chain Testnet,l1BlockNumber,sendRoot, andsendCount) are computed from the verified data.totalDifficultyis not served, because no block commits to it. BNB Smart Chain’s nodes reportsizeinconsistently (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’ssha3Uncles. Every other block must have none. - The block’s receipts are fetched with
eth_getBlockReceiptsby block hash, and must reconstruct the header’sreceiptsRoot. - The logs served are derived from those verified receipts. Each log’s
address,topics,data,logIndex,transactionIndex,transactionHash,blockNumber, andblockHashare taken from the verified data, andblockTimestampfrom 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.
Fields in full blocks
Section titled “Fields in full blocks”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’sstatus,cumulativeGasUsed,logsBloom, and logs. An Ethereum receipt before Byzantium (block 4,370,000) commitsroot, the post-state root, instead ofstatus, so Willow servesroot. Thestatusthat 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, thegasPriceof 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’sl1BlockNumber. - Passed through: an OP Stack deposit’s
noncefrom 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
gasUsedForL1andtimeboosted. 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.
Reorgs
Section titled “Reorgs”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.
Canonical chain
Section titled “Canonical chain”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, andminermust be that validator. Itsdifficultymust 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.
safeis the newest block voted that way, andfinalizedthe 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.
finalized and safe on the L2s
Section titled “finalized and safe on the L2s”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.
Relationship to proofs
Section titled “Relationship to proofs”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.