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 accept

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

ComponentSizeNotes
Header window~1 MBLast 10,000 headers (~12 hours at 1 BPS)
Per account cache~200 bytesSPK, balance, flash count
Per account proof (transient)~1 KBNot persisted after verification
Peer list~50 KBRotated periodically
Total, 100 accounts, 1 year< 5 MBIndependent of chain length
Total, 10,000 accounts, 5 years~50 MBStill 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 anchor

8. Verification Cost

OperationTimeSpace
Header verification (per header)~10 µsO(1)
State proof verification~0.5 msO(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

PropertyFull NodeLight Client
StorageGBs, grows with chainMBs, bounded by window + queries
BandwidthFull blocks, full DAGHeaders + proofs on demand
Sync timeHours to daysSeconds
VerifiesEverythingOnly what it queries
TrustsPoW + DAG rulesAnchor header + PoW continuation
Can produce blocksYesNo
Can serve proofsYesNo
Runs onServer, desktopPhone, 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.

Mobile Wallets
Verify balances and transaction history without a backend. Every displayed number comes from a proof the phone checked itself.
Browser Extensions
A wallet or DID manager runs entirely in the browser tab, verifying state as needed. No background node, no daemon.
IoT Devices
A sensor verifies firmware update signatures via state proofs without running a full node.
Cross-Chain Relayers
A relayer between Sahyadri and another chain holds one anchor header plus proofs for messages it forwards. Storage stays bounded regardless of Sahyadri's activity.

13. Roadmap

What is implemented, and what is pending.

ComponentStatusNotes
SMT inclusion proofsImplementedTested against verify_inclusion in crypto/smt
SMT exclusion proofsImplementedTested against verify_exclusion
Header verificationImplementedSame code path as full node's header check
get_account_proof RPCImplementedServes proofs on demand from any full node
Rolling header syncIn progressPhase 5c: header-only stream protocol
WASM light client SDKIn progressPhase 5d: browser + mobile targets
Reference CLI clientPendingPhase 5e
Rust no_std clientPendingPhase 5f: embedded targets
Batch proof APIPendingPhase 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.