@inversealtruism/csd-light 0.1.1 → 0.1.2

package/README.md

@@ -0,0 +1,11 @@
+# @inversealtruism/csd-light
+
+Light client: headers-first sync with client-side PoW + LWMA + chainwork verification, merkle-inclusion proofs, reorg + checkpoint-start, and a verified-RPC facade with an honest trustLevel.
+
+Part of the [Compute Substrate SDK](https://github.com/InverseAltruism/csd-sdk) (L0). Zero `Buffer` — runs in Node, browsers, and MV3 service workers. Deps: `@noble/*` only.
+
+```
+npm i @inversealtruism/csd-light
+```
+
+See the [repo README](https://github.com/InverseAltruism/csd-sdk#readme) and [examples/quickstart.mjs](https://github.com/InverseAltruism/csd-sdk/blob/master/examples/quickstart.mjs) for usage. MIT.

package/dist/index.cjs

@@ -23,6 +23,7 @@ __export(index_exports, {
   CsdClient: () => import_csd_client2.CsdClient,
   LightClient: () => LightClient,
   expectedBits: () => expectedBits,
+  expectedBitsFromWindow: () => expectedBitsFromWindow,
   rpcHeaderToHeader: () => import_csd_client2.rpcHeaderToHeader
 });
 module.exports = __toCommonJS(index_exports);
@@ -32,29 +33,23 @@ var import_csd_client = require("@inversealtruism/csd-client");
 // src/lwma.ts
 var import_csd_codec = require("@inversealtruism/csd-codec");
 var POW_LIMIT_TARGET = (0, import_csd_codec.targetToBigInt)((0, import_csd_codec.bitsToTarget)(import_csd_codec.POW_LIMIT_BITS));
-function expectedBits(headers, height) {
+function expectedBitsFromWindow(window, height) {
   if (height === 0) return import_csd_codec.INITIAL_BITS;
-  const parent = headers[height - 1];
-  if (!parent) throw new Error(`expectedBits: missing parent for height ${height}`);
+  const parent = window[window.length - 1];
+  if (!parent) throw new Error(`expectedBits: empty window for height ${height}`);
   if (height < 2) return parent.bits;
-  let n = Math.min(import_csd_codec.LWMA_WINDOW, height);
+  const n = Math.min(import_csd_codec.LWMA_WINDOW, height, window.length);
   if (n < 2) return parent.bits;
-  if (n > 1e3) n = 1e3;
+  const w = window.slice(window.length - n);
   const times = [];
   const targets = [];
-  for (let i = 0; i < n; i++) {
-    const idx = height - 1 - i;
-    if (idx < 0) break;
-    const h = headers[idx];
+  for (const h of w) {
     const tb = (0, import_csd_codec.bitsToTarget)(h.bits);
     if (tb.every((b) => b === 0)) throw new Error("expectedBits: invalid compact bits in window");
     times.push(BigInt(h.time));
     targets.push((0, import_csd_codec.targetToBigInt)(tb));
-    if (idx === 0) break;
   }
   if (times.length < 2) return parent.bits;
-  times.reverse();
-  targets.reverse();
   const m = times.length;
   const t = BigInt(Math.max(import_csd_codec.TARGET_BLOCK_SECS, 1));
   const maxSolve = BigInt(Math.max(import_csd_codec.LWMA_SOLVETIME_MAX_FACTOR, 1) * Math.max(import_csd_codec.TARGET_BLOCK_SECS, 1));
@@ -63,9 +58,9 @@ function expectedBits(headers, height) {
     let dt = times[i] - times[i - 1];
     if (dt < 0n) dt = 0n;
     const st = dt < 1n ? 1n : dt > maxSolve ? maxSolve : dt;
-    const w = BigInt(i);
-    weightedSum += st * w;
-    denom += w;
+    const ww = BigInt(i);
+    weightedSum += st * ww;
+    denom += ww;
   }
   if (denom === 0n) return parent.bits;
   const avgSolvetime = weightedSum / denom;
@@ -79,6 +74,12 @@ function expectedBits(headers, height) {
   if ((0, import_csd_codec.targetToBigInt)((0, import_csd_codec.bitsToTarget)(bits)) > POW_LIMIT_TARGET) return import_csd_codec.POW_LIMIT_BITS;
   return bits;
 }
+function expectedBits(headers, height) {
+  if (height === 0) return import_csd_codec.INITIAL_BITS;
+  const n = Math.min(import_csd_codec.LWMA_WINDOW, height);
+  const window = headers.slice(height - n, height);
+  return expectedBitsFromWindow(window, height);
+}
 
 // src/index.ts
 var import_csd_client2 = require("@inversealtruism/csd-client");
@@ -86,8 +87,10 @@ var LightClient = class {
   client;
   provider;
   checkpoints;
-  /** Verified header chain, index = height. */
+  /** Verified header chain. chain[i].height = baseHeight + i. */
   chain = [];
+  /** Height of chain[0] — 0 for genesis-start, the seed start for checkpoint-start. */
+  baseHeight = 0;
   constructor(opts = {}) {
     this.client = opts.client ?? (opts.baseUrl ? new import_csd_client.CsdClient({ baseUrl: opts.baseUrl }) : void 0);
     this.checkpoints = opts.checkpoints ?? {};
@@ -103,12 +106,22 @@ var LightClient = class {
   get chainwork() {
     return this.tip?.chainwork ?? 0n;
   }
-  /**
-   * Sync + VERIFY headers [from..to] inclusive onto the chain. `from` must be 0 (genesis) or
-   * exactly chain.length (contiguous). Throws on any consensus violation. Returns the new tip.
-   */
-  async sync(to, from = this.chain.length) {
-    if (from !== this.chain.length) throw new Error(`non-contiguous sync: have ${this.chain.length}, asked from ${from}`);
+  /** Whether every header back to genesis was verified (vs trusted from a checkpoint). */
+  get fullyVerified() {
+    return this.baseHeight === 0;
+  }
+  at(height) {
+    return this.chain[height - this.baseHeight];
+  }
+  /** The chronological LWMA window (≤ LWMA_WINDOW headers) immediately preceding `height`. */
+  windowBefore(height) {
+    const startIdx = Math.max(0, height - this.baseHeight - import_csd_codec2.LWMA_WINDOW);
+    const endIdx = height - this.baseHeight;
+    return this.chain.slice(startIdx, endIdx).map((c) => c.header);
+  }
+  /** Sync + VERIFY headers [from..to] from genesis (or contiguous to the current tip). */
+  async sync(to, from = this.baseHeight + this.chain.length) {
+    if (from !== this.baseHeight + this.chain.length) throw new Error(`non-contiguous sync: tip ${this.baseHeight + this.chain.length - 1}, asked from ${from}`);
     for (let h = from; h <= to; h++) {
       const { header, hash } = await this.provider(h);
       this.ingest(h, header, hash);
@@ -116,27 +129,99 @@ var LightClient = class {
     if (!this.tip) throw new Error("sync produced no tip");
     return this.tip;
   }
-  /** Verify a single header at the given height and append it (consensus checks). */
+  /** Verify a single header at `height` and append it (full consensus checks). */
   ingest(height, header, claimedHash) {
-    if (height !== this.chain.length) throw new Error(`out-of-order ingest at ${height} (have ${this.chain.length})`);
+    if (height !== this.baseHeight + this.chain.length) throw new Error(`out-of-order ingest at ${height} (tip ${this.baseHeight + this.chain.length - 1})`);
+    const vh = this.verifyOne(height, header, this.windowBefore(height), this.at(height - 1), claimedHash);
+    this.chain.push(vh);
+    return vh;
+  }
+  /** Pure verification of one header against a window + parent (no mutation). */
+  verifyOne(height, header, window, parent, claimedHash) {
     const hash = (0, import_csd_codec2.headerHash)(header);
     if (claimedHash && claimedHash.toLowerCase() !== hash.toLowerCase()) throw new Error(`header hash mismatch at ${height}`);
     if (height === 0) {
       if (hash.toLowerCase() !== import_csd_codec2.GENESIS_HASH.toLowerCase()) throw new Error(`foreign genesis: ${hash}`);
       if (header.bits !== import_csd_codec2.INITIAL_BITS) throw new Error("genesis bits != INITIAL_BITS");
     } else {
-      const parent = this.chain[height - 1];
+      if (!parent) throw new Error(`no parent context for height ${height}`);
       if (header.prev.toLowerCase() !== parent.hash.toLowerCase()) throw new Error(`broken prev link at ${height}`);
-      const exp = expectedBits(this.chain.map((c) => c.header), height);
+      const exp = expectedBitsFromWindow(window, height);
       if (header.bits !== exp) throw new Error(`bad bits at ${height}: header ${header.bits.toString(16)} != LWMA ${exp.toString(16)}`);
     }
     if (!(0, import_csd_codec2.powOk)((0, import_csd_codec2.headerHashBytes)(header), header.bits)) throw new Error(`invalid PoW at ${height}`);
     const cp = this.checkpoints[height];
     if (cp && cp.toLowerCase() !== hash.toLowerCase()) throw new Error(`checkpoint mismatch at ${height}`);
-    const chainwork = (this.chain[height - 1]?.chainwork ?? 0n) + (0, import_csd_codec2.workForBits)(header.bits);
-    const vh = { height, hash, header, chainwork };
-    this.chain.push(vh);
-    return vh;
+    return { height, hash, header, chainwork: (parent?.chainwork ?? 0n) + (0, import_csd_codec2.workForBits)(header.bits) };
+  }
+  /**
+   * Seed a TRUSTED, contiguous header run ending at a pinned checkpoint, so forward sync needs
+   * only a small window — not a 27k-block genesis fetch. The seed is the trust anchor (PoW links
+   * are still spot-checked, but seed bits aren't LWMA-re-derived; that's the explicit trade for
+   * not syncing from genesis). chainwork becomes RELATIVE to the seed. `checkpointHash` MUST match
+   * the last seeded header.
+   */
+  seedTrusted(seed, checkpointHash) {
+    if (this.chain.length) throw new Error("seedTrusted must be called on a fresh client");
+    if (!seed.length) throw new Error("empty seed");
+    this.baseHeight = seed[0].height;
+    let prevHash = null;
+    for (let i = 0; i < seed.length; i++) {
+      const s = seed[i];
+      if (s.height !== this.baseHeight + i) throw new Error("seed not contiguous");
+      const hash = (0, import_csd_codec2.headerHash)(s.header);
+      if (s.hash && s.hash.toLowerCase() !== hash.toLowerCase()) throw new Error(`seed header hash mismatch at ${s.height}`);
+      if (prevHash && s.header.prev.toLowerCase() !== prevHash.toLowerCase()) throw new Error(`seed prev link broken at ${s.height}`);
+      if (!(0, import_csd_codec2.powOk)((0, import_csd_codec2.headerHashBytes)(s.header), s.header.bits)) throw new Error(`seed PoW invalid at ${s.height}`);
+      this.chain.push({ height: s.height, hash, header: s.header, chainwork: (this.chain[i - 1]?.chainwork ?? 0n) + (0, import_csd_codec2.workForBits)(s.header.bits), trusted: true });
+      prevHash = hash;
+    }
+    if (this.tip.hash.toLowerCase() !== checkpointHash.toLowerCase()) throw new Error(`checkpoint hash mismatch: seeded tip ${this.tip.hash} != ${checkpointHash}`);
+  }
+  /** Fetch + seed the LWMA window ending at `checkpointHeight`, asserting its hash, then ready to sync forward. */
+  async syncFromCheckpoint(checkpointHeight, checkpointHash, context = import_csd_codec2.LWMA_WINDOW) {
+    const start = Math.max(0, checkpointHeight - context);
+    const seed = [];
+    for (let h = start; h <= checkpointHeight; h++) {
+      const { header, hash } = await this.provider(h);
+      seed.push({ height: h, header, hash });
+    }
+    this.seedTrusted(seed, checkpointHash);
+  }
+  /**
+   * Offer a competing branch (contiguous headers starting one above a common ancestor we hold).
+   * Verifies it from the ancestor; if its cumulative chainwork EXCEEDS our current tip, we roll
+   * back to the ancestor and adopt it (max-work rule). Otherwise we keep our chain.
+   */
+  tryReorg(alt) {
+    if (!alt.length) return { adopted: false, reason: "empty branch" };
+    const ancestorHeight = alt[0].height - 1;
+    const ancestor = this.at(ancestorHeight);
+    if (!ancestor) return { adopted: false, reason: `no common ancestor at ${ancestorHeight}` };
+    const verified = [];
+    let prev = ancestor;
+    const baseWindow = this.windowBefore(ancestorHeight + 1);
+    const window = [...baseWindow];
+    for (let i = 0; i < alt.length; i++) {
+      const a = alt[i];
+      if (a.height !== ancestorHeight + 1 + i) return { adopted: false, reason: "alt not contiguous" };
+      let vh;
+      try {
+        vh = this.verifyOne(a.height, a.header, window, prev, a.hash);
+      } catch (e) {
+        return { adopted: false, reason: `alt invalid at ${a.height}: ${e?.message}` };
+      }
+      verified.push(vh);
+      prev = vh;
+      window.push(a.header);
+      if (window.length > import_csd_codec2.LWMA_WINDOW) window.shift();
+    }
+    const altTip = verified[verified.length - 1];
+    if (altTip.chainwork <= this.chainwork) return { adopted: false, reason: `alt work ${altTip.chainwork} \u2264 current ${this.chainwork}` };
+    const rolledBack = this.baseHeight + this.chain.length - 1 - ancestorHeight;
+    this.chain.length = ancestorHeight - this.baseHeight + 1;
+    for (const v of verified) this.chain.push(v);
+    return { adopted: true, rolledBack, newTip: altTip.height };
   }
   /** Verify a tx's inclusion against a verified header (merkle proof built from the block). */
   async verifyTxInclusion(txidHex) {
@@ -144,26 +229,26 @@ var LightClient = class {
     const t = await this.client.tx(txidHex);
     if (!t.ok || t.height == null) return { trustLevel: "rpc-trusted", included: false, reason: "tx not in a block (mempool/unknown)" };
     const height = t.height;
-    if (height >= this.chain.length) {
-      const gap = height - this.chain.length + 1;
-      if (gap > 256) return { trustLevel: "rpc-trusted", included: false, reason: `tx at height ${height} is ${gap} blocks beyond the synced tip \u2014 call sync(${height}) first` };
+    const tipHeight = this.baseHeight + this.chain.length - 1;
+    if (height < this.baseHeight) return { trustLevel: "rpc-trusted", included: false, reason: `tx below the synced base (${this.baseHeight})` };
+    if (height > tipHeight) {
+      const gap = height - tipHeight;
+      if (gap > 256) return { trustLevel: "rpc-trusted", included: false, reason: `tx at ${height} is ${gap} blocks beyond tip \u2014 sync(${height}) first` };
       await this.sync(height);
     }
-    const verified = this.chain[height];
+    const verified = this.at(height);
     if (!verified) return { trustLevel: "rpc-trusted", included: false, reason: "could not verify the containing header" };
     const b = await this.client.blockByHeight(height);
     const txids = b.txs.map((x) => x.txid);
     const pos = txids.findIndex((x) => x.toLowerCase() === txidHex.toLowerCase());
     if (pos < 0) return { trustLevel: "rpc-trusted", included: false, reason: "tx not listed in block" };
-    const branch = (0, import_csd_codec2.merkleBranch)(txids, pos);
-    const ok = (0, import_csd_codec2.verifyMerkleProof)(txidHex, pos, branch, verified.header.merkle);
+    const ok = (0, import_csd_codec2.verifyMerkleProof)(txidHex, pos, (0, import_csd_codec2.merkleBranch)(txids, pos), verified.header.merkle);
     if (!ok) return { trustLevel: "rpc-trusted", included: false, reason: "merkle proof failed" };
-    return { trustLevel: "verified-inclusion", included: true, blockHeight: height, confirmations: this.chain.length - height };
+    return { trustLevel: "verified-inclusion", included: true, blockHeight: height, confirmations: tipHeight - height + 1 };
   }
   /**
-   * Balance for an address. HONEST: this is `rpc-trusted` — a header chain cannot prove an output
-   * is still unspent (no UTXO commitment). A future `scanBalance` will derive it from a Neutrino-
-   * style block scan (`trustLevel: 'scanned'`). Surfaced, never hidden.
+   * Balance for an address. HONEST: `rpc-trusted` — a header chain cannot prove an output is still
+   * unspent (no UTXO commitment). A future Neutrino-style scan would yield `trustLevel:'scanned'`.
    */
   async balance(addr) {
     if (!this.client) throw new Error("no client");
@@ -176,5 +261,6 @@ var LightClient = class {
   CsdClient,
   LightClient,
   expectedBits,
+  expectedBitsFromWindow,
   rpcHeaderToHeader
 });

package/dist/index.d.cts

@@ -2,9 +2,16 @@ import { BlockHeader } from '@inversealtruism/csd-codec';
 import { CsdClient } from '@inversealtruism/csd-client';
 export { CsdClient, RpcTxJson, rpcHeaderToHeader } from '@inversealtruism/csd-client';
 
+/**
+ * Expected `bits` for the block at `height`, given the CHRONOLOGICAL window of the (up to
+ * LWMA_WINDOW) headers immediately preceding it — `window[last]` is the parent (height-1).
+ * This is the core; works for any height with only a 45-header window (cheap spot-checks /
+ * checkpoint-start, no full chain needed). Mirrors expected_bits_strict exactly.
+ */
+declare function expectedBitsFromWindow(window: BlockHeader[], height: number): number;
 /**
  * Expected `bits` for the block at `height`, given the canonical chain `headers[0..=parent]`
- * (index = height; headers[height-1] is the parent). Mirrors expected_bits_strict exactly.
+ * (index = height). Convenience wrapper over expectedBitsFromWindow.
  */
 declare function expectedBits(headers: BlockHeader[], height: number): number;
 
@@ -14,6 +21,7 @@ interface VerifiedHeader {
     hash: string;
     header: BlockHeader;
     chainwork: bigint;
+    trusted?: boolean;
 }
 interface InclusionResult {
     trustLevel: TrustLevel;
@@ -22,7 +30,12 @@ interface InclusionResult {
     confirmations?: number;
     reason?: string;
 }
-/** A header provider — defaults to a CsdClient, injectable for tests. */
+interface ReorgResult {
+    adopted: boolean;
+    rolledBack?: number;
+    newTip?: number;
+    reason?: string;
+}
 type HeaderProvider = (height: number) => Promise<{
     header: BlockHeader;
     hash: string;
@@ -39,24 +52,53 @@ declare class LightClient {
     private readonly client?;
     private readonly provider;
     private readonly checkpoints;
-    /** Verified header chain, index = height. */
+    /** Verified header chain. chain[i].height = baseHeight + i. */
     readonly chain: VerifiedHeader[];
+    /** Height of chain[0] — 0 for genesis-start, the seed start for checkpoint-start. */
+    baseHeight: number;
     constructor(opts?: LightClientOptions);
     get tip(): VerifiedHeader | undefined;
     get chainwork(): bigint;
-    /**
-     * Sync + VERIFY headers [from..to] inclusive onto the chain. `from` must be 0 (genesis) or
-     * exactly chain.length (contiguous). Throws on any consensus violation. Returns the new tip.
-     */
+    /** Whether every header back to genesis was verified (vs trusted from a checkpoint). */
+    get fullyVerified(): boolean;
+    private at;
+    /** The chronological LWMA window (≤ LWMA_WINDOW headers) immediately preceding `height`. */
+    private windowBefore;
+    /** Sync + VERIFY headers [from..to] from genesis (or contiguous to the current tip). */
     sync(to: number, from?: number): Promise<VerifiedHeader>;
-    /** Verify a single header at the given height and append it (consensus checks). */
+    /** Verify a single header at `height` and append it (full consensus checks). */
     ingest(height: number, header: BlockHeader, claimedHash?: string): VerifiedHeader;
+    /** Pure verification of one header against a window + parent (no mutation). */
+    private verifyOne;
+    /**
+     * Seed a TRUSTED, contiguous header run ending at a pinned checkpoint, so forward sync needs
+     * only a small window — not a 27k-block genesis fetch. The seed is the trust anchor (PoW links
+     * are still spot-checked, but seed bits aren't LWMA-re-derived; that's the explicit trade for
+     * not syncing from genesis). chainwork becomes RELATIVE to the seed. `checkpointHash` MUST match
+     * the last seeded header.
+     */
+    seedTrusted(seed: {
+        height: number;
+        header: BlockHeader;
+        hash?: string;
+    }[], checkpointHash: string): void;
+    /** Fetch + seed the LWMA window ending at `checkpointHeight`, asserting its hash, then ready to sync forward. */
+    syncFromCheckpoint(checkpointHeight: number, checkpointHash: string, context?: number): Promise<void>;
+    /**
+     * Offer a competing branch (contiguous headers starting one above a common ancestor we hold).
+     * Verifies it from the ancestor; if its cumulative chainwork EXCEEDS our current tip, we roll
+     * back to the ancestor and adopt it (max-work rule). Otherwise we keep our chain.
+     */
+    tryReorg(alt: {
+        height: number;
+        header: BlockHeader;
+        hash?: string;
+    }[]): ReorgResult;
     /** Verify a tx's inclusion against a verified header (merkle proof built from the block). */
     verifyTxInclusion(txidHex: string): Promise<InclusionResult>;
     /**
-     * Balance for an address. HONEST: this is `rpc-trusted` — a header chain cannot prove an output
-     * is still unspent (no UTXO commitment). A future `scanBalance` will derive it from a Neutrino-
-     * style block scan (`trustLevel: 'scanned'`). Surfaced, never hidden.
+     * Balance for an address. HONEST: `rpc-trusted` — a header chain cannot prove an output is still
+     * unspent (no UTXO commitment). A future Neutrino-style scan would yield `trustLevel:'scanned'`.
      */
     balance(addr: string): Promise<{
         confirmed: number;
@@ -65,4 +107,4 @@ declare class LightClient {
     }>;
 }
 
-export { type HeaderProvider, type InclusionResult, LightClient, type LightClientOptions, type TrustLevel, type VerifiedHeader, expectedBits };
+export { type HeaderProvider, type InclusionResult, LightClient, type LightClientOptions, type ReorgResult, type TrustLevel, type VerifiedHeader, expectedBits, expectedBitsFromWindow };

package/dist/index.d.ts

@@ -2,9 +2,16 @@ import { BlockHeader } from '@inversealtruism/csd-codec';
 import { CsdClient } from '@inversealtruism/csd-client';
 export { CsdClient, RpcTxJson, rpcHeaderToHeader } from '@inversealtruism/csd-client';
 
+/**
+ * Expected `bits` for the block at `height`, given the CHRONOLOGICAL window of the (up to
+ * LWMA_WINDOW) headers immediately preceding it — `window[last]` is the parent (height-1).
+ * This is the core; works for any height with only a 45-header window (cheap spot-checks /
+ * checkpoint-start, no full chain needed). Mirrors expected_bits_strict exactly.
+ */
+declare function expectedBitsFromWindow(window: BlockHeader[], height: number): number;
 /**
  * Expected `bits` for the block at `height`, given the canonical chain `headers[0..=parent]`
- * (index = height; headers[height-1] is the parent). Mirrors expected_bits_strict exactly.
+ * (index = height). Convenience wrapper over expectedBitsFromWindow.
  */
 declare function expectedBits(headers: BlockHeader[], height: number): number;
 
@@ -14,6 +21,7 @@ interface VerifiedHeader {
     hash: string;
     header: BlockHeader;
     chainwork: bigint;
+    trusted?: boolean;
 }
 interface InclusionResult {
     trustLevel: TrustLevel;
@@ -22,7 +30,12 @@ interface InclusionResult {
     confirmations?: number;
     reason?: string;
 }
-/** A header provider — defaults to a CsdClient, injectable for tests. */
+interface ReorgResult {
+    adopted: boolean;
+    rolledBack?: number;
+    newTip?: number;
+    reason?: string;
+}
 type HeaderProvider = (height: number) => Promise<{
     header: BlockHeader;
     hash: string;
@@ -39,24 +52,53 @@ declare class LightClient {
     private readonly client?;
     private readonly provider;
     private readonly checkpoints;
-    /** Verified header chain, index = height. */
+    /** Verified header chain. chain[i].height = baseHeight + i. */
     readonly chain: VerifiedHeader[];
+    /** Height of chain[0] — 0 for genesis-start, the seed start for checkpoint-start. */
+    baseHeight: number;
     constructor(opts?: LightClientOptions);
     get tip(): VerifiedHeader | undefined;
     get chainwork(): bigint;
-    /**
-     * Sync + VERIFY headers [from..to] inclusive onto the chain. `from` must be 0 (genesis) or
-     * exactly chain.length (contiguous). Throws on any consensus violation. Returns the new tip.
-     */
+    /** Whether every header back to genesis was verified (vs trusted from a checkpoint). */
+    get fullyVerified(): boolean;
+    private at;
+    /** The chronological LWMA window (≤ LWMA_WINDOW headers) immediately preceding `height`. */
+    private windowBefore;
+    /** Sync + VERIFY headers [from..to] from genesis (or contiguous to the current tip). */
     sync(to: number, from?: number): Promise<VerifiedHeader>;
-    /** Verify a single header at the given height and append it (consensus checks). */
+    /** Verify a single header at `height` and append it (full consensus checks). */
     ingest(height: number, header: BlockHeader, claimedHash?: string): VerifiedHeader;
+    /** Pure verification of one header against a window + parent (no mutation). */
+    private verifyOne;
+    /**
+     * Seed a TRUSTED, contiguous header run ending at a pinned checkpoint, so forward sync needs
+     * only a small window — not a 27k-block genesis fetch. The seed is the trust anchor (PoW links
+     * are still spot-checked, but seed bits aren't LWMA-re-derived; that's the explicit trade for
+     * not syncing from genesis). chainwork becomes RELATIVE to the seed. `checkpointHash` MUST match
+     * the last seeded header.
+     */
+    seedTrusted(seed: {
+        height: number;
+        header: BlockHeader;
+        hash?: string;
+    }[], checkpointHash: string): void;
+    /** Fetch + seed the LWMA window ending at `checkpointHeight`, asserting its hash, then ready to sync forward. */
+    syncFromCheckpoint(checkpointHeight: number, checkpointHash: string, context?: number): Promise<void>;
+    /**
+     * Offer a competing branch (contiguous headers starting one above a common ancestor we hold).
+     * Verifies it from the ancestor; if its cumulative chainwork EXCEEDS our current tip, we roll
+     * back to the ancestor and adopt it (max-work rule). Otherwise we keep our chain.
+     */
+    tryReorg(alt: {
+        height: number;
+        header: BlockHeader;
+        hash?: string;
+    }[]): ReorgResult;
     /** Verify a tx's inclusion against a verified header (merkle proof built from the block). */
     verifyTxInclusion(txidHex: string): Promise<InclusionResult>;
     /**
-     * Balance for an address. HONEST: this is `rpc-trusted` — a header chain cannot prove an output
-     * is still unspent (no UTXO commitment). A future `scanBalance` will derive it from a Neutrino-
-     * style block scan (`trustLevel: 'scanned'`). Surfaced, never hidden.
+     * Balance for an address. HONEST: `rpc-trusted` — a header chain cannot prove an output is still
+     * unspent (no UTXO commitment). A future Neutrino-style scan would yield `trustLevel:'scanned'`.
      */
     balance(addr: string): Promise<{
         confirmed: number;
@@ -65,4 +107,4 @@ declare class LightClient {
     }>;
 }
 
-export { type HeaderProvider, type InclusionResult, LightClient, type LightClientOptions, type TrustLevel, type VerifiedHeader, expectedBits };
+export { type HeaderProvider, type InclusionResult, LightClient, type LightClientOptions, type ReorgResult, type TrustLevel, type VerifiedHeader, expectedBits, expectedBitsFromWindow };

package/dist/index.js

@@ -7,7 +7,8 @@ import {
   verifyMerkleProof,
   merkleBranch,
   GENESIS_HASH,
-  INITIAL_BITS as INITIAL_BITS2
+  INITIAL_BITS as INITIAL_BITS2,
+  LWMA_WINDOW as LWMA_WINDOW2
 } from "@inversealtruism/csd-codec";
 import { CsdClient, rpcHeaderToHeader } from "@inversealtruism/csd-client";
 
@@ -24,29 +25,23 @@ import {
   TARGET_BLOCK_SECS
 } from "@inversealtruism/csd-codec";
 var POW_LIMIT_TARGET = targetToBigInt(bitsToTarget(POW_LIMIT_BITS));
-function expectedBits(headers, height) {
+function expectedBitsFromWindow(window, height) {
   if (height === 0) return INITIAL_BITS;
-  const parent = headers[height - 1];
-  if (!parent) throw new Error(`expectedBits: missing parent for height ${height}`);
+  const parent = window[window.length - 1];
+  if (!parent) throw new Error(`expectedBits: empty window for height ${height}`);
   if (height < 2) return parent.bits;
-  let n = Math.min(LWMA_WINDOW, height);
+  const n = Math.min(LWMA_WINDOW, height, window.length);
   if (n < 2) return parent.bits;
-  if (n > 1e3) n = 1e3;
+  const w = window.slice(window.length - n);
   const times = [];
   const targets = [];
-  for (let i = 0; i < n; i++) {
-    const idx = height - 1 - i;
-    if (idx < 0) break;
-    const h = headers[idx];
+  for (const h of w) {
     const tb = bitsToTarget(h.bits);
     if (tb.every((b) => b === 0)) throw new Error("expectedBits: invalid compact bits in window");
     times.push(BigInt(h.time));
     targets.push(targetToBigInt(tb));
-    if (idx === 0) break;
   }
   if (times.length < 2) return parent.bits;
-  times.reverse();
-  targets.reverse();
   const m = times.length;
   const t = BigInt(Math.max(TARGET_BLOCK_SECS, 1));
   const maxSolve = BigInt(Math.max(LWMA_SOLVETIME_MAX_FACTOR, 1) * Math.max(TARGET_BLOCK_SECS, 1));
@@ -55,9 +50,9 @@ function expectedBits(headers, height) {
     let dt = times[i] - times[i - 1];
     if (dt < 0n) dt = 0n;
     const st = dt < 1n ? 1n : dt > maxSolve ? maxSolve : dt;
-    const w = BigInt(i);
-    weightedSum += st * w;
-    denom += w;
+    const ww = BigInt(i);
+    weightedSum += st * ww;
+    denom += ww;
   }
   if (denom === 0n) return parent.bits;
   const avgSolvetime = weightedSum / denom;
@@ -71,6 +66,12 @@ function expectedBits(headers, height) {
   if (targetToBigInt(bitsToTarget(bits)) > POW_LIMIT_TARGET) return POW_LIMIT_BITS;
   return bits;
 }
+function expectedBits(headers, height) {
+  if (height === 0) return INITIAL_BITS;
+  const n = Math.min(LWMA_WINDOW, height);
+  const window = headers.slice(height - n, height);
+  return expectedBitsFromWindow(window, height);
+}
 
 // src/index.ts
 import { CsdClient as CsdClient2, rpcHeaderToHeader as rpcHeaderToHeader2 } from "@inversealtruism/csd-client";
@@ -78,8 +79,10 @@ var LightClient = class {
   client;
   provider;
   checkpoints;
-  /** Verified header chain, index = height. */
+  /** Verified header chain. chain[i].height = baseHeight + i. */
   chain = [];
+  /** Height of chain[0] — 0 for genesis-start, the seed start for checkpoint-start. */
+  baseHeight = 0;
   constructor(opts = {}) {
     this.client = opts.client ?? (opts.baseUrl ? new CsdClient({ baseUrl: opts.baseUrl }) : void 0);
     this.checkpoints = opts.checkpoints ?? {};
@@ -95,12 +98,22 @@ var LightClient = class {
   get chainwork() {
     return this.tip?.chainwork ?? 0n;
   }
-  /**
-   * Sync + VERIFY headers [from..to] inclusive onto the chain. `from` must be 0 (genesis) or
-   * exactly chain.length (contiguous). Throws on any consensus violation. Returns the new tip.
-   */
-  async sync(to, from = this.chain.length) {
-    if (from !== this.chain.length) throw new Error(`non-contiguous sync: have ${this.chain.length}, asked from ${from}`);
+  /** Whether every header back to genesis was verified (vs trusted from a checkpoint). */
+  get fullyVerified() {
+    return this.baseHeight === 0;
+  }
+  at(height) {
+    return this.chain[height - this.baseHeight];
+  }
+  /** The chronological LWMA window (≤ LWMA_WINDOW headers) immediately preceding `height`. */
+  windowBefore(height) {
+    const startIdx = Math.max(0, height - this.baseHeight - LWMA_WINDOW2);
+    const endIdx = height - this.baseHeight;
+    return this.chain.slice(startIdx, endIdx).map((c) => c.header);
+  }
+  /** Sync + VERIFY headers [from..to] from genesis (or contiguous to the current tip). */
+  async sync(to, from = this.baseHeight + this.chain.length) {
+    if (from !== this.baseHeight + this.chain.length) throw new Error(`non-contiguous sync: tip ${this.baseHeight + this.chain.length - 1}, asked from ${from}`);
     for (let h = from; h <= to; h++) {
       const { header, hash } = await this.provider(h);
       this.ingest(h, header, hash);
@@ -108,27 +121,99 @@ var LightClient = class {
     if (!this.tip) throw new Error("sync produced no tip");
     return this.tip;
   }
-  /** Verify a single header at the given height and append it (consensus checks). */
+  /** Verify a single header at `height` and append it (full consensus checks). */
   ingest(height, header, claimedHash) {
-    if (height !== this.chain.length) throw new Error(`out-of-order ingest at ${height} (have ${this.chain.length})`);
+    if (height !== this.baseHeight + this.chain.length) throw new Error(`out-of-order ingest at ${height} (tip ${this.baseHeight + this.chain.length - 1})`);
+    const vh = this.verifyOne(height, header, this.windowBefore(height), this.at(height - 1), claimedHash);
+    this.chain.push(vh);
+    return vh;
+  }
+  /** Pure verification of one header against a window + parent (no mutation). */
+  verifyOne(height, header, window, parent, claimedHash) {
     const hash = headerHash(header);
     if (claimedHash && claimedHash.toLowerCase() !== hash.toLowerCase()) throw new Error(`header hash mismatch at ${height}`);
     if (height === 0) {
       if (hash.toLowerCase() !== GENESIS_HASH.toLowerCase()) throw new Error(`foreign genesis: ${hash}`);
       if (header.bits !== INITIAL_BITS2) throw new Error("genesis bits != INITIAL_BITS");
     } else {
-      const parent = this.chain[height - 1];
+      if (!parent) throw new Error(`no parent context for height ${height}`);
       if (header.prev.toLowerCase() !== parent.hash.toLowerCase()) throw new Error(`broken prev link at ${height}`);
-      const exp = expectedBits(this.chain.map((c) => c.header), height);
+      const exp = expectedBitsFromWindow(window, height);
       if (header.bits !== exp) throw new Error(`bad bits at ${height}: header ${header.bits.toString(16)} != LWMA ${exp.toString(16)}`);
     }
     if (!powOk(headerHashBytes(header), header.bits)) throw new Error(`invalid PoW at ${height}`);
     const cp = this.checkpoints[height];
     if (cp && cp.toLowerCase() !== hash.toLowerCase()) throw new Error(`checkpoint mismatch at ${height}`);
-    const chainwork = (this.chain[height - 1]?.chainwork ?? 0n) + workForBits(header.bits);
-    const vh = { height, hash, header, chainwork };
-    this.chain.push(vh);
-    return vh;
+    return { height, hash, header, chainwork: (parent?.chainwork ?? 0n) + workForBits(header.bits) };
+  }
+  /**
+   * Seed a TRUSTED, contiguous header run ending at a pinned checkpoint, so forward sync needs
+   * only a small window — not a 27k-block genesis fetch. The seed is the trust anchor (PoW links
+   * are still spot-checked, but seed bits aren't LWMA-re-derived; that's the explicit trade for
+   * not syncing from genesis). chainwork becomes RELATIVE to the seed. `checkpointHash` MUST match
+   * the last seeded header.
+   */
+  seedTrusted(seed, checkpointHash) {
+    if (this.chain.length) throw new Error("seedTrusted must be called on a fresh client");
+    if (!seed.length) throw new Error("empty seed");
+    this.baseHeight = seed[0].height;
+    let prevHash = null;
+    for (let i = 0; i < seed.length; i++) {
+      const s = seed[i];
+      if (s.height !== this.baseHeight + i) throw new Error("seed not contiguous");
+      const hash = headerHash(s.header);
+      if (s.hash && s.hash.toLowerCase() !== hash.toLowerCase()) throw new Error(`seed header hash mismatch at ${s.height}`);
+      if (prevHash && s.header.prev.toLowerCase() !== prevHash.toLowerCase()) throw new Error(`seed prev link broken at ${s.height}`);
+      if (!powOk(headerHashBytes(s.header), s.header.bits)) throw new Error(`seed PoW invalid at ${s.height}`);
+      this.chain.push({ height: s.height, hash, header: s.header, chainwork: (this.chain[i - 1]?.chainwork ?? 0n) + workForBits(s.header.bits), trusted: true });
+      prevHash = hash;
+    }
+    if (this.tip.hash.toLowerCase() !== checkpointHash.toLowerCase()) throw new Error(`checkpoint hash mismatch: seeded tip ${this.tip.hash} != ${checkpointHash}`);
+  }
+  /** Fetch + seed the LWMA window ending at `checkpointHeight`, asserting its hash, then ready to sync forward. */
+  async syncFromCheckpoint(checkpointHeight, checkpointHash, context = LWMA_WINDOW2) {
+    const start = Math.max(0, checkpointHeight - context);
+    const seed = [];
+    for (let h = start; h <= checkpointHeight; h++) {
+      const { header, hash } = await this.provider(h);
+      seed.push({ height: h, header, hash });
+    }
+    this.seedTrusted(seed, checkpointHash);
+  }
+  /**
+   * Offer a competing branch (contiguous headers starting one above a common ancestor we hold).
+   * Verifies it from the ancestor; if its cumulative chainwork EXCEEDS our current tip, we roll
+   * back to the ancestor and adopt it (max-work rule). Otherwise we keep our chain.
+   */
+  tryReorg(alt) {
+    if (!alt.length) return { adopted: false, reason: "empty branch" };
+    const ancestorHeight = alt[0].height - 1;
+    const ancestor = this.at(ancestorHeight);
+    if (!ancestor) return { adopted: false, reason: `no common ancestor at ${ancestorHeight}` };
+    const verified = [];
+    let prev = ancestor;
+    const baseWindow = this.windowBefore(ancestorHeight + 1);
+    const window = [...baseWindow];
+    for (let i = 0; i < alt.length; i++) {
+      const a = alt[i];
+      if (a.height !== ancestorHeight + 1 + i) return { adopted: false, reason: "alt not contiguous" };
+      let vh;
+      try {
+        vh = this.verifyOne(a.height, a.header, window, prev, a.hash);
+      } catch (e) {
+        return { adopted: false, reason: `alt invalid at ${a.height}: ${e?.message}` };
+      }
+      verified.push(vh);
+      prev = vh;
+      window.push(a.header);
+      if (window.length > LWMA_WINDOW2) window.shift();
+    }
+    const altTip = verified[verified.length - 1];
+    if (altTip.chainwork <= this.chainwork) return { adopted: false, reason: `alt work ${altTip.chainwork} \u2264 current ${this.chainwork}` };
+    const rolledBack = this.baseHeight + this.chain.length - 1 - ancestorHeight;
+    this.chain.length = ancestorHeight - this.baseHeight + 1;
+    for (const v of verified) this.chain.push(v);
+    return { adopted: true, rolledBack, newTip: altTip.height };
   }
   /** Verify a tx's inclusion against a verified header (merkle proof built from the block). */
   async verifyTxInclusion(txidHex) {
@@ -136,26 +221,26 @@ var LightClient = class {
     const t = await this.client.tx(txidHex);
     if (!t.ok || t.height == null) return { trustLevel: "rpc-trusted", included: false, reason: "tx not in a block (mempool/unknown)" };
     const height = t.height;
-    if (height >= this.chain.length) {
-      const gap = height - this.chain.length + 1;
-      if (gap > 256) return { trustLevel: "rpc-trusted", included: false, reason: `tx at height ${height} is ${gap} blocks beyond the synced tip \u2014 call sync(${height}) first` };
+    const tipHeight = this.baseHeight + this.chain.length - 1;
+    if (height < this.baseHeight) return { trustLevel: "rpc-trusted", included: false, reason: `tx below the synced base (${this.baseHeight})` };
+    if (height > tipHeight) {
+      const gap = height - tipHeight;
+      if (gap > 256) return { trustLevel: "rpc-trusted", included: false, reason: `tx at ${height} is ${gap} blocks beyond tip \u2014 sync(${height}) first` };
       await this.sync(height);
     }
-    const verified = this.chain[height];
+    const verified = this.at(height);
     if (!verified) return { trustLevel: "rpc-trusted", included: false, reason: "could not verify the containing header" };
     const b = await this.client.blockByHeight(height);
     const txids = b.txs.map((x) => x.txid);
     const pos = txids.findIndex((x) => x.toLowerCase() === txidHex.toLowerCase());
     if (pos < 0) return { trustLevel: "rpc-trusted", included: false, reason: "tx not listed in block" };
-    const branch = merkleBranch(txids, pos);
-    const ok = verifyMerkleProof(txidHex, pos, branch, verified.header.merkle);
+    const ok = verifyMerkleProof(txidHex, pos, merkleBranch(txids, pos), verified.header.merkle);
     if (!ok) return { trustLevel: "rpc-trusted", included: false, reason: "merkle proof failed" };
-    return { trustLevel: "verified-inclusion", included: true, blockHeight: height, confirmations: this.chain.length - height };
+    return { trustLevel: "verified-inclusion", included: true, blockHeight: height, confirmations: tipHeight - height + 1 };
   }
   /**
-   * Balance for an address. HONEST: this is `rpc-trusted` — a header chain cannot prove an output
-   * is still unspent (no UTXO commitment). A future `scanBalance` will derive it from a Neutrino-
-   * style block scan (`trustLevel: 'scanned'`). Surfaced, never hidden.
+   * Balance for an address. HONEST: `rpc-trusted` — a header chain cannot prove an output is still
+   * unspent (no UTXO commitment). A future Neutrino-style scan would yield `trustLevel:'scanned'`.
    */
   async balance(addr) {
     if (!this.client) throw new Error("no client");
@@ -167,5 +252,6 @@ export {
   CsdClient2 as CsdClient,
   LightClient,
   expectedBits,
+  expectedBitsFromWindow,
   rpcHeaderToHeader2 as rpcHeaderToHeader
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inversealtruism/csd-light",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Compute Substrate light client — headers-first sync with client-side PoW/LWMA/chainwork verification + merkle-inclusion proofs, behind a Helios-style verified-RPC facade with an honest trustLevel on every read.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -15,11 +15,12 @@
   },
   "files": [
     "dist",
-    "LICENSE"
+    "LICENSE",
+    "README.md"
   ],
   "dependencies": {
-    "@inversealtruism/csd-codec": "0.1.1",
-    "@inversealtruism/csd-client": "0.1.1"
+    "@inversealtruism/csd-client": "0.1.2",
+    "@inversealtruism/csd-codec": "0.1.2"
   },
   "license": "MIT",
   "sideEffects": false,