@inversealtruism/cairn-sdk 0.1.1 → 0.1.3

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.

package/dist/board.cjs

@@ -27,10 +27,41 @@ var import_csd_codec = require("@inversealtruism/csd-codec");
 var import_csd_codec2 = require("@inversealtruism/csd-codec");
 
 // 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;
   }
 };
 

package/dist/board.js

@@ -1,7 +1,7 @@
 import {
   BoardClient
-} from "./chunk-OGP2W7DL.js";
-import "./chunk-PHMU3CG5.js";
+} from "./chunk-645CYBVN.js";
+import "./chunk-UMGWVOOT.js";
 export {
   BoardClient
 };

package/dist/chain.cjs

@@ -29,6 +29,7 @@ __export(chain_exports, {
   buildAttest: () => import_csd_tx.buildAttest,
   buildPropose: () => import_csd_tx.buildPropose,
   buildSend: () => import_csd_tx.buildSend,
+  buildSendVerified: () => import_csd_tx.buildSendVerified,
   canonicalJson: () => import_csd_codec.canonicalJson,
   deserialize: () => import_csd_codec.deserialize,
   expectedBits: () => import_csd_light.expectedBits,
@@ -60,6 +61,7 @@ __export(chain_exports, {
   txid: () => import_csd_codec.txid,
   verifyContentBytes: () => import_csd_codec.verifyContentBytes,
   verifyDigest: () => import_csd_crypto.verifyDigest,
+  verifyInputValues: () => import_csd_client.verifyInputValues,
   verifyMerkleProof: () => import_csd_codec.verifyMerkleProof
 });
 module.exports = __toCommonJS(chain_exports);
@@ -70,6 +72,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;
@@ -90,6 +94,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) {
@@ -109,6 +136,7 @@ var Chain = class {
   buildAttest,
   buildPropose,
   buildSend,
+  buildSendVerified,
   canonicalJson,
   deserialize,
   expectedBits,
@@ -140,5 +168,6 @@ var Chain = class {
   txid,
   verifyContentBytes,
   verifyDigest,
+  verifyInputValues,
   verifyMerkleProof
 });

package/dist/chain.d.cts

@@ -1,7 +1,8 @@
 import * as _inversealtruism_csd_client from '@inversealtruism/csd-client';
 import { CsdClient } from '@inversealtruism/csd-client';
-export { ClientOptions, CsdClient, RpcBlock, RpcHeaderJson, RpcSubmit, RpcTip, RpcTxJson, RpcUtxo, RpcUtxos, rpcHeaderToHeader, rpcTxToTx } from '@inversealtruism/csd-client';
-export { BuildResult, Selection, Signed, Utxo, buildAttest, buildPropose, buildSend, selectInputs, signTx, txSize, txToNodeJson } from '@inversealtruism/csd-tx';
+export { ClientOptions, CsdClient, RpcBlock, RpcHeaderJson, RpcSubmit, RpcTip, RpcTxJson, RpcUtxo, RpcUtxos, rpcHeaderToHeader, rpcTxToTx, verifyInputValues } from '@inversealtruism/csd-client';
+import { BuildResult } from '@inversealtruism/csd-tx';
+export { BuildResult, InputVerifier, Selection, Signed, Utxo, buildAttest, buildPropose, buildSend, buildSendVerified, selectInputs, signTx, txSize, txToNodeJson } from '@inversealtruism/csd-tx';
 export { App, BlockHeader, Tx, TxInput, TxOutput, canonicalJson, deserialize, hb, headerHash, hx, merkleBranch, merkleRoot, payloadHash, serialize, sha256d, sighash, strip0x, strippedTx, txid, verifyContentBytes, verifyMerkleProof } from '@inversealtruism/csd-codec';
 export { ADDR_RE, addrFromPriv, addrFromPub, hash160, isValidAddr, isValidPriv, keygen, pubFromPriv, randomNonce, signDigest, verifyDigest } from '@inversealtruism/csd-crypto';
 import { LightClient } from '@inversealtruism/csd-light';
@@ -29,6 +30,26 @@ declare class Chain {
     utxos(addr: string): Promise<_inversealtruism_csd_client.RpcUtxos>;
     /** Submit a signed transaction (node-shaped JSON from `signTx().nodeJson`). */
     submit(nodeJsonTx: unknown): Promise<_inversealtruism_csd_client.RpcSubmit>;
+    /**
+     * 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.
+     */
+    send(p: {
+        priv: string;
+        outputs: {
+            to: string;
+            value: number;
+        }[];
+        fee: number;
+        maxFee?: number;
+        broadcast?: boolean;
+    }): Promise<BuildResult & {
+        submitResult?: _inversealtruism_csd_client.RpcSubmit;
+    }>;
     /** A verifying light client over the same RPC (built once, reused). */
     light(): LightClient;
 }

package/dist/chain.d.ts

@@ -1,7 +1,8 @@
 import * as _inversealtruism_csd_client from '@inversealtruism/csd-client';
 import { CsdClient } from '@inversealtruism/csd-client';
-export { ClientOptions, CsdClient, RpcBlock, RpcHeaderJson, RpcSubmit, RpcTip, RpcTxJson, RpcUtxo, RpcUtxos, rpcHeaderToHeader, rpcTxToTx } from '@inversealtruism/csd-client';
-export { BuildResult, Selection, Signed, Utxo, buildAttest, buildPropose, buildSend, selectInputs, signTx, txSize, txToNodeJson } from '@inversealtruism/csd-tx';
+export { ClientOptions, CsdClient, RpcBlock, RpcHeaderJson, RpcSubmit, RpcTip, RpcTxJson, RpcUtxo, RpcUtxos, rpcHeaderToHeader, rpcTxToTx, verifyInputValues } from '@inversealtruism/csd-client';
+import { BuildResult } from '@inversealtruism/csd-tx';
+export { BuildResult, InputVerifier, Selection, Signed, Utxo, buildAttest, buildPropose, buildSend, buildSendVerified, selectInputs, signTx, txSize, txToNodeJson } from '@inversealtruism/csd-tx';
 export { App, BlockHeader, Tx, TxInput, TxOutput, canonicalJson, deserialize, hb, headerHash, hx, merkleBranch, merkleRoot, payloadHash, serialize, sha256d, sighash, strip0x, strippedTx, txid, verifyContentBytes, verifyMerkleProof } from '@inversealtruism/csd-codec';
 export { ADDR_RE, addrFromPriv, addrFromPub, hash160, isValidAddr, isValidPriv, keygen, pubFromPriv, randomNonce, signDigest, verifyDigest } from '@inversealtruism/csd-crypto';
 import { LightClient } from '@inversealtruism/csd-light';
@@ -29,6 +30,26 @@ declare class Chain {
     utxos(addr: string): Promise<_inversealtruism_csd_client.RpcUtxos>;
     /** Submit a signed transaction (node-shaped JSON from `signTx().nodeJson`). */
     submit(nodeJsonTx: unknown): Promise<_inversealtruism_csd_client.RpcSubmit>;
+    /**
+     * 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.
+     */
+    send(p: {
+        priv: string;
+        outputs: {
+            to: string;
+            value: number;
+        }[];
+        fee: number;
+        maxFee?: number;
+        broadcast?: boolean;
+    }): Promise<BuildResult & {
+        submitResult?: _inversealtruism_csd_client.RpcSubmit;
+    }>;
     /** A verifying light client over the same RPC (built once, reused). */
     light(): LightClient;
 }

package/dist/chain.js

@@ -8,6 +8,7 @@ import {
   buildAttest,
   buildPropose,
   buildSend,
+  buildSendVerified,
   canonicalJson,
   deserialize,
   expectedBits,
@@ -39,8 +40,9 @@ import {
   txid,
   verifyContentBytes,
   verifyDigest,
+  verifyInputValues,
   verifyMerkleProof
-} from "./chunk-6VWLWF7R.js";
+} from "./chunk-5KAUQH72.js";
 export {
   ADDR_RE,
   Chain,
@@ -51,6 +53,7 @@ export {
   buildAttest,
   buildPropose,
   buildSend,
+  buildSendVerified,
   canonicalJson,
   deserialize,
   expectedBits,
@@ -82,5 +85,6 @@ export {
   txid,
   verifyContentBytes,
   verifyDigest,
+  verifyInputValues,
   verifyMerkleProof
 };

package/dist/{chunk-6VWLWF7R.js → chunk-5KAUQH72.js}

@@ -2,7 +2,8 @@
 import {
   CsdClient,
   rpcTxToTx,
-  rpcHeaderToHeader
+  rpcHeaderToHeader,
+  verifyInputValues
 } from "@inversealtruism/csd-client";
 import {
   selectInputs,
@@ -10,6 +11,7 @@ import {
   txToNodeJson,
   signTx,
   buildSend,
+  buildSendVerified,
   buildPropose,
   buildAttest
 } from "@inversealtruism/csd-tx";
@@ -45,8 +47,10 @@ import {
   ADDR_RE
 } from "@inversealtruism/csd-crypto";
 import { LightClient, expectedBits, expectedBitsFromWindow } from "@inversealtruism/csd-light";
-import { CsdClient as CsdClient2 } from "@inversealtruism/csd-client";
+import { CsdClient as CsdClient2, verifyInputValues as verifyInputValues2 } from "@inversealtruism/csd-client";
 import { LightClient as LightClient2 } from "@inversealtruism/csd-light";
+import { buildSendVerified as buildSendVerified2 } from "@inversealtruism/csd-tx";
+import { addrFromPriv as addrFromPriv2 } from "@inversealtruism/csd-crypto";
 var Chain = class {
   client;
   opts;
@@ -67,6 +71,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 = addrFromPriv2(p.priv);
+    const u = await this.client.utxos(from);
+    const built = await buildSendVerified2({
+      outputs: p.outputs,
+      fee: p.fee,
+      utxos: u.utxos,
+      priv: p.priv,
+      maxFee: p.maxFee,
+      verify: (inputs) => verifyInputValues2(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) {
@@ -81,11 +108,13 @@ export {
   CsdClient,
   rpcTxToTx,
   rpcHeaderToHeader,
+  verifyInputValues,
   selectInputs,
   txSize,
   txToNodeJson,
   signTx,
   buildSend,
+  buildSendVerified,
   buildPropose,
   buildAttest,
   payloadHash,

package/dist/{chunk-OGP2W7DL.js → chunk-645CYBVN.js}

@@ -1,6 +1,6 @@
 import {
   CairnError
-} from "./chunk-PHMU3CG5.js";
+} from "./chunk-UMGWVOOT.js";
 
 // src/board.ts
 import { payloadHash } from "@inversealtruism/csd-codec";

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/chunk-G4OZKZSJ.js

@@ -0,0 +1,213 @@
+import {
+  NotInstalledError,
+  UnsupportedMethodError,
+  mapProviderError
+} from "./chunk-UMGWVOOT.js";
+
+// 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) => {
+    if (typeof window === "undefined") {
+      reject(new NotInstalledError("Not running in a browser \u2014 `window.cairn` is unavailable."));
+      return;
+    }
+    let done = false;
+    const finish = (p) => {
+      if (done) return;
+      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;
+      done = true;
+      cleanup();
+      reject(new NotInstalledError());
+    }, timeoutMs);
+    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();
+  });
+}
+function isInstalled() {
+  return typeof window !== "undefined" && !!window.cairn?.isCairn;
+}
+function unwrap(reply) {
+  if (reply && reply.ok) return reply.result;
+  throw mapProviderError(reply?.error ?? "Unknown wallet error");
+}
+var WalletConnection = class {
+  provider;
+  _addr = null;
+  constructor(provider) {
+    this.provider = provider;
+  }
+  /** The wallet's version string (e.g. "0.2.x"). */
+  get version() {
+    return this.provider.version;
+  }
+  /** The connected address, if `connect()`/`getAddress()` has resolved. */
+  get address() {
+    return this._addr;
+  }
+  /** Request connection. First time per origin prompts the user; afterwards may be silent. */
+  async connect() {
+    const { addr } = unwrap(await this.provider.connect());
+    this._addr = addr;
+    return addr;
+  }
+  /** Get the connected address (does not force a new connection prompt if already consented). */
+  async getAddress() {
+    const { addr } = unwrap(await this.provider.getAddress());
+    this._addr = addr;
+    return addr;
+  }
+  /**
+   * @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);
+  }
+  /** Low-level Propose (always prompts). Prefer `cairn.board.propose()` which computes the hash/uri/expiry. */
+  propose(params) {
+    return Promise.resolve(this.provider.propose(params)).then(unwrap);
+  }
+  /** Attest/support a proposal (always prompts). */
+  attest(params) {
+    return Promise.resolve(this.provider.attest(params)).then(unwrap);
+  }
+  /** Seal a commit-reveal claim (always prompts; salt stays inside the wallet). */
+  sealClaim(params) {
+    return Promise.resolve(this.provider.sealClaim(params)).then(unwrap);
+  }
+  /** Reveal a previously sealed claim by its sealing txid (always prompts). */
+  revealClaim(txid) {
+    if (typeof txid !== "string" || !txid) {
+      return Promise.reject(new UnsupportedMethodError("revealClaim requires the sealing txid"));
+    }
+    return Promise.resolve(this.provider.revealClaim(txid)).then(unwrap);
+  }
+};
+async function getWallet(opts = {}) {
+  return new WalletConnection(await detectProvider(opts));
+}
+async function connect(opts = {}) {
+  const wallet = await getWallet(opts);
+  const address = await wallet.connect();
+  return { wallet, address };
+}
+
+export {
+  discoverProviders,
+  detectProvider,
+  isInstalled,
+  WalletConnection,
+  getWallet,
+  connect
+};

package/dist/{chunk-BZVJVL4Q.js → chunk-OSXS26RA.js}

@@ -1,6 +1,6 @@
 import {
   ContentVerificationError
-} from "./chunk-PHMU3CG5.js";
+} from "./chunk-UMGWVOOT.js";
 
 // src/content.ts
 import { payloadHash, canonicalJson, verifyContentBytes } from "@inversealtruism/csd-codec";

package/dist/chunk-UMGWVOOT.js

@@ -0,0 +1,99 @@
+// src/errors.ts
+var SDK_VERSION = "0.1.2";
+var DOCS_BASE = "https://cairn-substrate.com/docs/sdk";
+var CairnError = class extends Error {
+  /** 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, { code: "NOT_INSTALLED", docsPath: "/install" });
+  }
+};
+var UserRejectedError = class extends CairnError {
+  constructor(message = "Request rejected by user.") {
+    super(message, { code: "USER_REJECTED", docsPath: "/errors#user-rejected" });
+  }
+};
+var WalletLockedError = class extends CairnError {
+  constructor(message = "Wallet is locked.") {
+    super(message, { code: "WALLET_LOCKED", docsPath: "/errors#wallet-locked" });
+  }
+};
+var UnsupportedMethodError = class extends CairnError {
+  constructor(message = "Method not supported by the wallet.") {
+    super(message, { code: "UNSUPPORTED_METHOD", docsPath: "/errors#unsupported-method" });
+  }
+};
+var HttpError = class extends CairnError {
+  status;
+  url;
+  body;
+  constructor(status, url, body) {
+    super(`HTTP ${status} for ${url}${body ? `: ${String(body).slice(0, 200)}` : ""}`, { code: "HTTP_ERROR" });
+    this.status = status;
+    this.url = url;
+    this.body = body;
+  }
+};
+var ContentVerificationError = class extends CairnError {
+  expected;
+  constructor(expected) {
+    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;
+  }
+};
+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") || 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";
+}
+
+export {
+  SDK_VERSION,
+  CairnError,
+  NotInstalledError,
+  UserRejectedError,
+  WalletLockedError,
+  UnsupportedMethodError,
+  HttpError,
+  ContentVerificationError,
+  mapProviderError,
+  errorCode
+};