@inversealtruism/cairn-sdk 0.4.6 → 0.5.0

package/dist/index.cjs

@@ -20,7 +20,6 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
-  BoardClient: () => BoardClient,
   Cairn: () => Cairn,
   CairnController: () => CairnController,
   CairnError: () => CairnError,
@@ -60,7 +59,7 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/errors.ts
-var SDK_VERSION = "0.4.6";
+var SDK_VERSION = "0.5.0";
 var DOCS_BASE = "https://cairn-substrate.com/docs/sdk";
 var CairnError = class extends Error {
   /** Stable machine code for programmatic branching. */
@@ -205,6 +204,26 @@ function errorCode(err) {
 // 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})`);
@@ -253,9 +272,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) {
@@ -304,11 +324,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);
         }
@@ -316,7 +341,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) {
@@ -403,164 +431,8 @@ var Chain = class {
   }
 };
 
-// src/board.ts
-var import_csd_codec2 = require("@inversealtruism/csd-codec");
-var import_csd_codec3 = require("@inversealtruism/csd-codec");
-var BoardClient = class {
-  http;
-  wallet;
-  constructor(http, wallet) {
-    this.http = http;
-    this.wallet = wallet;
-  }
-  requireWallet() {
-    if (!this.wallet) {
-      throw new CairnError("This action needs a connected wallet. Construct Cairn with a wallet, or call cairn.connect() first.");
-    }
-    return this.wallet;
-  }
-  // ---- reads (public) ----------------------------------------------------
-  /** Ranked board for a domain + time window. */
-  board(opts = {}) {
-    return this.http.getJson("/api/board", { domain: opts.domain ?? "all", window: opts.window ?? "all" });
-  }
-  /** Alias for `board()` — the top items. */
-  top(opts = {}) {
-    return this.board(opts);
-  }
-  /** A single item with its supports + pledges + integrity flag. */
-  item(id) {
-    return this.http.getJson(`/api/item/${encodeURIComponent(id)}`);
-  }
-  /** Known + discovered domains. */
-  domains() {
-    return this.http.getJson("/api/domains");
-  }
-  /** All quests (work-graph items). */
-  quests() {
-    return this.http.getJson("/api/quests");
-  }
-  /** A single quest with claims/submissions/payouts. */
-  quest(id) {
-    return this.http.getJson(`/api/quest/${encodeURIComponent(id)}`);
-  }
-  /** An address's on-chain-derived profile + identity + reputation. */
-  profile(addr, opts = {}) {
-    return this.http.getJson(`/api/profile/${encodeURIComponent(addr)}`, opts.live ? { live: 1 } : void 0);
-  }
-  /** Reputation leaderboard (top 50). */
-  leaderboard() {
-    return this.http.getJson("/api/leaderboard");
-  }
-  /** Network dashboard snapshot. */
-  network() {
-    return this.http.getJson("/api/network");
-  }
-  /** Network time-series for charts. */
-  networkSeries(range = "24h") {
-    return this.http.getJson("/api/network/series", { range });
-  }
-  /** Recent blocks with miner/reward. */
-  networkBlocks(limit = 15) {
-    return this.http.getJson("/api/network/blocks", { limit });
-  }
-  /** Per-miner hashrate estimate. */
-  miner(addr) {
-    return this.http.getJson(`/api/miner/${encodeURIComponent(addr)}`);
-  }
-  /** Recent activity feed. */
-  activity() {
-    return this.http.getJson("/api/activity");
-  }
-  /** The gamified cairn wall. */
-  wall() {
-    return this.http.getJson("/api/wall");
-  }
-  /** Server health + chain reachability. */
-  health() {
-    return this.http.getJson("/api/health");
-  }
-  // ---- writes (wallet-signed) -------------------------------------------
-  /**
-   * Publish a board item: compute the canonical payload hash, have the WALLET
-   * build/sign/submit the Propose (clear-signed approval), then register the
-   * off-chain content. The payload hash is byte-identical to what the cairn
-   * server verifies (csd-codec.payloadHash over { v:1, domain, title, body, links }).
-   */
-  async propose(input) {
-    const wallet = this.requireWallet();
-    const content = {
-      v: 1,
-      domain: input.domain,
-      title: input.title,
-      body: input.body ?? "",
-      links: input.links ?? []
-    };
-    const ph = (0, import_csd_codec2.payloadHash)(content);
-    const uri = `cairn:v1:${ph.slice(2, 14)}`;
-    const lifetime = input.lifetimeEpochs ?? 720;
-    const height = await this.tipHeight();
-    const expiresEpoch = Math.floor(height / import_csd_codec3.EPOCH_LEN) + lifetime;
-    const fee = input.fee ?? import_csd_codec3.MIN_FEE_PROPOSE;
-    const r = await wallet.propose({ domain: content.domain, payloadHash: ph, uri, expiresEpoch, fee });
-    const txid3 = String(r.txid ?? "");
-    if (!txid3) throw new CairnError("Propose submitted but no txid was returned by the wallet.");
-    const reg = await this.tryRegister(content, txid3);
-    return { txid: txid3, payloadHash: ph, content, registered: reg.ok, registerError: reg.error };
-  }
-  /**
-   * Register off-chain content for an already-submitted proposal txid. Idempotent.
-   * Returns { ok } — the cairn server verifies sha256(canonical) == on-chain payload_hash.
-   */
-  async registerContent(content, txid3) {
-    try {
-      const res = await this.http.postJson("/api/content", {
-        domain: content.domain,
-        title: content.title,
-        body: content.body,
-        links: content.links,
-        txid: txid3
-      });
-      return { ok: !!res.ok, error: res.ok ? void 0 : res.error };
-    } catch (e) {
-      return { ok: false, error: e instanceof Error ? e.message : String(e) };
-    }
-  }
-  /** Support/attest a proposal (wallet-signed; always clear-signed). */
-  async support(proposalId, opts = {}) {
-    const wallet = this.requireWallet();
-    return wallet.attest({
-      proposalId,
-      score: opts.score ?? 80,
-      confidence: opts.confidence ?? 70,
-      fee: opts.fee ?? import_csd_codec3.MIN_FEE_ATTEST
-    });
-  }
-  // ---- internal ----------------------------------------------------------
-  async tipHeight() {
-    const tip = await this.http.getJson("/api/rpc/tip");
-    const h = Number(tip?.height);
-    if (!Number.isFinite(h)) throw new CairnError("Could not read chain tip height for expiry computation.");
-    return h;
-  }
-  async tryRegister(content, txid3) {
-    const delays = [0, 1500, 3e3, 5e3];
-    let last = { ok: false, error: "not attempted" };
-    for (const d of delays) {
-      if (d) await sleep(d);
-      last = await this.registerContent(content, txid3);
-      if (last.ok) return last;
-      if (!/not found yet|not found/i.test(last.error ?? "")) return last;
-    }
-    return last;
-  }
-};
-function sleep(ms) {
-  return new Promise((r) => setTimeout(r, ms));
-}
-
 // src/indexer.ts
