@inversealtruism/cairn-sdk 0.4.6 → 0.6.0

package/dist/index.js

@@ -1,24 +1,16 @@
-import {
-  Http,
-  RegistryClient,
-  readCapped
-} from "./chunk-2HP3ZXBO.js";
-import {
-  BoardClient
-} from "./chunk-E2MA75S3.js";
 import {
   Chain,
   LightClient
 } from "./chunk-C452UODV.js";
 import {
   ContentClient
-} from "./chunk-E4YQRWZZ.js";
+} from "./chunk-QEYBWBXC.js";
 import {
   IndexerClient
-} from "./chunk-J5J4JEJ6.js";
+} from "./chunk-K5MGEYEU.js";
 import {
   CairnController
-} from "./chunk-OB33SSGA.js";
+} from "./chunk-MLNW2RQB.js";
 import {
   WalletConnection,
   connect,
@@ -26,7 +18,14 @@ import {
   discoverProviders,
   getWallet,
   isInstalled
-} from "./chunk-FWTPXLGV.js";
+} from "./chunk-BMH2MACB.js";
+import {
+  Http,
+  RegistryClient,
+  RetryWaitBudget,
+  readCapped,
+  retryAfterMs
+} from "./chunk-67QBDZPW.js";
 import {
   CairnError,
   ContentVerificationError,
@@ -40,16 +39,51 @@ import {
   errorCode,
   mapProviderError,
   mapSubmitResultError
-} from "./chunk-ZFVE6MU7.js";
+} from "./chunk-2A4AJBO5.js";
 
 // src/names.ts
-import { NAME_RE, RESERVED_NAMES } from "@inversealtruism/cairnx-core";
+import { NAME_RE, RESERVED_NAMES, TICKER_RE, AMOUNT_RE, HASH_RE } from "@inversealtruism/cairnx-core";
 var nameOk = (n) => typeof n === "string" && NAME_RE.test(n) && !RESERVED_NAMES.has(n);
