@inversealtruism/cairn-sdk 0.1.0 → 0.1.2

package/README.md

@@ -81,7 +81,7 @@ Subpath imports are available for tree-shaking: `@inversealtruism/cairn-sdk/{con
 ## Trust model & honest limits
 
 - **Content is always verified client-side.** `cairn.content.get()` rejects bytes that don't hash to the requested `payloadHash` — an untrusted gateway can't serve tampered content.
-- **Merkle inclusion is trust-minimized.** `verifyInclusion()` folds the proof and cross-checks the root against the on-chain header merkle → `trustLevel: "verified-inclusion"`. Without that cross-check it reports `"proof-consistent"` (indexer trusted).
+- **Merkle inclusion is trust-minimized — to the strength of your header source.** `verifyInclusion()` folds the proof and, when a header-merkle source is wired, cross-checks the root against it → `trustLevel: "verified-inclusion"`; otherwise `"proof-consistent"` (indexer trusted). That cross-check only means something against an *independent* header, so the default `Cairn` wiring enables it ONLY when your node RPC is a different origin than the indexer (the default same-origin proxy stays at `"proof-consistent"` — a single compromised server can't be cross-checked against itself). For full trust-minimization against a lying node too, supply a PoW-verifying `headerMerkleAt` (e.g. backed by `cairn.chain.light()`).
 - **Balances are RPC-trusted.** Headers don't commit to the UTXO set; balance reads trust the node/proxy (same as every light client).
 - **Indexer/swarm run behind the cairn proxy.** By default `cairn.index` and content resolution use the cairn server's hardened, read-only, rate-limited `/explorer/api` reverse proxy (no separate public indexer needed). **SSE works through it; `subscribe()` (WebSocket) needs a direct indexer endpoint** — set `baseUrls.indexer` to a private/localhost indexer for WS.
 - **Today the wallet injects only on `cairn-substrate.com` + localhost.** Connecting from an arbitrary third-party origin requires the wallet's "connect anywhere" release (broadened injection), which ships after the per-origin consent layer is proven.
@@ -103,6 +103,17 @@ new Cairn({
 });
 ```
 
+## Testing
+
+```bash
+pnpm build && pnpm test         # unit (offline): error mapping, client paths, content+merkle verify
+pnpm test:e2e:read              # live reads vs mainnet + adversarial (free)
+pnpm test:e2e:wallet            # real extension + real connector under Xvfb: connect/consent/sign (free)
+pnpm test:e2e:write             # full pipeline incl. a real on-chain Propose+Attest (spends ~0.3 CSD)
+```
+
+See [`test/e2e/README.md`](test/e2e/README.md) for coverage, requirements, and cost of each layer. The unit + live-read + wallet-connector suites are CI-friendly and free; the write suite needs a funded key and is opt-in.
+
 ## License
 
 MIT

package/dist/{chunk-ETZYBDFC.js → chunk-FNBE2FPE.js}