-var import_csd_codec4 = require("@inversealtruism/csd-codec");
+var import_csd_codec2 = require("@inversealtruism/csd-codec");
 var HEX64 = /^0x[0-9a-fA-F]{64}$/;
 var MAX_SSE_BUF = 1024 * 1024;
 function isValidMerkleProof(p) {
@@ -667,24 +539,34 @@ var IndexerClient = class {
     }
     let folds = false;
     try {
-      folds = (0, import_csd_codec4.verifyMerkleProof)(txid3, proof.pos, proof.merkle, proof.merkle_root);
+      folds = (0, import_csd_codec2.verifyMerkleProof)(txid3, proof.pos, proof.merkle, proof.merkle_root);
     } catch {
       return { included: false, trustLevel: "not-found", blockHeight: proof.block_height, reason: "malformed merkle proof" };
     }
     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(txid3) ? "; 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. */
@@ -824,7 +706,7 @@ function norm(h) {
 }
 
 // src/content.ts
-var import_csd_codec5 = require("@inversealtruism/csd-codec");
+var import_csd_codec3 = require("@inversealtruism/csd-codec");
 var ContentClient = class {
   sources;
   constructor(opts) {
@@ -838,29 +720,32 @@ var ContentClient = class {
    * This is byte-identical to what the cairn server and wallet compute.
    */
   prepare(obj) {
-    const canonical = (0, import_csd_codec5.canonicalJson)(obj);
+    const canonical = (0, import_csd_codec3.canonicalJson)(obj);
     return {
-      payloadHash: (0, import_csd_codec5.payloadHash)(obj),
+      payloadHash: (0, import_csd_codec3.payloadHash)(obj),
       canonical,
       bytes: new TextEncoder().encode(canonical)
     };
   }
-  /** Alias for `prepare()` — emphasises this does not itself publish (anchor via board.propose). */
+  /** Alias for `prepare()`. It does not publish anything; anchor the hash with a Propose. */
   put(obj) {
     return this.prepare(obj);
   }
   /** Just the payload hash for an object. */
   hash(obj) {
-    return (0, import_csd_codec5.payloadHash)(obj);
+    return (0, import_csd_codec3.payloadHash)(obj);
   }
   /**
    * Fetch content by hash and VERIFY it self-certifies (sha256(bytes) == hash).
-   * Tries each configured source in order. Returns raw bytes, or null if no
-   * source holds it. Throws ContentVerificationError if a source returns bytes
-   * that don't match the hash (tampering / wrong object).
+   * Tries each configured source in order; a source that is unreachable, lacks
+   * the content or serves bytes that don't match the hash is skipped. Returns the
+   * first verified bytes, or null if no source holds it. Throws
+   * ContentVerificationError only when no source served verified bytes and at
+   * least one served mismatching bytes (tampering / wrong object).
    */
   async getBytes(hash) {
     const h = normalizeHash(hash);
+    let mismatched = false;
     for (const src of this.sources) {
       let got = null;
       try {
@@ -869,22 +754,29 @@ var ContentClient = class {
         continue;
       }
       if (!got) continue;
-      if (!(0, import_csd_codec5.verifyContentBytes)(got.bytes, h)) {
-        throw new ContentVerificationError(h);
+      if (!(0, import_csd_codec3.verifyContentBytes)(got.bytes, h)) {
+        mismatched = true;
+        continue;
       }
       return got.bytes;
     }
+    if (mismatched) throw new ContentVerificationError(h);
     return null;
   }
-  /** Fetch + verify + parse as UTF-8 JSON. Returns null if not found. */
+  /** Fetch + verify + parse as UTF-8 JSON. Returns null if not found. Throws a CairnError with code
+   *  CONTENT_NOT_JSON when the verified bytes are not JSON. */
   async get(hash) {
     const bytes = await this.getBytes(hash);
     if (!bytes) return null;
-    return JSON.parse(new TextDecoder().decode(bytes));
+    try {
+      return JSON.parse(new TextDecoder().decode(bytes));
+    } catch (e) {
+      throw new CairnError(`Content ${normalizeHash(hash)} verified against its hash but is not JSON; use getBytes() for raw content.`, { code: "CONTENT_NOT_JSON", cause: e });
+    }
   }
   /** Verify already-fetched bytes against a hash (no network). */
   verify(bytes, hash) {
-    return (0, import_csd_codec5.verifyContentBytes)(bytes, normalizeHash(hash));
+    return (0, import_csd_codec3.verifyContentBytes)(bytes, normalizeHash(hash));
   }
 };
 function normalizeHash(hash) {
@@ -948,11 +840,46 @@ var RegistryClient = class {
 // src/names.ts
 var import_cairnx_core = require("@inversealtruism/cairnx-core");
 var nameOk = (n) => typeof n === "string" && import_cairnx_core.NAME_RE.test(n) && !import_cairnx_core.RESERVED_NAMES.has(n);
+var amountOk = (v) => typeof v === "string" && import_cairnx_core.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" || !import_cairnx_core.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" || !import_cairnx_core.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;
@@ -973,15 +900,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) {
@@ -1005,29 +938,40 @@ var NamesClient = class {
   }
   /** All registered names (display list; short-edge-cached server-side). */
   names() {
-    return this.http.getJson(`/trade/api/cairnx/names`);
-  }
-  /** All deployed tokens. */
-  tokens() {
-    return this.http.getJson(`/trade/api/cairnx/tokens`);
+    return this.list(`/trade/api/cairnx/names`);
+  }
+  /** 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" || !import_cairnx_core.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() {
@@ -1260,7 +1204,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);
   }
@@ -1291,9 +1235,10 @@ async function connect(opts = {}) {
 
 // src/fillverify.ts
 var import_csd_client3 = require("@inversealtruism/csd-client");
-var import_csd_codec6 = require("@inversealtruism/csd-codec");
+var import_csd_codec4 = require("@inversealtruism/csd-codec");
 var import_cairnx_core2 = require("@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) {
@@ -1330,7 +1275,7 @@ async function provenAuthor(client, provenTx) {
   } catch {
     return null;
   }
-  if (String((0, import_csd_codec6.txid)(src)).toLowerCase() !== String(in0.prevTxid).toLowerCase()) return null;
+  if (String((0, import_csd_codec4.txid)(src)).toLowerCase() !== String(in0.prevTxid).toLowerCase()) return null;
   const out = src.outputs?.[Number(in0.vout)];
   const spk = out?.scriptPubkey ? String(out.scriptPubkey).toLowerCase() : null;
   return spk && ADDR.test(spk) ? spk : null;
@@ -1344,13 +1289,17 @@ 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 {
     provenTx = (0, import_csd_client3.rpcTxToTx)(incl.tx);
-    provenId = (0, import_csd_codec6.txid)(provenTx);
+    provenId = (0, import_csd_codec4.txid)(provenTx);
   } catch {
     return { ok: false, trust: "unverified", reason: "the on-chain offer tx couldn't be re-derived" };
   }
@@ -1366,7 +1315,7 @@ async function preverifyOffer(opts) {
     rec = null;
   }
   if (!rec || rec.t !== "offer") return { ok: false, trust: "unverified", reason: "the offer record doesn't bind to its on-chain commitment" };
-  if (String((0, import_csd_codec6.payloadHash)(rec)).toLowerCase() !== String(incl.appPayloadHash).toLowerCase())
+  if (String((0, import_csd_codec4.payloadHash)(rec)).toLowerCase() !== String(incl.appPayloadHash).toLowerCase())
     return { ok: false, trust: "unverified", reason: "the offer record doesn't match the on-chain (merkle-proven) commitment" };
   const seller = await provenAuthor(opts.client, provenTx);
   if (!seller) return { ok: false, trust: "verified", transient: true, blockHeight, reason: "couldn't prove the offer's on-chain author yet; the chain view may be catching up, try again" };
@@ -1381,8 +1330,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 && !(0, import_cairnx_core2.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 ((0, import_cairnx_core2.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,
@@ -1390,7 +1346,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
@@ -1399,16 +1355,25 @@ async function preverifyOffer(opts) {
       const plan = (0, import_cairnx_core2.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)
@@ -1433,8 +1398,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;
@@ -1465,6 +1431,7 @@ var CairnController = class {
   }
   onAccounts = (accounts) => {
     if (!Array.isArray(accounts) || accounts.length === 0) {
+      this.epoch++;
       this.setState({ status: "disconnected", account: null });
       return;
     }
@@ -1476,6 +1443,7 @@ var CairnController = class {
     }
   };
   onDisconnect = () => {
+    this.epoch++;
     this.setState({ status: "disconnected", account: null });
   };
   // Detach the provider listeners (ghost-reconnect fix). Idempotent + best-effort.
@@ -1530,7 +1498,7 @@ var CairnController = class {
 };
 
 // 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;
@@ -1542,7 +1510,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;
@@ -1551,7 +1522,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).
@@ -1577,7 +1547,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,
@@ -1595,16 +1564,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);
@@ -1616,11 +1586,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 {
@@ -1633,6 +1600,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).
@@ -1645,7 +1622,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 {
     }
@@ -1690,6 +1667,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;
@@ -1701,8 +1679,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);
@@ -1715,7 +1694,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}`);
@@ -1738,12 +1719,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);
@@ -1753,7 +1742,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() {
@@ -1762,7 +1750,6 @@ var Cairn = class {
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  BoardClient,
   Cairn,
   CairnController,
   CairnError,