@inversealtruism/cairn-sdk 0.1.4 → 0.2.1

package/README.md

@@ -1,6 +1,6 @@
 # @inversealtruism/cairn-sdk
 
-The **Compute Substrate dApp kit** — one cohesive toolkit for building apps on CSD. It composes everything in the Cairn ecosystem behind a single `Cairn` object:
+The **Compute Substrate dApp kit:** one cohesive toolkit for building apps on CSD. It composes everything in the Cairn ecosystem behind a single `Cairn` object:
 
 | | |
 |---|---|
@@ -8,8 +8,9 @@ The **Compute Substrate dApp kit** — one cohesive toolkit for building apps on
 | `cairn.chain` | Node RPC + transaction builders + a verifying **light client** (re-exports the `csd-*` primitives). |
 | `cairn.board` | The signal **board** + work graph. Reads are public; writes are wallet-signed. |
 | `cairn.index` | The L2 **explorer/indexer**: REST + merkle proofs + live SSE/WS feeds. |
-| `cairn.content` | **Self-certifying content** — publish via the board, fetch with client-side verification. |
+| `cairn.content` | **Self-certifying content:** publish via the board, fetch with client-side verification. |
 | `cairn.registry` | L3 **peer / gateway / identity** resolution. |
+| `cairn.names` | **.csd names + CairnX reads:** name resolution, reverse/primary lookup, tokens, offers, bids, canonical state. |
 
 ```bash
 npm i @inversealtruism/cairn-sdk
@@ -26,7 +27,7 @@ const cairn = new Cairn({ network: "mainnet" });   // defaults to cairn-substrat
 const top = await cairn.board.top({ domain: "csd:apps" });
 const tip = await cairn.chain.tip();
 
-// connect the user's wallet (browser) — prompts once, then "connected"
+// connect the user's wallet (browser): prompts once, then "connected"
 await cairn.connect();
 
 // publish a board item, signed by the user's wallet (clear-signed approval)
@@ -42,17 +43,17 @@ cairn.index.streamAll({ onProposal: (e) => console.log("new proposal", e) });
 
 ## How wallet connection works (and why it's safe)
 
-The SDK follows the exact model MetaMask uses — there is **no allowlist you maintain**:
+The SDK follows the exact model MetaMask uses, there is **no allowlist you maintain**:
 
 - **`connect()` / `getAddress()`** grant *address visibility*. The first time a site connects, the user approves once; after that the wallet answers silently (the site shows up under **Settings → Connected sites**, revocable anytime). This is the only "silent" call.
-- **Every signing / fund-moving call** — `send`, `propose`, `attest`, `signIn`, `sealClaim`, `revealClaim` — **always** opens the wallet's clear-signing approval window, **every time**, no matter what. Being "connected" never pre-approves a signature. A connected site cannot move a satoshi without an explicit, fully-disclosed approval click.
+- **Every signing / fund-moving call:** `send`, `propose`, `attest`, `signIn`, `sealClaim`, `revealClaim`, **always** opens the wallet's clear-signing approval window, **every time**, no matter what. Being "connected" never pre-approves a signature. A connected site cannot move a satoshi without an explicit, fully-disclosed approval click.
 
 ```ts
 import { connect, UserRejectedError, NotInstalledError } from "@inversealtruism/cairn-sdk";
 
 try {
   const { wallet, address } = await connect();
-  await wallet.send({ to: "0x…", amount: 100_000_000 }); // 1 CSD — still prompts
+  await wallet.send({ to: "0x…", amount: 100_000_000 }); // 1 CSD, still prompts
 } catch (e) {
   if (e instanceof NotInstalledError) { /* tell the user to install the wallet */ }
   if (e instanceof UserRejectedError) { /* they declined */ }
@@ -61,30 +62,32 @@ try {
 
 ## API by namespace
 
-**`cairn.board`** — `top()/board({domain,window})`, `item(id)`, `domains()`, `quests()/quest(id)`, `profile(addr)`, `leaderboard()`, `network()/networkSeries()/miner(addr)`, `activity()`, `wall()`; writes `propose({domain,title,body,links?,fee?})`, `support(id,{score?,confidence?,fee?})`.
+**`cairn.board`:** `top()/board({domain,window})`, `item(id)`, `domains()`, `quests()/quest(id)`, `profile(addr)`, `leaderboard()`, `network()/networkSeries()/miner(addr)`, `activity()`, `wall()`; writes `propose({domain,title,body,links?,fee?})`, `support(id,{score?,confidence?,fee?})`.
 
-**`cairn.index`** — `tipHeight()`, `block()/blockTxids()`, `tx()/txStatus()/txMerkleProof()`, `address()/addressTxs()/addressUtxo()`, `proposal()/attestations()`, `reputation()`, `registryPeers()/registryGateways()/identity()`, **`verifyInclusion(txid)`** (trust-minimized), `streamAll()/streamBlocks()/streamDomain()` (SSE), `subscribe()` (WS).
+**`cairn.index`:** `tipHeight()`, `block()/blockTxids()`, `tx()/txStatus()/txMerkleProof()`, `address()/addressTxs()/addressUtxo()`, `proposal()/attestations()`, `reputation()`, `registryPeers()/registryGateways()/identity()`, **`verifyInclusion(txid)`** (trust-minimized), `streamAll()/streamBlocks()/streamDomain()` (SSE), `subscribe()` (WS).
 
-**`cairn.content`** — `prepare(obj)`/`put(obj)` → `{ payloadHash, canonical, bytes }`; `get(hash)` / `getBytes(hash)` (fetch **and verify** `sha256(bytes) === hash`, throws `ContentVerificationError` on tamper); `hash(obj)`.
+**`cairn.names`:** `resolve(name)` (display-path name to address), `name(name)`/`nameHistory(name)`, `primary(addr)` (reverse lookup)/`namesOf(addr)`, `names()`, `tokens()/token(ticker)`, `offers()`, `bids()`, `state()` (the canonical CairnX state). Reads go through the public `/trade/api/cairnx/*` proxy; for payment-grade name resolution verify through the wallet or a replaying resolver, not a bare read (see `src/names.ts` header).
 
-**`cairn.chain`** — `tip()`, `utxos(addr)`, `submit(nodeJsonTx)`, `.client` (full `CsdClient`), `.light()` (verifying light client). The package also re-exports the primitives under the `/chain` subpath: `buildSend/buildPropose/buildAttest`, `signTx`, `keygen`, `payloadHash`, `verifyMerkleProof`, `LightClient`, etc.
+**`cairn.content`:** `prepare(obj)`/`put(obj)` → `{ payloadHash, canonical, bytes }`; `get(hash)` / `getBytes(hash)` (fetch **and verify** `sha256(bytes) === hash`, throws `ContentVerificationError` on tamper); `hash(obj)`.
 
-**`cairn.registry`** — `gateways()`, `peers()`, `resolveName(handle)`, `reverseName(addr)`, `.fromRecords` (deterministic local resolvers).
+**`cairn.chain`:** `tip()`, `utxos(addr)`, `submit(nodeJsonTx)`, `.client` (full `CsdClient`), `.light()` (verifying light client). The package also re-exports the primitives under the `/chain` subpath: `buildSend/buildPropose/buildAttest`, `signTx`, `keygen`, `payloadHash`, `verifyMerkleProof`, `LightClient`, etc.
+
+**`cairn.registry`:** `gateways()`, `peers()`, `resolveName(handle)`, `reverseName(addr)`, `.fromRecords` (deterministic local resolvers).
 
 Subpath imports are available for tree-shaking: `@inversealtruism/cairn-sdk/{connect,board,indexer,content,registry,chain}`.
 
 ## Examples
 
-- **`examples/read-only.mjs`** — runs today against live mainnet, no wallet, no build: `npm run test:live`. Demonstrates chain/board/indexer/registry reads + verified merkle inclusion + verified content fetch.
-- **`examples/hello-csd/`** — a no-framework browser dApp (connect → read board → publish → live feed). Build the bundle with `npm run build:example`, then serve the folder from **localhost** (the wallet injects there) with the Cairn Wallet installed.
+- **`examples/read-only.mjs`:** runs today against live mainnet, no wallet, no build: `npm run test:live`. Demonstrates chain/board/indexer/registry reads + verified merkle inclusion + verified content fetch.
+- **`examples/hello-csd/`:** a no-framework browser dApp (connect → read board → publish → live feed). Build the bundle with `npm run build:example`, then serve the folder from **localhost** (the wallet injects there) with the Cairn Wallet installed.
 
 ## 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 — 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()`).
+- **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, 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.
+- **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.
+- **The wallet injects on every site** (connect-anywhere shipped in 0.2.4x) behind a per-origin consent gate: a site sees nothing until the user approves the connection, and some request kinds stay first-party-only (the `FIRST_PARTY_ONLY` error code).
 
 ## Configuration
 

package/dist/board.cjs

@@ -27,7 +27,7 @@ var import_csd_codec = require("@inversealtruism/csd-codec");
 var import_csd_codec2 = require("@inversealtruism/csd-codec");
 
 // src/errors.ts
-var SDK_VERSION = "0.1.4";
+var SDK_VERSION = "0.2.1";
 var DOCS_BASE = "https://cairn-substrate.com/docs/sdk";
 var CairnError = class extends Error {
   /** Stable machine code for programmatic branching. */

package/dist/board.d.cts

@@ -1,4 +1,4 @@
-import { H as Http } from './http-CQsNL8w9.cjs';
+import { H as Http } from './http-C9C4L4hz.cjs';
 import { WalletConnection, TxResult } from './connect.cjs';
 
 type BoardWindow = "24h" | "7d" | "30d" | "all";

package/dist/board.d.ts

@@ -1,4 +1,4 @@
-import { H as Http } from './http-CQsNL8w9.js';
+import { H as Http } from './http-C9C4L4hz.js';
 import { WalletConnection, TxResult } from './connect.js';
 
 type BoardWindow = "24h" | "7d" | "30d" | "all";

package/dist/board.js

@@ -1,7 +1,7 @@
 import {
   BoardClient
-} from "./chunk-FSQZVNEM.js";
-import "./chunk-RELP23CH.js";
+} from "./chunk-7LQKND43.js";
+import "./chunk-IYQEEMV2.js";
 export {
   BoardClient
 };

package/dist/chain.d.cts

@@ -7,7 +7,7 @@ export { App, BlockHeader, Tx, TxInput, TxOutput, canonicalJson, deserialize, hb
 export { ADDR_RE, addrFromPriv, addrFromPub, hash160, isValidAddr, isValidPriv, keygen, pubFromPriv, randomNonce, signDigest, verifyDigest } from '@inversealtruism/csd-crypto';
 import { LightClient } from '@inversealtruism/csd-light';
 export { InclusionResult, LightClient, ReorgResult, TrustLevel, VerifiedHeader, expectedBits, expectedBitsFromWindow } from '@inversealtruism/csd-light';
-import { F as FetchLike } from './http-CQsNL8w9.cjs';
+import { F as FetchLike } from './http-C9C4L4hz.cjs';
 
 interface ChainOptions {
     /** Node RPC base URL — defaults to the public Cairn proxy (no local node needed). */

package/dist/chain.d.ts

@@ -7,7 +7,7 @@ export { App, BlockHeader, Tx, TxInput, TxOutput, canonicalJson, deserialize, hb
 export { ADDR_RE, addrFromPriv, addrFromPub, hash160, isValidAddr, isValidPriv, keygen, pubFromPriv, randomNonce, signDigest, verifyDigest } from '@inversealtruism/csd-crypto';
 import { LightClient } from '@inversealtruism/csd-light';
 export { InclusionResult, LightClient, ReorgResult, TrustLevel, VerifiedHeader, expectedBits, expectedBitsFromWindow } from '@inversealtruism/csd-light';
-import { F as FetchLike } from './http-CQsNL8w9.js';
+import { F as FetchLike } from './http-C9C4L4hz.js';
 
 interface ChainOptions {
     /** Node RPC base URL — defaults to the public Cairn proxy (no local node needed). */

package/dist/{chunk-K7SJOW3O.js → chunk-7IAFWBTW.js}

@@ -2,7 +2,7 @@ import {
   NotInstalledError,
   UnsupportedMethodError,
   mapProviderError
-} from "./chunk-RELP23CH.js";
+} from "./chunk-IYQEEMV2.js";
 
 // src/connect.ts
 function discoverProviders(opts = {}) {
@@ -72,7 +72,7 @@ function isInstalled() {
 }
 function unwrap(reply) {
   if (reply && reply.ok) return reply.result;
-  throw mapProviderError(reply?.error ?? "Unknown wallet error");
+  throw mapProviderError(reply?.error ?? "Unknown wallet error", reply?.code);
 }
 var WalletConnection = class {
   provider;
@@ -106,6 +106,9 @@ var WalletConnection = class {
    * Passwordless sign-in: a signature over a login nonce (always prompts; structurally cannot sign a tx).
    */
   signIn() {
+    if (typeof this.provider.signIn !== "function") {
+      return Promise.reject(new UnsupportedMethodError("this wallet does not expose signIn()"));
+    }
     return Promise.resolve(this.provider.signIn()).then(unwrap);
   }
   /**
@@ -139,6 +142,9 @@ var WalletConnection = class {
   }
   /** Atomic fill (CairnX DvP): pay + attest in ONE tx. Always prompts with clear-signing. */
   fillOffer(params) {
+    if (typeof this.provider.fillOffer !== "function") {
+      return Promise.reject(new UnsupportedMethodError("this wallet predates fillOffer() \u2014 ask the user to update the Cairn Wallet"));
+    }
     return Promise.resolve(this.provider.fillOffer(params)).then(unwrap);
   }
   /** This origin's current permission grant (EIP-2255-style). Silent; [] if none / unsupported. */

package/dist/{chunk-FSQZVNEM.js → chunk-7LQKND43.js}

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

package/dist/{chunk-RELP23CH.js → chunk-IYQEEMV2.js}

@@ -1,5 +1,5 @@
 // src/errors.ts
-var SDK_VERSION = "0.1.4";
+var SDK_VERSION = "0.2.1";
 var DOCS_BASE = "https://cairn-substrate.com/docs/sdk";
 var CairnError = class extends Error {
   /** Stable machine code for programmatic branching. */
@@ -74,7 +74,12 @@ var ContentVerificationError = class extends CairnError {
     this.expected = expected;
   }
 };
-function mapProviderError(error) {
+var NATIVE_CODES = /* @__PURE__ */ new Set(["ACCOUNT_CHANGED", "FIRST_PARTY_ONLY", "RATE_LIMITED", "APPROVAL_CLOSED", "FORBIDDEN", "INTERNAL"]);
+function mapProviderError(error, code) {
+  if (code === "USER_REJECTED" || code === "APPROVAL_CLOSED") return new UserRejectedError(error);
+  if (code === "WALLET_LOCKED") return new WalletLockedError(error);
+  if (code === "UNSUPPORTED_METHOD" || code === "UNKNOWN_KIND") return new UnsupportedMethodError(error);
+  if (code && NATIVE_CODES.has(code)) return new CairnError(error || code, { code });
   const e = String(error || "").toLowerCase();
   if (e.includes("rejected by user")) return new UserRejectedError(error);
   if (e.includes("wallet locked")) return new WalletLockedError(error);

package/dist/{chunk-OG4KA3LS.js → chunk-J5J4JEJ6.js}

@@ -221,7 +221,7 @@ var IndexerClient = class {
           handlers.onError?.(err);
         }
         if (closed) return;
-        await new Promise((r) => setTimeout(r, 2e3));
+        await new Promise((r) => setTimeout(r, 1e3 + Math.floor(Math.random() * 2e3)));
       }
     };
     void run();

package/dist/{chunk-MVX7VQT4.js → chunk-PQ4BSDPD.js}

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

package/dist/{chunk-MBSPHWZG.js → chunk-XXOQC4R2.js}

@@ -1,6 +1,6 @@
 import {
   getWallet
-} from "./chunk-K7SJOW3O.js";
+} from "./chunk-7IAFWBTW.js";
 
 // src/controller.ts
 var DISCONNECTED = Object.freeze({ status: "disconnected", account: null, error: null });

package/dist/connect.cjs

@@ -30,7 +30,7 @@ __export(connect_exports, {
 module.exports = __toCommonJS(connect_exports);
 
 // src/errors.ts
-var SDK_VERSION = "0.1.4";
+var SDK_VERSION = "0.2.1";
 var DOCS_BASE = "https://cairn-substrate.com/docs/sdk";
 var CairnError = class extends Error {
   /** Stable machine code for programmatic branching. */
@@ -87,7 +87,12 @@ var UnsupportedMethodError = class extends CairnError {
     super(message, { code: "UNSUPPORTED_METHOD", docsPath: "/errors#unsupported-method" });
   }
 };
-function mapProviderError(error) {
+var NATIVE_CODES = /* @__PURE__ */ new Set(["ACCOUNT_CHANGED", "FIRST_PARTY_ONLY", "RATE_LIMITED", "APPROVAL_CLOSED", "FORBIDDEN", "INTERNAL"]);
+function mapProviderError(error, code) {
+  if (code === "USER_REJECTED" || code === "APPROVAL_CLOSED") return new UserRejectedError(error);
+  if (code === "WALLET_LOCKED") return new WalletLockedError(error);
+  if (code === "UNSUPPORTED_METHOD" || code === "UNKNOWN_KIND") return new UnsupportedMethodError(error);
+  if (code && NATIVE_CODES.has(code)) return new CairnError(error || code, { code });
   const e = String(error || "").toLowerCase();
   if (e.includes("rejected by user")) return new UserRejectedError(error);
   if (e.includes("wallet locked")) return new WalletLockedError(error);
@@ -163,7 +168,7 @@ function isInstalled() {
 }
 function unwrap(reply) {
   if (reply && reply.ok) return reply.result;
-  throw mapProviderError(reply?.error ?? "Unknown wallet error");
+  throw mapProviderError(reply?.error ?? "Unknown wallet error", reply?.code);
 }
 var WalletConnection = class {
   provider;
@@ -197,6 +202,9 @@ var WalletConnection = class {
    * Passwordless sign-in: a signature over a login nonce (always prompts; structurally cannot sign a tx).
    */
   signIn() {
+    if (typeof this.provider.signIn !== "function") {
+      return Promise.reject(new UnsupportedMethodError("this wallet does not expose signIn()"));
+    }
     return Promise.resolve(this.provider.signIn()).then(unwrap);
   }
   /**
@@ -230,6 +238,9 @@ var WalletConnection = class {
   }
   /** Atomic fill (CairnX DvP): pay + attest in ONE tx. Always prompts with clear-signing. */
   fillOffer(params) {
+    if (typeof this.provider.fillOffer !== "function") {
+      return Promise.reject(new UnsupportedMethodError("this wallet predates fillOffer() \u2014 ask the user to update the Cairn Wallet"));
+    }
     return Promise.resolve(this.provider.fillOffer(params)).then(unwrap);
   }
   /** This origin's current permission grant (EIP-2255-style). Silent; [] if none / unsupported. */

package/dist/connect.d.cts

@@ -145,6 +145,7 @@ type ProviderReply<T> = {
 } | {
     ok: false;
     error: string;
+    code?: string;
 };
 declare global {
     interface Window {

package/dist/connect.d.ts

@@ -145,6 +145,7 @@ type ProviderReply<T> = {
 } | {
     ok: false;
     error: string;
+    code?: string;
 };
 declare global {
     interface Window {

package/dist/connect.js

@@ -5,8 +5,8 @@ import {
   discoverProviders,
   getWallet,
   isInstalled
-} from "./chunk-K7SJOW3O.js";
-import "./chunk-RELP23CH.js";
+} from "./chunk-7IAFWBTW.js";
+import "./chunk-IYQEEMV2.js";
 export {
   WalletConnection,
   connect,

package/dist/content.cjs

@@ -26,7 +26,7 @@ module.exports = __toCommonJS(content_exports);
 var import_csd_codec = require("@inversealtruism/csd-codec");
 
 // src/errors.ts
-var SDK_VERSION = "0.1.4";
+var SDK_VERSION = "0.2.1";
 var DOCS_BASE = "https://cairn-substrate.com/docs/sdk";
 var CairnError = class extends Error {
   /** Stable machine code for programmatic branching. */

package/dist/content.d.cts

@@ -1,4 +1,4 @@
-import { H as Http } from './http-CQsNL8w9.cjs';
+import { H as Http } from './http-C9C4L4hz.cjs';
 
 interface ContentClientOptions {
     /** Swarm gateway HTTP client (e.g. https://cairn-substrate.com/swarm). */

package/dist/content.d.ts

@@ -1,4 +1,4 @@
-import { H as Http } from './http-CQsNL8w9.js';
+import { H as Http } from './http-C9C4L4hz.js';
 
 interface ContentClientOptions {
     /** Swarm gateway HTTP client (e.g. https://cairn-substrate.com/swarm). */

package/dist/content.js

@@ -1,7 +1,7 @@
 import {
   ContentClient
-} from "./chunk-MVX7VQT4.js";
-import "./chunk-RELP23CH.js";
+} from "./chunk-PQ4BSDPD.js";
+import "./chunk-IYQEEMV2.js";
 export {
   ContentClient
 };

package/dist/controller.cjs

@@ -25,7 +25,7 @@ __export(controller_exports, {
 module.exports = __toCommonJS(controller_exports);
 
 // src/errors.ts
-var SDK_VERSION = "0.1.4";
+var SDK_VERSION = "0.2.1";
 var DOCS_BASE = "https://cairn-substrate.com/docs/sdk";
 var CairnError = class extends Error {
   /** Stable machine code for programmatic branching. */
@@ -82,7 +82,12 @@ var UnsupportedMethodError = class extends CairnError {
     super(message, { code: "UNSUPPORTED_METHOD", docsPath: "/errors#unsupported-method" });
   }
 };
-function mapProviderError(error) {
+var NATIVE_CODES = /* @__PURE__ */ new Set(["ACCOUNT_CHANGED", "FIRST_PARTY_ONLY", "RATE_LIMITED", "APPROVAL_CLOSED", "FORBIDDEN", "INTERNAL"]);
+function mapProviderError(error, code) {
+  if (code === "USER_REJECTED" || code === "APPROVAL_CLOSED") return new UserRejectedError(error);
+  if (code === "WALLET_LOCKED") return new WalletLockedError(error);
+  if (code === "UNSUPPORTED_METHOD" || code === "UNKNOWN_KIND") return new UnsupportedMethodError(error);
+  if (code && NATIVE_CODES.has(code)) return new CairnError(error || code, { code });
   const e = String(error || "").toLowerCase();
   if (e.includes("rejected by user")) return new UserRejectedError(error);
   if (e.includes("wallet locked")) return new WalletLockedError(error);
@@ -135,7 +140,7 @@ function detectProvider(opts = {}) {
 }
 function unwrap(reply) {
   if (reply && reply.ok) return reply.result;
-  throw mapProviderError(reply?.error ?? "Unknown wallet error");
+  throw mapProviderError(reply?.error ?? "Unknown wallet error", reply?.code);
 }
 var WalletConnection = class {
   provider;
@@ -169,6 +174,9 @@ var WalletConnection = class {
    * Passwordless sign-in: a signature over a login nonce (always prompts; structurally cannot sign a tx).
    */
   signIn() {
+    if (typeof this.provider.signIn !== "function") {
+      return Promise.reject(new UnsupportedMethodError("this wallet does not expose signIn()"));
+    }
     return Promise.resolve(this.provider.signIn()).then(unwrap);
   }
   /**
@@ -202,6 +210,9 @@ var WalletConnection = class {
   }
   /** Atomic fill (CairnX DvP): pay + attest in ONE tx. Always prompts with clear-signing. */
   fillOffer(params) {
+    if (typeof this.provider.fillOffer !== "function") {
+      return Promise.reject(new UnsupportedMethodError("this wallet predates fillOffer() \u2014 ask the user to update the Cairn Wallet"));
+    }
     return Promise.resolve(this.provider.fillOffer(params)).then(unwrap);
   }
   /** This origin's current permission grant (EIP-2255-style). Silent; [] if none / unsupported. */

package/dist/controller.js

@@ -1,8 +1,8 @@
 import {
   CairnController
-} from "./chunk-MBSPHWZG.js";
-import "./chunk-K7SJOW3O.js";
-import "./chunk-RELP23CH.js";
+} from "./chunk-XXOQC4R2.js";
+import "./chunk-7IAFWBTW.js";
+import "./chunk-IYQEEMV2.js";
 export {
   CairnController
 };

package/dist/{http-CQsNL8w9.d.cts → http-C9C4L4hz.d.cts}

@@ -12,6 +12,10 @@ interface HttpOptions {
     maxBytes?: number;
     /** Extra headers sent on every request. */
     headers?: Record<string, string>;
+    /** Opt-in retry budget for IDEMPOTENT GETs only (default 0 = today's behavior). Retries fire on
+     *  network errors/timeouts and 5xx, never on 4xx (mirrors csd-client's posture), with full-jitter
+     *  backoff. POSTs are never retried (they may not be idempotent). */
+    retries?: number;
 }
 declare class Http {
     readonly baseUrl: string;
@@ -19,10 +23,12 @@ declare class Http {
     private readonly timeoutMs;
     private readonly maxBytes;
     private readonly headers;
+    private readonly retries;
     constructor(opts: HttpOptions);
     /** Build an absolute URL from a path + optional query params. */
     url(path: string, query?: Record<string, string | number | boolean | undefined>): string;
     private raw;
+    private parseJson;
     getJson<T = unknown>(path: string, query?: Record<string, string | number | boolean | undefined>): Promise<T>;
     postJson<T = unknown>(path: string, body: unknown, headers?: Record<string, string>): Promise<T>;
     /** GET raw bytes (for content retrieval). Returns null on 404. */

package/dist/{http-CQsNL8w9.d.ts → http-C9C4L4hz.d.ts}

@@ -12,6 +12,10 @@ interface HttpOptions {
     maxBytes?: number;
     /** Extra headers sent on every request. */
     headers?: Record<string, string>;
+    /** Opt-in retry budget for IDEMPOTENT GETs only (default 0 = today's behavior). Retries fire on
+     *  network errors/timeouts and 5xx, never on 4xx (mirrors csd-client's posture), with full-jitter
+     *  backoff. POSTs are never retried (they may not be idempotent). */
+    retries?: number;
 }
 declare class Http {
     readonly baseUrl: string;
@@ -19,10 +23,12 @@ declare class Http {
     private readonly timeoutMs;
     private readonly maxBytes;
     private readonly headers;
+    private readonly retries;
     constructor(opts: HttpOptions);
     /** Build an absolute URL from a path + optional query params. */
     url(path: string, query?: Record<string, string | number | boolean | undefined>): string;
     private raw;
+    private parseJson;
     getJson<T = unknown>(path: string, query?: Record<string, string | number | boolean | undefined>): Promise<T>;
     postJson<T = unknown>(path: string, body: unknown, headers?: Record<string, string>): Promise<T>;
     /** GET raw bytes (for content retrieval). Returns null on 404. */