@unconfirmed/kei 0.0.1

package/README.md

@@ -0,0 +1,213 @@
+# Kei
+
+Lightweight Sui light client in pure TypeScript. Verify checkpoint signatures, committee transitions, and transaction inclusion using BLS12-381.
+
+## Why
+
+Sui fullnodes return data, but how do you know it's correct? Kei verifies responses cryptographically by checking that checkpoint summaries are signed by a quorum of validators, then proving that transactions and objects are included in those certified checkpoints.
+
+No native dependencies — works in browsers, Cloudflare Workers, Bun, and Node.js.
+
+## How it works
+
+Sui validators sign checkpoint summaries using BLS12-381 aggregate signatures. A checkpoint is valid if validators holding ≥66.67% of voting power (6667/10000) have signed it. Kei:
+
+1. **Decodes the signers bitmap** (RoaringBitmap) to identify which validators signed
+2. **Aggregates their BLS public keys** (G2 points in min-sig mode)
+3. **Verifies the aggregate signature** against the BCS-serialized checkpoint summary
+4. **Validates quorum** — total voting power of signers must meet the threshold
+
+Once a checkpoint is verified, any data committed to it (transactions, objects, events) can be trusted via hash chains.
+
+```
+Genesis → Committee₀ → verify Checkpoint₀ → Committee₁ → verify Checkpoint₁ → ...
+                         ↓
+                   ContentDigest → CheckpointContents → TransactionDigest
+```
+
+## Performance
+
+| Operation | Time | Notes |
+|-----------|------|-------|
+| `PreparedCommittee` init | ~118ms | One-time per epoch (~24h), parses all G2 pubkeys |
+| Checkpoint verification | **~11ms** | With `PreparedCommittee` |
+| Cold verification | ~188ms | Without pre-parsed keys |
+| Throughput | **~88 checkpoints/sec** | Single core, prepared committee |
+
+No WASM needed. The bottleneck was G2 point deserialization, not the BLS pairing math — `PreparedCommittee` pre-parses all public keys once per epoch, making per-checkpoint aggregation <1ms (point additions instead of decompression).
+
+## CLI
+
+Try it out against live checkpoints:
+
+```sh
+# Set your fullnode endpoint
+export GRPC_URL=https://fullnode.testnet.sui.io
+export NETWORK=testnet
+
+# Verify a single checkpoint
+bun src/cli.ts verify 318460000
+
+# Verify a range (uses PreparedCommittee for bulk speed)
+bun src/cli.ts verify-range 318460000 318460009
+
+# Or pass as flags
+bun src/cli.ts verify 318460000 --network testnet --url https://fullnode.testnet.sui.io
+```
+
+```
+$ bun src/cli.ts verify-range 318460000 318460009
+
+Verifying 10 checkpoints (318460000 → 318460009)
+
+Fetching first checkpoint... epoch 1052 (204ms)
+Preparing committee... 118 validators, 232ms
+
+  [1/10]  seq=318460000  signers=74  fetch=111ms  verify=78ms
+  [2/10]  seq=318460001  signers=73  fetch=95ms   verify=11ms
+  [3/10]  seq=318460002  signers=76  fetch=176ms  verify=11ms
+  ...
+  [10/10] seq=318460009  signers=75  fetch=96ms   verify=10ms
+
+10 checkpoints verified in 1.3s
+Avg verify: 17.4ms/checkpoint
+Throughput: 7.5 checkpoints/sec (including network)
+```
+
+## Usage
+
+```typescript
+import {
+  verifyCheckpoint,
+  PreparedCommittee,
+} from '@unconfirmed/kei';
+
+// Build committee from validator data (once per epoch)
+const committee = {
+  epoch: 1052n,
+  members: validators.map(({ publicKey, votingPower }) => ({
+    publicKey, // 96-byte BLS12-381 G2 compressed
+    votingPower,
+  })),
+};
+
+// Pre-parse for fast bulk verification
+const prepared = new PreparedCommittee(committee);
+
+// Verify using the raw BCS bytes from the gRPC response
+// (the exact bytes validators signed — no re-serialization)
+verifyCheckpoint(summaryBcsBytes, authSignature, prepared);
+// Throws on invalid signature or insufficient quorum
+```
+
+### With Sui gRPC API
+
+```typescript
+import { SuiGrpcClient } from '@mysten/sui/grpc';
+import { verifyCheckpoint, PreparedCommittee } from '@unconfirmed/kei';
+
+const client = new SuiGrpcClient({ network: 'testnet', baseUrl: 'https://fullnode.testnet.sui.io' });
+
+// Fetch checkpoint with BCS summary + validator signature
+const { response } = await client.ledgerService.getCheckpoint({
+  checkpointId: { oneofKind: 'sequenceNumber', sequenceNumber: '318460000' },
+  readMask: { paths: ['summary.bcs', 'signature'] },
+});
+
+const cp = response.checkpoint!;
+
+// Build auth signature from gRPC response
+const authSignature = {
+  epoch: cp.signature!.epoch!,
+  signature: cp.signature!.signature!,   // 48-byte BLS aggregate sig
+  signersMap: cp.signature!.bitmap!,      // RoaringBitmap of signer indices
+};
+
+// Verify using raw BCS bytes
+verifyCheckpoint(cp.summary!.bcs!.value!, authSignature, prepared);
+```
+
+### Committee transitions
+
+```typescript
+import { verifyCommitteeTransition, walkCommitteeChain, parseBcsSummary } from '@unconfirmed/kei';
+
+// Parse the summary to read endOfEpochData
+const summary = parseBcsSummary(summaryBcsBytes);
+
+// Verify a single epoch transition from an end-of-epoch checkpoint
+const nextCommittee = verifyCommitteeTransition(summaryBcsBytes, summary, authSignature, currentCommittee);
+
+// Walk a chain of end-of-epoch checkpoints to advance multiple epochs
+const latestCommittee = walkCommitteeChain(endOfEpochCheckpoints, trustedCommittee);
+```
+
+## Cryptographic details
+
+| Component | Implementation |
+|-----------|---------------|
+| Signature scheme | BLS12-381 min-sig (G2 pubkeys 96 bytes, G1 sigs 48 bytes) |
+| Hash function | Blake2b-256 with struct name domain separators |
+| Serialization | BCS (Binary Canonical Serialization) |
+| Signers bitmap | RoaringBitmap (standard portable format) |
+| Quorum threshold | 6667/10000 (Byzantine 2f+1) |
+
+### Signed message format
+
+```
+[0x02, 0x00, 0x00]              Intent: scope=CheckpointSummary, version=V0, app=Sui
+|| BCS(CheckpointSummary)       The checkpoint data
+|| epoch (u64 LE)               Appended epoch
+```
+
+### Digest computation
+
+All Sui digests follow: `Blake2b-256("StructName::" || BCS(struct))`
+
+## API
+
+### `verifyCheckpoint(summaryBcs, authSignature, committee)`
+
+Verify a checkpoint certificate using raw BCS bytes. Throws on failure.
+
+### `PreparedCommittee`
+
+Pre-parses G2 public keys for fast bulk verification. Create once per epoch.
+
+### `parseBcsSummary(bcsBytes)`
+
+Parse raw BCS bytes into a typed `CheckpointSummary`.
+
+### `verifyCheckpointContents(summary, contents)`
+
+Verify that checkpoint contents match the content digest in the summary.
+
+### `verifyTransactionInCheckpoint(txDigest, contents)`
+
+Prove a transaction exists in checkpoint contents. Returns the execution digests.
+
+### `verifyCommitteeTransition(summaryBcs, summary, authSignature, committee)`
+
+Verify an epoch transition and extract the next committee.
+
+### `walkCommitteeChain(checkpoints, trustedCommittee)`
+
+Walk multiple epoch transitions from a trusted starting committee.
+
+### BCS schemas
+
+`bcsCheckpointSummary`, `bcsCheckpointContents`, `bcsAuthorityQuorumSignInfo` — for parsing raw BCS bytes from gRPC responses.
+
+### Utilities
+
+`suiDigest(structName, bcsBytes)`, `decodeRoaringBitmap(data)`, `digestsEqual(a, b)`, and specific digest helpers (`checkpointDigest`, `transactionDigest`, etc.).
+
+## Dependencies
+
+- [`@noble/curves`](https://github.com/paulmillr/noble-curves) — BLS12-381 (audited, pure JS)
+- [`@noble/hashes`](https://github.com/paulmillr/noble-hashes) — Blake2b-256 (audited, pure JS)
+- [`@mysten/bcs`](https://github.com/MystenLabs/sui/tree/main/sdk/bcs) — BCS serialization
+
+## License
+
+Apache-2.0

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@unconfirmed/kei",
+  "version": "0.0.1",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": ["dist"],
+  "bin": {
+    "kei": "src/cli.ts"
+  },
+  "scripts": {
+    "build": "bun build src/index.ts --outdir dist --target node",
+    "test": "bun test",
+    "verify": "bun src/cli.ts verify"
+  },
+  "dependencies": {
+    "@mysten/bcs": "^1.3.0",
+    "@noble/curves": "^1.8.0",
+    "@noble/hashes": "^1.7.0"
+  },
+  "devDependencies": {
+    "@mysten/sui": "^2.13.0",
+    "bun-types": "^1.3.11"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,195 @@
+#!/usr/bin/env bun
+/**
+ * CLI for testing Sui light client verification against live checkpoints.
+ *
+ * Usage:
+ *   bun src/cli.ts verify <checkpoint_seq> [--url <fullnode_url>]
+ *   bun src/cli.ts verify-range <from> <to> [--url <fullnode_url>]
+ */
+
+import { decodeRoaringBitmap } from './bitmap.js';
+import { verifyCheckpoint, PreparedCommittee } from './verify.js';
+import type { Committee, AuthorityQuorumSignInfo } from './types.js';
+
+type Network = 'testnet' | 'mainnet';
+
+function usage(): never {
+	console.log(`Usage:
+  sui-light-client verify <checkpoint_seq> --network <testnet|mainnet> --url <grpc_url>
+  sui-light-client verify-range <from> <to> --network <testnet|mainnet> --url <grpc_url>
+
+Environment variables (override flags):
+  GRPC_URL    — fullnode gRPC endpoint
+  NETWORK     — testnet or mainnet
+
+Examples:
+  bun src/cli.ts verify 318460000 --network testnet --url https://fullnode.testnet.sui.io
+  GRPC_URL=https://fullnode.testnet.sui.io NETWORK=testnet bun src/cli.ts verify 318460000`);
+	process.exit(1);
+}
+
+function getFlag(args: string[], flag: string): string | undefined {
+	const idx = args.indexOf(flag);
+	return idx !== -1 ? args[idx + 1] : undefined;
+}
+
+function parseArgs() {
+	const args = process.argv.slice(2);
+	if (args.length === 0) usage();
+
+	const command = args[0];
+	const network = (process.env.NETWORK || getFlag(args, '--network')) as Network | undefined;
+	const url = process.env.GRPC_URL || getFlag(args, '--url');
+
+	if (!network || !url) {
+		console.error('Error: --network and --url are required (or set NETWORK and GRPC_URL env vars)\n');
+		usage();
+	}
+
+	if (command === 'verify') {
+		const seq = args[1];
+		if (!seq || isNaN(Number(seq))) usage();
+		return { command: 'verify' as const, seq: Number(seq), network, url };
+	}
+
+	if (command === 'verify-range') {
+		const from = args[1];
+		const to = args[2];
+		if (!from || !to || isNaN(Number(from)) || isNaN(Number(to))) usage();
+		return { command: 'verify-range' as const, from: Number(from), to: Number(to), network, url };
+	}
+
+	usage();
+}
+
+interface GrpcCheckpoint {
+	summary: { bcs: { value: Uint8Array } };
+	signature: { epoch: bigint; signature: Uint8Array; bitmap: Uint8Array };
+}
+
+let _grpcClient: InstanceType<typeof import('@mysten/sui/grpc').SuiGrpcClient> | null = null;
+async function getGrpcClient(network: Network, url: string) {
+	if (_grpcClient) return _grpcClient;
+	const { SuiGrpcClient } = await import('@mysten/sui/grpc');
+	_grpcClient = new SuiGrpcClient({ network, baseUrl: url });
+	return _grpcClient;
+}
+
+async function fetchCheckpoint(network: Network, url: string, seq: number): Promise<GrpcCheckpoint> {
+	const client = await getGrpcClient(network, url);
+	const { response } = await client.ledgerService.getCheckpoint({
+		checkpointId: { oneofKind: 'sequenceNumber', sequenceNumber: BigInt(seq) },
+		readMask: { paths: ['summary.bcs', 'signature'] },
+	});
+	return response.checkpoint as unknown as GrpcCheckpoint;
+}
+
+async function fetchCommittee(url: string, epoch: string): Promise<Committee> {
+	const resp = await fetch(url, {
+		method: 'POST',
+		headers: { 'Content-Type': 'application/json' },
+		body: JSON.stringify({
+			jsonrpc: '2.0', id: 1,
+			method: 'suix_getCommitteeInfo',
+			params: [epoch],
+		}),
+	});
+	const json = (await resp.json()) as { result: { validators: [string, string][] } };
+	return {
+		epoch: BigInt(epoch),
+		members: json.result.validators.map(([pk, stake]) => ({
+			publicKey: new Uint8Array(Buffer.from(pk, 'base64')),
+			votingPower: BigInt(stake),
+		})),
+	};
+}
+
+function extractAuthSignature(cp: GrpcCheckpoint): AuthorityQuorumSignInfo {
+	return {
+		epoch: cp.signature.epoch,
+		signature: cp.signature.signature,
+		signersMap: cp.signature.bitmap,
+	};
+}
+
+async function verifySingle(seq: number, network: Network, url: string) {
+	const total = performance.now();
+
+	process.stdout.write(`Fetching checkpoint ${seq}...`);
+	let t = performance.now();
+	const cp = await fetchCheckpoint(network, url, seq);
+	console.log(` ${(performance.now() - t).toFixed(0)}ms`);
+
+	const summaryBcs = cp.summary.bcs.value;
+	const authSignature = extractAuthSignature(cp);
+	const signers = decodeRoaringBitmap(authSignature.signersMap);
+
+	process.stdout.write(`Fetching committee for epoch ${authSignature.epoch}...`);
+	t = performance.now();
+	const committee = await fetchCommittee(url, authSignature.epoch.toString());
+	console.log(` ${(performance.now() - t).toFixed(0)}ms (${committee.members.length} validators)`);
+
+	process.stdout.write(`Verifying signature (${signers.length} signers)...`);
+	t = performance.now();
+	verifyCheckpoint(summaryBcs, authSignature, committee);
+	console.log(` ${(performance.now() - t).toFixed(0)}ms`);
+
+	console.log(`\nCheckpoint ${seq} verified in ${(performance.now() - total).toFixed(0)}ms`);
+}
+
+async function verifyRange(from: number, to: number, network: Network, url: string) {
+	const count = to - from + 1;
+	console.log(`Verifying ${count} checkpoints (${from} → ${to})\n`);
+
+	process.stdout.write('Fetching first checkpoint...');
+	let t = performance.now();
+	const firstCp = await fetchCheckpoint(network, url, from);
+	const firstAuth = extractAuthSignature(firstCp);
+	console.log(` epoch ${firstAuth.epoch} (${(performance.now() - t).toFixed(0)}ms)`);
+
+	process.stdout.write('Preparing committee...');
+	t = performance.now();
+	const committee = await fetchCommittee(url, firstAuth.epoch.toString());
+	const prepared = new PreparedCommittee(committee);
+	console.log(` ${committee.members.length} validators, ${(performance.now() - t).toFixed(0)}ms\n`);
+
+	let verified = 0;
+	let totalVerifyMs = 0;
+	const batchStart = performance.now();
+
+	for (let seq = from; seq <= to; seq++) {
+		t = performance.now();
+		const cp = await fetchCheckpoint(network, url, seq);
+		const fetchMs = performance.now() - t;
+
+		const authSignature = extractAuthSignature(cp);
+		const signers = decodeRoaringBitmap(authSignature.signersMap);
+
+		t = performance.now();
+		verifyCheckpoint(cp.summary.bcs.value, authSignature, prepared);
+		const verifyMs = performance.now() - t;
+		totalVerifyMs += verifyMs;
+		verified++;
+
+		console.log(`  [${verified}/${count}] seq=${seq} signers=${signers.length} fetch=${fetchMs.toFixed(0)}ms verify=${verifyMs.toFixed(0)}ms`);
+	}
+
+	const elapsed = performance.now() - batchStart;
+	console.log(`\n${verified} checkpoints verified in ${(elapsed / 1000).toFixed(1)}s`);
+	console.log(`Avg verify: ${(totalVerifyMs / verified).toFixed(1)}ms/checkpoint`);
+	console.log(`Throughput: ${(verified / (elapsed / 1000)).toFixed(1)} checkpoints/sec (including network)`);
+}
+
+async function main() {
+	const parsed = parseArgs();
+	if (parsed.command === 'verify') {
+		await verifySingle(parsed.seq, parsed.network, parsed.url);
+	} else {
+		await verifyRange(parsed.from, parsed.to, parsed.network, parsed.url);
+	}
+}
+
+main().catch((err) => {
+	console.error(err.message);
+	process.exit(1);
+});