Verifying client
@willow-network/rpc is a JSON-RPC client for Willow RPC that verifies every
response before the app sees it. For each request, it fetches the proof behind
the response, verifies it, verifies the block with its own light client (on
Ethereum, or on BNB Smart Chain against its validators), and returns the
standard JSON-RPC response built from the proven data alone. That means an app
no longer has to trust its RPC. A response that fails verification never
reaches the app as a value.
It works as a viem transport, an ethers v6 provider, or an EIP-1193 request
function, so an existing app changes in one place, where its client is
created.
Install
Section titled “Install”npm install @willow-network/rpcThe package is ESM and CommonJS, and runs on Node 18 and later and in evergreen browsers. viem (2.21 or later) and ethers (6.13 or later) are optional peer dependencies. The verifiers are WebAssembly modules shipped in the package, each loaded the first time it is needed. The largest, the state module, which runs calls, gas estimates, and traces, is about 5 MB uncompressed. In browsers they run in a Web Worker.
import { createPublicClient } from 'viem';import { mainnet } from 'viem/chains';import { willowTransport } from '@willow-network/rpc/viem';
const client = createPublicClient({ chain: mainnet, transport: willowTransport({ chainId: 1, key: process.env.WILLOW_KEY }),});
// Verified against Ethereum's validators, or it throws.const balance = await client.getBalance({ address: '0x00000000219ab540356cbb839cbe05303d7705fa' });willowTransport is a viem custom() transport. Its retry count is 0, so a
response that failed verification is never requested again. viem’s own
transport settings go in its transport option.
ethers
Section titled “ethers”import { WillowProvider } from '@willow-network/rpc/ethers';
const provider = new WillowProvider({ chainId: 8453, key: process.env.WILLOW_KEY });const block = await provider.getBlock('latest');WillowProvider extends ethers’ JsonRpcApiProvider, with its network fixed
to chainId and batches of up to 100 requests. The client’s own errors reach
the app as they are, not wrapped in an ethers error. provider.destroy() stops
the verifiers.
EIP-1193
Section titled “EIP-1193”import { createVerifier } from '@willow-network/rpc';
const willow = createVerifier({ chainId: 1, key: process.env.WILLOW_KEY });const block = await willow.request({ method: 'eth_getBlockByNumber', params: ['latest', false] });willow.close();createVerifier(options) returns { chainId, request, close }. request
takes { method, params } and returns the standard result, verified, or
throws.
Options
Section titled “Options”| Option | Default | Description |
|---|---|---|
chainId | Required | The chain. Anchored on Ethereum: 1, 8453, 10, 130, 57073, 1868, 7777777, 480, 42161, and 4663. Anchored on Sepolia: 11155420, 84532, 1301, 763373, 421614, and 46630. Anchored on its own validators: 56. One client serves one chain. |
key | public | The API key. Without one, the client uses the public path, /v1/rpc/{chainId}/public, which serves blocks, transactions, receipts, logs, and fees with their proofs, but not state or traces. |
url | https://api.willow.tech/v1/rpc/{chainId}/{key} | The RPC URL. |
lightClientUrl | url with chain 1 | Ethereum’s route, from which the light client reads. |
minLevel | signed | The lowest anchor level a response may rest on: signed, committed, or final. |
unverifiable | throw | What happens to a value the client can’t verify. throw raises WillowUnverifiableError, and flag returns the value and marks it in onVerification. See What can’t be verified. |
onVerification | None | Called once for every response. See Events. |
headMaxAgeMs | 12000 on Ethereum, 2000 on the other chains | How long the newest anchored block is used before the client anchors the chain’s head again. |
maxHeadAgeSec | 600 | The oldest that the newest block Willow anchors may be, in seconds. |
checkpoint | The shipped one | The light client’s starting point on Ethereum, {root, slot}. |
checkpointUrl | https://api.willow.tech/verify/checkpoint.json | Where a newer starting point is read once the shipped one is 29 days old. The same file carries newer starting points for Sepolia and BNB Smart Chain. |
sepoliaCheckpoint | The shipped one | The Sepolia light client’s starting point, {root, slot}, for the six testnets. Read from checkpointUrl once the shipped one is 29 days old. |
bnbStart | The shipped one | BNB Smart Chain’s light client’s starting point, {number, hash, time}, an epoch block. Read from checkpointUrl once the shipped one is a day old. The light client refuses a start older than 7 days. |
beaconApis | publicnode’s and ChainSafe’s beacon APIs in Node, none in browsers | Beacon APIs that confirm a starting point read from checkpointUrl: at least one must confirm it, and none may disagree. One that fails or has no header for that slot is skipped. false for none. |
storage | localStorage in browsers, ~/.cache/willow-rpc/ in Node | Where the light client keeps the sync committees it verified. They are verified again when read. false keeps nothing. |
worker | true in browsers, false in Node | Whether the verifiers run in a Web Worker. |
batchWindowMs | 5 | Requests this many milliseconds apart go out as one JSON-RPC batch, of at most 100 items. |
logsTimeoutMs | 120000 | How long eth_getLogs waits for Willow to prove blocks. |
anchorWaitMs | 36000 | How long a request waits for the anchor of a block newer than the newest one anchored. See The newest block. |
verifiers | The package’s modules | Other builds of the verifier modules, for testing. |
The public path queues no proof jobs, serves a few requests at a time, and has a byte budget, so an app in production passes a key.
What each method is verified by
Section titled “What each method is verified by”| Method | Verification |
|---|---|
eth_getBlockByNumber, eth_getBlockByHash, eth_getBlockTransactionCountByNumber, eth_getBlockTransactionCountByHash | A block proof, cached by block hash. With true, each transaction’s from is recovered from its signature. |
eth_blockNumber | The newest block the client has anchored. |
eth_getBalance, eth_getTransactionCount, eth_getCode, eth_getStorageAt, eth_getProof | A state proof, with a key whose plan includes state methods. Reads of one account at one block share one proof, and code is cached by its hash. |
eth_call, eth_estimateGas (Ethereum, Unichain, Robinhood Chain) | A call proof or an estimate proof, with a key whose plan includes state methods. The client runs the EVM itself over the proven state, with the call’s state and block overrides laid over it. On Robinhood Chain the estimate is Nitro’s search (nitro-v3.12.2-estimate). |
eth_gasPrice, eth_maxPriorityFeePerGas, eth_blobBaseFee | One fee proof at the anchored head, computed with the willow-fee-v1 formula. |
eth_feeHistory | Fee-history proofs, 16 blocks to a proof when rewards are requested. |
eth_getTransactionByHash, eth_getTransactionByBlockHashAndIndex, eth_getTransactionByBlockNumberAndIndex, eth_getTransactionReceipt, eth_getBlockReceipts | Transaction and receipt proofs. An unknown transaction is null. |
eth_getLogs | Up to 8 blocks: a block receipts proof of each block, anchored from the newest through parent hashes. More than 8: a log proof, waiting up to logsTimeoutMs for its proof jobs. |
debug_traceTransaction, debug_traceBlockByNumber, debug_traceBlockByHash, trace_block, trace_transaction, trace_replayBlockTransactions, trace_replayTransaction (Ethereum, Unichain) | A trace proof, with a key whose plan includes state methods. The client runs the block itself over the proven parent state, checks every transaction against its receipt, and writes the trace with the same tracers as Willow’s server. |
debug_traceCall, trace_call (Ethereum) | A trace proof of the call, at the block the client resolved. The client runs the call as eth_call runs it, under the call’s overrides, and traces it. |
trace_filter (Ethereum, Unichain) | A trace proof of trace_block for each block in the range (at most 16), filtered by the client, the range anchored from its newest block through parent hashes. |
eth_sendRawTransaction | No proof. The client computes the transaction’s hash from its bytes and requires the server’s hash to match. |
eth_newFilter, eth_newBlockFilter, eth_getFilterChanges, eth_getFilterLogs, eth_uninstallFilter | Served by the client over the verified methods, so viem’s watch* actions are verified too. Willow’s server doesn’t serve filters. A block filter returns at most 2,000 blocks a poll, oldest first, and the next poll goes on from there. |
eth_chainId, net_version, net_listening, net_peerCount, web3_clientVersion, eth_syncing, eth_accounts | Served by the client. At start, one eth_chainId must name the configured chain, which catches a wrong endpoint. |
Log proofs are priced per block on the plans that
include them, so an eth_getLogs over more than 8 blocks is charged as a log
proof request, and a range that costs more than $10 is refused with -32602
and a quote, as willow_getLogsProof is. Logs from a log proof carry only the
fields it proves, so their blockHash and
transactionHash are left out.
The client returns only fields its proofs cover. A field no block commits to,
such as a block’s totalDifficulty, is never returned. A field that a
particular proof can’t cover is left out and listed in the event’s unproven,
for example an OP Stack deposit’s nonce from before Canyon, or the uncles
and size of a pre-Merge block whose uncle headers Willow doesn’t hold.
eth_getTransactionCount with pending returns the proven nonce at the head,
or one more than the highest nonce this client has itself sent from that
address, whichever is higher. A server’s mempool nonce can’t be proven, so the
client never uses one.
Blocks and tags
Section titled “Blocks and tags”latest,pending, and an absent block are the chain’s anchored head.finalizedon Ethereum is the light client’s finalized block.safeon Ethereum is refused, as Willow’s server refuses it.- On BNB Smart Chain,
latestis the newest block its validators voted final, so it is served at anyminLevel. finalizedandsafeon an L2 are unverifiable: the block’s contents verify, but the tag’s meaning doesn’t.- A block number the client has already anchored goes out by its hash, so a reorg can’t put another block in its place.
eth_blockNumber can trail the server’s own eth_blockNumber. No proof can
show that a block is the newest one, so the client returns the newest block it
has anchored, which is the block every latest request goes to.
The newest block
Section titled “The newest block”Ethereum’s sync committee signs a block only in the slot after it, and
Willow’s server can serve a block before then. A request that names such a
block by number waits for its anchor: while
willow_getBlockAnchor reports the block as waiting, the client asks again,
after the server’s retryAfterSeconds or every 4 seconds, for up to
anchorWaitMs (36 seconds, three slots, by default). After that, the request
fails as unverifiable with anchor-waiting.
Anchoring
Section titled “Anchoring”Every proof ends at a block hash, and the client verifies that hash before it returns anything. Three light clients anchor the chains:
- Ethereum’s anchors Ethereum and the nine L2s that settle on it. It follows Ethereum’s sync committee from a checkpoint shipped in the package.
- Sepolia’s anchors the six testnets, which settle on Sepolia. It follows Sepolia’s sync committee, and reads its data from the testnet’s own route.
- BNB Smart Chain’s follows BNB Smart Chain’s validator set from an epoch block shipped in the package, each new set taken from an epoch block that at least two thirds of the set before it voted final. It reads its data from BNB Smart Chain’s route.
The client keeps what each light client verified in storage, verified again
from the starting point on the next start. A first start on Ethereum downloads
one light-client update for each sync committee period since the checkpoint,
about 58 KB each. The light client refuses a checkpoint older than 30 days, so
once the shipped one is 29 days old the client reads a newer one from
checkpointUrl and, in Node, requires at least one of the beaconApis to
confirm it and none to disagree. BNB
Smart Chain’s light client walks one update for each epoch since its start,
and refuses a start older than 7 days, so the client reads a newer start from
checkpointUrl once the shipped one is a day old.
Each anchored block reaches a level:
- Ethereum:
signedonce the validators sign a head whose history contains the block, andfinalonce Ethereum finalizes it. - The L2s:
signedby the chain’s sequencer, whose key the client reads from Ethereum (from Sepolia, for a testnet);committedonce a claim by the chain’s proposer covers the block (a dispute game on the OP Stack chains, an assertion on Arbitrum One, Robinhood Chain, and their testnets); andfinalonce that claim settles, as for a withdrawal. - BNB Smart Chain:
finalonce at least two thirds of the validator set vote it final, andsignedbefore that, by the validator that sealed it, for 10 minutes.
minLevel sets the lowest level a response may rest on. The default, signed,
covers the newest blocks within seconds. On an L2 the newest block is always
signed, so with a higher minLevel the app names a block instead of latest.
Which blocks can be anchored
Section titled “Which blocks can be anchored”- Ethereum, recent blocks.
latestis the light client’s signed head. Each of the last 8,191 blocks (about 27 hours) is anchored through Ethereum’s block-hash history contract (EIP-2935):finalonce the light client’s finalized block reaches it, andsignedbefore that. - Ethereum, older blocks. Every older block, back to genesis, is anchored
as
final. From the Merge (block 15,537,394) on, a block is anchored through the beacon state’s block roots, committed to by the finalized state’shistorical_rootsbefore Capella and itshistorical_summariesfrom Capella on. A block before the Merge is anchored through EIP-7643’s historical hashes accumulator, whose root the client pins, with no light client involved. - The OP Stack chains (Base, OP Mainnet, Unichain, Ink, Soneium, Zora, World Chain, and the OP Stack testnets). The newest blocks by their sequencer’s signature, and older ones through the dispute game that covers them, once one does.
- Arbitrum One, Robinhood Chain, and their testnets. The newest blocks by the sequencer’s signed feed, and older ones through the assertion that covers them.
- Older L2 blocks. A block below the claimed block is reached through the chain’s block-hash history, and further down through the block headers between them, linked by parent hash. The first anchor of an old block can take longer, while Willow finds its claim and collects those headers.
- BNB Smart Chain. Every block from the client’s starting epoch block on.
For a block that can’t be anchored, the client raises
WillowUnverifiableError with an anchor- kind, such as anchor-refused when
Willow refuses the anchor. With unverifiable: "flag", it returns the value
its proof verified, and the event says the block isn’t anchored. The response
shapes are in
willow_getBlockAnchor.
What can’t be verified
Section titled “What can’t be verified”Absences and refusals can deny service, but they can’t forge a value, so they
always pass through to the app, marked in onVerification:
nullfrometh_getTransactionReceiptandeth_getTransactionByHash, which viem’swaitForTransactionReceiptpolls on;- the server’s JSON-RPC errors, such as
-32601foreth_callandeth_estimateGason a chain where Willow doesn’t execute them, or for a trace method on a chain other than Ethereum and Unichain (a-32601for a proof method is the exception, below); - a provider’s error from
eth_sendRawTransaction.
A value the client can’t verify follows unverifiable. With throw, the
default, it raises WillowUnverifiableError. With flag, it returns the
server’s value and the event says why. This covers:
finalizedandsafeon an L2;eth_getLogsover more than 8 blocks, on a key or path without log proofs;- a block that can’t be anchored now, or is anchored below
minLevel; - a proof method the key’s plan or the public path doesn’t serve, such as state proofs without a key;
- a method with no proof: a call or override the client’s EVM doesn’t run,
such as an override with
movePrecompileToAddress, or any method not listed above.
Willow’s server has no filters, so the client’s filters have no server value
of their own. Under flag, a log filter whose logs can’t be verified returns
the server’s eth_getLogs over the same blocks. Anything else a filter can’t
verify, such as a block filter’s new blocks, raises WillowUnverifiableError
under either setting.
A proof that fails verification always raises WillowVerificationError, under
either setting. It means the server sent something false or Willow has a bug,
and either one must stop the app.
Errors
Section titled “Errors”Every error the client raises has code, message, and data. Decide by
data.kind, never by the message.
| Error | Code | Meaning |
|---|---|---|
WillowVerificationError | -32098 | A proof failed verification. Never passed through, under either unverifiable setting. |
WillowUnverifiableError | -32099 | The client can’t verify a value, and unverifiable is throw. |
WillowRpcError | The server’s, or the client’s own | A refusal from the server, passed through as sent; a request or option the client refuses itself, such as bad params or a chainId over 32 bits (-32602); or a revert (code 3, with its data) that the client computed itself from a call proof. |
data.kind of WillowVerificationError (-32098):
data.kind | What failed |
|---|---|
header, wrong-block, wrong-chain, transactions, receipts, withdrawals, uncles, missing, wrong-item, broken-link, wrong-range, body, unknown-formula, malformed | A block, fee, transaction, or receipt proof. |
account, slot, code, history, missing-read, outcome, estimate, algorithm, limits | A state, call, or estimate proof. |
parent, disagrees, too-large, no-trace, and the kinds above | A trace proof. |
logs | A log proof. |
rejected | A proof, in a verifier build that doesn’t report the kind. |
anchor-rejected, anchor-malformed | The anchor’s data. |
anchor-mismatch | Ethereum attests another hash for the block. |
anchor-head | latest or finalized was anchored by the wrong path. |
batch | A batch response without an item that was requested, or with one twice. |
tx-hash | The server’s transaction hash isn’t the hash of the transaction’s bytes. |
internal | A verifier failed to run, so the client fails closed. |
data.kind of WillowUnverifiableError (-32099):
data.kind | Why |
|---|---|
tag | safe or finalized on an L2. |
method | A value from a method with no proof. |
not-on-plan | The proof method isn’t served for this key or path (-32601). |
logs-range, logs-timeout, logs-job-failed | eth_getLogs over more than 8 blocks, with no log proof for the key, none in time, or a proof job that failed. |
no-verifier | A verifier module is missing from this build. |
anchor-level | The block is anchored below minLevel, or latest on an L2 with minLevel above signed. |
anchor-waiting | The block’s anchor was still waiting for the light client after anchorWaitMs. |
anchor-stale-head, anchor-not-covered, anchor-declined, anchor-disputed, anchor-unreachable, anchor-stale-checkpoint, anchor-unknown-fork, anchor-refused | The block can’t be anchored now. A stale or replayed head lands here, since it can’t forge a value. |
Events
Section titled “Events”onVerification receives one event per response:
{ method, status, chainId, block?, level?, kind?, detail?, flags?, unproven?, ms }status:verified(built from verified proofs),local(served by the client itself),absent(anullor a not-found passed through),refused(a server error passed through),unverifiable(returned underflag, withflags), orfailed(an error was raised).block,level: the block the response was verified at, the newest when there are several, and the lowest anchor level it rests on.kind,detail,flags: why a response is unverifiable or failed, the first reason and all of them.unproven: the fields the proofs don’t cover, which were left out of the response.
Trust assumptions
Section titled “Trust assumptions”- Ethereum’s sync committee. A false Ethereum chain needs the signatures of 342 of the 512 members of the current sync committee. This is the light client assumption. The testnets rest on Sepolia’s sync committee in the same way.
- BNB Smart Chain’s validators. A false BNB Smart Chain needs the votes of two thirds of its validator set. The light client refuses a starting point older than 7 days, BNB Smart Chain’s unbonding period, within which the validators of its set still hold their stake.
- Ethereum’s history before the Merge, through the root of EIP-7643’s historical hashes accumulator, which the client pins. Anyone can recompute it from the pre-Merge headers.
- The checkpoint, which ships with the package’s code, or the one passed
in
checkpoint(and for the testnets and BNB Smart Chain,sepoliaCheckpointandbnbStart). What the client keeps between runs is verified again from it. Once the shipped checkpoint is 29 days old, the client takes a newer one fromcheckpointUrl. In Node, at least one of thebeaconApismust confirm it and none may disagree, so a false one needs Willow and every beacon API that serves that slot to agree on it. In browsers nothing confirms it, so a newer package, or acheckpointof the app’s own, avoids relying on that one read. Newer starting points for the testnets and BNB Smart Chain come from the same file with nothing to confirm them, in Node too;sepoliaCheckpointandbnbStartavoid relying on them. - On the L2s, the party behind each level: the sequencer for
signed, the proposer and its bond forcommitted, and forfinalthe chain’s fault proofs and governance, as for any withdrawal to Ethereum. - Keccak-256 and the chain’s signature scheme, as the chain itself relies on them.
- The client’s code: its EVM and the Ethereum upgrades it knows, the fee formula, and the rules that render standard responses from proven bytes. A network upgrade that changes these needs a newer version of the package.
Beyond that one read, the client does not trust Willow’s servers, Willow’s providers, or public nodes.
Requests and data
Section titled “Requests and data”An app request takes at most one round trip, plus one more for a block new to
the client, whose anchor goes out with the proof when the block number is known
in advance. The client also anchors each chain’s head once per
headMaxAgeMs. In testing, Ethereum’s head anchor was about 5 KB of JSON, and
an L2’s 68 to 147 KB. Block anchors and the light-client methods cost 0
units. Other proof responses are metered in units (see
Units and pricing). On Ethereum, the fee proof behind
eth_gasPrice carries four whole blocks, about 55 units with gzip in testing,
once for each new head the client anchors. A trace of a whole Ethereum block is
verified from a proof of 5 to 6 MB gzipped, about 1,250 to 1,540 units in
testing (see Trace proofs).