@inversealtruism/cairn-sdk 0.1.1 → 0.1.3

package/dist/index.d.ts

@@ -9,7 +9,8 @@ import { ContentClient } from './content.js';
 export { ContentClientOptions, PreparedContent } from './content.js';
 import { RegistryClient } from './registry.js';
 import { WalletConnection, DetectOptions } from './connect.js';
-export { AttestParams, CairnProvider, ConnectResult, ProposeParams, SealClaimParams, SendParams, SignInResult, TxResult, connect, detectProvider, getWallet, isInstalled } from './connect.js';
+export { AttestParams, CairnProvider, ConnectResult, FillParams, ProposeParams, ProviderDetail, ProviderInfo, SealClaimParams, SendParams, SignInResult, SiwcParams, SiwcResult, TxResult, WalletCapabilities, WalletPermission, connect, detectProvider, discoverProviders, getWallet, isInstalled } from './connect.js';
+export { CairnController, CairnControllerOptions, CairnState } from './controller.js';
 import '@inversealtruism/csd-client';
 import '@inversealtruism/csd-tx';
 import '@inversealtruism/csd-codec';
@@ -17,8 +18,29 @@ import '@inversealtruism/csd-crypto';
 import '@inversealtruism/csd-light';
 import '@inversealtruism/csd-registry';
 
+/** Stable machine-readable error codes (branch on these, not the message text). */
+type CairnErrorCode = "NOT_INSTALLED" | "USER_REJECTED" | "WALLET_LOCKED" | "UNSUPPORTED_METHOD" | "HTTP_ERROR" | "CONTENT_VERIFICATION" | "UNKNOWN";
+declare const SDK_VERSION = "0.1.2";
+interface CairnErrorOptions {
+    code?: CairnErrorCode;
+    docsPath?: string;
+    cause?: unknown;
+}
 declare class CairnError extends Error {
-    constructor(message: string);
+    /** Stable machine code for programmatic branching. */
+    readonly code: CairnErrorCode;
+    /** The human message without the appended docs/version footer. */
+    readonly shortMessage: string;
+    /** Relative docs path (under the SDK docs base), if any. */
+    readonly docsPath?: string;
+    /** The cairn-sdk version that produced this error. */
+    readonly version = "0.1.2";
+    constructor(shortMessage: string, opts?: CairnErrorOptions);
+    /**
+     * Walk the `cause` chain. With a predicate, returns the FIRST matching error (or null). Without one,
+     * returns the DEEPEST cause (the root). Mirrors viem's `BaseError.walk()`.
+     */
+    walk(fn?: (err: unknown) => boolean): unknown;
 }
 /** The Cairn Wallet extension is not installed (no `window.cairn` appeared). */
 declare class NotInstalledError extends CairnError {
@@ -32,7 +54,7 @@ declare class UserRejectedError extends CairnError {
 declare class WalletLockedError extends CairnError {
     constructor(message?: string);
 }
-/** The method is not exposed to dApps by the wallet boundary. */
+/** The method is not exposed to dApps by the wallet boundary (or the wallet is too old for it). */
 declare class UnsupportedMethodError extends CairnError {
     constructor(message?: string);
 }
@@ -48,6 +70,13 @@ declare class ContentVerificationError extends CairnError {
     expected: string;
     constructor(expected: string);
 }
+/**
+ * Map a provider error string (from the wallet's `{ ok:false, error }`) onto a typed error. The
+ * wallet's strings are stable: "rejected by user", "wallet locked", "unsupported dApp method: …".
+ */
+declare function mapProviderError(error: string): CairnError;
+/** Convenience: the stable code of any error (or "UNKNOWN" for a non-CairnError). */
+declare function errorCode(err: unknown): CairnErrorCode;
 
 interface CairnBaseUrls {
     /** Cairn board server (board + /api/rpc proxy + /content origin). Default https://cairn-substrate.com */
@@ -80,6 +109,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 +131,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.
@@ -102,4 +155,4 @@ declare class Cairn {
     get connected(): boolean;
 }
 
-export { BoardClient, Cairn, type CairnBaseUrls, type CairnConfig, CairnError, Chain, ContentClient, ContentVerificationError, DetectOptions, FetchLike, HttpError, IndexerClient, NotInstalledError, RegistryClient, UnsupportedMethodError, UserRejectedError, WalletConnection, WalletLockedError };
+export { BoardClient, Cairn, type CairnBaseUrls, type CairnConfig, CairnError, type CairnErrorCode, type CairnErrorOptions, Chain, ContentClient, ContentVerificationError, DetectOptions, FetchLike, HttpError, IndexerClient, NotInstalledError, RegistryClient, SDK_VERSION, UnsupportedMethodError, UserRejectedError, WalletConnection, WalletLockedError, errorCode, mapProviderError };

package/dist/index.js

@@ -1,34 +1,42 @@
+import {
+  RegistryClient
+} from "./chunk-G7FABIF4.js";
 import {
   BoardClient
-} from "./chunk-OGP2W7DL.js";
+} from "./chunk-645CYBVN.js";
+import {
+  Chain,
+  LightClient
+} from "./chunk-5KAUQH72.js";
+import {
+  ContentClient
+} from "./chunk-OSXS26RA.js";
+import {
+  IndexerClient
+} from "./chunk-FNBE2FPE.js";
 import {
-  Chain
-} from "./chunk-6VWLWF7R.js";
+  CairnController
+} from "./chunk-ZAE2BIH5.js";
 import {
   WalletConnection,
   connect,
   detectProvider,
+  discoverProviders,
   getWallet,
   isInstalled
-} from "./chunk-SMAPCKVG.js";
-import {
-  ContentClient
-} from "./chunk-BZVJVL4Q.js";
+} from "./chunk-G4OZKZSJ.js";
 import {
   CairnError,
   ContentVerificationError,
   HttpError,
   NotInstalledError,
+  SDK_VERSION,
   UnsupportedMethodError,
   UserRejectedError,
-  WalletLockedError
-} from "./chunk-PHMU3CG5.js";
-import {
-  IndexerClient
-} from "./chunk-ETZYBDFC.js";
-import {
-  RegistryClient
-} from "./chunk-G7FABIF4.js";
+  WalletLockedError,
+  errorCode,
+  mapProviderError
+} from "./chunk-UMGWVOOT.js";
 
 // src/http.ts
 var Http = class {
@@ -103,6 +111,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 +122,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 +136,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.
@@ -161,6 +193,7 @@ var Cairn = class {
 export {
   BoardClient,
   Cairn,
+  CairnController,
   CairnError,
   Chain,
   ContentClient,
@@ -170,12 +203,16 @@ export {
   IndexerClient,
   NotInstalledError,
   RegistryClient,
+  SDK_VERSION,
   UnsupportedMethodError,
   UserRejectedError,
   WalletConnection,
   WalletLockedError,
   connect,
   detectProvider,
+  discoverProviders,
+  errorCode,
   getWallet,
-  isInstalled
+  isInstalled,
+  mapProviderError
 };

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
 };