Skip to content

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.

Terminal window
npm install @willow-network/rpc

The 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.

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.

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.

OptionDefaultDescription
chainIdRequiredThe 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.
keypublicThe 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.
urlhttps://api.willow.tech/v1/rpc/{chainId}/{key}The RPC URL.
lightClientUrlurl with chain 1Ethereum’s route, from which the light client reads.
minLevelsignedThe lowest anchor level a response may rest on: signed, committed, or final.
unverifiablethrowWhat 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.
onVerificationNoneCalled once for every response. See Events.
headMaxAgeMs12000 on Ethereum, 2000 on the other chainsHow long the newest anchored block is used before the client anchors the chain’s head again.
maxHeadAgeSec600The oldest that the newest block Willow anchors may be, in seconds.
checkpointThe shipped oneThe light client’s starting point on Ethereum, {root, slot}.
checkpointUrlhttps://api.willow.tech/verify/checkpoint.jsonWhere 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.
sepoliaCheckpointThe shipped oneThe Sepolia light client’s starting point, {root, slot}, for the six testnets. Read from checkpointUrl once the shipped one is 29 days old.
bnbStartThe shipped oneBNB 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.
beaconApispublicnode’s and ChainSafe’s beacon APIs in Node, none in browsersBeacon 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.
storagelocalStorage in browsers, ~/.cache/willow-rpc/ in NodeWhere the light client keeps the sync committees it verified. They are verified again when read. false keeps nothing.
workertrue in browsers, false in NodeWhether the verifiers run in a Web Worker.
batchWindowMs5Requests this many milliseconds apart go out as one JSON-RPC batch, of at most 100 items.
logsTimeoutMs120000How long eth_getLogs waits for Willow to prove blocks.
anchorWaitMs36000How long a request waits for the anchor of a block newer than the newest one anchored. See The newest block.
verifiersThe package’s modulesOther 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.

MethodVerification
eth_getBlockByNumber, eth_getBlockByHash, eth_getBlockTransactionCountByNumber, eth_getBlockTransactionCountByHashA block proof, cached by block hash. With true, each transaction’s from is recovered from its signature.
eth_blockNumberThe newest block the client has anchored.
eth_getBalance, eth_getTransactionCount, eth_getCode, eth_getStorageAt, eth_getProofA 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_blobBaseFeeOne fee proof at the anchored head, computed with the willow-fee-v1 formula.
eth_feeHistoryFee-history proofs, 16 blocks to a proof when rewards are requested.
eth_getTransactionByHash, eth_getTransactionByBlockHashAndIndex, eth_getTransactionByBlockNumberAndIndex, eth_getTransactionReceipt, eth_getBlockReceiptsTransaction and receipt proofs. An unknown transaction is null.
eth_getLogsUp 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_sendRawTransactionNo 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_uninstallFilterServed 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_accountsServed 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.

  • latest, pending, and an absent block are the chain’s anchored head.
  • finalized on Ethereum is the light client’s finalized block. safe on Ethereum is refused, as Willow’s server refuses it.
  • On BNB Smart Chain, latest is the newest block its validators voted final, so it is served at any minLevel.
  • finalized and safe on 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.

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.

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: signed once the validators sign a head whose history contains the block, and final once Ethereum finalizes it.
  • The L2s: signed by the chain’s sequencer, whose key the client reads from Ethereum (from Sepolia, for a testnet); committed once 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); and final once that claim settles, as for a withdrawal.
  • BNB Smart Chain: final once at least two thirds of the validator set vote it final, and signed before 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.

  • Ethereum, recent blocks. latest is 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): final once the light client’s finalized block reaches it, and signed before 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’s historical_roots before Capella and its historical_summaries from 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.

Absences and refusals can deny service, but they can’t forge a value, so they always pass through to the app, marked in onVerification:

  • null from eth_getTransactionReceipt and eth_getTransactionByHash, which viem’s waitForTransactionReceipt polls on;
  • the server’s JSON-RPC errors, such as -32601 for eth_call and eth_estimateGas on a chain where Willow doesn’t execute them, or for a trace method on a chain other than Ethereum and Unichain (a -32601 for 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:

  • finalized and safe on an L2;
  • eth_getLogs over 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.

Every error the client raises has code, message, and data. Decide by data.kind, never by the message.

ErrorCodeMeaning
WillowVerificationError-32098A proof failed verification. Never passed through, under either unverifiable setting.
WillowUnverifiableError-32099The client can’t verify a value, and unverifiable is throw.
WillowRpcErrorThe server’s, or the client’s ownA 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.kindWhat failed
header, wrong-block, wrong-chain, transactions, receipts, withdrawals, uncles, missing, wrong-item, broken-link, wrong-range, body, unknown-formula, malformedA block, fee, transaction, or receipt proof.
account, slot, code, history, missing-read, outcome, estimate, algorithm, limitsA state, call, or estimate proof.
parent, disagrees, too-large, no-trace, and the kinds aboveA trace proof.
logsA log proof.
rejectedA proof, in a verifier build that doesn’t report the kind.
anchor-rejected, anchor-malformedThe anchor’s data.
anchor-mismatchEthereum attests another hash for the block.
anchor-headlatest or finalized was anchored by the wrong path.
batchA batch response without an item that was requested, or with one twice.
tx-hashThe server’s transaction hash isn’t the hash of the transaction’s bytes.
internalA verifier failed to run, so the client fails closed.

data.kind of WillowUnverifiableError (-32099):

data.kindWhy
tagsafe or finalized on an L2.
methodA value from a method with no proof.
not-on-planThe proof method isn’t served for this key or path (-32601).
logs-range, logs-timeout, logs-job-failedeth_getLogs over more than 8 blocks, with no log proof for the key, none in time, or a proof job that failed.
no-verifierA verifier module is missing from this build.
anchor-levelThe block is anchored below minLevel, or latest on an L2 with minLevel above signed.
anchor-waitingThe 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-refusedThe block can’t be anchored now. A stale or replayed head lands here, since it can’t forge a value.

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 (a null or a not-found passed through), refused (a server error passed through), unverifiable (returned under flag, with flags), or failed (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.
  • 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, sepoliaCheckpoint and bnbStart). 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 from checkpointUrl. In Node, at least one of the beaconApis must 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 a checkpoint of 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; sepoliaCheckpoint and bnbStart avoid relying on them.
  • On the L2s, the party behind each level: the sequencer for signed, the proposer and its bond for committed, and for final the 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.

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).