+var amountOk = (v) => typeof v === "string" && AMOUNT_RE.test(v);
+var heightOk = (v) => Number.isSafeInteger(v) && v >= 0;
+function nameHistoryProblem(h, name) {
+  if (!h || typeof h !== "object" || Array.isArray(h)) return "not an object";
+  const r = h;
+  if (r.name !== name) return `name is ${JSON.stringify(r.name)}, expected ${JSON.stringify(name)}`;
+  if (!heightOk(r.tipHeight)) return "bad tipHeight";
+  if (!r.resolve || typeof r.resolve !== "object") return "resolve is not an object";
+  if (typeof r.scopedReplaySufficient !== "boolean") return "scopedReplaySufficient is not a boolean";
+  if (!Array.isArray(r.events)) return "events is not an array";
+  for (const [i, e] of r.events.entries()) {
+    const ev = e;
+    if (!ev || typeof ev.txid !== "string" || !HASH_RE.test(ev.txid) || !heightOk(ev.height) || !heightOk(ev.pos) || typeof ev.kind !== "string")
+      return `event ${i} is malformed`;
+  }
+  return null;
+}
+function tokenProblem(t) {
+  if (!t || typeof t !== "object") return "not an object";
+  const r = t;
+  if (typeof r.ticker !== "string" || !TICKER_RE.test(r.ticker)) return "bad ticker";
+  if (!Number.isSafeInteger(r.decimals) || r.decimals < 0) return `bad decimals (${String(r.decimals)})`;
+  if (!amountOk(r.supply)) return "supply is not a base-unit integer string";
+  if (!amountOk(r.minted)) return "minted is not a base-unit integer string";
+  if (r.mintLimit !== void 0 && !amountOk(r.mintLimit)) return "mintLimit is not a base-unit integer string";
+  return null;
+}
 var NamesClient = class {
   constructor(http) {
     this.http = http;
   }
   http;
+  malformed(path, what) {
+    return new HttpError(200, this.http.url(path), `malformed response: ${what}`);
+  }
+  async list(path) {
+    const body = await this.http.getJson(path);
+    if (!Array.isArray(body)) throw this.malformed(path, "expected an array");
+    return body;
+  }
   /** Resolve a .csd name for DISPLAY (server-trusted; see the module trust note). null = unknown/invalid name. */
   async resolve(name) {
     if (!nameOk(name)) return null;
@@ -70,15 +104,21 @@ var NamesClient = class {
       throw e;
     }
   }
-  /** The event history of one name (registrations, transfers, sets, renewals). null = invalid name. */
+  /** The event history of one name (registrations, transfers, sets, renewals) with the server's current
+   *  claim. null = invalid or unregistered name. Throws a typed HttpError on a malformed body. */
   async nameHistory(name) {
     if (!nameOk(name)) return null;
+    const path = `/trade/api/cairnx/name-history/${encodeURIComponent(name)}`;
+    let h;
     try {
-      return await this.http.getJson(`/trade/api/cairnx/name-history/${encodeURIComponent(name)}`);
+      h = await this.http.getJson(path);
     } catch (e) {
       if (e?.status === 404) return null;
       throw e;
     }
+    const p = nameHistoryProblem(h, name);
+    if (p) throw this.malformed(path, p);
+    return h;
   }
   /** Reverse lookup: an address's chosen primary .csd name (null name = none set). */
   async primary(addr) {
@@ -102,29 +142,40 @@ var NamesClient = class {
   }
   /** All registered names (display list; short-edge-cached server-side). */
   names() {
-    return this.http.getJson(`/trade/api/cairnx/names`);
+    return this.list(`/trade/api/cairnx/names`);
   }
-  /** All deployed tokens. */
-  tokens() {
-    return this.http.getJson(`/trade/api/cairnx/tokens`);
+  /** All deployed tokens. Throws a typed HttpError if any row has a malformed ticker, decimals or amount. */
+  async tokens() {
+    const path = `/trade/api/cairnx/tokens`;
+    const rows = await this.list(path);
+    rows.forEach((t, i) => {
+      const p = tokenProblem(t);
+      if (p) throw this.malformed(path, `token row ${i}: ${p}`);
+    });
+    return rows;
   }
-  /** One token by ticker. null = unknown/invalid ticker. */
+  /** One token by ticker. null = unknown/invalid ticker. Throws a typed HttpError on a malformed body. */
   async token(ticker) {
-    if (typeof ticker !== "string" || !/^[A-Z][A-Z0-9]{2,11}$/.test(ticker)) return null;
+    if (typeof ticker !== "string" || !TICKER_RE.test(ticker)) return null;
+    const path = `/trade/api/cairnx/token/${ticker}`;
+    let t;
     try {
-      return await this.http.getJson(`/trade/api/cairnx/token/${ticker}`);
+      t = await this.http.getJson(path);
     } catch (e) {
       if (e?.status === 404) return null;
       throw e;
     }
+    const p = tokenProblem(t);
+    if (p) throw this.malformed(path, p);
+    return t;
   }
   /** Open offers (the market's display list). */
   offers() {
-    return this.http.getJson(`/trade/api/cairnx/offers`);
+    return this.list(`/trade/api/cairnx/offers`);
   }
   /** Open bids. */
   bids() {
-    return this.http.getJson(`/trade/api/cairnx/bids`);
+    return this.list(`/trade/api/cairnx/bids`);
   }
   /** The full canonical CairnX state (large; prefer the scoped reads above). */
   state() {
@@ -151,6 +202,7 @@ import {
   epochOf
 } from "@inversealtruism/cairnx-core";
 var ADDR = /^0x[0-9a-f]{40}$/;
+var BELOW_BASE = /^tx below the synced base \((\d+)\)/;
 var HASH = /^0x[0-9a-f]{64}$/;
 var COINBASE = "0x" + "00".repeat(32);
 function bindPlannedSums(planned, proven) {
@@ -201,8 +253,12 @@ async function preverifyOffer(opts) {
   } catch (e) {
     return { ok: false, trust: "unverified", transient: true, reason: `couldn't reach the chain to verify the offer (${e?.message ?? e})` };
   }
-  if (!incl.included || incl.trustLevel !== "verified-inclusion" || !incl.tx || !incl.appPayloadHash)
+  if (!incl.included || incl.trustLevel !== "verified-inclusion" || !incl.tx || !incl.appPayloadHash) {
+    const below = BELOW_BASE.exec(incl.reason ?? "");
+    if (below)
+      return { ok: false, trust: "unverified", blockHeight: incl.blockHeight, reason: `the offer was mined below this SDK's SPV checkpoint window (base ${below[1]}), so it cannot be merkle-proven here and retrying will not change that; pass an older anchor in config.spvCheckpoint to verify it` };
     return { ok: false, trust: "unverified", transient: true, blockHeight: incl.blockHeight, reason: incl.reason ?? `offer not merkle-proven on-chain (${incl.trustLevel})` };
+  }
   const blockHeight = Number(incl.blockHeight);
   let provenTx, provenId;
   try {
@@ -238,8 +294,15 @@ async function preverifyOffer(opts) {
     return { ok: false, trust: "verified", blockHeight, reason: "the offer was already expired when it was mined - the chain rejects it, and a fill would move CSD for nothing" };
   let outputPlan;
   let sumsMismatch;
-  if (opts.pay !== void 0 && opts.pay !== null && !isTokenWant(offerRec.want) && offerRec.min === void 0) {
-    const servedStatus = opts.servedOffer?.status;
+  let planReason;
+  let planBound = false;
+  const has = (v) => v !== void 0 && v !== null;
+  const servedStatus = opts.servedOffer?.status;
+  if (!has(opts.pay)) planReason = "no `pay` was given, so no output plan was sized";
+  else if (isTokenWant(offerRec.want)) planReason = "the offer is token-priced: the payment is a token transfer, not CSD outputs";
+  else if (offerRec.min !== void 0) planReason = "the offer is partially fillable: its running paid/delivered is not provable here (the wallet's fill-SPV sizes it)";
+  else if (typeof servedStatus !== "string") planReason = "no served offer status: liveness is not provable here, so no output plan was sized (pass the resolver's offer object)";
+  else {
     const provenState = {
       id,
       seller,
@@ -247,7 +310,7 @@ async function preverifyOffer(opts) {
       want: { ...offerRec.want, payto },
       taker: offerRec.taker,
       bid: offerRec.bid,
-      status: typeof servedStatus === "string" ? servedStatus : "open",
+      status: servedStatus,
       expiresEpoch: 0,
       height: blockHeight,
       feeBps: terms.feeBps
@@ -256,16 +319,25 @@ async function preverifyOffer(opts) {
       const plan = fillOutputPlan(provenState, opts.pay);
       if (plan.kind === "csd-outputs") {
         outputPlan = plan.outputs;
-        if (opts.plannedOutputs !== void 0 && opts.plannedOutputs !== null)
+        if (has(opts.plannedOutputs)) {
           sumsMismatch = bindPlannedSums(opts.plannedOutputs, plan.outputs);
+          planBound = true;
+        }
       } else if (plan.kind === "undeliverable") {
         sumsMismatch = `this pay would not deliver against the proven offer (${plan.reason}) - refusing (the CSD would be lost)`;
+      } else {
+        planReason = `the proven offer settles without CSD outputs (${plan.kind})`;
       }
     } catch (e) {
       sumsMismatch = `couldn't size the fill against the proven offer (${e?.message ?? e}) - refusing rather than sizing from served fields`;
     }
   }
-  const base = { payto, seller, terms, blockHeight, ...outputPlan ? { outputPlan } : {} };
+  const planFields = {
+    ...outputPlan ? { outputPlan } : {},
+    ...has(opts.plannedOutputs) ? { planBound } : {},
+    ...!outputPlan && planReason && (has(opts.pay) || has(opts.plannedOutputs)) ? { planReason } : {}
+  };
+  const base = { payto, seller, terms, blockHeight, ...planFields };
   if (opts.servedOffer !== void 0 && opts.servedOffer !== null) {
     const so = opts.servedOffer;
     if (so?.want?.payto === void 0 || so?.want?.payto === null)
@@ -286,7 +358,7 @@ async function preverifyOffer(opts) {
 }
 
 // src/index.ts
-var DEFAULT_SPV_CHECKPOINT = { height: 101998, hash: "0x0000000000085295c9e13bbf276a11affb5470059235d1ea85d6334c8b43c49c" };
+var DEFAULT_SPV_CHECKPOINT = { height: 115403, hash: "0x00000000000052e29166597d598827b137af1dea7542123b848637fee0b67347" };
 var DEFAULT_CAIRN = "https://cairn-substrate.com";
 var SPV_HTTP_TIMEOUT_MS = 15e3;
 var SPV_HTTP_MAX_RETRIES = 4;
@@ -298,7 +370,10 @@ var spvIsTransient = (e) => {
   return SPV_TRANSIENT_RE.test(msg) || SPV_TRANSIENT_JSON_RE.test(msg);
 };
 var spvSleep = (ms) => new Promise((r) => setTimeout(r, ms));
-var spvRetryDelayMs = (attempt, retryAfterSecs) => Math.min(4e3, Math.max(700 * (attempt + 1), retryAfterSecs * 1e3));
+var spvBackoffMs = (attempt) => Math.min(4e3, 700 * (attempt + 1));
+var SPV_RETRY_WAIT_BUDGET_MS = 16e3;
+var SPV_RECHECK_DEPTH = 12;
+var spvTipOf = (lc) => lc.baseHeight + lc.chain.length - 1;
 var Cairn = class {
   config;
   chain;
@@ -307,7 +382,6 @@ var Cairn = class {
   registry;
   /** .csd names + CairnX market READS (server-trusted display reads; see names.ts trust note). */
   names;
-  board;
   wallet;
   cairnHttp;
   // Lazily-seeded SPV light client + its checkpoint (audit M3 — PoW-verified header source).
@@ -333,7 +407,6 @@ var Cairn = class {
     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,
@@ -351,16 +424,17 @@ var Cairn = class {
    * 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.
    * MF-03: a STRUCTURAL forward-sync break (a reorg orphaned the cached tip) reseeds ONCE via
-   * withSpvReseed. RESIDUAL: a height at or below the cached tip answers from the cached branch with
-   * NO network touch, so a tx in a reorg-orphaned block can still read "verified-inclusion" until a
-   * read PAST the tip trips the reseed; this closes the permanent post-reorg brick, not reorg-blindness.
+   * withSpvReseed. A height within SPV_RECHECK_DEPTH of the cached tip is re-checked against the served
+   * chain first (recheckCachedHeader), so a block orphaned after it was cached stops backing
+   * "verified-inclusion". Deeper heights answer from the cache with no network touch.
    */
   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)`);
     return this.withSpvReseed(async (lc) => {
-      const haveTo = lc.baseHeight + lc.chain.length - 1;
+      const haveTo = spvTipOf(lc);
       if (haveTo < height) await lc.sync(height);
+      else await this.recheckCachedHeader(lc, height, haveTo);
       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);
@@ -372,11 +446,8 @@ var Cairn = class {
   // this._spvLight first - the wallet G8 lesson, same shape as the MF-14 seed). A TRANSIENT failure
   // (rate limit / gateway / timeout / non-dense / CF 200-HTML) keeps the cache and rethrows: wiping
   // on those turns one /api/headers 429 into a reseed storm (DOS-HDR-3). A second structural
-  // failure propagates fail-closed; there is no loop.
-  // RESIDUAL (recorded, not closed): heights at or below the cached tip answer from the cached
-  // branch with NO network touch, so after a reorg "verified-inclusion" can still be over-claimed
-  // for a tx in an orphaned block until some read past the tip trips this reseed. This fix closes
-  // the permanent-brick leg only.
+  // failure propagates fail-closed; there is no loop. recheckCachedHeader feeds this path: a near-tip
+  // cached header that the served chain no longer carries is a structural failure.
   async withSpvReseed(op) {
     const lc = await this.seededSpvLight();
     try {
@@ -389,6 +460,16 @@ var Cairn = class {
       return out;
     }
   }
+  // A near-tip cached header the served chain no longer carries is a reorg: throw a structural error so
+  // withSpvReseed rebuilds. The message must not match SPV_TRANSIENT_RE, or it would be retried on the stale cache.
+  async recheckCachedHeader(lc, height, haveTo) {
+    if (height <= haveTo - SPV_RECHECK_DEPTH) return;
+    const cached = lc.chain[height - lc.baseHeight];
+    if (!cached) return;
+    const [served] = await this.fetchHeadersBatch(height, 1);
+    if (String(served?.hash ?? "").toLowerCase() !== String(cached.hash).toLowerCase())
+      throw new Error(`SPV cached block at height ${height} is no longer on the served chain (reorg); reseeding`);
+  }
   // Build + seed + tip-advance a FRESH light client into a LOCAL. Never touches this._spvLight:
   // the caller commits the result only on success (MF-14; the wallet G8 posture - never null or
   // dirty the shared field while an attempt is in flight).
@@ -401,7 +482,7 @@ var Cairn = class {
     await lc.syncFromCheckpoint(this._spvCp.height, this._spvCp.hash);
     try {
       const tipHeight = Number((await this.chain.tip()).height);
-      const have = lc.baseHeight + lc.chain.length - 1;
+      const have = spvTipOf(lc);
       if (Number.isFinite(tipHeight) && tipHeight > have) await lc.sync(tipHeight);
     } catch {
     }
@@ -446,6 +527,7 @@ var Cairn = class {
     if (!g) throw new Error("No fetch available for SPV header sync - pass `fetch` in the SDK options.");
     const doFetch = this.config.fetch ? this.config.fetch : g.bind(globalThis);
     const url = `${this._cairnBase}/api/headers/${from}/${count}`;
+    const budget = new RetryWaitBudget(SPV_RETRY_WAIT_BUDGET_MS);
     for (let attempt = 0; ; attempt++) {
       let res;
       let parsed;
@@ -457,8 +539,9 @@ var Cairn = class {
           parsed = JSON.parse(new TextDecoder().decode(await readCapped(res, SPV_MAX_BATCH_BYTES)));
         }
       } catch (e) {
-        if (attempt >= SPV_HTTP_MAX_RETRIES) throw e;
-        await spvSleep(spvRetryDelayMs(attempt, 0));
+        const waitMs = attempt < SPV_HTTP_MAX_RETRIES ? budget.take(spvBackoffMs(attempt), 0) : null;
+        if (waitMs === null) throw e;
+        await spvSleep(waitMs);
         continue;
       } finally {
         clearTimeout(timer);
@@ -471,7 +554,9 @@ var Cairn = class {
       if ((res.status === 429 || res.status === 502 || res.status === 503) && attempt < SPV_HTTP_MAX_RETRIES) {
         res.body?.cancel?.().catch(() => {
         });
-        await spvSleep(spvRetryDelayMs(attempt, Number(res.headers.get("retry-after")) || 0));
+        const waitMs = budget.take(spvBackoffMs(attempt), retryAfterMs(res));
+        if (waitMs === null) throw new Error(`/api/headers ${res.status}: Retry-After exceeds the remaining retry budget`);
+        await spvSleep(waitMs);
         continue;
       }
       throw new Error(`/api/headers ${res.status}`);
@@ -494,12 +579,20 @@ var Cairn = class {
    * EXACTLY the outputPlan, never resolver-served outputs.
    */
   async verifyOfferForFill(offerId, servedOffer, opts) {
-    const light = { verifyTxInclusion: (txidHex) => this.withSpvReseed((lc) => lc.verifyTxInclusion(txidHex)) };
+    const light = {
+      verifyTxInclusion: (txidHex) => this.withSpvReseed(async (lc) => {
+        const haveTo = spvTipOf(lc);
+        const r = await lc.verifyTxInclusion(txidHex);
+        if (r.trustLevel === "verified-inclusion" && typeof r.blockHeight === "number" && r.blockHeight <= haveTo)
+          await this.recheckCachedHeader(lc, r.blockHeight, haveTo);
+        return r;
+      })
+    };
     return preverifyOffer({ light, client: this.chain.client, offerId, servedOffer, pay: opts?.pay, plannedOutputs: opts?.plannedOutputs });
   }
   /**
-   * Detect + connect the Cairn Wallet (browser only). Wires the wallet into
-   * `cairn.board` for signed writes. Resolves to the connected address.
+   * Detect + connect the Cairn Wallet (browser only) and attach it as `cairn.wallet`.
+   * Resolves to the connected address.
    */
   async connect(opts = {}) {
     const { wallet, address } = await connect(opts);
@@ -509,7 +602,6 @@ var Cairn = class {
   /** Attach an already-connected wallet (e.g. one you constructed yourself). */
   attachWallet(wallet) {
     this.wallet = wallet;
-    this.board = new BoardClient(this.cairnHttp, wallet);
   }
   /** True if a wallet is attached. */
   get connected() {
@@ -517,7 +609,6 @@ var Cairn = class {
   }
 };
 export {
-  BoardClient,
   Cairn,
   CairnController,
   CairnError,

package/dist/indexer.cjs

@@ -137,17 +137,27 @@ var IndexerClient = class {
     if (!folds) {
       return { included: false, trustLevel: "not-found", blockHeight: proof.block_height, reason: "merkle branch does not fold to the claimed root" };
     }
+    let unverified;
     if (this.opts.headerMerkleAt) {
+      let onchain;
       try {
-        const onchain = await this.opts.headerMerkleAt(proof.block_height);
+        onchain = await this.opts.headerMerkleAt(proof.block_height);
+      } catch (e) {
+        onchain = "";
+        unverified = `header at ${proof.block_height} not verified (${e?.message ?? String(e)})`;
+      }
+      if (onchain) {
         if (norm(onchain) !== norm(proof.merkle_root)) {
           return { included: false, trustLevel: "not-found", equivocation: true, blockHeight: proof.block_height, reason: "proof root != on-chain header merkle (indexer disagrees with chain)" };
         }
         return { included: true, trustLevel: "verified-inclusion", blockHeight: proof.block_height, pos: proof.pos, merkleRoot: proof.merkle_root };
-      } catch {
       }
+      unverified ??= `header source returned no merkle root for ${proof.block_height}`;
+    } else {
+      unverified = "no header source configured (headerMerkleAt)";
     }
-    return { included: true, trustLevel: "proof-consistent", blockHeight: proof.block_height, pos: proof.pos, merkleRoot: proof.merkle_root };
+    const trivial = proof.merkle.length === 0 && norm(proof.merkle_root) === norm(txid) ? "; empty branch (root equals the txid)" : "";
+    return { included: false, trustLevel: "proof-consistent", blockHeight: proof.block_height, pos: proof.pos, merkleRoot: proof.merkle_root, reason: `indexer proof only, ${unverified}${trivial}` };
   }
   // ---- live streams ------------------------------------------------------
   /** Stream all events (blocks, proposals, attestations, reorgs) via SSE. */

package/dist/indexer.d.cts

@@ -8,6 +8,9 @@ interface MerkleProof {
 }
 type TrustLevel = "verified-inclusion" | "proof-consistent" | "not-found";
 interface InclusionResult {
+    /** True only when the proof root matched a header the `headerMerkleAt` source verified (trustLevel
+     *  "verified-inclusion"). A proof that merely folds is "proof-consistent" with `included: false` and a
+     *  `reason`: the indexer alone vouches for it, and an empty branch whose root is the txid folds trivially. */
     included: boolean;
     trustLevel: TrustLevel;
     blockHeight?: number;

package/dist/indexer.d.ts

@@ -8,6 +8,9 @@ interface MerkleProof {
 }
 type TrustLevel = "verified-inclusion" | "proof-consistent" | "not-found";
 interface InclusionResult {
+    /** True only when the proof root matched a header the `headerMerkleAt` source verified (trustLevel
+     *  "verified-inclusion"). A proof that merely folds is "proof-consistent" with `included: false` and a
+     *  `reason`: the indexer alone vouches for it, and an empty branch whose root is the txid folds trivially. */
     included: boolean;
     trustLevel: TrustLevel;
     blockHeight?: number;

package/dist/indexer.js

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

package/dist/react.cjs

@@ -26,7 +26,7 @@ __export(react_exports, {
 module.exports = __toCommonJS(react_exports);
 
 // src/errors.ts
-var SDK_VERSION = "0.4.6";
+var SDK_VERSION = "0.6.0";
 var DOCS_BASE = "https://cairn-substrate.com/docs/sdk";
 var CairnError = class extends Error {
   /** Stable machine code for programmatic branching. */
@@ -349,7 +349,7 @@ var WalletConnection = class {
   send(params) {
     return this.call(() => this.provider.send(params), "send").then(unwrapWrite);
   }
-  /** Low-level Propose (always prompts). Prefer `cairn.board.propose()` which computes the hash/uri/expiry. */
+  /** Low-level Propose (always prompts). The caller computes the payload hash, uri and expiry epoch. */
   propose(params) {
     return this.call(() => this.provider.propose(params), "propose").then(unwrapWrite);
   }
@@ -378,8 +378,9 @@ var DISCONNECTED = Object.freeze({ status: "disconnected", account: null, error:
 var CairnController = class {
   state = DISCONNECTED;
   conn = null;
-  // MF-15: connect/disconnect generation token. disconnect() bumps it; a connect() whose await straddled
-  // the bump must never commit "connected" over the torn-down session (a zombie null-connection session).
+  // Connect/disconnect generation token. disconnect(), the wallet's `disconnect` event and an empty
+  // accountsChanged (lock, account switch, revoke) bump it; a connect() whose await straddled the bump must
+  // never commit "connected" over the torn-down session.
   epoch = 0;
   listeners = /* @__PURE__ */ new Set();
   getWalletFn;
@@ -410,6 +411,7 @@ var CairnController = class {
   }
   onAccounts = (accounts) => {
     if (!Array.isArray(accounts) || accounts.length === 0) {
+      this.epoch++;
       this.setState({ status: "disconnected", account: null });
       return;
     }
@@ -421,6 +423,7 @@ var CairnController = class {
     }
   };
   onDisconnect = () => {
+    this.epoch++;
     this.setState({ status: "disconnected", account: null });
   };
   // Detach the provider listeners (ghost-reconnect fix). Idempotent + best-effort.
@@ -476,7 +479,7 @@ var CairnController = class {
 
 // src/react.ts
 function createCairnHooks(React, controllerOrOpts) {
-  const controller = controllerOrOpts instanceof CairnController ? controllerOrOpts : new CairnController(controllerOrOpts);
+  const controller = isController(controllerOrOpts) ? controllerOrOpts : new CairnController(controllerOrOpts);
   const useCairnState = () => React.useSyncExternalStore(controller.subscribe, controller.getSnapshot, controller.getSnapshot);
   const useCairnAccount = () => useCairnState().account;
   const useCairn = () => ({
@@ -487,6 +490,10 @@ function createCairnHooks(React, controllerOrOpts) {
   });
   return { controller, useCairnState, useCairnAccount, useCairn };
 }
+function isController(v) {
+  const c = v;
+  return !!c && typeof c.subscribe === "function" && typeof c.getSnapshot === "function" && typeof c.connect === "function" && typeof c.disconnect === "function" && typeof c.signInWithCsd === "function";
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   CairnController,

package/dist/react.js

@@ -1,12 +1,12 @@
 import {
   CairnController
-} from "./chunk-OB33SSGA.js";
-import "./chunk-FWTPXLGV.js";
-import "./chunk-ZFVE6MU7.js";
+} from "./chunk-MLNW2RQB.js";
+import "./chunk-BMH2MACB.js";
+import "./chunk-2A4AJBO5.js";
 
 // src/react.ts
 function createCairnHooks(React, controllerOrOpts) {
-  const controller = controllerOrOpts instanceof CairnController ? controllerOrOpts : new CairnController(controllerOrOpts);
+  const controller = isController(controllerOrOpts) ? controllerOrOpts : new CairnController(controllerOrOpts);
   const useCairnState = () => React.useSyncExternalStore(controller.subscribe, controller.getSnapshot, controller.getSnapshot);
   const useCairnAccount = () => useCairnState().account;
   const useCairn = () => ({
@@ -17,6 +17,10 @@ function createCairnHooks(React, controllerOrOpts) {
   });
   return { controller, useCairnState, useCairnAccount, useCairn };
 }
+function isController(v) {
+  const c = v;
+  return !!c && typeof c.subscribe === "function" && typeof c.getSnapshot === "function" && typeof c.connect === "function" && typeof c.disconnect === "function" && typeof c.signInWithCsd === "function";
+}
 export {
   CairnController,
   createCairnHooks

package/dist/registry.cjs

@@ -36,7 +36,7 @@ module.exports = __toCommonJS(registry_exports);
 var import_csd_registry = require("@inversealtruism/csd-registry");
 
 // src/errors.ts
-var SDK_VERSION = "0.4.6";
+var SDK_VERSION = "0.6.0";
 var DOCS_BASE = "https://cairn-substrate.com/docs/sdk";
 var CairnError = class extends Error {
   /** Stable machine code for programmatic branching. */
@@ -95,6 +95,26 @@ var HttpError = class extends CairnError {
 // src/http.ts
 var DEFAULT_MAX_BYTES = 16 * 1024 * 1024;
 var ERR_TEXT_CAP = 8 * 1024;
+var MAX_RETRY_AFTER_MS = 6e4;
+function retryAfterMs(res) {
+  const secs = Number(res.headers.get("retry-after"));
+  return Number.isFinite(secs) && secs > 0 ? Math.min(secs * 1e3, MAX_RETRY_AFTER_MS) : 0;
+}
+var RetryWaitBudget = class {
+  left;
+  constructor(totalMs) {
+    this.left = totalMs;
+  }
+  /** The ms to sleep before the next attempt (`ownMs` is the caller's backoff, clipped to what is left), or
+   *  null when the server's hint exceeds the remaining budget. */
+  take(ownMs, serverMs) {
+    if (serverMs > this.left) return null;
+    const ms = Math.min(Math.max(ownMs, serverMs), this.left);
+    this.left -= ms;
+    return ms;
+  }
+};
+var HTTP_RETRY_WAIT_BUDGET_MS = 3e4;
 async function readCapped(res, maxBytes) {
   const cl = Number(res.headers.get("content-length"));
   if (Number.isFinite(cl) && cl > maxBytes) throw new HttpError(res.status, res.url, `response too large (content-length ${cl} > ${maxBytes})`);
@@ -143,9 +163,10 @@ var Http = class {
     if (!f) throw new Error("No fetch available \u2014 pass `fetch` in the SDK options.");
     this._fetch = opts.fetch ? opts.fetch : f.bind(globalThis);
     this.timeoutMs = opts.timeoutMs ?? 15e3;
-    this.maxBytes = opts.maxBytes ?? DEFAULT_MAX_BYTES;
+    this.maxBytes = Number.isFinite(opts.maxBytes) && opts.maxBytes >= 1 ? Math.floor(opts.maxBytes) : DEFAULT_MAX_BYTES;
     this.headers = opts.headers ?? {};
-    this.retries = Math.min(10, Math.max(0, Math.floor(opts.retries ?? 0)));
+    const retries = Number(opts.retries ?? 0);
+    this.retries = Number.isNaN(retries) ? 0 : Math.min(10, Math.max(0, Math.floor(retries)));
   }
   /** Build an absolute URL from a path + optional query params. */
   url(path, query) {
@@ -194,11 +215,16 @@ var Http = class {
   }
   async getJson(path, query) {
     const url = this.url(path, query);
+    const budget = new RetryWaitBudget(HTTP_RETRY_WAIT_BUDGET_MS);
     for (let attempt = 0; ; attempt++) {
+      let serverWaitMs = 0;
+      let last;
       try {
         const { res, body } = await this.raw("GET", path, { query });
         if (!res.ok) {
-          if (!(res.status >= 500 && attempt < this.retries)) throw new HttpError(res.status, url, errText(body));
+          last = new HttpError(res.status, url, errText(body));
+          if (!(res.status >= 500 && attempt < this.retries)) throw last;
+          serverWaitMs = retryAfterMs(res);
         } else {
           return this.parseJson(res, new TextDecoder().decode(body), url);
         }
@@ -206,7 +232,10 @@ var Http = class {
         if (e instanceof HttpError && e.status < 500) throw e;
         if (attempt >= this.retries) throw e;
       }
-      await new Promise((r) => setTimeout(r, Math.floor(Math.random() * Math.min(4e3, 250 * 2 ** attempt))));
+      const jitterMs = Math.floor(Math.random() * Math.min(4e3, 250 * 2 ** attempt));
+      const waitMs = budget.take(jitterMs, serverWaitMs);
+      if (waitMs === null) throw last ?? new HttpError(0, url, "retry wait budget exhausted");
+      await new Promise((r) => setTimeout(r, waitMs));
     }
   }
   async postJson(path, body, headers) {

package/dist/registry.js

@@ -10,8 +10,8 @@ import {
   verifyGateway,
   verifyIdentitySig,
   verifyPeer
-} from "./chunk-2HP3ZXBO.js";
-import "./chunk-ZFVE6MU7.js";
+} from "./chunk-67QBDZPW.js";
+import "./chunk-2A4AJBO5.js";
 export {
   DOMAINS,
   RegistryClient,