Skip to content

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.

Terminal window
cargo add willow-rpc

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

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.

Config::new(chain_id) takes the same options as the npm client, as builder methods:

Methodnpm optionDefault
keykeypublic
urlurlhttps://api.willow.tech/v1/rpc/{chainId}/{key}
light_client_urllightClientUrlurl with chain 1
min_levelminLevelLevel::Signed
unverifiableunverifiableUnverifiable::Throw
on_verificationonVerificationNone
head_max_ageheadMaxAgeMs12 s on Ethereum, 2 s on the other chains
max_head_agemaxHeadAgeSec600 s
checkpoint, sepolia_checkpoint, bnb_startcheckpoint, sepoliaCheckpoint, bnbStartThe shipped ones
checkpoint_url, beacon_apischeckpointUrl, beaconApisWillow’s checkpoint.json, and publicnode’s and ChainSafe’s beacon APIs
storagestorage~/.cache/willow-rpc/, the same files the npm client uses in Node
batch_windowbatchWindowMs5 ms
logs_timeoutlogsTimeoutMs120 s
anchor_waitanchorWaitMs36 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, or Anchoring::None to leave block hashes unverified. Every event says which one a response rests on.
  • openvm_verifier: where OpenVM log proofs are verified (below).

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.

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.