Light Client
A client that verifies account state against a trusted block header without holding the chain. Storage is bounded by the number of distinct accounts it queries, not by chain length.
1. Formal Definition
A light client is a state-verification participant that holds three things: a trusted block header, a rolling window of headers extending that trust forward, and state proofs for the accounts it queries. It does not hold the chain, replay history, or download block bodies.
Definition 1.1 (Light Client)
A light client is a tuple:
LC = (H_anchor, W, Proofs, Cache)
where:
H_anchor ∈ Header Trusted header at some block B_0
W ⊆ Header Rolling window of verified headers
extending H_anchor forward
Proofs : Address → Proof State proofs cached per account
Cache : Address → State Verified state cached per account
Definition 1.2 (State verification)
For any account A and any header H ∈ W:
verify(A, H) = ⊤
⟺ Reconstruct(key(A), proof_H(A)) = H.account_commitment
∧ terminal.key = key(A)
If verify(A, H) = ⊤, then A's state at block H is authentic — no
trust in the peer that served the proof is required.The definition captures the security model precisely. The client trusts exactly one thing: its anchor header. Everything else — every peer, every proof, every state — is verified cryptographically before use.
2. Trust Model
The light client's trust is bounded and explicit. Three trust assumptions, no more.
Trusted (one-time, at bootstrap):
1. Anchor header H_anchor
Chosen either as a bundled checkpoint or as the endpoint of a
header chain verified back to a known ancestor. This is the only
trust assumption in the entire light client.
Trusted (continuous, per header):
2. PoW continuation
Each new header in W must extend H_anchor with valid PoW and
valid DAG structure. The deeper the confirmed chain on top of
H_anchor, the more secure the anchor becomes. This is
probabilistic finality — not an event.
3. Header structure
Each header in W must have valid parents, valid difficulty,
valid timestamps. These checks are identical to a full node's
header checks.
NOT trusted:
- RPC nodes (can lie arbitrarily; proofs verify or fail)
- Explorers (display only; no state attestation)
- DNS (can be hijacked; malicious peer still can't forge proofs)
- Block producers (proofs verify against header; producer has
no special trust weight)The second assumption is what makes the anchor trustable over time. A header with 10,000 blocks of PoW on top is much harder to reverse than a header with 10 blocks. The client chooses its confirmation depth based on the value at stake: a shallow depth for balance display, a deeper depth for high-value operations.
3. Header Verification
Before a header can be added to the window, the client runs four checks. These checks are the full extent of what the client trusts the network for.
Algorithm 3.1 (Header-Verify)
Input: H_new (proposed header), H_parent (declared parent)
Output: accept or reject
Step 1: Parent exists
if H_parent ∉ W ∪ {H_anchor}:
return reject
Step 2: PoW check
if not ValidPoW(H_new):
return reject
Step 3: Blue work progression
if H_new.blue_work ≤ H_parent.blue_work:
return reject
Step 4: Timestamp
if not ValidTimestamp(H_new, H_parent):
return reject
return acceptEach check defends against a specific attack:
Step 1 defends against: A header with a fabricated parent that
doesn't exist in the chain.
Step 2 defends against: A header whose PoW does not satisfy
its declared difficulty.
Step 3 defends against: A header that rolls back accumulated
work (impossible in an honest chain, but
a malicious peer could try).
Step 4 defends against: A header with an absurd timestamp that
would distort difficulty adjustment.4. State Proof Verification
Once a header is in the window, state verification against it is a local operation. The client recomputes the SMT root from a Merkle path and compares.
Algorithm 4.1 (State-Verify)
Input: account A, header H ∈ W, proof π = (siblings, terminal)
Output: state_A or reject
Step 1: Reconstruct root
h = HashTerminal(π.terminal)
for i in depth-1 downto 0:
if bit(key(A), i) = 0:
h = H_branch(h, π.siblings[i])
else:
h = H_branch(π.siblings[i], h)
Step 2: Compare to header
if h ≠ H.account_commitment:
return reject
Step 3: Check key
if π.terminal.kind = Leaf:
if π.terminal.key ≠ key(A):
return reject
return state_at(π.terminal.value)
if π.terminal.kind = Empty:
return absent (A has no state at H)
Step 4: (exclusion case — see below)Verification cost is O(depth) hash operations, where depth is the compressed SMT depth (typically under 64, worst case 256). On any device from the last decade, this is under 1 millisecond.
5. Bootstrap
The client's first action is to obtain a trusted anchor. Two approaches are supported:
Approach A: Bundled checkpoint
The client ships with a known-good header embedded in the
binary. This header is trusted implicitly — if it is corrupted
or malicious, the entire light client is compromised.
Pros: Instant bootstrap, no network required at install time
Cons: The bundle must be updated frequently, or it becomes
stale. If the bundle is manipulated at distribution time,
the client is compromised.
Approach B: Chain back to known ancestor
The client ships with a checkpoint from a few months ago.
On first startup, it downloads headers from that checkpoint
to the current tip, verifying each one.
Pros: The shipped checkpoint can be old (older = more
accumulated PoW on it = more secure)
Cons: Bootstrap requires network access and a few seconds
to minutes of verification
Sahyadri default: Approach B. The shipped checkpoint is a few
months old, verified by accumulated PoW at bootstrap. A client
that has not been used for a long time will re-run bootstrap
against the latest checkpoint.6. Storage Bounds
The light client's storage is bounded by the number of distinct accounts it queries, not by chain length. This is the primary property that makes light clients useful on constrained devices.
| Component | Size | Notes |
|---|---|---|
| Header window | ~1 MB | Last 10,000 headers (~12 hours at 1 BPS) |
| Per account cache | ~200 bytes | SPK, balance, flash count |
| Per account proof (transient) | ~1 KB | Not persisted after verification |
| Peer list | ~50 KB | Rotated periodically |
| Total, 100 accounts, 1 year | < 5 MB | Independent of chain length |
| Total, 10,000 accounts, 5 years | ~50 MB | Still bounded |
The key invariant: storage = O(window + distinct accounts), independent of chain length. A full node that has processed the same period of activity would store orders of magnitude more.
7. Sync Flow
Flow 7.1 (Client bootstrap and steady-state sync)
On startup:
1. Load bundled checkpoint from local storage
2. Download headers from checkpoint to current tip
3. Verify each header via Algorithm 3.1
4. Add accepted headers to W
5. Prune headers older than confirmation depth
6. W is now trusted to current depth
Per account query:
1. Pick deepest header H_deep in W (or user-chosen depth)
2. If cache[A] exists at H_deep: return cached
3. Else: request proof from any peer
4. Verify proof against H_deep.account_commitment
5. If valid: cache result, return
6. If invalid: rotate peer, retry
Cache eviction:
- Cache invalidated when anchor advances past queried depth
- Re-verify on next query against new anchor
- No persistence beyond current anchor8. Verification Cost
| Operation | Time | Space |
|---|---|---|
| Header verification (per header) | ~10 µs | O(1) |
| State proof verification | ~0.5 ms | O(depth) |
| Bootstrap (12 months of headers) | ~5 s | ~1 MB |
| Per account query (network) | ~50-200 ms | ~1 KB transient |
| Per account query (cached) | ~1 µs | ~200 B |
The dominant cost for a light client is network round-trip for proofs, not the verification itself. Verification is cheap enough to run thousands of times per second on a phone.
9. Comparison with Full Node
| Property | Full Node | Light Client |
|---|---|---|
| Storage | GBs, grows with chain | MBs, bounded by window + queries |
| Bandwidth | Full blocks, full DAG | Headers + proofs on demand |
| Sync time | Hours to days | Seconds |
| Verifies | Everything | Only what it queries |
| Trusts | PoW + DAG rules | Anchor header + PoW continuation |
| Can produce blocks | Yes | No |
| Can serve proofs | Yes | No |
| Runs on | Server, desktop | Phone, browser, IoT |
10. Limitations
What a light client cannot do, stated plainly.
Limitation 10.1: Cannot produce blocks A light client has no view of the full DAG. It cannot mine, cannot fully validate blocks, and cannot participate in consensus. Limitation 10.2: Cannot relay to others A light client's network view is narrow. Full nodes are needed for network propagation and peer discovery. Limitation 10.3: Trusts its initial anchor The very first header a light client adopts comes from somewhere — a bundled checkpoint, a peer, or a bootstrap. This is a one-time trust assumption, but a real one. If the initial anchor is corrupted, all subsequent verification is compromised. Limitation 10.4: Does not see the mempool Light clients cannot observe unconfirmed transactions or estimate fees. They see only what is in the headers they trust. Limitation 10.5: Requires a proof-serving peer If no peer serves proofs, the light client is stuck. Any full node can serve, so this is an availability concern, not a trust concern. Limitation 10.6: Probabilistic finality A trusted header can, in principle, be reorged out. The client should wait for a confirmation depth matching the value at stake before treating state as final. Limitation 10.7: No transaction submission A light client cannot submit transactions directly. It must delegate to a full node for broadcast.
11. Pruning and Retention
A Sahyadri full node prunes old state to maintain a bounded footprint. Light clients interact with this differently depending on whether they need historical state or only current state.
Retention parameters (mainnet):
Finality depth: 43,200 blocks (~12 hours at 1 BPS)
Pruning depth: 108,000 blocks (~30 hours at 1 BPS)
Effect:
- Blocks within finality depth: fully available
- Blocks between finality and pruning: available if node chose
to retain, otherwise not
- Blocks beyond pruning: deleted from regular nodes; available
only from archive nodes
Light client implications:
For current state: query any regular node
For historical state: query archive node (if archive is honest)
or verify against a header the client retains
A light client that keeps a header from a historical block can
still verify historical state — but only if some node serves the
proof. The proof itself is valid forever; the availability of the
proof depends on some node having retained the SMT nodes.12. Use Cases
The light client enables four classes of application that are otherwise impractical on constrained devices.
13. Roadmap
What is implemented, and what is pending.
| Component | Status | Notes |
|---|---|---|
| SMT inclusion proofs | Implemented | Tested against verify_inclusion in crypto/smt |
| SMT exclusion proofs | Implemented | Tested against verify_exclusion |
| Header verification | Implemented | Same code path as full node's header check |
| get_account_proof RPC | Implemented | Serves proofs on demand from any full node |
| Rolling header sync | In progress | Phase 5c: header-only stream protocol |
| WASM light client SDK | In progress | Phase 5d: browser + mobile targets |
| Reference CLI client | Pending | Phase 5e |
| Rust no_std client | Pending | Phase 5f: embedded targets |
| Batch proof API | Pending | Phase 5g: one RPC, N accounts |
14. Summary
A light client verifies account state against a trusted block header without downloading the chain. Storage is bounded by the number of distinct accounts queried, not by chain length. Verification cost is O(depth) in the SMT — typically under 1 millisecond per account.
The client's only trust assumption is its anchor header. Everything else — every peer, every proof, every state — is verified cryptographically before use. This is what makes Sahyadri usable on phones, browsers, and embedded devices without any trust in a third party.
The protocol's commitment to pure-function, content-addressed state is what enables the light client. Without it, verifying state would require either the full chain or trust in a node. With it, verification is a local hash computation that any device can perform.