@unconfirmed/kei 0.0.1 → 0.0.2

package/dist/bcs.d.ts

@@ -0,0 +1,96 @@
+/**
+ * BCS schemas for Sui checkpoint types.
+ * Field order matches the Rust struct declarations exactly.
+ */
+export declare const bcsCheckpointSummary: import("@mysten/bcs").BcsStruct<{
+    epoch: import("@mysten/bcs").BcsType<string, string | number | bigint, "u64">;
+    sequenceNumber: import("@mysten/bcs").BcsType<string, string | number | bigint, "u64">;
+    networkTotalTransactions: import("@mysten/bcs").BcsType<string, string | number | bigint, "u64">;
+    contentDigest: import("@mysten/bcs").BcsType<number[], Iterable<number> & {
+        length: number;
+    }, "vector<u8>">;
+    previousDigest: import("@mysten/bcs").BcsType<number[] | null, (Iterable<number> & {
+        length: number;
+    }) | null | undefined, "Option<vector<u8>>">;
+    epochRollingGasCostSummary: import("@mysten/bcs").BcsStruct<{
+        computationCost: import("@mysten/bcs").BcsType<string, string | number | bigint, "u64">;
+        storageCost: import("@mysten/bcs").BcsType<string, string | number | bigint, "u64">;
+        storageRebate: import("@mysten/bcs").BcsType<string, string | number | bigint, "u64">;
+        nonRefundableStorageFee: import("@mysten/bcs").BcsType<string, string | number | bigint, "u64">;
+    }, string>;
+    timestampMs: import("@mysten/bcs").BcsType<string, string | number | bigint, "u64">;
+    checkpointCommitments: import("@mysten/bcs").BcsType<import("@mysten/bcs").EnumOutputShapeWithKeys<{
+        ECMHLiveObjectSetDigest: number[];
+        CheckpointArtifactsDigest: number[];
+    }, "ECMHLiveObjectSetDigest" | "CheckpointArtifactsDigest">[], Iterable<import("@mysten/bcs").EnumInputShape<{
+        ECMHLiveObjectSetDigest: Iterable<number> & {
+            length: number;
+        };
+        CheckpointArtifactsDigest: Iterable<number> & {
+            length: number;
+        };
+    }>> & {
+        length: number;
+    }, string>;
+    endOfEpochData: import("@mysten/bcs").BcsType<{
+        nextEpochCommittee: [number[], string][];
+        nextEpochProtocolVersion: string;
+        epochCommitments: import("@mysten/bcs").EnumOutputShapeWithKeys<{
+            ECMHLiveObjectSetDigest: number[];
+            CheckpointArtifactsDigest: number[];
+        }, "ECMHLiveObjectSetDigest" | "CheckpointArtifactsDigest">[];
+    } | null, {
+        nextEpochCommittee: Iterable<readonly [Iterable<number> & {
+            length: number;
+        }, string | number | bigint]> & {
+            length: number;
+        };
+        nextEpochProtocolVersion: string | number | bigint;
+        epochCommitments: Iterable<import("@mysten/bcs").EnumInputShape<{
+            ECMHLiveObjectSetDigest: Iterable<number> & {
+                length: number;
+            };
+            CheckpointArtifactsDigest: Iterable<number> & {
+                length: number;
+            };
+        }>> & {
+            length: number;
+        };
+    } | null | undefined, `Option<${string}>`>;
+    versionSpecificData: import("@mysten/bcs").BcsType<number[], Iterable<number> & {
+        length: number;
+    }, string>;
+}, string>;
+export declare const bcsCheckpointContents: import("@mysten/bcs").BcsEnum<{
+    V1: import("@mysten/bcs").BcsStruct<{
+        transactions: import("@mysten/bcs").BcsType<{
+            transaction: number[];
+            effects: number[];
+        }[], Iterable<{
+            transaction: Iterable<number> & {
+                length: number;
+            };
+            effects: Iterable<number> & {
+                length: number;
+            };
+        }> & {
+            length: number;
+        }, string>;
+        userSignatures: import("@mysten/bcs").BcsType<number[][][], Iterable<Iterable<Iterable<number> & {
+            length: number;
+        }> & {
+            length: number;
+        }> & {
+            length: number;
+        }, string>;
+    }, string>;
+}, "CheckpointContents">;
+export declare const bcsAuthorityQuorumSignInfo: import("@mysten/bcs").BcsStruct<{
+    epoch: import("@mysten/bcs").BcsType<string, string | number | bigint, "u64">;
+    signature: import("@mysten/bcs").BcsType<number[], Iterable<number> & {
+        length: number;
+    }, string>;
+    signersMap: import("@mysten/bcs").BcsType<number[], Iterable<number> & {
+        length: number;
+    }, string>;
+}, string>;

package/dist/bitmap.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Minimal RoaringBitmap decoder for Sui's validator signers bitmap.
+ *
+ * Supports the standard portable serialization format:
+ * - Cookie 12346: array and bitset containers
+ * - Cookie 12347: array, bitset, and run containers
+ *
+ * See: https://github.com/RoaringBitmap/RoaringFormatSpec
+ */
+/** Decode a serialized RoaringBitmap into a sorted array of set bit positions. */
+export declare function decodeRoaringBitmap(data: Uint8Array): number[];

package/dist/cli.d.ts

@@ -0,0 +1,9 @@
+#!/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>]
+ */
+export {};

