@inversealtruism/cairn-sdk 0.1.1 → 0.1.3

package/dist/index.cjs

@@ -22,6 +22,7 @@ var index_exports = {};
 __export(index_exports, {
   BoardClient: () => BoardClient,
   Cairn: () => Cairn,
+  CairnController: () => CairnController,
   CairnError: () => CairnError,
   Chain: () => Chain,
   ContentClient: () => ContentClient,
@@ -31,42 +32,77 @@ __export(index_exports, {
   IndexerClient: () => IndexerClient,
   NotInstalledError: () => NotInstalledError,
   RegistryClient: () => RegistryClient,
+  SDK_VERSION: () => SDK_VERSION,
   UnsupportedMethodError: () => UnsupportedMethodError,
   UserRejectedError: () => UserRejectedError,
   WalletConnection: () => WalletConnection,
   WalletLockedError: () => WalletLockedError,
   connect: () => connect,
   detectProvider: () => detectProvider,
+  discoverProviders: () => discoverProviders,
+  errorCode: () => errorCode,
   getWallet: () => getWallet,
-  isInstalled: () => isInstalled
+  isInstalled: () => isInstalled,
+  mapProviderError: () => mapProviderError
 });
 module.exports = __toCommonJS(index_exports);
 
 // src/errors.ts
+var SDK_VERSION = "0.1.2";
+var DOCS_BASE = "https://cairn-substrate.com/docs/sdk";
 var CairnError = class extends Error {
-  constructor(message) {
-    super(message);
+  /** Stable machine code for programmatic branching. */
+  code;
+  /** The human message without the appended docs/version footer. */
+  shortMessage;
+  /** Relative docs path (under the SDK docs base), if any. */
+  docsPath;
+  /** The cairn-sdk version that produced this error. */
+  version = SDK_VERSION;
+  constructor(shortMessage, opts = {}) {
+    const docs = opts.docsPath;
+    super(
+      [shortMessage, docs ? `Docs: ${DOCS_BASE}${docs}` : "", `Version: cairn-sdk@${SDK_VERSION}`].filter(Boolean).join("\n"),
+      { cause: opts.cause }
+    );
     this.name = new.target.name;
+    this.code = opts.code ?? "UNKNOWN";
+    this.shortMessage = shortMessage;
+    this.docsPath = docs;
+  }
+  /**
+   * 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) {
+    let current = this;
+    let last = this;
+    while (current != null) {
+      if (fn && fn(current)) return current;
+      last = current;
+      current = current?.cause;
+    }
+    return fn ? null : last;
   }
 };
 var NotInstalledError = class extends CairnError {
   constructor(message = "Cairn Wallet not detected. Install it from cairn-substrate.com.") {
-    super(message);
+    super(message, { code: "NOT_INSTALLED", docsPath: "/install" });
   }
 };
 var UserRejectedError = class extends CairnError {
   constructor(message = "Request rejected by user.") {
-    super(message);
+    super(message, { code: "USER_REJECTED", docsPath: "/errors#user-rejected" });
   }
 };
 var WalletLockedError = class extends CairnError {
   constructor(message = "Wallet is locked.") {
-    super(message);
+    super(message, { code: "WALLET_LOCKED", docsPath: "/errors#wallet-locked" });
   }
 };
 var UnsupportedMethodError = class extends CairnError {
   constructor(message = "Method not supported by the wallet.") {
-    super(message);
+    super(message, { code: "UNSUPPORTED_METHOD", docsPath: "/errors#unsupported-method" });
   }
 };
 var HttpError = class extends CairnError {
@@ -74,7 +110,7 @@ var HttpError = class extends CairnError {
   url;
   body;
   constructor(status, url, body) {
-    super(`HTTP ${status} for ${url}${body ? `: ${String(body).slice(0, 200)}` : ""}`);
+    super(`HTTP ${status} for ${url}${body ? `: ${String(body).slice(0, 200)}` : ""}`, { code: "HTTP_ERROR" });
     this.status = status;
     this.url = url;
     this.body = body;
@@ -83,7 +119,7 @@ var HttpError = class extends CairnError {
 var ContentVerificationError = class extends CairnError {
   expected;
   constructor(expected) {
-    super(`Content does not match its payload hash ${expected} \u2014 bytes were tampered with in transit.`);
+    super(`Content does not match its payload hash ${expected} \u2014 bytes were tampered with in transit.`, { code: "CONTENT_VERIFICATION", docsPath: "/content#verification" });
     this.expected = expected;
   }
 };
@@ -91,9 +127,12 @@ function mapProviderError(error) {
   const e = String(error || "").toLowerCase();
   if (e.includes("rejected by user")) return new UserRejectedError(error);
   if (e.includes("wallet locked")) return new WalletLockedError(error);
-  if (e.includes("unsupported dapp method")) return new UnsupportedMethodError(error);
+  if (e.includes("unsupported dapp method") || e.includes("predates") || e.includes("too old")) return new UnsupportedMethodError(error);
   return new CairnError(error || "Unknown wallet error");
 }
+function errorCode(err) {
+  return err instanceof CairnError ? err.code : "UNKNOWN";
+}
 
 // src/http.ts
 var Http = class {
@@ -175,6 +214,8 @@ var import_csd_crypto = require("@inversealtruism/csd-crypto");
 var import_csd_light = require("@inversealtruism/csd-light");
 var import_csd_client2 = require("@inversealtruism/csd-client");
 var import_csd_light2 = require("@inversealtruism/csd-light");
+var import_csd_tx2 = require("@inversealtruism/csd-tx");
+var import_csd_crypto2 = require("@inversealtruism/csd-crypto");
 var Chain = class {
   client;
   opts;
@@ -195,6 +236,29 @@ var Chain = class {
   submit(nodeJsonTx) {
     return this.client.submit(nodeJsonTx);
   }
+  /**
+   * Build + sign (+ optionally broadcast) a transfer with INPUT-VALUE VERIFICATION (the H2-safe send).
+   * Fetches the signer's UTXOs, selects, then re-verifies each selected input's REAL value against the
+   * chain (`verifyInputValues` recomputes each source tx's txid, so a lying RPC can't under-report) and
+   * computes change from the VERIFIED total — closing the UTXO-VALUE-1 implicit-fee-burn. Fail-closed:
+   * if any source can't be verified it signs nothing. Prefer this over the pure `buildSend`. Pass
+   * `broadcast:false` to get the signed tx back without submitting.
+   */
+  async send(p) {
+    const from = (0, import_csd_crypto2.addrFromPriv)(p.priv);
+    const u = await this.client.utxos(from);
+    const built = await (0, import_csd_tx2.buildSendVerified)({
+      outputs: p.outputs,
+      fee: p.fee,
+      utxos: u.utxos,
+      priv: p.priv,
+      maxFee: p.maxFee,
+      verify: (inputs) => (0, import_csd_client2.verifyInputValues)(this.client, inputs)
+    });
+    if (!built.ok || p.broadcast === false) return built;
+    const submitResult = await this.client.submit(built.nodeJson);
+    return { ...built, submitResult };
+  }
   /** A verifying light client over the same RPC (built once, reused). */
   light() {
     if (!this._light) {
@@ -437,9 +501,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;
@@ -689,6 +756,26 @@ var RegistryClient = class {
 };
 
 // src/connect.ts
+function discoverProviders(opts = {}) {
+  const timeoutMs = opts.timeoutMs ?? 1e3;
+  return new Promise((resolve) => {
+    if (typeof window === "undefined") {
+      resolve([]);
+      return;
+    }
+    const found = /* @__PURE__ */ new Map();
+    const onAnnounce = (ev) => {
+      const d = ev?.detail;
+      if (d?.info?.uuid && d?.provider?.isCairn) found.set(d.info.uuid, d);
+    };
+    window.addEventListener("csd:announceProvider", onAnnounce);
+    window.dispatchEvent(new CustomEvent("csd:requestProvider"));
+    setTimeout(() => {
+      window.removeEventListener("csd:announceProvider", onAnnounce);
+      resolve([...found.values()]);
+    }, timeoutMs);
+  });
+}
 function detectProvider(opts = {}) {
   const timeoutMs = opts.timeoutMs ?? 3e3;
   return new Promise((resolve, reject) => {
@@ -696,18 +783,19 @@ function detectProvider(opts = {}) {
       reject(new NotInstalledError("Not running in a browser \u2014 `window.cairn` is unavailable."));
       return;
     }
-    if (window.cairn?.isCairn) {
-      resolve(window.cairn);
-      return;
-    }
     let done = false;
-    const onInit = () => {
+    const finish = (p) => {
       if (done) return;
-      if (window.cairn?.isCairn) {
-        done = true;
-        cleanup();
-        resolve(window.cairn);
-      }
+      done = true;
+      cleanup();
+      resolve(p);
+    };
+    const onInit = () => {
+      if (!done && window.cairn?.isCairn) finish(window.cairn);
+    };
+    const onAnnounce = (ev) => {
+      const p = ev?.detail?.provider;
+      if (p?.isCairn) finish(p);
     };
     const timer = setTimeout(() => {
       if (done) return;
@@ -718,8 +806,15 @@ function detectProvider(opts = {}) {
     const cleanup = () => {
       clearTimeout(timer);
       window.removeEventListener("cairn#initialized", onInit);
+      window.removeEventListener("csd:announceProvider", onAnnounce);
     };
     window.addEventListener("cairn#initialized", onInit);
+    window.addEventListener("csd:announceProvider", onAnnounce);
+    if (window.cairn?.isCairn) {
+      finish(window.cairn);
+      return;
+    }
+    window.dispatchEvent(new CustomEvent("csd:requestProvider"));
     onInit();
   });
 }
@@ -756,10 +851,76 @@ var WalletConnection = class {
     this._addr = addr;
     return addr;
   }
-  /** Passwordless sign-in: a signature over a login nonce (always prompts; structurally cannot sign a tx). */
+  /**
+   * @deprecated First-party-only legacy login (it authenticates against the wallet's own configured
+   * server and is rejected from third-party origins). Use {@link signInWithCsd} for any site.
+   * Passwordless sign-in: a signature over a login nonce (always prompts; structurally cannot sign a tx).
+   */
   signIn() {
     return Promise.resolve(this.provider.signIn()).then(unwrap);
   }
+  /**
+   * Audience-bound "Sign in with CSD" (SIWC) — the secure, replay-resistant third-party login.
+   * The wallet binds the REAL requesting origin + your single-use server `nonce` into the signed
+   * message and returns the artifact; it never mints a session. VERIFY the result SERVER-SIDE with
+   * `verifySiwc` from `@inversealtruism/csd-siwc` (domain/nonce/chain/time/signature/account), then
+   * issue your OWN session. The signature is proof-of-control, NOT a bearer token. Always prompts.
+   */
+  signInWithCsd(params) {
+    if (!params || typeof params.nonce !== "string" || !params.nonce) {
+      return Promise.reject(new UnsupportedMethodError("signInWithCsd requires a server-issued { nonce }"));
+    }
+    if (typeof this.provider.signInWithCsd !== "function") {
+      return Promise.reject(new UnsupportedMethodError("this wallet predates Sign-in-with-CSD \u2014 ask the user to update the Cairn Wallet"));
+    }
+    return Promise.resolve(this.provider.signInWithCsd(params)).then(unwrap);
+  }
+  /** True if this wallet supports audience-bound SIWC (safe to call `signInWithCsd`). */
+  get supportsSiwc() {
+    return typeof this.provider.signInWithCsd === "function";
+  }
+  /** Feature/capability detection. Returns null if the wallet predates `getCapabilities`. */
+  async getCapabilities() {
+    if (typeof this.provider.getCapabilities !== "function") return null;
+    try {
+      return await this.provider.getCapabilities();
+    } catch {
+      return null;
+    }
+  }
+  /** Atomic fill (CairnX DvP): pay + attest in ONE tx. Always prompts with clear-signing. */
+  fillOffer(params) {
+    return Promise.resolve(this.provider.fillOffer(params)).then(unwrap);
+  }
+  /** This origin's current permission grant (EIP-2255-style). Silent; [] if none / unsupported. */
+  async getPermissions() {
+    if (typeof this.provider.getPermissions !== "function") return [];
+    return unwrap(await this.provider.getPermissions());
+  }
+  /** Explicitly request permission to see the address (prompts, like connect). */
+  requestPermissions() {
+    if (typeof this.provider.requestPermissions !== "function") {
+      return Promise.reject(new UnsupportedMethodError("this wallet predates requestPermissions \u2014 use connect()"));
+    }
+    return Promise.resolve(this.provider.requestPermissions()).then(unwrap);
+  }
+  /** Revoke THIS origin's own access (silent). Returns { revoked }. Safe no-op on older wallets. */
+  async revokePermissions() {
+    if (typeof this.provider.revokePermissions !== "function") return { revoked: false };
+    return unwrap(await this.provider.revokePermissions());
+  }
+  /**
+   * Subscribe to provider events. `accountsChanged` fires with `[]` when this site loses access
+   * (wallet lock / account switch / revoke) — re-call connect() to (re)share; `disconnect` likewise.
+   * No-op if the wallet predates events. Use the SAME handler reference with off() to unsubscribe.
+   */
+  on(event, handler) {
+    this.provider.on?.(event, handler);
+  }
+  /** Remove a previously-added event handler (must be the same reference passed to on()). */
+  off(event, handler) {
+    this.provider.removeListener?.(event, handler);
+  }
   /** Send CSD (always prompts with clear-signing; wallet picks inputs + returns change to itself). */
   send(params) {
     return Promise.resolve(this.provider.send(params)).then(unwrap);
@@ -793,7 +954,79 @@ async function connect(opts = {}) {
   return { wallet, address };
 }
 
+// src/controller.ts
+var DISCONNECTED = Object.freeze({ status: "disconnected", account: null, error: null });
+var CairnController = class {
+  state = DISCONNECTED;
+  conn = null;
+  listeners = /* @__PURE__ */ new Set();
+  getWalletFn;
+  detectOpts;
+  constructor(opts = {}) {
+    const { getWallet: gw, ...detect } = opts;
+    this.getWalletFn = gw ?? getWallet;
+    this.detectOpts = detect;
+  }
+  /** useSyncExternalStore-compatible. Returns an unsubscribe fn. */
+  subscribe = (cb) => {
+    this.listeners.add(cb);
+    return () => {
+      this.listeners.delete(cb);
+    };
+  };
+  /** useSyncExternalStore-compatible snapshot — stable reference until the state actually changes. */
+  getSnapshot = () => this.state;
+  /** The underlying WalletConnection (for advanced use: send/propose/permissions/…). Null until connect(). */
+  get connection() {
+    return this.conn;
+  }
+  setState(patch) {
+    const next = { ...this.state, ...patch };
+    if (next.status === this.state.status && next.account === this.state.account && next.error === this.state.error) return;
+    this.state = Object.freeze(next);
+    for (const l of [...this.listeners]) l();
+  }
+  onAccounts = (accounts) => {
+    if (!Array.isArray(accounts) || accounts.length === 0) this.setState({ status: "disconnected", account: null });
+    else this.setState({ status: "connected", account: String(accounts[0]), error: null });
+  };
+  onDisconnect = () => {
+    this.setState({ status: "disconnected", account: null });
+  };
+  /** Detect + connect (prompts the user the first time per origin). Resolves the connected address. */
+  connect = async () => {
+    this.setState({ status: "connecting", error: null });
+    try {
+      if (!this.conn) {
+        this.conn = await this.getWalletFn(this.detectOpts);
+        this.conn.on("accountsChanged", this.onAccounts);
+        this.conn.on("disconnect", this.onDisconnect);
+      }
+      const addr = await this.conn.connect();
+      this.setState({ status: "connected", account: addr, error: null });
+      return addr;
+    } catch (e) {
+      this.setState({ status: "disconnected", account: null, error: e?.message ?? String(e) });
+      throw e;
+    }
+  };
+  /** Forget the connection locally AND revoke this origin's wallet-side permission (best-effort). */
+  disconnect = async () => {
+    try {
+      await this.conn?.revokePermissions();
+    } catch {
+    }
+    this.setState({ status: "disconnected", account: null, error: null });
+  };
+  /** Audience-bound sign-in (must connect() first). Returns the signed artifact to verify server-side. */
+  signInWithCsd = (params) => {
+    if (!this.conn) return Promise.reject(new Error("call connect() before signInWithCsd()"));
+    return this.conn.signInWithCsd(params);
+  };
+};
+
 // src/index.ts
+var DEFAULT_SPV_CHECKPOINT = { height: 31310, hash: "0x000000000000138bd3eee4b8d2fbacb8d5433ac3040ddbf1c45a5e3e0cc9e814" };
 var DEFAULT_CAIRN = "https://cairn-substrate.com";
 var Cairn = class {
   config;
@@ -804,6 +1037,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 +1051,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.
@@ -853,6 +1109,7 @@ var Cairn = class {
 0 && (module.exports = {
   BoardClient,
   Cairn,
+  CairnController,
   CairnError,
   Chain,
   ContentClient,
@@ -862,12 +1119,16 @@ var Cairn = class {
   IndexerClient,
   NotInstalledError,
   RegistryClient,
+  SDK_VERSION,
   UnsupportedMethodError,
   UserRejectedError,
   WalletConnection,
   WalletLockedError,
   connect,
   detectProvider,
+  discoverProviders,
+  errorCode,
   getWallet,
-  isInstalled
+  isInstalled,
+  mapProviderError
 });

package/dist/index.d.cts

@@ -9,7 +9,8 @@ import { ContentClient } from './content.cjs';
 export { ContentClientOptions, PreparedContent } from './content.cjs';
 import { RegistryClient } from './registry.cjs';
 import { WalletConnection, DetectOptions } from './connect.cjs';
-export { AttestParams, CairnProvider, ConnectResult, ProposeParams, SealClaimParams, SendParams, SignInResult, TxResult, connect, detectProvider, getWallet, isInstalled } from './connect.cjs';
+export { AttestParams, CairnProvider, ConnectResult, FillParams, ProposeParams, ProviderDetail, ProviderInfo, SealClaimParams, SendParams, SignInResult, SiwcParams, SiwcResult, TxResult, WalletCapabilities, WalletPermission, connect, detectProvider, discoverProviders, getWallet, isInstalled } from './connect.cjs';
+export { CairnController, CairnControllerOptions, CairnState } from './controller.cjs';
 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 };