Verifying client for Rust
willow-rpc is the Rust counterpart of the
verifying client. For each request, it fetches the
proof behind the response, verifies it on your machine with the same Rust
verifiers the verify page runs, verifies the
block with its own light client, and returns the standard JSON-RPC response
built from the proven data alone. A response that fails verification never
reaches your code as a value.
It covers the same methods, refuses the same requests, and raises the same
error codes as @willow-network/rpc, so the
method table,
anchoring,
errors and
trust assumptions on that page
apply here too.
Install
Section titled “Install”cargo add willow-rpcThe client runs on tokio. The verifiers are compiled in: there’s no WebAssembly runtime and nothing downloaded at run time.
WillowTransport is an alloy transport, so every call a provider makes is
verified:
use alloy_provider::{Provider, ProviderBuilder};use alloy_rpc_client::RpcClient;use willow_rpc::{alloy::WillowTransport, Config};
let key = std::env::var("WILLOW_KEY")?;let transport = WillowTransport::new(Config::new(1).key(key))?;let provider = ProviderBuilder::new().connect_client(RpcClient::new(transport, false));
// Verified against Ethereum's validators, or an error.let balance = provider.get_balance("0x00000000219ab540356cbb839cbe05303d7705fa".parse()?).await?;The alloy feature, on by default, is for alloy 2. For alloy 1, turn on the
alloy-v1 feature and use willow_rpc::alloy::v1::WillowTransport. The
client’s own errors reach alloy as JSON-RPC errors with their code and
data.kind.
Without alloy
Section titled “Without alloy”use serde_json::json;use willow_rpc::{Config, Verifier};
let willow = Verifier::new(Config::new(8453).key(key))?;let block = willow.request("eth_getBlockByNumber", json!(["latest", false])).await?;Verifier::request takes a method and its params and returns the standard
result, verified, or an Error. A Verifier is cheap to clone, and clones
share their caches and light clients.
Options
Section titled “Options”Config::new(chain_id) takes the same options as the npm client, as builder
methods:
| Method | npm option | Default |
|---|---|---|
key | key | public |
url | url | https://api.willow.tech/v1/rpc/{chainId}/{key} |
light_client_url | lightClientUrl | url with chain 1 |
min_level | minLevel | Level::Signed |
unverifiable | unverifiable | Unverifiable::Throw |
on_verification | onVerification | None |
head_max_age | headMaxAgeMs | 12 s on Ethereum, 2 s on the other chains |
max_head_age | maxHeadAgeSec | 600 s |
checkpoint, sepolia_checkpoint, bnb_start | checkpoint, sepoliaCheckpoint, bnbStart | The shipped ones |
checkpoint_url, beacon_apis | checkpointUrl, beaconApis | Willow’s checkpoint.json, and publicnode’s and ChainSafe’s beacon APIs |
storage | storage | ~/.cache/willow-rpc/, the same files the npm client uses in Node |
batch_window | batchWindowMs | 5 ms |
logs_timeout | logsTimeoutMs | 120 s |
anchor_wait | anchorWaitMs | 36 s |
Two more come from the willow-logs-verify CLI:
anchoring:Anchoring::LightClient(the default),Anchoring::Rpc(url)to compare each proven block’s hash with a node you trust, orAnchoring::Noneto leave block hashes unverified. Every event says which one a response rests on.openvm_verifier: where OpenVM log proofs are verified (below).
The checkpoint
Section titled “The checkpoint”Each release ships a starting point for its light clients, its Ethereum
checkpoint at most 10 days old when the release is cut. The light client
refuses a starting point more than 30 days old, so once the shipped one is 29
days old the client reads Willow’s checkpoint.json. It takes that checkpoint
only when it is newer than the shipped one and the beacon APIs confirm it: at
least one must serve the same root at that slot, and none may serve anything
else. One that can’t be reached or returns an HTTP error is skipped. If the
client can’t take one, anchored responses are unverifiable
(anchor-stale-checkpoint) until a later request can, the crate is updated,
or a checkpoint is passed with Config::checkpoint.
willow_rpc::checkpoint::shipped_checkpoint_expires() says when the shipped
one stops being used. Newer starting points for Sepolia (the testnets) and BNB
Smart Chain come from the same file without a beacon API to confirm them, so
an app that wants to trust neither passes its own with sepolia_checkpoint
and bnb_start.
Log proofs
Section titled “Log proofs”eth_getLogs over more than 8 blocks is verified by log proofs.
SP1 proofs are verified in the client. OpenVM proofs are verified by the
willow-logs-verify-openvm helper, which the client runs when it finds it
next to your executable or on PATH; it’s built from source, from
willow-verify. Without it,
an OpenVM-proven range is unverifiable (no-verifier). A helper that fails on
a proof fails that check, and the client starts it again for the next one.
Turning off the logs feature leaves SP1’s verifier out of the build too.