@@ -75,9 +75,12 @@ var IndexerClient = class {
   /**
    * Verify a tx is included in a block by folding its merkle branch to the root
    * with csd-codec.verifyMerkleProof. If `headerMerkleAt` was provided, the
-   * proof's root is cross-checked against the ON-CHAIN header merkle at that
-   * height → trustLevel "verified-inclusion". Otherwise the proof is only
-   * internally consistent → "proof-consistent" (still useful, but the indexer is trusted).
+   * proof's root is cross-checked against the header merkle at that height →
+   * trustLevel "verified-inclusion" (only as trustworthy as that header source —
+   * see headerMerkleAt). Otherwise the proof is only internally consistent →
+   * "proof-consistent" (still useful, but the indexer is trusted). The Cairn
+   * facade wires headerMerkleAt ONLY when the node RPC is an independent origin
+   * from the indexer, so the default same-origin setup stays at "proof-consistent".
    */
   async verifyInclusion(txid) {
     let proof;

package/dist/index.cjs

@@ -437,9 +437,12 @@ var IndexerClient = class {
   /**
    * Verify a tx is included in a block by folding its merkle branch to the root
    * with csd-codec.verifyMerkleProof. If `headerMerkleAt` was provided, the
-   * proof's root is cross-checked against the ON-CHAIN header merkle at that
-   * height → trustLevel "verified-inclusion". Otherwise the proof is only
-   * internally consistent → "proof-consistent" (still useful, but the indexer is trusted).
+   * proof's root is cross-checked against the header merkle at that height →
+   * trustLevel "verified-inclusion" (only as trustworthy as that header source —
+   * see headerMerkleAt). Otherwise the proof is only internally consistent →
+   * "proof-consistent" (still useful, but the indexer is trusted). The Cairn
+   * facade wires headerMerkleAt ONLY when the node RPC is an independent origin
+   * from the indexer, so the default same-origin setup stays at "proof-consistent".
    */
   async verifyInclusion(txid2) {
     let proof;
@@ -794,6 +797,7 @@ async function connect(opts = {}) {
 }
 
 // src/index.ts
+var DEFAULT_SPV_CHECKPOINT = { height: 31310, hash: "0x000000000000138bd3eee4b8d2fbacb8d5433ac3040ddbf1c45a5e3e0cc9e814" };
 var DEFAULT_CAIRN = "https://cairn-substrate.com";
 var Cairn = class {
   config;
@@ -804,6 +808,10 @@ var Cairn = class {
   board;
   wallet;
   cairnHttp;
+  // Lazily-seeded SPV light client + its checkpoint (audit M3 — PoW-verified header source).
+  _spvLight = null;
+  _spvSeeded = false;
+  _spvCp;
   constructor(config = {}) {
     this.config = config;
     const fetch = config.fetch;
@@ -814,22 +822,41 @@ var Cairn = class {
     this.cairnHttp = new Http({ baseUrl: cairn, fetch, timeoutMs });
     const indexerHttp = new Http({ baseUrl: indexer, fetch, timeoutMs });
     const swarmHttp = config.baseUrls?.swarm ? new Http({ baseUrl: config.baseUrls.swarm.replace(/\/+$/, ""), fetch, timeoutMs }) : void 0;
+    this._spvCp = config.spvCheckpoint ?? DEFAULT_SPV_CHECKPOINT;
     this.chain = new Chain({ rpcUrl: rpc, fetch, timeoutMs });
     this.wallet = config.wallet;
     this.board = new BoardClient(this.cairnHttp, this.wallet);
     this.index = new IndexerClient(indexerHttp, {
       fetch,
       WebSocketImpl: config.WebSocketImpl,
-      // Upgrade inclusion proofs to fully trust-minimized by cross-checking the
-      // proof root against the on-chain header merkle at that height.
-      headerMerkleAt: async (h) => {
-        const block = await this.chain.client.blockByHeight(h);
-        return String(block.header.merkle);
-      }
+      headerMerkleAt: (h) => this.verifiedHeaderMerkleAt(h)
     });
     this.content = new ContentClient({ swarm: swarmHttp, indexer: indexerHttp, cairn: this.cairnHttp });
     this.registry = new RegistryClient({ baseUrl: indexer, fetch });
   }
+  /**
+   * PoW-VERIFIED header merkle at a height (audit M3 — the no-PoW half). Lazily seeds a light
+   * client from the pinned SPV checkpoint and verifies the header chain FORWARD (PoW + LWMA +
+   * chainwork) to `height`, then returns that header's merkle root. THROWS for a height below the
+   * checkpoint (can't verify backward) or if verification fails — the IndexerClient then degrades
+   * to the honest "proof-consistent" instead of over-claiming "verified-inclusion". The verified
+   * header chain is cached across calls; the first call near tip syncs the post-checkpoint span.
+   */
+  async verifiedHeaderMerkleAt(height) {
+    if (!Number.isInteger(height) || height < this._spvCp.height)
+      throw new Error(`height ${height} is below the SPV checkpoint ${this._spvCp.height} (cannot PoW-verify backward)`);
+    if (!this._spvLight) this._spvLight = new import_csd_light.LightClient({ client: this.chain.client, checkpoints: { [this._spvCp.height]: this._spvCp.hash } });
+    const lc = this._spvLight;
+    if (!this._spvSeeded) {
+      await lc.syncFromCheckpoint(this._spvCp.height, this._spvCp.hash);
+      this._spvSeeded = true;
+    }
+    const haveTo = lc.baseHeight + lc.chain.length - 1;
+    if (haveTo < height) await lc.sync(height);
+    const vh = lc.chain[height - lc.baseHeight];
+    if (!vh) throw new Error(`light client has no verified header at ${height}`);
+    return String(vh.header.merkle);
+  }
   /**
    * Detect + connect the Cairn Wallet (browser only). Wires the wallet into
    * `cairn.board` for signed writes. Resolves to the connected address.

package/dist/index.d.cts

@@ -80,6 +80,18 @@ interface CairnConfig {
     wallet?: WalletConnection;
     /** WebSocket implementation for indexer subscriptions (defaults to global). */
     WebSocketImpl?: typeof WebSocket;
+    /**
+     * SPV trust anchor for genuine "verified-inclusion" (audit M3). A merkle inclusion proof is only
+     * "verified-inclusion" when its block header is PoW-verified — otherwise a lying node can serve a
+     * fake header whose merkle matches a fake proof. The light client verifies the header chain
+     * (PoW + LWMA + chainwork) forward from this pinned checkpoint; inclusion at a height ≥ the
+     * checkpoint is then trust-minimized. Defaults to the ecosystem checkpoint (same hash swapguard
+     * ships). Pin your own for full control. Txs BELOW the checkpoint degrade to "proof-consistent".
+     */
+    spvCheckpoint?: {
+        height: number;
+        hash: string;
+    };
 }
 declare class Cairn {
     readonly config: CairnConfig;
@@ -90,7 +102,19 @@ declare class Cairn {
     board: BoardClient;
     wallet?: WalletConnection;
     private readonly cairnHttp;
+    private _spvLight;
+    private _spvSeeded;
+    private readonly _spvCp;
     constructor(config?: CairnConfig);
+    /**
+     * PoW-VERIFIED header merkle at a height (audit M3 — the no-PoW half). Lazily seeds a light
+     * client from the pinned SPV checkpoint and verifies the header chain FORWARD (PoW + LWMA +
+     * chainwork) to `height`, then returns that header's merkle root. THROWS for a height below the
+     * checkpoint (can't verify backward) or if verification fails — the IndexerClient then degrades
+     * to the honest "proof-consistent" instead of over-claiming "verified-inclusion". The verified
+     * header chain is cached across calls; the first call near tip syncs the post-checkpoint span.
+     */
+    private verifiedHeaderMerkleAt;
     /**
      * Detect + connect the Cairn Wallet (browser only). Wires the wallet into
      * `cairn.board` for signed writes. Resolves to the connected address.

package/dist/index.d.ts

@@ -80,6 +80,18 @@ interface CairnConfig {
     wallet?: WalletConnection;
     /** WebSocket implementation for indexer subscriptions (defaults to global). */
     WebSocketImpl?: typeof WebSocket;
+    /**
+     * SPV trust anchor for genuine "verified-inclusion" (audit M3). A merkle inclusion proof is only
+     * "verified-inclusion" when its block header is PoW-verified — otherwise a lying node can serve a
+     * fake header whose merkle matches a fake proof. The light client verifies the header chain
+     * (PoW + LWMA + chainwork) forward from this pinned checkpoint; inclusion at a height ≥ the
+     * checkpoint is then trust-minimized. Defaults to the ecosystem checkpoint (same hash swapguard
+     * ships). Pin your own for full control. Txs BELOW the checkpoint degrade to "proof-consistent".
+     */
+    spvCheckpoint?: {
+        height: number;
+        hash: string;
+    };
 }
 declare class Cairn {
     readonly config: CairnConfig;
@@ -90,7 +102,19 @@ declare class Cairn {
     board: BoardClient;
     wallet?: WalletConnection;
     private readonly cairnHttp;
+    private _spvLight;
+    private _spvSeeded;
+    private readonly _spvCp;
     constructor(config?: CairnConfig);
+    /**
+     * PoW-VERIFIED header merkle at a height (audit M3 — the no-PoW half). Lazily seeds a light
+     * client from the pinned SPV checkpoint and verifies the header chain FORWARD (PoW + LWMA +
+     * chainwork) to `height`, then returns that header's merkle root. THROWS for a height below the
+     * checkpoint (can't verify backward) or if verification fails — the IndexerClient then degrades
+     * to the honest "proof-consistent" instead of over-claiming "verified-inclusion". The verified
+     * header chain is cached across calls; the first call near tip syncs the post-checkpoint span.
+     */
+    private verifiedHeaderMerkleAt;
     /**
      * Detect + connect the Cairn Wallet (browser only). Wires the wallet into
      * `cairn.board` for signed writes. Resolves to the connected address.

package/dist/index.js

@@ -2,7 +2,8 @@ import {
   BoardClient
 } from "./chunk-OGP2W7DL.js";
 import {
-  Chain
+  Chain,
+  LightClient
 } from "./chunk-6VWLWF7R.js";
 import {
   WalletConnection,
@@ -25,7 +26,7 @@ import {
 } from "./chunk-PHMU3CG5.js";
 import {
   IndexerClient
-} from "./chunk-ETZYBDFC.js";
+} from "./chunk-FNBE2FPE.js";
 import {
   RegistryClient
 } from "./chunk-G7FABIF4.js";
@@ -103,6 +104,7 @@ async function safeText(res) {
 }
 
 // src/index.ts
+var DEFAULT_SPV_CHECKPOINT = { height: 31310, hash: "0x000000000000138bd3eee4b8d2fbacb8d5433ac3040ddbf1c45a5e3e0cc9e814" };
 var DEFAULT_CAIRN = "https://cairn-substrate.com";
 var Cairn = class {
   config;
@@ -113,6 +115,10 @@ var Cairn = class {
   board;
   wallet;
   cairnHttp;
+  // Lazily-seeded SPV light client + its checkpoint (audit M3 — PoW-verified header source).
+  _spvLight = null;
+  _spvSeeded = false;
+  _spvCp;
   constructor(config = {}) {
     this.config = config;
     const fetch = config.fetch;
@@ -123,22 +129,41 @@ var Cairn = class {
     this.cairnHttp = new Http({ baseUrl: cairn, fetch, timeoutMs });
     const indexerHttp = new Http({ baseUrl: indexer, fetch, timeoutMs });
     const swarmHttp = config.baseUrls?.swarm ? new Http({ baseUrl: config.baseUrls.swarm.replace(/\/+$/, ""), fetch, timeoutMs }) : void 0;
+    this._spvCp = config.spvCheckpoint ?? DEFAULT_SPV_CHECKPOINT;
     this.chain = new Chain({ rpcUrl: rpc, fetch, timeoutMs });
     this.wallet = config.wallet;
     this.board = new BoardClient(this.cairnHttp, this.wallet);
     this.index = new IndexerClient(indexerHttp, {
       fetch,
       WebSocketImpl: config.WebSocketImpl,
-      // Upgrade inclusion proofs to fully trust-minimized by cross-checking the
-      // proof root against the on-chain header merkle at that height.
-      headerMerkleAt: async (h) => {
-        const block = await this.chain.client.blockByHeight(h);
-        return String(block.header.merkle);
-      }
+      headerMerkleAt: (h) => this.verifiedHeaderMerkleAt(h)
     });
     this.content = new ContentClient({ swarm: swarmHttp, indexer: indexerHttp, cairn: this.cairnHttp });
     this.registry = new RegistryClient({ baseUrl: indexer, fetch });
   }
+  /**
+   * PoW-VERIFIED header merkle at a height (audit M3 — the no-PoW half). Lazily seeds a light
+   * client from the pinned SPV checkpoint and verifies the header chain FORWARD (PoW + LWMA +
+   * chainwork) to `height`, then returns that header's merkle root. THROWS for a height below the
+   * checkpoint (can't verify backward) or if verification fails — the IndexerClient then degrades
+   * to the honest "proof-consistent" instead of over-claiming "verified-inclusion". The verified
+   * header chain is cached across calls; the first call near tip syncs the post-checkpoint span.
+   */
+  async verifiedHeaderMerkleAt(height) {
+    if (!Number.isInteger(height) || height < this._spvCp.height)
+      throw new Error(`height ${height} is below the SPV checkpoint ${this._spvCp.height} (cannot PoW-verify backward)`);
+    if (!this._spvLight) this._spvLight = new LightClient({ client: this.chain.client, checkpoints: { [this._spvCp.height]: this._spvCp.hash } });
+    const lc = this._spvLight;
+    if (!this._spvSeeded) {
+      await lc.syncFromCheckpoint(this._spvCp.height, this._spvCp.hash);
+      this._spvSeeded = true;
+    }
+    const haveTo = lc.baseHeight + lc.chain.length - 1;
+    if (haveTo < height) await lc.sync(height);
+    const vh = lc.chain[height - lc.baseHeight];
+    if (!vh) throw new Error(`light client has no verified header at ${height}`);
+    return String(vh.header.merkle);
+  }
   /**
    * Detect + connect the Cairn Wallet (browser only). Wires the wallet into
    * `cairn.board` for signed writes. Resolves to the connected address.

package/dist/indexer.cjs

@@ -99,9 +99,12 @@ var IndexerClient = class {
   /**
    * Verify a tx is included in a block by folding its merkle branch to the root
    * with csd-codec.verifyMerkleProof. If `headerMerkleAt` was provided, the
-   * proof's root is cross-checked against the ON-CHAIN header merkle at that
-   * height → trustLevel "verified-inclusion". Otherwise the proof is only
-   * internally consistent → "proof-consistent" (still useful, but the indexer is trusted).
+   * proof's root is cross-checked against the header merkle at that height →
+   * trustLevel "verified-inclusion" (only as trustworthy as that header source —
+   * see headerMerkleAt). Otherwise the proof is only internally consistent →
+   * "proof-consistent" (still useful, but the indexer is trusted). The Cairn
+   * facade wires headerMerkleAt ONLY when the node RPC is an independent origin
+   * from the indexer, so the default same-origin setup stays at "proof-consistent".
    */
   async verifyInclusion(txid) {
     let proof;

package/dist/indexer.d.cts

@@ -25,9 +25,13 @@ interface IndexerClientOptions {
     /** A WebSocket implementation (defaults to globalThis.WebSocket). */
     WebSocketImpl?: typeof WebSocket;
     /**
-     * Optional: given a block height, return its on-chain header merkle root. Wire
-     * this from the chain/light client to upgrade verifyInclusion() from
-     * "proof-consistent" to fully trust-minimized "verified-inclusion".
+     * Optional: given a block height, return its on-chain header merkle root. verifyInclusion()
+     * cross-checks the indexer's proof root against this and, on a match, labels the result
+     * "verified-inclusion". IMPORTANT: that label is only as strong as THIS source — it is fully
+     * trust-minimized ONLY if the header is independently verified (e.g. a PoW-checking light client,
+     * or at least a node on a DIFFERENT trust domain than the indexer). A header fetched by raw RPC
+     * from the SAME server that serves the proof proves nothing (one compromised server controls
+     * both); for that case prefer no headerMerkleAt → an honest "proof-consistent".
      */
     headerMerkleAt?: (height: number) => Promise<string>;
 }
@@ -64,9 +68,12 @@ declare class IndexerClient {
     /**
      * Verify a tx is included in a block by folding its merkle branch to the root
      * with csd-codec.verifyMerkleProof. If `headerMerkleAt` was provided, the
-     * proof's root is cross-checked against the ON-CHAIN header merkle at that
-     * height → trustLevel "verified-inclusion". Otherwise the proof is only
-     * internally consistent → "proof-consistent" (still useful, but the indexer is trusted).
+     * proof's root is cross-checked against the header merkle at that height →
+     * trustLevel "verified-inclusion" (only as trustworthy as that header source —
+     * see headerMerkleAt). Otherwise the proof is only internally consistent →
+     * "proof-consistent" (still useful, but the indexer is trusted). The Cairn
+     * facade wires headerMerkleAt ONLY when the node RPC is an independent origin
+     * from the indexer, so the default same-origin setup stays at "proof-consistent".
      */
     verifyInclusion(txid: string): Promise<InclusionResult>;
     /** Stream all events (blocks, proposals, attestations, reorgs) via SSE. */

package/dist/indexer.d.ts

@@ -25,9 +25,13 @@ interface IndexerClientOptions {
     /** A WebSocket implementation (defaults to globalThis.WebSocket). */
     WebSocketImpl?: typeof WebSocket;
     /**
-     * Optional: given a block height, return its on-chain header merkle root. Wire
-     * this from the chain/light client to upgrade verifyInclusion() from
-     * "proof-consistent" to fully trust-minimized "verified-inclusion".
+     * Optional: given a block height, return its on-chain header merkle root. verifyInclusion()
+     * cross-checks the indexer's proof root against this and, on a match, labels the result
+     * "verified-inclusion". IMPORTANT: that label is only as strong as THIS source — it is fully
+     * trust-minimized ONLY if the header is independently verified (e.g. a PoW-checking light client,
+     * or at least a node on a DIFFERENT trust domain than the indexer). A header fetched by raw RPC
+     * from the SAME server that serves the proof proves nothing (one compromised server controls
+     * both); for that case prefer no headerMerkleAt → an honest "proof-consistent".
      */
     headerMerkleAt?: (height: number) => Promise<string>;
 }
@@ -64,9 +68,12 @@ declare class IndexerClient {
     /**
      * Verify a tx is included in a block by folding its merkle branch to the root
      * with csd-codec.verifyMerkleProof. If `headerMerkleAt` was provided, the
-     * proof's root is cross-checked against the ON-CHAIN header merkle at that
-     * height → trustLevel "verified-inclusion". Otherwise the proof is only
-     * internally consistent → "proof-consistent" (still useful, but the indexer is trusted).
+     * proof's root is cross-checked against the header merkle at that height →
+     * trustLevel "verified-inclusion" (only as trustworthy as that header source —
+     * see headerMerkleAt). Otherwise the proof is only internally consistent →
+     * "proof-consistent" (still useful, but the indexer is trusted). The Cairn
+     * facade wires headerMerkleAt ONLY when the node RPC is an independent origin
+     * from the indexer, so the default same-origin setup stays at "proof-consistent".
      */
     verifyInclusion(txid: string): Promise<InclusionResult>;
     /** Stream all events (blocks, proposals, attestations, reorgs) via SSE. */

package/dist/indexer.js

@@ -1,6 +1,6 @@
 import {
   IndexerClient
-} from "./chunk-ETZYBDFC.js";
+} from "./chunk-FNBE2FPE.js";
 export {
   IndexerClient
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inversealtruism/cairn-sdk",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "The Compute Substrate dApp kit — one cohesive toolkit to connect the Cairn Wallet, read the chain/board, publish self-certifying content, and resolve registries. Composes the published csd-* primitives.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -53,18 +53,24 @@
     "test": "tsx test/sdk.test.ts && tsx test/connect.test.ts",
     "test:live": "node examples/read-only.mjs",
     "build:example": "node scripts/build-example.mjs",
-    "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\""
+    "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
+    "test:e2e:read": "node test/e2e/e2e-read.mjs",
+    "test:e2e:wallet": "xvfb-run -a node test/e2e/e2e-wallet-connect.mjs",
+    "test:e2e:write": "node test/e2e/e2e-write.mjs",
+    "test:e2e": "node test/e2e/e2e-read.mjs && xvfb-run -a node test/e2e/e2e-wallet-connect.mjs",
+    "test:all": "pnpm test && pnpm test:e2e"
   },
   "dependencies": {
-    "@inversealtruism/csd-codec": "^0.1.3",
-    "@inversealtruism/csd-crypto": "^0.1.3",
-    "@inversealtruism/csd-tx": "^0.1.3",
-    "@inversealtruism/csd-client": "^0.1.3",
-    "@inversealtruism/csd-light": "^0.1.3",
-    "@inversealtruism/csd-registry": "^0.1.3"
+    "@inversealtruism/csd-client": "^0.1.5",
+    "@inversealtruism/csd-codec": "^0.1.5",
+    "@inversealtruism/csd-crypto": "^0.1.5",
+    "@inversealtruism/csd-light": "^0.1.5",
+    "@inversealtruism/csd-registry": "^0.1.5",
+    "@inversealtruism/csd-tx": "^0.1.5"
   },
   "devDependencies": {
     "esbuild": "^0.27.0",
+    "playwright-core": "^1.49.0",
     "tsup": "^8.5.1",
     "tsx": "^4.19.2",
     "typescript": "^5.6.0"