package/dist/cli.js

@@ -0,0 +1,433 @@
+#!/usr/bin/env bun
+// @bun
+import { createRequire } from "node:module";
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+
+// src/bitmap.ts
+var SERIAL_COOKIE_NO_RUNCONTAINER = 12346;
+var SERIAL_COOKIE = 12347;
+var NO_OFFSET_THRESHOLD = 4;
+function decodeRoaringBitmap(data) {
+  if (data.byteLength < 4) {
+    throw new Error(`RoaringBitmap too small: ${data.byteLength} bytes`);
+  }
+  const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+  let offset = 0;
+  const firstU32 = view.getUint32(0, true);
+  const firstU16 = firstU32 & 65535;
+  let containerCount;
+  let isRunBitmap = [];
+  if (firstU32 === SERIAL_COOKIE_NO_RUNCONTAINER) {
+    offset = 4;
+    containerCount = view.getUint32(offset, true);
+    offset += 4;
+  } else if (firstU16 === SERIAL_COOKIE) {
+    offset = 2;
+    containerCount = view.getUint16(offset, true) + 1;
+    offset += 2;
+    const runBitmapBytes = Math.ceil(containerCount / 8);
+    for (let i = 0;i < containerCount; i++) {
+      const byteIdx = Math.floor(i / 8);
+      const bitIdx = i % 8;
+      isRunBitmap.push((data[offset + byteIdx] & 1 << bitIdx) !== 0);
+    }
+    offset += runBitmapBytes;
+  } else {
+    throw new Error(`Invalid RoaringBitmap cookie: ${firstU32}`);
+  }
+  const keys = [];
+  const cardinalities = [];
+  for (let i = 0;i < containerCount; i++) {
+    keys.push(view.getUint16(offset, true));
+    offset += 2;
+    cardinalities.push(view.getUint16(offset, true) + 1);
+    offset += 2;
+  }
+  if (firstU32 === SERIAL_COOKIE_NO_RUNCONTAINER) {
+    offset += containerCount * 4;
+  } else if (containerCount >= NO_OFFSET_THRESHOLD) {
+    offset += containerCount * 4;
+  }
+  const result = [];
+  for (let i = 0;i < containerCount; i++) {
+    const highBits = keys[i] << 16;
+    const cardinality = cardinalities[i];
+    if (isRunBitmap[i]) {
+      const numRuns = view.getUint16(offset, true);
+      offset += 2;
+      for (let r = 0;r < numRuns; r++) {
+        const start = view.getUint16(offset, true);
+        offset += 2;
+        const length = view.getUint16(offset, true);
+        offset += 2;
+        for (let v = start;v <= start + length; v++) {
+          result.push(highBits | v);
+        }
+      }
+    } else if (cardinality <= 4096) {
+      for (let j = 0;j < cardinality; j++) {
+        result.push(highBits | view.getUint16(offset, true));
+        offset += 2;
+      }
+    } else {
+      for (let word = 0;word < 1024; word++) {
+        const lo = view.getUint32(offset, true);
+        const hi = view.getUint32(offset + 4, true);
+        offset += 8;
+        for (let bit = 0;bit < 32; bit++) {
+          if (lo & 1 << bit)
+            result.push(highBits | word * 64 + bit);
+          if (hi & 1 << bit)
+            result.push(highBits | word * 64 + 32 + bit);
+        }
+      }
+    }
+  }
+  return result;
+}
+
+// src/verify.ts
+import { bls12_381 } from "@noble/curves/bls12-381";
+
+// src/bitmap.ts
+var SERIAL_COOKIE_NO_RUNCONTAINER2 = 12346;
+var SERIAL_COOKIE2 = 12347;
+var NO_OFFSET_THRESHOLD2 = 4;
+function decodeRoaringBitmap2(data) {
+  if (data.byteLength < 4) {
+    throw new Error(`RoaringBitmap too small: ${data.byteLength} bytes`);
+  }
+  const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+  let offset = 0;
+  const firstU32 = view.getUint32(0, true);
+  const firstU16 = firstU32 & 65535;
+  let containerCount;
+  let isRunBitmap = [];
+  if (firstU32 === SERIAL_COOKIE_NO_RUNCONTAINER2) {
+    offset = 4;
+    containerCount = view.getUint32(offset, true);
+    offset += 4;
+  } else if (firstU16 === SERIAL_COOKIE2) {
+    offset = 2;
+    containerCount = view.getUint16(offset, true) + 1;
+    offset += 2;
+    const runBitmapBytes = Math.ceil(containerCount / 8);
+    for (let i = 0;i < containerCount; i++) {
+      const byteIdx = Math.floor(i / 8);
+      const bitIdx = i % 8;
+      isRunBitmap.push((data[offset + byteIdx] & 1 << bitIdx) !== 0);
+    }
+    offset += runBitmapBytes;
+  } else {
+    throw new Error(`Invalid RoaringBitmap cookie: ${firstU32}`);
+  }
+  const keys = [];
+  const cardinalities = [];
+  for (let i = 0;i < containerCount; i++) {
+    keys.push(view.getUint16(offset, true));
+    offset += 2;
+    cardinalities.push(view.getUint16(offset, true) + 1);
+    offset += 2;
+  }
+  if (firstU32 === SERIAL_COOKIE_NO_RUNCONTAINER2) {
+    offset += containerCount * 4;
+  } else if (containerCount >= NO_OFFSET_THRESHOLD2) {
+    offset += containerCount * 4;
+  }
+  const result = [];
+  for (let i = 0;i < containerCount; i++) {
+    const highBits = keys[i] << 16;
+    const cardinality = cardinalities[i];
+    if (isRunBitmap[i]) {
+      const numRuns = view.getUint16(offset, true);
+      offset += 2;
+      for (let r = 0;r < numRuns; r++) {
+        const start = view.getUint16(offset, true);
+        offset += 2;
+        const length = view.getUint16(offset, true);
+        offset += 2;
+        for (let v = start;v <= start + length; v++) {
+          result.push(highBits | v);
+        }
+      }
+    } else if (cardinality <= 4096) {
+      for (let j = 0;j < cardinality; j++) {
+        result.push(highBits | view.getUint16(offset, true));
+        offset += 2;
+      }
+    } else {
+      for (let word = 0;word < 1024; word++) {
+        const lo = view.getUint32(offset, true);
+        const hi = view.getUint32(offset + 4, true);
+        offset += 8;
+        for (let bit = 0;bit < 32; bit++) {
+          if (lo & 1 << bit)
+            result.push(highBits | word * 64 + bit);
+          if (hi & 1 << bit)
+            result.push(highBits | word * 64 + 32 + bit);
+        }
+      }
+    }
+  }
+  return result;
+}
+
+// src/digest.ts
+import { blake2b } from "@noble/hashes/blake2b";
+var encoder = new TextEncoder;
+
+// src/types.ts
+var QUORUM_THRESHOLD = 6667n;
+var CHECKPOINT_SUMMARY_INTENT = new Uint8Array([2, 0, 0]);
+
+// src/bcs.ts
+import { bcs } from "@mysten/bcs";
+var Digest = bcs.vector(bcs.u8());
+var AuthorityPublicKeyBytes = bcs.vector(bcs.u8());
+var GasCostSummary = bcs.struct("GasCostSummary", {
+  computationCost: bcs.u64(),
+  storageCost: bcs.u64(),
+  storageRebate: bcs.u64(),
+  nonRefundableStorageFee: bcs.u64()
+});
+var CheckpointCommitment = bcs.enum("CheckpointCommitment", {
+  ECMHLiveObjectSetDigest: Digest,
+  CheckpointArtifactsDigest: Digest
+});
+var EndOfEpochData = bcs.struct("EndOfEpochData", {
+  nextEpochCommittee: bcs.vector(bcs.tuple([AuthorityPublicKeyBytes, bcs.u64()])),
+  nextEpochProtocolVersion: bcs.u64(),
+  epochCommitments: bcs.vector(CheckpointCommitment)
+});
+var bcsCheckpointSummary = bcs.struct("CheckpointSummary", {
+  epoch: bcs.u64(),
+  sequenceNumber: bcs.u64(),
+  networkTotalTransactions: bcs.u64(),
+  contentDigest: Digest,
+  previousDigest: bcs.option(Digest),
+  epochRollingGasCostSummary: GasCostSummary,
+  timestampMs: bcs.u64(),
+  checkpointCommitments: bcs.vector(CheckpointCommitment),
+  endOfEpochData: bcs.option(EndOfEpochData),
+  versionSpecificData: bcs.vector(bcs.u8())
+});
+var ExecutionDigests = bcs.struct("ExecutionDigests", {
+  transaction: Digest,
+  effects: Digest
+});
+var CheckpointContentsV1 = bcs.struct("CheckpointContentsV1", {
+  transactions: bcs.vector(ExecutionDigests),
+  userSignatures: bcs.vector(bcs.vector(bcs.vector(bcs.u8())))
+});
+var bcsCheckpointContents = bcs.enum("CheckpointContents", {
+  V1: CheckpointContentsV1
+});
+var bcsAuthorityQuorumSignInfo = bcs.struct("AuthorityQuorumSignInfo", {
+  epoch: bcs.u64(),
+  signature: bcs.vector(bcs.u8()),
+  signersMap: bcs.vector(bcs.u8())
+});
+
+// src/verify.ts
+class PreparedCommittee {
+  epoch;
+  members;
+  constructor(committee) {
+    this.epoch = committee.epoch;
+    this.members = committee.members.map((m) => ({
+      point: bls12_381.G2.ProjectivePoint.fromHex(m.publicKey),
+      votingPower: m.votingPower
+    }));
+  }
+}
+function verifyCheckpoint(summaryBcs, authSignature, committee) {
+  const prepared = committee instanceof PreparedCommittee ? committee : new PreparedCommittee(committee);
+  if (authSignature.epoch !== prepared.epoch) {
+    throw new Error(`Epoch mismatch: signature epoch ${authSignature.epoch} !== committee epoch ${prepared.epoch}`);
+  }
+  const signerIndices = decodeRoaringBitmap2(authSignature.signersMap);
+  let totalPower = 0n;
+  let aggregatedPoint = null;
+  for (const idx of signerIndices) {
+    if (idx >= prepared.members.length) {
+      throw new Error(`Signer index ${idx} exceeds committee size ${prepared.members.length}`);
+    }
+    const member = prepared.members[idx];
+    totalPower += member.votingPower;
+    aggregatedPoint = aggregatedPoint ? aggregatedPoint.add(member.point) : member.point;
+  }
+  if (totalPower < QUORUM_THRESHOLD) {
+    throw new Error(`Insufficient voting power: ${totalPower} < ${QUORUM_THRESHOLD} (${signerIndices.length}/${prepared.members.length} validators)`);
+  }
+  const epochBytes = new Uint8Array(8);
+  const epochView = new DataView(epochBytes.buffer);
+  epochView.setBigUint64(0, authSignature.epoch, true);
+  const message = new Uint8Array(CHECKPOINT_SUMMARY_INTENT.length + summaryBcs.length + epochBytes.length);
+  message.set(CHECKPOINT_SUMMARY_INTENT);
+  message.set(summaryBcs, CHECKPOINT_SUMMARY_INTENT.length);
+  message.set(epochBytes, CHECKPOINT_SUMMARY_INTENT.length + summaryBcs.length);
+  const hashedMessage = bls12_381.shortSignatures.hash(message);
+  const valid = bls12_381.shortSignatures.verify(authSignature.signature, hashedMessage, aggregatedPoint.toRawBytes(true));
+  if (!valid) {
+    throw new Error("BLS signature verification failed");
+  }
+}
+
+// src/cli.ts
+function usage() {
+  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    \u2014 fullnode gRPC endpoint
+  NETWORK     \u2014 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, flag) {
+  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");
+  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)
+`);
+    usage();
+  }
+  if (command === "verify") {
+    const seq = args[1];
+    if (!seq || isNaN(Number(seq)))
+      usage();
+    return { command: "verify", 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", from: Number(from), to: Number(to), network, url };
+  }
+  usage();
+}
+var _grpcClient = null;
+async function getGrpcClient(network, url) {
+  if (_grpcClient)
+    return _grpcClient;
+  const { SuiGrpcClient } = await import("@mysten/sui/grpc");
+  _grpcClient = new SuiGrpcClient({ network, baseUrl: url });
+  return _grpcClient;
+}
+async function fetchCheckpoint(network, url, seq) {
+  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;
+}
+async function fetchCommittee(url, epoch) {
+  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();
+  return {
+    epoch: BigInt(epoch),
+    members: json.result.validators.map(([pk, stake]) => ({
+      publicKey: new Uint8Array(Buffer.from(pk, "base64")),
+      votingPower: BigInt(stake)
+    }))
+  };
+}
+function extractAuthSignature(cp) {
+  return {
+    epoch: cp.signature.epoch,
+    signature: cp.signature.signature,
+    signersMap: cp.signature.bitmap
+  };
+}
+async function verifySingle(seq, network, url) {
+  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(`
+Checkpoint ${seq} verified in ${(performance.now() - total).toFixed(0)}ms`);
+}
+async function verifyRange(from, to, network, url) {
+  const count = to - from + 1;
+  console.log(`Verifying ${count} checkpoints (${from} \u2192 ${to})
+`);
+  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
+`);
+  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(`
+${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);
+});

package/dist/committee.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Committee management and transition verification.
+ */
+import type { CheckpointSummary, Committee, AuthorityQuorumSignInfo } from './types.js';
+/**
+ * Verify a committee transition: given a certified end-of-epoch checkpoint
+ * and the current committee, extract and return the next epoch's committee.
+ *
+ * @param summaryBcs - Raw BCS bytes of the CheckpointSummary
+ * @param summary - Parsed CheckpointSummary (for reading endOfEpochData)
+ * @param authSignature - The quorum signature
+ * @param currentCommittee - The committee that signed this checkpoint
+ */
+export declare function verifyCommitteeTransition(summaryBcs: Uint8Array, summary: CheckpointSummary, authSignature: AuthorityQuorumSignInfo, currentCommittee: Committee): Committee;
+/**
+ * Walk a chain of end-of-epoch checkpoints to advance from a trusted committee
+ * to a target epoch.
+ *
+ * @param checkpoints - Ordered end-of-epoch certified checkpoints with raw BCS + parsed summary
+ * @param trustedCommittee - Starting committee (must match first checkpoint's epoch)
+ * @returns The committee for the epoch after the last checkpoint
+ */
+export declare function walkCommitteeChain(checkpoints: {
+    summaryBcs: Uint8Array;
+    summary: CheckpointSummary;
+    authSignature: AuthorityQuorumSignInfo;
+}[], trustedCommittee: Committee): Committee;

package/dist/digest.d.ts

@@ -0,0 +1,10 @@
+/** Sui digest computation: Blake2b-256 with struct name domain separators. */
+/**
+ * Compute a Sui digest: Blake2b-256("StructName::" || data)
+ * All Sui digests follow this pattern for domain separation.
+ */
+export declare function suiDigest(structName: string, bcsBytes: Uint8Array): Uint8Array;
+export declare function checkpointDigest(summaryBcs: Uint8Array): Uint8Array;
+export declare function checkpointContentsDigest(contentsBcs: Uint8Array): Uint8Array;
+export declare function transactionDigest(txDataBcs: Uint8Array): Uint8Array;
+export declare function transactionEffectsDigest(effectsBcs: Uint8Array): Uint8Array;

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { verifyCheckpoint, verifyCheckpointContents, verifyTransactionInCheckpoint, PreparedCommittee, digestsEqual } from './verify.js';
+export { parseBcsSummary } from './parse.js';
+export { verifyCommitteeTransition, walkCommitteeChain } from './committee.js';
+export { suiDigest, checkpointDigest, checkpointContentsDigest, transactionDigest, transactionEffectsDigest } from './digest.js';
+export { decodeRoaringBitmap } from './bitmap.js';
+export { bcsCheckpointSummary, bcsCheckpointContents, bcsAuthorityQuorumSignInfo } from './bcs.js';
+export type { CheckpointSummary, CheckpointContents, ExecutionDigests, Committee, CommitteeMember, AuthorityQuorumSignInfo, CertifiedCheckpointSummary, EndOfEpochData, GasCostSummary, CheckpointCommitment, } from './types.js';
+export { TOTAL_VOTING_POWER, QUORUM_THRESHOLD, CHECKPOINT_SUMMARY_INTENT } from './types.js';

package/dist/index.js

@@ -0,0 +1,318 @@
+// src/verify.ts
+import { bls12_381 } from "@noble/curves/bls12-381";
+
+// src/bitmap.ts
+var SERIAL_COOKIE_NO_RUNCONTAINER = 12346;
+var SERIAL_COOKIE = 12347;
+var NO_OFFSET_THRESHOLD = 4;
+function decodeRoaringBitmap(data) {
+  if (data.byteLength < 4) {
+    throw new Error(`RoaringBitmap too small: ${data.byteLength} bytes`);
+  }
+  const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+  let offset = 0;
+  const firstU32 = view.getUint32(0, true);
+  const firstU16 = firstU32 & 65535;
+  let containerCount;
+  let isRunBitmap = [];
+  if (firstU32 === SERIAL_COOKIE_NO_RUNCONTAINER) {
+    offset = 4;
+    containerCount = view.getUint32(offset, true);
+    offset += 4;
+  } else if (firstU16 === SERIAL_COOKIE) {
+    offset = 2;
+    containerCount = view.getUint16(offset, true) + 1;
+    offset += 2;
+    const runBitmapBytes = Math.ceil(containerCount / 8);
+    for (let i = 0;i < containerCount; i++) {
+      const byteIdx = Math.floor(i / 8);
+      const bitIdx = i % 8;
+      isRunBitmap.push((data[offset + byteIdx] & 1 << bitIdx) !== 0);
+    }
+    offset += runBitmapBytes;
+  } else {
+    throw new Error(`Invalid RoaringBitmap cookie: ${firstU32}`);
+  }
+  const keys = [];
+  const cardinalities = [];
+  for (let i = 0;i < containerCount; i++) {
+    keys.push(view.getUint16(offset, true));
+    offset += 2;
+    cardinalities.push(view.getUint16(offset, true) + 1);
+    offset += 2;
+  }
+  if (firstU32 === SERIAL_COOKIE_NO_RUNCONTAINER) {
+    offset += containerCount * 4;
+  } else if (containerCount >= NO_OFFSET_THRESHOLD) {
+    offset += containerCount * 4;
+  }
+  const result = [];
+  for (let i = 0;i < containerCount; i++) {
+    const highBits = keys[i] << 16;
+    const cardinality = cardinalities[i];
+    if (isRunBitmap[i]) {
+      const numRuns = view.getUint16(offset, true);
+      offset += 2;
+      for (let r = 0;r < numRuns; r++) {
+        const start = view.getUint16(offset, true);
+        offset += 2;
+        const length = view.getUint16(offset, true);
+        offset += 2;
+        for (let v = start;v <= start + length; v++) {
+          result.push(highBits | v);
+        }
+      }
+    } else if (cardinality <= 4096) {
+      for (let j = 0;j < cardinality; j++) {
+        result.push(highBits | view.getUint16(offset, true));
+        offset += 2;
+      }
+    } else {
+      for (let word = 0;word < 1024; word++) {
+        const lo = view.getUint32(offset, true);
+        const hi = view.getUint32(offset + 4, true);
+        offset += 8;
+        for (let bit = 0;bit < 32; bit++) {
+          if (lo & 1 << bit)
+            result.push(highBits | word * 64 + bit);
+          if (hi & 1 << bit)
+            result.push(highBits | word * 64 + 32 + bit);
+        }
+      }
+    }
+  }
+  return result;
+}
+
+// src/digest.ts
+import { blake2b } from "@noble/hashes/blake2b";
+var encoder = new TextEncoder;
+function suiDigest(structName, bcsBytes) {
+  const prefix = encoder.encode(`${structName}::`);
+  const input = new Uint8Array(prefix.length + bcsBytes.length);
+  input.set(prefix);
+  input.set(bcsBytes, prefix.length);
+  return blake2b(input, { dkLen: 32 });
+}
+function checkpointDigest(summaryBcs) {
+  return suiDigest("CheckpointSummary", summaryBcs);
+}
+function checkpointContentsDigest(contentsBcs) {
+  return suiDigest("CheckpointContents", contentsBcs);
+}
+function transactionDigest(txDataBcs) {
+  return suiDigest("TransactionData", txDataBcs);
+}
+function transactionEffectsDigest(effectsBcs) {
+  return suiDigest("TransactionEffects", effectsBcs);
+}
+
+// src/types.ts
+var TOTAL_VOTING_POWER = 10000n;
+var QUORUM_THRESHOLD = 6667n;
+var CHECKPOINT_SUMMARY_INTENT = new Uint8Array([2, 0, 0]);
+
+// src/bcs.ts
+import { bcs } from "@mysten/bcs";
+var Digest = bcs.vector(bcs.u8());
+var AuthorityPublicKeyBytes = bcs.vector(bcs.u8());
+var GasCostSummary = bcs.struct("GasCostSummary", {
+  computationCost: bcs.u64(),
+  storageCost: bcs.u64(),
+  storageRebate: bcs.u64(),
+  nonRefundableStorageFee: bcs.u64()
+});
+var CheckpointCommitment = bcs.enum("CheckpointCommitment", {
+  ECMHLiveObjectSetDigest: Digest,
+  CheckpointArtifactsDigest: Digest
+});
+var EndOfEpochData = bcs.struct("EndOfEpochData", {
+  nextEpochCommittee: bcs.vector(bcs.tuple([AuthorityPublicKeyBytes, bcs.u64()])),
+  nextEpochProtocolVersion: bcs.u64(),
+  epochCommitments: bcs.vector(CheckpointCommitment)
+});
+var bcsCheckpointSummary = bcs.struct("CheckpointSummary", {
+  epoch: bcs.u64(),
+  sequenceNumber: bcs.u64(),
+  networkTotalTransactions: bcs.u64(),
+  contentDigest: Digest,
+  previousDigest: bcs.option(Digest),
+  epochRollingGasCostSummary: GasCostSummary,
+  timestampMs: bcs.u64(),
+  checkpointCommitments: bcs.vector(CheckpointCommitment),
+  endOfEpochData: bcs.option(EndOfEpochData),
+  versionSpecificData: bcs.vector(bcs.u8())
+});
+var ExecutionDigests = bcs.struct("ExecutionDigests", {
+  transaction: Digest,
+  effects: Digest
+});
+var CheckpointContentsV1 = bcs.struct("CheckpointContentsV1", {
+  transactions: bcs.vector(ExecutionDigests),
+  userSignatures: bcs.vector(bcs.vector(bcs.vector(bcs.u8())))
+});
+var bcsCheckpointContents = bcs.enum("CheckpointContents", {
+  V1: CheckpointContentsV1
+});
+var bcsAuthorityQuorumSignInfo = bcs.struct("AuthorityQuorumSignInfo", {
+  epoch: bcs.u64(),
+  signature: bcs.vector(bcs.u8()),
+  signersMap: bcs.vector(bcs.u8())
+});
+
+// src/verify.ts
+class PreparedCommittee {
+  epoch;
+  members;
+  constructor(committee) {
+    this.epoch = committee.epoch;
+    this.members = committee.members.map((m) => ({
+      point: bls12_381.G2.ProjectivePoint.fromHex(m.publicKey),
+      votingPower: m.votingPower
+    }));
+  }
+}
+function verifyCheckpoint(summaryBcs, authSignature, committee) {
+  const prepared = committee instanceof PreparedCommittee ? committee : new PreparedCommittee(committee);
+  if (authSignature.epoch !== prepared.epoch) {
+    throw new Error(`Epoch mismatch: signature epoch ${authSignature.epoch} !== committee epoch ${prepared.epoch}`);
+  }
+  const signerIndices = decodeRoaringBitmap(authSignature.signersMap);
+  let totalPower = 0n;
+  let aggregatedPoint = null;
+  for (const idx of signerIndices) {
+    if (idx >= prepared.members.length) {
+      throw new Error(`Signer index ${idx} exceeds committee size ${prepared.members.length}`);
+    }
+    const member = prepared.members[idx];
+    totalPower += member.votingPower;
+    aggregatedPoint = aggregatedPoint ? aggregatedPoint.add(member.point) : member.point;
+  }
+  if (totalPower < QUORUM_THRESHOLD) {
+    throw new Error(`Insufficient voting power: ${totalPower} < ${QUORUM_THRESHOLD} (${signerIndices.length}/${prepared.members.length} validators)`);
+  }
+  const epochBytes = new Uint8Array(8);
+  const epochView = new DataView(epochBytes.buffer);
+  epochView.setBigUint64(0, authSignature.epoch, true);
+  const message = new Uint8Array(CHECKPOINT_SUMMARY_INTENT.length + summaryBcs.length + epochBytes.length);
+  message.set(CHECKPOINT_SUMMARY_INTENT);
+  message.set(summaryBcs, CHECKPOINT_SUMMARY_INTENT.length);
+  message.set(epochBytes, CHECKPOINT_SUMMARY_INTENT.length + summaryBcs.length);
+  const hashedMessage = bls12_381.shortSignatures.hash(message);
+  const valid = bls12_381.shortSignatures.verify(authSignature.signature, hashedMessage, aggregatedPoint.toRawBytes(true));
+  if (!valid) {
+    throw new Error("BLS signature verification failed");
+  }
+}
+function verifyCheckpointContents(summary, contents) {
+  const contentsBcs = bcsCheckpointContents.serialize({ V1: contents }).toBytes();
+  const computedDigest = checkpointContentsDigest(contentsBcs);
+  if (!digestsEqual(computedDigest, summary.contentDigest)) {
+    throw new Error("Checkpoint contents digest mismatch");
+  }
+}
+function verifyTransactionInCheckpoint(txDigest, contents) {
+  for (const exec of contents.transactions) {
+    if (digestsEqual(exec.transaction, txDigest)) {
+      return exec;
+    }
+  }
+  throw new Error("Transaction not found in checkpoint contents");
+}
+function digestsEqual(a, b) {
+  if (a.length !== b.length)
+    return false;
+  for (let i = 0;i < a.length; i++) {
+    if (a[i] !== b[i])
+      return false;
+  }
+  return true;
+}
+// src/parse.ts
+function parseBcsSummary(bcsBytes) {
+  const p = bcsCheckpointSummary.parse(bcsBytes);
+  return {
+    epoch: BigInt(p.epoch),
+    sequenceNumber: BigInt(p.sequenceNumber),
+    networkTotalTransactions: BigInt(p.networkTotalTransactions),
+    contentDigest: Uint8Array.from(p.contentDigest),
+    previousDigest: p.previousDigest ? Uint8Array.from(p.previousDigest) : null,
+    epochRollingGasCostSummary: {
+      computationCost: BigInt(p.epochRollingGasCostSummary.computationCost),
+      storageCost: BigInt(p.epochRollingGasCostSummary.storageCost),
+      storageRebate: BigInt(p.epochRollingGasCostSummary.storageRebate),
+      nonRefundableStorageFee: BigInt(p.epochRollingGasCostSummary.nonRefundableStorageFee)
+    },
+    timestampMs: BigInt(p.timestampMs),
+    checkpointCommitments: p.checkpointCommitments.map(convertCommitment),
+    endOfEpochData: p.endOfEpochData ? convertEndOfEpochData(p.endOfEpochData) : null,
+    versionSpecificData: Uint8Array.from(p.versionSpecificData)
+  };
+}
+function convertCommitment(c) {
+  if ("ECMHLiveObjectSetDigest" in c && c.ECMHLiveObjectSetDigest) {
+    return { ECMHLiveObjectSetDigest: Uint8Array.from(c.ECMHLiveObjectSetDigest) };
+  }
+  if ("CheckpointArtifactsDigest" in c && c.CheckpointArtifactsDigest) {
+    return { CheckpointArtifactsDigest: Uint8Array.from(c.CheckpointArtifactsDigest) };
+  }
+  throw new Error(`Unknown CheckpointCommitment variant: ${JSON.stringify(c)}`);
+}
+function convertEndOfEpochData(e) {
+  return {
+    nextEpochCommittee: e.nextEpochCommittee.map(([pk, stake]) => [
+      Uint8Array.from(pk),
+      BigInt(stake)
+    ]),
+    nextEpochProtocolVersion: BigInt(e.nextEpochProtocolVersion),
+    epochCommitments: e.epochCommitments.map(convertCommitment)
+  };
+}
+// src/committee.ts
+function verifyCommitteeTransition(summaryBcs, summary, authSignature, currentCommittee) {
+  verifyCheckpoint(summaryBcs, authSignature, currentCommittee);
+  if (!summary.endOfEpochData) {
+    throw new Error("Checkpoint is not an end-of-epoch checkpoint");
+  }
+  const nextEpoch = summary.epoch + 1n;
+  const members = summary.endOfEpochData.nextEpochCommittee.map(([publicKey, votingPower]) => ({
+    publicKey: Uint8Array.from(publicKey),
+    votingPower
+  }));
+  if (members.length === 0) {
+    throw new Error("End-of-epoch checkpoint has empty next committee");
+  }
+  return { epoch: nextEpoch, members };
+}
+function walkCommitteeChain(checkpoints, trustedCommittee) {
+  let committee = trustedCommittee;
+  for (const { summaryBcs, summary, authSignature } of checkpoints) {
+    if (summary.epoch !== committee.epoch) {
+      throw new Error(`Epoch gap: expected checkpoint for epoch ${committee.epoch}, got ${summary.epoch}`);
+    }
+    committee = verifyCommitteeTransition(summaryBcs, summary, authSignature, committee);
+  }
+  return committee;
+}
+export {
+  walkCommitteeChain,
+  verifyTransactionInCheckpoint,
+  verifyCommitteeTransition,
+  verifyCheckpointContents,
+  verifyCheckpoint,
+  transactionEffectsDigest,
+  transactionDigest,
+  suiDigest,
+  parseBcsSummary,
+  digestsEqual,
+  decodeRoaringBitmap,
+  checkpointDigest,
+  checkpointContentsDigest,
+  bcsCheckpointSummary,
+  bcsCheckpointContents,
+  bcsAuthorityQuorumSignInfo,
+  TOTAL_VOTING_POWER,
+  QUORUM_THRESHOLD,
+  PreparedCommittee,
+  CHECKPOINT_SUMMARY_INTENT
+};

package/dist/parse.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Convert BCS-deserialized checkpoint data to typed CheckpointSummary.
+ *
+ * @mysten/bcs returns u64 as strings and byte arrays as number[].
+ * This module bridges from the BCS output shape to our typed interfaces.
+ */
+import type { CheckpointSummary } from './types.js';
+/** Parse raw BCS bytes into a typed CheckpointSummary. */
+export declare function parseBcsSummary(bcsBytes: Uint8Array): CheckpointSummary;

package/dist/types.d.ts

@@ -0,0 +1,63 @@
+/** Sui checkpoint types for BCS serialization and light client verification. */
+/** 32-byte digest (Blake2b-256 output) */
+export type Digest = Uint8Array;
+/** BLS12-381 public key in min-sig mode (G2 compressed) */
+export type AuthorityPublicKeyBytes = Uint8Array;
+/** BLS12-381 aggregate signature in min-sig mode (G1 compressed) */
+export type AggregateSignatureBytes = Uint8Array;
+export interface GasCostSummary {
+    computationCost: bigint;
+    storageCost: bigint;
+    storageRebate: bigint;
+    nonRefundableStorageFee: bigint;
+}
+export interface EndOfEpochData {
+    nextEpochCommittee: [AuthorityPublicKeyBytes, bigint][];
+    nextEpochProtocolVersion: bigint;
+    epochCommitments: CheckpointCommitment[];
+}
+export type CheckpointCommitment = {
+    ECMHLiveObjectSetDigest: Digest;
+} | {
+    CheckpointArtifactsDigest: Digest;
+};
+export interface CheckpointSummary {
+    epoch: bigint;
+    sequenceNumber: bigint;
+    networkTotalTransactions: bigint;
+    contentDigest: Digest;
+    previousDigest: Digest | null;
+    epochRollingGasCostSummary: GasCostSummary;
+    timestampMs: bigint;
+    checkpointCommitments: CheckpointCommitment[];
+    endOfEpochData: EndOfEpochData | null;
+    versionSpecificData: Uint8Array;
+}
+export interface AuthorityQuorumSignInfo {
+    epoch: bigint;
+    signature: AggregateSignatureBytes;
+    signersMap: Uint8Array;
+}
+export interface CertifiedCheckpointSummary {
+    summary: CheckpointSummary;
+    authSignature: AuthorityQuorumSignInfo;
+}
+export interface ExecutionDigests {
+    transaction: Digest;
+    effects: Digest;
+}
+export interface CheckpointContents {
+    transactions: ExecutionDigests[];
+    userSignatures: Uint8Array[][];
+}
+export interface CommitteeMember {
+    publicKey: AuthorityPublicKeyBytes;
+    votingPower: bigint;
+}
+export interface Committee {
+    epoch: bigint;
+    members: CommitteeMember[];
+}
+export declare const TOTAL_VOTING_POWER = 10000n;
+export declare const QUORUM_THRESHOLD = 6667n;
+export declare const CHECKPOINT_SUMMARY_INTENT: Uint8Array<ArrayBuffer>;

package/dist/verify.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Checkpoint certificate verification.
+ *
+ * Verifies that a CheckpointSummary was signed by a quorum (≥6667/10000)
+ * of validators using BLS12-381 aggregate signatures.
+ */
+import { bls12_381 } from '@noble/curves/bls12-381';
+import { type AuthorityQuorumSignInfo, type CheckpointContents, type CheckpointSummary, type Committee, type ExecutionDigests } from './types.js';
+type G2Point = ReturnType<typeof bls12_381.G2.ProjectivePoint.fromHex>;
+/**
+ * A committee with pre-parsed G2 public key points.
+ *
+ * Parsing 96-byte compressed G2 points is the bottleneck (~1ms per key).
+ * Pre-parsing the full committee once (~113ms for 118 validators) lets
+ * per-checkpoint aggregation drop from ~75ms to <1ms.
+ *
+ * Create once per epoch, reuse for all checkpoints in that epoch.
+ */
+export declare class PreparedCommittee {
+    readonly epoch: bigint;
+    readonly members: {
+        point: G2Point;
+        votingPower: bigint;
+    }[];
+    constructor(committee: Committee);
+}
+/**
+ * Verify a checkpoint certificate against a committee.
+ *
+ * Takes the raw BCS bytes of the CheckpointSummary — the exact bytes
+ * that validators signed. Using raw bytes avoids re-serialization which
+ * could introduce subtle mismatches.
+ *
+ * ~10ms per checkpoint with a PreparedCommittee (vs ~150ms without).
+ */
+export declare function verifyCheckpoint(summaryBcs: Uint8Array, authSignature: AuthorityQuorumSignInfo, committee: Committee | PreparedCommittee): void;
+/**
+ * Verify that checkpoint contents match the content digest in a checkpoint summary.
+ */
+export declare function verifyCheckpointContents(summary: CheckpointSummary, contents: CheckpointContents): void;
+/**
+ * Verify that a transaction (by digest) is included in checkpoint contents.
+ * Returns the execution digests (tx + effects) for the matched transaction.
+ */
+export declare function verifyTransactionInCheckpoint(txDigest: Uint8Array, contents: CheckpointContents): ExecutionDigests;
+export declare function digestsEqual(a: Uint8Array, b: Uint8Array): boolean;
+export {};

package/package.json

@@ -1,15 +1,16 @@
 {
   "name": "@unconfirmed/kei",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": ["dist"],
   "bin": {
-    "kei": "src/cli.ts"
+    "kei": "dist/cli.js"
   },
   "scripts": {
-    "build": "bun build src/index.ts --outdir dist --target node",
+    "prepublishOnly": "bun run build",
+    "build": "bun build src/index.ts --outdir dist --target node --external '@noble/*' --external '@mysten/*' && bun build src/cli.ts --outdir dist --target node --external '@noble/*' --external '@mysten/*' && bunx tsc --emitDeclarationOnly --outDir dist",
     "test": "bun test",
     "verify": "bun src/cli.ts verify"
   },

package/src/cli.ts

@@ -1,195 +0,0 @@
-#!/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);
-});