Consensus Light Client
Verify Ethereum state without running a full node. These packages implement the beacon chain light client sync protocol, BLS signature verification, SSZ serialization, and Merkle proof-based state verification — giving you cryptographically verified balances, nonces, storage, and contract code using only a beacon chain API and a standard RPC endpoint.
The Simple Path
using Nethereum.ChainStateVerification.Interceptor;
var web3 = new Web3("https://mainnet.rpc.url")
.UseVerifiedState(verifiedStateService);
// All queries are now cryptographically verified via Merkle proofs
var balance = await web3.Eth.GetBalance.SendRequestAsync(address);
The UseVerifiedState() extension intercepts RPC calls and verifies responses against the light client's trusted state root. No changes to your existing web3.Eth code — just add one line.
| Intercepted Method | What's Verified |
|---|---|
eth_getBalance | Account balance via account proof |
eth_getTransactionCount | Account nonce via account proof |
eth_getCode | Contract bytecode via account proof + code hash |
eth_blockNumber | Returns the light client's verified block number |
What Can I Do?
| I want to... | Guide |
|---|---|
| Verify balances, nonces, and contract code without trusting my RPC | Verified State Queries |
Use web3.Eth with automatic proof verification | Verified State Queries |
| Query verified storage slots and ERC-20 balances via proofs | Verified State Queries |
| Understand the light client protocol (sync committees, BLS, staleness) | Beacon Chain Light Client |
| Customize light client behavior (staleness thresholds, persistence) | Beacon Chain Light Client |
Guides
| Guide | What You'll Learn |
|---|---|
| Verified State Queries | Initialize the light client stack, use UseVerifiedState() for transparent proof verification, query balances/nonces/storage directly, finalized vs optimistic modes |
| Beacon Chain Light Client | How sync committees and BLS signatures work, configuration for different chains, update lifecycle, staleness detection, state persistence |
Packages
| Package | Description |
|---|---|
Nethereum.Beaconchain | Beacon Chain REST API client for light client bootstrap, sync updates, and finality data |
Nethereum.Consensus.LightClient | Light client sync protocol — initialization, updates, trusted header tracking, staleness detection |
Nethereum.ChainStateVerification | Verified state queries with Merkle proof verification, RPC interceptor, caching |
Nethereum.Consensus.Ssz | SSZ container types for beacon headers, sync committees, and light client messages |
Nethereum.Ssz | Core SSZ encoding/decoding and merkleization primitives |
Supporting Packages
These packages are dependencies used by the light client stack but documented in other sections:
| Package | Section | Role |
|---|---|---|
Nethereum.Signer.Bls.Herumi | Signing & Key Management | BLS12-381 signature verification (native Herumi library) |
Nethereum.Merkle.Patricia | Core Foundation | Patricia trie proof verification for account and storage proofs |
Supported Chains
| Chain | Chain ID | Status |
|---|---|---|
| Ethereum Mainnet | 1 | Fully supported |
| Sepolia | 11155111 | Fully supported |
| Holesky | 17000 | Fully supported |