Light Client Reference

Light client verification surface in the TypeScript SDK.

Current Status

Mode	Status	Notes
Mock verification	Available	deterministic hash-based verification for testing/integration
Real ZK verification	Not yet implemented	`LightClientVerifier.verifyBundle(..., 'real')` currently returns a stub error

Implementation source: sdk/ts/src/lightclient.ts

SDK Surface

import { LightClientVerifier } from '@rivellum/sdk';

const verifier = new LightClientVerifier({
  nodeUrl: 'https://rpc.rivellum.network',
  timeout: 30000,
});

Fetch Proof Bundle

const bundle = await verifier.fetchProofBundle('batch_0000000000000001');
console.log(bundle.batch.batchId, bundle.batch.height, bundle.traceProofs.length);

Current endpoint used by SDK:

GET /batches/:batchId/proof-bundle

Verify (Mock Mode)

const result = await verifier.verifyBundle(bundle, 'mock');

if (!result.verified) {
  throw new Error(result.error ?? 'mock verification failed');
}

console.log(result.details);

Verify (Real Mode)

const result = await verifier.verifyBundle(bundle, 'real');
console.log(result.verified, result.error);

Expected current behavior:

verified: false
error: "Real ZK verification not yet implemented. WASM verifier stub pending."

Data Types

Primary interfaces (from sdk/ts/src/types.ts):

LightClientProofBundle
ExecutionBatchSummary
TraceProof
BatchProof
VerificationResult
AccountStateProof (future)

Operational Guidance

Use mock mode for local testing, SDK integration tests, and UI workflow validation.
Do not treat real mode as production verification until WASM verifier lands.
Keep proof-bundle fetch and verification paths feature-flagged in production apps.

Related References

/docs/dev/sdk-guide
/docs/research/zk-pipeline
/docs/research/pouw-spec