@inversealtruism/csd-light 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 InverseAltruism
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.cjs

@@ -0,0 +1,180 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  CsdClient: () => import_csd_client2.CsdClient,
+  LightClient: () => LightClient,
+  expectedBits: () => expectedBits,
+  rpcHeaderToHeader: () => import_csd_client2.rpcHeaderToHeader
+});
+module.exports = __toCommonJS(index_exports);
+var import_csd_codec2 = require("@inversealtruism/csd-codec");
+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) {
+  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}`);
+  if (height < 2) return parent.bits;
+  let n = Math.min(import_csd_codec.LWMA_WINDOW, height);
+  if (n < 2) return parent.bits;
+  if (n > 1e3) n = 1e3;
+  const times = [];
+  const targets = [];
+  for (let i = 0; i < n; i++) {
+    const idx = height - 1 - i;
+    if (idx < 0) break;
+    const h = headers[idx];
+    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));
+  let weightedSum = 0n, denom = 0n;
+  for (let i = 1; i < m; i++) {
+    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;
+  }
+  if (denom === 0n) return parent.bits;
+  const avgSolvetime = weightedSum / denom;
+  let sumTarget = 0n;
+  for (const tg of targets) sumTarget += tg;
+  const avgTarget = sumTarget / BigInt(m);
+  let nextTarget = avgTarget * avgSolvetime / t;
+  if (nextTarget > POW_LIMIT_TARGET) nextTarget = POW_LIMIT_TARGET;
+  if (nextTarget === 0n || nextTarget >= 1n << 256n) return import_csd_codec.POW_LIMIT_BITS;
+  const bits = (0, import_csd_codec.targetToBits)((0, import_csd_codec.bigIntToTarget)(nextTarget));
+  if ((0, import_csd_codec.targetToBigInt)((0, import_csd_codec.bitsToTarget)(bits)) > POW_LIMIT_TARGET) return import_csd_codec.POW_LIMIT_BITS;
+  return bits;
+}
+
+// src/index.ts
+var import_csd_client2 = require("@inversealtruism/csd-client");
+var LightClient = class {
+  client;
+  provider;
+  checkpoints;
+  /** Verified header chain, index = height. */
+  chain = [];
+  constructor(opts = {}) {
+    this.client = opts.client ?? (opts.baseUrl ? new import_csd_client.CsdClient({ baseUrl: opts.baseUrl }) : void 0);
+    this.checkpoints = opts.checkpoints ?? {};
+    this.provider = opts.headerProvider ?? (async (h) => {
+      if (!this.client) throw new Error("LightClient needs a client/baseUrl or a headerProvider");
+      const b = await this.client.blockByHeight(h);
+      return { header: (0, import_csd_client.rpcHeaderToHeader)(b.header), hash: b.hash, txids: b.txs.map((t) => t.txid) };
+    });
+  }
+  get tip() {
+    return this.chain[this.chain.length - 1];
+  }
+  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}`);
+    for (let h = from; h <= to; h++) {
+      const { header, hash } = await this.provider(h);
+      this.ingest(h, header, hash);
+    }
+    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). */
+  ingest(height, header, claimedHash) {
+    if (height !== this.chain.length) throw new Error(`out-of-order ingest at ${height} (have ${this.chain.length})`);
+    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 (header.prev.toLowerCase() !== parent.hash.toLowerCase()) throw new Error(`broken prev link at ${height}`);
+      const exp = expectedBits(this.chain.map((c) => c.header), 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;
+  }
+  /** Verify a tx's inclusion against a verified header (merkle proof built from the block). */
+  async verifyTxInclusion(txidHex) {
+    if (!this.client) return { trustLevel: "rpc-trusted", included: false, reason: "no client for proof fetch" };
+    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` };
+      await this.sync(height);
+    }
+    const verified = this.chain[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);
+    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 };
+  }
+  /**
+   * 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.
+   */
+  async balance(addr) {
+    if (!this.client) throw new Error("no client");
+    const u = await this.client.utxos(addr);
+    return { confirmed: u.confirmed_balance, trustLevel: "rpc-trusted", note: "balance is RPC-trusted; a header chain cannot prove non-spend (no UTXO commitment)" };
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CsdClient,
+  LightClient,
+  expectedBits,
+  rpcHeaderToHeader
+});

package/dist/index.d.cts

@@ -0,0 +1,68 @@
+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 canonical chain `headers[0..=parent]`
+ * (index = height; headers[height-1] is the parent). Mirrors expected_bits_strict exactly.
+ */
+declare function expectedBits(headers: BlockHeader[], height: number): number;
+
+type TrustLevel = "verified-inclusion" | "scanned" | "rpc-trusted";
+interface VerifiedHeader {
+    height: number;
+    hash: string;
+    header: BlockHeader;
+    chainwork: bigint;
+}
+interface InclusionResult {
+    trustLevel: TrustLevel;
+    included: boolean;
+    blockHeight?: number;
+    confirmations?: number;
+    reason?: string;
+}
+/** A header provider — defaults to a CsdClient, injectable for tests. */
+type HeaderProvider = (height: number) => Promise<{
+    header: BlockHeader;
+    hash: string;
+    txids: string[];
+}>;
+interface LightClientOptions {
+    client?: CsdClient;
+    baseUrl?: string;
+    headerProvider?: HeaderProvider;
+    /** Pin checkpoints {height: expectedHash} to bound/accelerate sync (optional). */
+    checkpoints?: Record<number, string>;
+}
+declare class LightClient {
+    private readonly client?;
+    private readonly provider;
+    private readonly checkpoints;
+    /** Verified header chain, index = height. */
+    readonly chain: VerifiedHeader[];
+    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.
+     */
+    sync(to: number, from?: number): Promise<VerifiedHeader>;
+    /** Verify a single header at the given height and append it (consensus checks). */
+    ingest(height: number, header: BlockHeader, claimedHash?: string): VerifiedHeader;
+    /** 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(addr: string): Promise<{
+        confirmed: number;
+        trustLevel: TrustLevel;
+        note: string;
+    }>;
+}
+
+export { type HeaderProvider, type InclusionResult, LightClient, type LightClientOptions, type TrustLevel, type VerifiedHeader, expectedBits };

package/dist/index.d.ts

@@ -0,0 +1,68 @@
+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 canonical chain `headers[0..=parent]`
+ * (index = height; headers[height-1] is the parent). Mirrors expected_bits_strict exactly.
+ */
+declare function expectedBits(headers: BlockHeader[], height: number): number;
+
+type TrustLevel = "verified-inclusion" | "scanned" | "rpc-trusted";
+interface VerifiedHeader {
+    height: number;
+    hash: string;
+    header: BlockHeader;
+    chainwork: bigint;
+}
+interface InclusionResult {
+    trustLevel: TrustLevel;
+    included: boolean;
+    blockHeight?: number;
+    confirmations?: number;
+    reason?: string;
+}
+/** A header provider — defaults to a CsdClient, injectable for tests. */
+type HeaderProvider = (height: number) => Promise<{
+    header: BlockHeader;
+    hash: string;
+    txids: string[];
+}>;
+interface LightClientOptions {
+    client?: CsdClient;
+    baseUrl?: string;
+    headerProvider?: HeaderProvider;
+    /** Pin checkpoints {height: expectedHash} to bound/accelerate sync (optional). */
+    checkpoints?: Record<number, string>;
+}
+declare class LightClient {
+    private readonly client?;
+    private readonly provider;
+    private readonly checkpoints;
+    /** Verified header chain, index = height. */
+    readonly chain: VerifiedHeader[];
+    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.
+     */
+    sync(to: number, from?: number): Promise<VerifiedHeader>;
+    /** Verify a single header at the given height and append it (consensus checks). */
+    ingest(height: number, header: BlockHeader, claimedHash?: string): VerifiedHeader;
+    /** 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(addr: string): Promise<{
+        confirmed: number;
+        trustLevel: TrustLevel;
+        note: string;
+    }>;
+}
+
+export { type HeaderProvider, type InclusionResult, LightClient, type LightClientOptions, type TrustLevel, type VerifiedHeader, expectedBits };

package/dist/index.js

@@ -0,0 +1,171 @@
+// src/index.ts
+import {
+  headerHash,
+  headerHashBytes,
+  powOk,
+  workForBits,
+  verifyMerkleProof,
+  merkleBranch,
+  GENESIS_HASH,
+  INITIAL_BITS as INITIAL_BITS2
+} from "@inversealtruism/csd-codec";
+import { CsdClient, rpcHeaderToHeader } from "@inversealtruism/csd-client";
+
+// src/lwma.ts
+import {
+  bitsToTarget,
+  targetToBigInt,
+  bigIntToTarget,
+  targetToBits,
+  INITIAL_BITS,
+  POW_LIMIT_BITS,
+  LWMA_WINDOW,
+  LWMA_SOLVETIME_MAX_FACTOR,
+  TARGET_BLOCK_SECS
+} from "@inversealtruism/csd-codec";
+var POW_LIMIT_TARGET = targetToBigInt(bitsToTarget(POW_LIMIT_BITS));
+function expectedBits(headers, height) {
+  if (height === 0) return INITIAL_BITS;
+  const parent = headers[height - 1];
+  if (!parent) throw new Error(`expectedBits: missing parent for height ${height}`);
+  if (height < 2) return parent.bits;
+  let n = Math.min(LWMA_WINDOW, height);
+  if (n < 2) return parent.bits;
+  if (n > 1e3) n = 1e3;
+  const times = [];
+  const targets = [];
+  for (let i = 0; i < n; i++) {
+    const idx = height - 1 - i;
+    if (idx < 0) break;
+    const h = headers[idx];
+    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));
+  let weightedSum = 0n, denom = 0n;
+  for (let i = 1; i < m; i++) {
+    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;
+  }
+  if (denom === 0n) return parent.bits;
+  const avgSolvetime = weightedSum / denom;
+  let sumTarget = 0n;
+  for (const tg of targets) sumTarget += tg;
+  const avgTarget = sumTarget / BigInt(m);
+  let nextTarget = avgTarget * avgSolvetime / t;
+  if (nextTarget > POW_LIMIT_TARGET) nextTarget = POW_LIMIT_TARGET;
+  if (nextTarget === 0n || nextTarget >= 1n << 256n) return POW_LIMIT_BITS;
+  const bits = targetToBits(bigIntToTarget(nextTarget));
+  if (targetToBigInt(bitsToTarget(bits)) > POW_LIMIT_TARGET) return POW_LIMIT_BITS;
+  return bits;
+}
+
+// src/index.ts
+import { CsdClient as CsdClient2, rpcHeaderToHeader as rpcHeaderToHeader2 } from "@inversealtruism/csd-client";
+var LightClient = class {
+  client;
+  provider;
+  checkpoints;
+  /** Verified header chain, index = height. */
+  chain = [];
+  constructor(opts = {}) {
+    this.client = opts.client ?? (opts.baseUrl ? new CsdClient({ baseUrl: opts.baseUrl }) : void 0);
+    this.checkpoints = opts.checkpoints ?? {};
+    this.provider = opts.headerProvider ?? (async (h) => {
+      if (!this.client) throw new Error("LightClient needs a client/baseUrl or a headerProvider");
+      const b = await this.client.blockByHeight(h);
+      return { header: rpcHeaderToHeader(b.header), hash: b.hash, txids: b.txs.map((t) => t.txid) };
+    });
+  }
+  get tip() {
+    return this.chain[this.chain.length - 1];
+  }
+  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}`);
+    for (let h = from; h <= to; h++) {
+      const { header, hash } = await this.provider(h);
+      this.ingest(h, header, hash);
+    }
+    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). */
+  ingest(height, header, claimedHash) {
+    if (height !== this.chain.length) throw new Error(`out-of-order ingest at ${height} (have ${this.chain.length})`);
+    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 (header.prev.toLowerCase() !== parent.hash.toLowerCase()) throw new Error(`broken prev link at ${height}`);
+      const exp = expectedBits(this.chain.map((c) => c.header), 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;
+  }
+  /** Verify a tx's inclusion against a verified header (merkle proof built from the block). */
+  async verifyTxInclusion(txidHex) {
+    if (!this.client) return { trustLevel: "rpc-trusted", included: false, reason: "no client for proof fetch" };
+    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` };
+      await this.sync(height);
+    }
+    const verified = this.chain[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);
+    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 };
+  }
+  /**
+   * 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.
+   */
+  async balance(addr) {
+    if (!this.client) throw new Error("no client");
+    const u = await this.client.utxos(addr);
+    return { confirmed: u.confirmed_balance, trustLevel: "rpc-trusted", note: "balance is RPC-trusted; a header chain cannot prove non-spend (no UTXO commitment)" };
+  }
+};
+export {
+  CsdClient2 as CsdClient,
+  LightClient,
+  expectedBits,
+  rpcHeaderToHeader2 as rpcHeaderToHeader
+};

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@inversealtruism/csd-light",
+  "version": "0.1.0",
+  "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",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@inversealtruism/csd-codec": "0.1.0",
+    "@inversealtruism/csd-client": "0.1.0"
+  },
+  "license": "MIT",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/InverseAltruism/csd-sdk.git",
+    "directory": "packages/light"
+  },
+  "homepage": "https://cairn-substrate.com",
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "test": "tsx test/light.test.ts"
+  }
+}