@inversealtruism/cairn-sdk 0.3.0 → 0.4.0

package/dist/index.d.ts

@@ -10,6 +10,8 @@ export { ContentClientOptions, PreparedContent } from './content.js';
 import { RegistryClient } from './registry.js';
 import { WalletConnection, DetectOptions } from './connect.js';
 export { AttestParams, CairnProvider, ConnectResult, FillParams, ProposeParams, ProviderDetail, ProviderInfo, SealClaimParams, SendParams, SignInResult, SiwcParams, SiwcResult, TxResult, WalletCapabilities, WalletPermission, connect, detectProvider, discoverProviders, getWallet, isInstalled } from './connect.js';
+import { ProvenOfferTerms } from '@inversealtruism/cairnx-core';
+export { FillEndorsement, FillOutputPlan, FillPreview, FillSafety, ProvenOfferTerms, bindOfferTerms, feeBpsAt, fillEndorsement, fillIsSafe, fillOutputPlan, previewFill, requiredFillOutputs } from '@inversealtruism/cairnx-core';
 import { InclusionResult } from '@inversealtruism/csd-light';
 export { CairnController, CairnControllerOptions, CairnState } from './controller.js';
 import '@inversealtruism/csd-client';
@@ -104,15 +106,6 @@ declare class NamesClient {
     state(): Promise<unknown>;
 }
 
-/** The fee/rebate-relevant fields of an offer, derived from the MERKLE-PROVEN offer (never a served object). */
-interface ProvenOfferTerms {
-    height: number;
-    feeBps: number;
-    value?: string;
-    taker?: string;
-    bid?: string;
-    min?: string;
-}
 /** The trust-labeled verdict. `ok:false` + `transient:true` = a retryable chain-catching-up soft-fail (NOT a
  *  proven mismatch). `payto`/`seller`/`terms` are populated whenever they could be merkle-derived. */
 interface OfferFillCheck {
@@ -126,12 +119,17 @@ interface OfferFillCheck {
     seller?: string;
     terms?: ProvenOfferTerms;
     blockHeight?: number;
+    /** B7b (REBIND W3/M1): the PROVEN CSD outputs to build for `pay` (a WHOLE fill of a non-partial offer),
+     *  sized from the merkle-proven offer by the single-sourced `fillOutputPlan`. Present only when `pay` was
+     *  passed and the offer could be sized. Build EXACTLY these; never the resolver-served outputs a lying
+     *  resolver could redirect. A partial (min-bearing) offer is left unsized (its running paid/delivered is
+     *  not provable at this corroboration layer; the wallet's fill-SPV is the payment-grade sizer). */
+    outputPlan?: {
+        to: string;
+        value: bigint;
+    }[];
 }
-/** The treasury fee rate stamped on an offer at its creation height (resolve.ts: v11 ? (v16 ? 150 : 100) : 0). */
-declare const feeBpsAt: (height: number) => number;
-/** true iff any fee/rebate/partial-sizing field of the SERVED offer diverges from the merkle-proven terms `t`
- *  (fail-closed: any divergence => the caller refuses). Byte-identical to cairnx-core `bindOfferTerms`. */
-declare function bindOfferTerms(servedOffer: unknown, t: ProvenOfferTerms): boolean;
+
 /**
  * Pre-verify an offer on-chain before building a `fillOffer` payment. `light` is a PoW-verifying light client
  * (its `verifyTxInclusion` surfaces the merkle-proven tx + committed appPayloadHash); `client` reads source txs
@@ -147,11 +145,20 @@ declare function preverifyOffer(opts: {
     };
     offerId: string;
     servedOffer?: unknown;
+    /** B7b (REBIND W3/M1): the CSD base units you intend to pay. When given, the result carries `outputPlan`
+     *  (the PROVEN CSD outputs to build for a WHOLE fill of a non-partial offer, sized by the single-sourced
+     *  `fillOutputPlan`) and, if you also pass `plannedOutputs`, binds them EXACTLY to that proven plan.
+     *  A partial (min-bearing) offer is left unsized here; the wallet's fill-SPV is its payment-grade sizer. */
+    pay?: bigint | string | number;
+    /** B7b: your planned per-address CSD sums (the outputs you WILL build), bound both ways to `outputPlan`.
+     *  Requires `pay`. A missing/low leg is a doomed underpay; an extra/high leg is a W3 overpay or an N26
+     *  smuggled output - both refused. */
+    plannedOutputs?: Record<string, bigint | string | number>;
 }): Promise<OfferFillCheck>;
 
 /** Stable machine-readable error codes (branch on these, not the message text). */
 type CairnErrorCode = "NOT_INSTALLED" | "USER_REJECTED" | "WALLET_LOCKED" | "UNSUPPORTED_METHOD" | "HTTP_ERROR" | "CONTENT_VERIFICATION" | "ACCOUNT_CHANGED" | "FIRST_PARTY_ONLY" | "RATE_LIMITED" | "APPROVAL_CLOSED" | "FORBIDDEN" | "INTERNAL" | "GHOST_INPUTS_SKIPPED" | "VERIFY_UNAVAILABLE" | "VERIFY_TAMPER" | "INSUFFICIENT" | "TOO_MANY_INPUTS" | "FEE_TOO_LOW" | "FEE_CAP" | "BAD_FEE" | "ZERO_ADDR_REFUSED" | "BAD_OUTPUTS" | "NO_OUTPUTS" | "BAD_REQUEST" | "OFFER_UNKNOWN" | "FILL_UNSAFE" | "FILL_WRONG_TARGET" | "SOURCE_DIVERGENCE" | "SUBMIT_REJECTED" | "SUBMIT_MAYBE_INFLIGHT" | "SUBMIT_DUPLICATE" | "NOTHING_TO_CONSOLIDATE" | "UNKNOWN";
-declare const SDK_VERSION = "0.3.0";
+declare const SDK_VERSION = "0.4.0";
 interface CairnErrorOptions {
     code?: CairnErrorCode;
     docsPath?: string;
@@ -171,7 +178,7 @@ declare class CairnError extends Error {
     /** Relative docs path (under the SDK docs base), if any. */
     readonly docsPath?: string;
     /** The cairn-sdk version that produced this error. */
-    readonly version = "0.3.0";
+    readonly version = "0.4.0";
     /**
      * Whether a dApp may safely AUTO-retry this failure. `false` for fund-safety refusals and user-intent
      * declines (the default); `true` only for provably transient infra faults where nothing was signed.
@@ -312,6 +319,7 @@ declare class Cairn {
     private _spvLight;
     private _spvSeeded;
     private readonly _spvCp;
+    private readonly _cairnBase;
     constructor(config?: CairnConfig);
     /**
      * PoW-VERIFIED header merkle at a height (audit M3 — the no-PoW half). Lazily seeds a light
@@ -325,6 +333,21 @@ declare class Cairn {
     /** The PoW-verifying SPV light client, seeded ONCE from the pinned checkpoint (shared by the M3 header-merkle
      *  bind and the F13 offer pre-verify). Reused across calls; the first call near tip syncs the post-checkpoint span. */
     private seededSpvLight;
+    /**
+     * W12 batch header transport for the checkpoint..tip forward sync, backed by the cairn server's
+     * `/api/headers/:from/:count`. Carries ZERO trust: the LightClient re-verifies every header's PoW /
+     * prev-link / LWMA, so a forged or stale row fails closed and retrying transport proves nothing new.
+     * Retry budget: a 429 (per-IP header budget) or 502/503 (a height past the lagging indexer, or the
+     * server's 10s deadline) is a transient data-availability hiccup; back off (honouring Retry-After) a
+     * bounded number of times, then THROW so `sync()` fails closed. A non-dense range is rejected.
+     *
+     * B7d / F6 DEPENDENCY: `/api/headers` serves no Access-Control-Allow-Origin today (`corsPublic` is
+     * mounted on `/explorer/api`, `/trade/api` and `/api/rpc`, not here). A SAME-ORIGIN dApp (hosted on the
+     * cairn base) reaches it now; a CROSS-ORIGIN third-party dApp cannot until B7d adds the CORS mount and
+     * restarts the cairn service. This code is correct as written; it becomes reachable cross-origin only
+     * once B7d ships. This is a recorded dependency, not a blocker for authoring/testing.
+     */
+    private fetchHeadersBatch;
     /**
      * F13 — corroborate an offer ON-CHAIN before building a `fillOffer` payment's `outputs`. Merkle-proves the
      * offer into the PoW-verified header chain (from the pinned SPV checkpoint), binds the record to its on-chain
@@ -349,4 +372,4 @@ declare class Cairn {
     get connected(): boolean;
 }
 
-export { BoardClient, Cairn, type CairnBaseUrls, type CairnConfig, CairnError, type CairnErrorCode, type CairnErrorOptions, Chain, ContentClient, ContentVerificationError, DEFAULT_SPV_CHECKPOINT, DetectOptions, FetchLike, Http, HttpError, IndexerClient, type NameDetail, type NameResolution, NamesClient, NotInstalledError, type OfferFillCheck, type PrimaryName, type ProvenOfferTerms, RegistryClient, SDK_VERSION, SubmitInFlightError, type TokenInfo, UnsupportedMethodError, UserRejectedError, WalletConnection, WalletLockedError, bindOfferTerms, errorCode, feeBpsAt, mapProviderError, mapSubmitResultError, preverifyOffer };
+export { BoardClient, Cairn, type CairnBaseUrls, type CairnConfig, CairnError, type CairnErrorCode, type CairnErrorOptions, Chain, ContentClient, ContentVerificationError, DEFAULT_SPV_CHECKPOINT, DetectOptions, FetchLike, Http, HttpError, IndexerClient, type NameDetail, type NameResolution, NamesClient, NotInstalledError, type OfferFillCheck, type PrimaryName, RegistryClient, SDK_VERSION, SubmitInFlightError, type TokenInfo, UnsupportedMethodError, UserRejectedError, WalletConnection, WalletLockedError, errorCode, mapProviderError, mapSubmitResultError, preverifyOffer };

package/dist/index.js

@@ -3,20 +3,20 @@ import {
 } from "./chunk-BGJZF7S2.js";
 import {
   BoardClient
-} from "./chunk-NLCF5T2F.js";
+} from "./chunk-2ZML7IKV.js";
 import {
   Chain,
   LightClient
 } from "./chunk-C452UODV.js";
 import {
   ContentClient
-} from "./chunk-4RDXEW35.js";
+} from "./chunk-2L5QNDAE.js";
 import {
   IndexerClient
 } from "./chunk-J5J4JEJ6.js";
 import {
   CairnController
-} from "./chunk-UMXLWUEF.js";
+} from "./chunk-GTTLMWGY.js";
 import {
   WalletConnection,
   connect,
@@ -24,7 +24,7 @@ import {
   discoverProviders,
   getWallet,
   isInstalled
-} from "./chunk-QV2GIXO7.js";
+} from "./chunk-RKR3JMIA.js";
 import {
   CairnError,
   ContentVerificationError,
@@ -38,7 +38,7 @@ import {
   errorCode,
   mapProviderError,
   mapSubmitResultError
-} from "./chunk-E2Z3XSCW.js";
+} from "./chunk-MREZG2HN.js";
 
 // src/http.ts
 var DEFAULT_MAX_BYTES = 16 * 1024 * 1024;
@@ -145,8 +145,9 @@ var Http = class {
       try {
         const res = await this.raw("GET", path, { query });
         if (!res.ok) {
-          const err = new HttpError(res.status, url, await safeText(res));
-          if (!(res.status >= 500 && attempt < this.retries)) throw err;
+          if (!(res.status >= 500 && attempt < this.retries)) throw new HttpError(res.status, url, await safeText(res));
+          res.body?.cancel().catch(() => {
+          });
         } else {
           return this.parseJson(res, new TextDecoder().decode(await readCapped(res, this.maxBytes)), url);
         }
@@ -191,7 +192,7 @@ var NamesClient = class {
   async resolve(name) {
     if (!nameOk(name)) return null;
     try {
-      return await this.http.getJson(`/trade/api/cairnx/resolve/${name}`);
+      return await this.http.getJson(`/trade/api/cairnx/resolve/${encodeURIComponent(name)}`);
     } catch (e) {
       if (e?.status === 404) return null;
       throw e;
@@ -201,7 +202,7 @@ var NamesClient = class {
   async name(name) {
     if (!nameOk(name)) return null;
     try {
-      return await this.http.getJson(`/trade/api/cairnx/name/${name}`);
+      return await this.http.getJson(`/trade/api/cairnx/name/${encodeURIComponent(name)}`);
     } catch (e) {
       if (e?.status === 404) return null;
       throw e;
@@ -211,7 +212,7 @@ var NamesClient = class {
   async nameHistory(name) {
     if (!nameOk(name)) return null;
     try {
-      return await this.http.getJson(`/trade/api/cairnx/name-history/${name}`);
+      return await this.http.getJson(`/trade/api/cairnx/name-history/${encodeURIComponent(name)}`);
     } catch (e) {
       if (e?.status === 404) return null;
       throw e;
@@ -272,23 +273,37 @@ var NamesClient = class {
 // src/fillverify.ts
 import { rpcTxToTx } from "@inversealtruism/csd-client";
 import { txid, payloadHash } from "@inversealtruism/csd-codec";
-import { parseRecord, V11_HEIGHT, V16_HEIGHT, FEE_BPS, FEE_BPS_V16 } from "@inversealtruism/cairnx-core";
+import {
+  parseRecord,
+  feeBpsAt,
+  bindOfferTerms,
+  provenOfferTerms,
+  fillOutputPlan,
+  isTokenWant,
+  fillEndorsement,
+  fillIsSafe,
+  requiredFillOutputs,
+  previewFill
+} from "@inversealtruism/cairnx-core";
 var ADDR = /^0x[0-9a-f]{40}$/;
 var HASH = /^0x[0-9a-f]{64}$/;
 var COINBASE = "0x" + "00".repeat(32);
-var feeBpsAt = (height) => height >= V11_HEIGHT ? height >= V16_HEIGHT ? FEE_BPS_V16 : FEE_BPS : 0;
-function bindOfferTerms(servedOffer, t) {
-  const o = servedOffer;
-  const s = (v) => v === void 0 || v === null ? "" : String(v).toLowerCase();
-  if (Number(o?.height) !== t.height) return true;
-  if (Number(o?.feeBps) !== t.feeBps) return true;
-  if (t.value !== void 0 && String(o?.want?.value) !== t.value) return true;
-  if (s(o?.taker) !== s(t.taker)) return true;
-  if (s(o?.bid) !== s(t.bid)) return true;
-  const om = o?.min;
-  if ((om !== void 0 && om !== null) !== (t.min !== void 0)) return true;
-  if (t.min !== void 0 && String(om) !== t.min) return true;
-  return false;
+function bindPlannedSums(planned, proven) {
+  const provenMap = new Map(proven.map((o) => [o.to.toLowerCase(), o.value]));
+  const plannedMap = /* @__PURE__ */ new Map();
+  try {
+    for (const [a, v] of Object.entries(planned)) {
+      const k = String(a).toLowerCase();
+      plannedMap.set(k, (plannedMap.get(k) ?? 0n) + BigInt(v));
+    }
+  } catch {
+    return "invalid plannedOutputs (amounts must be base-unit integers)";
+  }
+  for (const k of /* @__PURE__ */ new Set([...provenMap.keys(), ...plannedMap.keys()])) {
+    if ((provenMap.get(k) ?? 0n) !== (plannedMap.get(k) ?? 0n))
+      return `your planned payment doesn't match the proven fill outputs (${k}: planned ${(plannedMap.get(k) ?? 0n).toString()}, proven ${(provenMap.get(k) ?? 0n).toString()}) - refusing (an overpay past the proven amount is unrecoverable, and a missing or low leg is a doomed underpay)`;
+  }
+  return void 0;
 }
 async function provenAuthor(client, provenTx) {
   const in0 = provenTx.inputs?.[0];
@@ -345,17 +360,35 @@ async function preverifyOffer(opts) {
     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" };
+  const offerRec = rec;
   const w = rec.want ?? {};
   const payto = w.payto && ADDR.test(String(w.payto).toLowerCase()) ? String(w.payto).toLowerCase() : seller;
-  const terms = {
-    height: blockHeight,
-    feeBps: feeBpsAt(blockHeight),
-    value: w.value !== void 0 ? String(w.value) : void 0,
-    taker: rec.taker !== void 0 ? String(rec.taker).toLowerCase() : void 0,
-    bid: rec.bid !== void 0 ? String(rec.bid).toLowerCase() : void 0,
-    min: rec.min !== void 0 ? String(rec.min) : void 0
-  };
-  const base = { payto, seller, terms, blockHeight };
+  const terms = provenOfferTerms(offerRec, blockHeight);
+  let outputPlan;
+  let sumsMismatch;
+  if (opts.pay !== void 0 && opts.pay !== null && !isTokenWant(offerRec.want) && offerRec.min === void 0) {
+    const provenState = {
+      id,
+      seller,
+      give: offerRec.give,
+      want: offerRec.want,
+      taker: offerRec.taker,
+      bid: offerRec.bid,
+      status: "open",
+      expiresEpoch: 0,
+      height: blockHeight,
+      feeBps: terms.feeBps
+    };
+    const plan = fillOutputPlan(provenState, opts.pay);
+    if (plan.kind === "csd-outputs") {
+      outputPlan = plan.outputs;
+      if (opts.plannedOutputs !== void 0 && opts.plannedOutputs !== null)
+        sumsMismatch = bindPlannedSums(opts.plannedOutputs, plan.outputs);
+    } else if (plan.kind === "undeliverable") {
+      sumsMismatch = `this pay would not deliver against the proven offer (${plan.reason}) - refusing (the CSD would be lost)`;
+    }
+  }
+  const base = { payto, seller, terms, blockHeight, ...outputPlan ? { outputPlan } : {} };
   if (opts.servedOffer !== void 0 && opts.servedOffer !== null) {
     const so = opts.servedOffer;
     const servedPayto = so?.want?.payto !== void 0 && so?.want?.payto !== null ? String(so.want.payto).toLowerCase() : "";
@@ -363,15 +396,20 @@ async function preverifyOffer(opts) {
       return { ok: false, trust: "verified", reason: "the served payment recipient doesn't match the offer's on-chain author/record", ...base };
     if (so?.seller !== void 0 && so?.seller !== null && String(so.seller).toLowerCase() !== seller)
       return { ok: false, trust: "verified", reason: "the served seller doesn't match the offer's on-chain author (a lying resolver may be redirecting your payment)", ...base };
-    if (bindOfferTerms(opts.servedOffer, terms))
-      return { ok: false, trust: "verified", reason: "the served fee/rebate/partial terms don't match the offer's on-chain record (a lying resolver could mis-size the fill, causing a rejected fill after your payment)", ...base };
+    if (bindOfferTerms(opts.servedOffer, terms, { give: true, wantType: true }))
+      return { ok: false, trust: "verified", reason: "the served terms don't match the offer's on-chain record (fee, rebate, partial sizing, the give, or the want type - a lying resolver could mis-size or re-route the fill, redirecting or burning your payment)", ...base };
   }
+  if (sumsMismatch) return { ok: false, trust: "verified", reason: sumsMismatch, ...base };
   return { ok: true, trust: "verified", ...base };
 }
 
 // src/index.ts
 var DEFAULT_SPV_CHECKPOINT = { height: 38142, hash: "0x00000000000140f023cc0ee1457a40833f2fcb4de44291b9d373e50f17b97232" };
 var DEFAULT_CAIRN = "https://cairn-substrate.com";
+var SPV_HTTP_TIMEOUT_MS = 15e3;
+var SPV_HTTP_MAX_RETRIES = 4;
+var spvSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+var spvRetryDelayMs = (attempt, retryAfterSecs) => Math.min(4e3, Math.max(700 * (attempt + 1), retryAfterSecs * 1e3));
 var Cairn = class {
   config;
   chain;
@@ -387,6 +425,8 @@ var Cairn = class {
   _spvLight = null;
   _spvSeeded = false;
   _spvCp;
+  // W12: the cairn base the SPV header-batch provider fetches /api/headers from (same base the rest of the SDK uses).
+  _cairnBase;
   constructor(config = {}) {
     this.config = config;
     const fetch = config.fetch;
@@ -395,6 +435,7 @@ var Cairn = class {
     const rpc = config.baseUrls?.rpc ?? `${cairn}/api/rpc`;
     const indexer = (config.baseUrls?.indexer ?? `${cairn}/explorer/api`).replace(/\/+$/, "");
     this.cairnHttp = new Http({ baseUrl: cairn, fetch, timeoutMs });
+    this._cairnBase = cairn;
     const indexerHttp = new Http({ baseUrl: indexer, fetch, timeoutMs });
     const swarmHttp = config.baseUrls?.swarm ? new Http({ baseUrl: config.baseUrls.swarm.replace(/\/+$/, ""), fetch, timeoutMs }) : void 0;
     this._spvCp = config.spvCheckpoint ?? DEFAULT_SPV_CHECKPOINT;
@@ -431,13 +472,69 @@ var Cairn = class {
   /** The PoW-verifying SPV light client, seeded ONCE from the pinned checkpoint (shared by the M3 header-merkle
    *  bind and the F13 offer pre-verify). Reused across calls; the first call near tip syncs the post-checkpoint span. */
   async seededSpvLight() {
-    if (!this._spvLight) this._spvLight = new LightClient({ client: this.chain.client, checkpoints: { [this._spvCp.height]: this._spvCp.hash } });
+    if (!this._spvLight) this._spvLight = new LightClient({
+      client: this.chain.client,
+      checkpoints: { [this._spvCp.height]: this._spvCp.hash },
+      headersBatchProvider: (from, count) => this.fetchHeadersBatch(from, count)
+    });
     if (!this._spvSeeded) {
       await this._spvLight.syncFromCheckpoint(this._spvCp.height, this._spvCp.hash);
+      try {
+        const tipHeight = Number((await this.chain.tip()).height);
+        const have = this._spvLight.baseHeight + this._spvLight.chain.length - 1;
+        if (Number.isFinite(tipHeight) && tipHeight > have) await this._spvLight.sync(tipHeight);
+      } catch {
+      }
       this._spvSeeded = true;
     }
     return this._spvLight;
   }
+  /**
+   * W12 batch header transport for the checkpoint..tip forward sync, backed by the cairn server's
+   * `/api/headers/:from/:count`. Carries ZERO trust: the LightClient re-verifies every header's PoW /
+   * prev-link / LWMA, so a forged or stale row fails closed and retrying transport proves nothing new.
+   * Retry budget: a 429 (per-IP header budget) or 502/503 (a height past the lagging indexer, or the
+   * server's 10s deadline) is a transient data-availability hiccup; back off (honouring Retry-After) a
+   * bounded number of times, then THROW so `sync()` fails closed. A non-dense range is rejected.
+   *
+   * B7d / F6 DEPENDENCY: `/api/headers` serves no Access-Control-Allow-Origin today (`corsPublic` is
+   * mounted on `/explorer/api`, `/trade/api` and `/api/rpc`, not here). A SAME-ORIGIN dApp (hosted on the
+   * cairn base) reaches it now; a CROSS-ORIGIN third-party dApp cannot until B7d adds the CORS mount and
+   * restarts the cairn service. This code is correct as written; it becomes reachable cross-origin only
+   * once B7d ships. This is a recorded dependency, not a blocker for authoring/testing.
+   */
+  async fetchHeadersBatch(from, count) {
+    const g = this.config.fetch ?? globalThis.fetch;
+    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}`;
+    for (let attempt = 0; ; attempt++) {
+      let res;
+      const ctrl = new AbortController();
+      const timer = setTimeout(() => ctrl.abort(), SPV_HTTP_TIMEOUT_MS);
+      try {
+        res = await doFetch(url, { signal: ctrl.signal });
+      } catch (e) {
+        if (attempt >= SPV_HTTP_MAX_RETRIES) throw e;
+        await spvSleep(spvRetryDelayMs(attempt, 0));
+        continue;
+      } finally {
+        clearTimeout(timer);
+      }
+      if (res.ok) {
+        const rows = (await res.json())?.headers;
+        if (!Array.isArray(rows) || rows.length !== count) throw new Error(`/api/headers: non-dense range (${from}/${count})`);
+        return rows.map((r) => ({ header: r.header, hash: r.hash }));
+      }
+      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));
+        continue;
+      }
+      throw new Error(`/api/headers ${res.status}`);
+    }
+  }
   /**
    * F13 — corroborate an offer ON-CHAIN before building a `fillOffer` payment's `outputs`. Merkle-proves the
    * offer into the PoW-verified header chain (from the pinned SPV checkpoint), binds the record to its on-chain
@@ -500,9 +597,14 @@ export {
   discoverProviders,
   errorCode,
   feeBpsAt,
+  fillEndorsement,
+  fillIsSafe,
+  fillOutputPlan,
   getWallet,
   isInstalled,
   mapProviderError,
   mapSubmitResultError,
-  preverifyOffer
+  preverifyOffer,
+  previewFill,
+  requiredFillOutputs
 };

package/dist/react.cjs

@@ -26,7 +26,7 @@ __export(react_exports, {
 module.exports = __toCommonJS(react_exports);
 
 // src/errors.ts
-var SDK_VERSION = "0.3.0";
+var SDK_VERSION = "0.4.0";
 var DOCS_BASE = "https://cairn-substrate.com/docs/sdk";
 var CairnError = class extends Error {
   /** Stable machine code for programmatic branching. */
@@ -100,7 +100,7 @@ var SubmitInFlightError = class extends CairnError {
     this.txid = txid;
   }
 };
-var NATIVE_CODES = /* @__PURE__ */ new Set(["ACCOUNT_CHANGED", "FIRST_PARTY_ONLY", "RATE_LIMITED", "APPROVAL_CLOSED", "FORBIDDEN", "INTERNAL"]);
+var NATIVE_CODES = /* @__PURE__ */ new Set(["FIRST_PARTY_ONLY", "RATE_LIMITED", "FORBIDDEN", "INTERNAL"]);
 var NESTED_TRANSIENT = /* @__PURE__ */ new Set(["VERIFY_UNAVAILABLE", "OFFER_UNKNOWN"]);
 var NESTED_TERMINAL = /* @__PURE__ */ new Set([
   "FILL_UNSAFE",
@@ -144,6 +144,7 @@ function mapSubmitResultError(result) {
 }
 
 // src/connect.ts
+var DEFAULT_PROVIDER_TIMEOUT_MS = 10 * 6e4;
 function detectProvider(opts = {}) {
   const timeoutMs = opts.timeoutMs ?? 3e3;
   return new Promise((resolve, reject) => {
@@ -200,8 +201,24 @@ function unwrapWrite(reply) {
 var WalletConnection = class {
   provider;
   _addr = null;
-  constructor(provider) {
+  /** B7c: per-call provider timeout (ms). GENEROUS by default so it never rejects an in-flight human
+   *  approval; 0 disables it. Every provider call (writes especially) races against it. */
+  _timeoutMs;
+  constructor(provider, opts = {}) {
     this.provider = provider;
+    this._timeoutMs = opts.timeoutMs ?? DEFAULT_PROVIDER_TIMEOUT_MS;
+  }
+  // B7c: race a provider call against the per-call timeout. On timeout, throw a fail-closed CairnError
+  // (retryable:false: a write may already have reached the wallet, so never invite a blind auto-retry). The
+  // genuine wallet resolves quickly once the user acts; this only fires on a truly hung/absent response.
+  call(op, label) {
+    const ms = this._timeoutMs;
+    if (!Number.isFinite(ms) || ms <= 0) return Promise.resolve(op());
+    let timer;
+    const timeout = new Promise((_, reject) => {
+      timer = setTimeout(() => reject(new CairnError(`the wallet did not respond to ${label} within ${ms}ms`, { retryable: false })), ms);
+    });
+    return Promise.race([Promise.resolve(op()), timeout]).finally(() => clearTimeout(timer));
   }
   /** The wallet's version string (e.g. "0.2.x"). */
   get version() {
@@ -213,13 +230,13 @@ var WalletConnection = class {
   }
   /** Request connection. First time per origin prompts the user; afterwards may be silent. */
   async connect() {
-    const { addr } = unwrap(await this.provider.connect());
+    const { addr } = unwrap(await this.call(() => this.provider.connect(), "connect"));
     this._addr = addr;
     return addr;
   }
   /** Get the connected address (does not force a new connection prompt if already consented). */
   async getAddress() {
-    const { addr } = unwrap(await this.provider.getAddress());
+    const { addr } = unwrap(await this.call(() => this.provider.getAddress(), "getAddress"));
     this._addr = addr;
     return addr;
   }
@@ -232,7 +249,7 @@ var WalletConnection = class {
     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);
+    return this.call(() => this.provider.signIn(), "signIn").then(unwrap);
   }
   /**
    * Audience-bound "Sign in with CSD" (SIWC) — the secure, replay-resistant third-party login.
@@ -248,7 +265,7 @@ var WalletConnection = class {
     if (typeof this.provider.signInWithCsd !== "function") {
       return Promise.reject(new UnsupportedMethodError("this wallet predates Sign-in-with-CSD \u2014 ask the user to update the Cairn Wallet"));
     }
-    return Promise.resolve(this.provider.signInWithCsd(params)).then(unwrap);
+    return this.call(() => this.provider.signInWithCsd(params), "signInWithCsd").then(unwrap);
   }
   /** True if this wallet supports audience-bound SIWC (safe to call `signInWithCsd`). */
   get supportsSiwc() {
@@ -258,7 +275,7 @@ var WalletConnection = class {
   async getCapabilities() {
     if (typeof this.provider.getCapabilities !== "function") return null;
     try {
-      return await this.provider.getCapabilities();
+      return await this.call(() => this.provider.getCapabilities(), "getCapabilities");
     } catch {
       return null;
     }
@@ -274,24 +291,24 @@ var WalletConnection = class {
     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(unwrapWrite);
+    return this.call(() => this.provider.fillOffer(params), "fillOffer").then(unwrapWrite);
   }
   /** This origin's current permission grant (EIP-2255-style). Silent; [] if none / unsupported. */
   async getPermissions() {
     if (typeof this.provider.getPermissions !== "function") return [];
-    return unwrap(await this.provider.getPermissions());
+    return unwrap(await this.call(() => this.provider.getPermissions(), "getPermissions"));
   }
   /** Explicitly request permission to see the address (prompts, like connect). */
   requestPermissions() {
     if (typeof this.provider.requestPermissions !== "function") {
       return Promise.reject(new UnsupportedMethodError("this wallet predates requestPermissions \u2014 use connect()"));
     }
-    return Promise.resolve(this.provider.requestPermissions()).then(unwrap);
+    return this.call(() => this.provider.requestPermissions(), "requestPermissions").then(unwrap);
   }
   /** Revoke THIS origin's own access (silent). Returns { revoked }. Safe no-op on older wallets. */
   async revokePermissions() {
     if (typeof this.provider.revokePermissions !== "function") return { revoked: false };
-    return unwrap(await this.provider.revokePermissions());
+    return unwrap(await this.call(() => this.provider.revokePermissions(), "revokePermissions"));
   }
   /**
    * Subscribe to provider events. `accountsChanged` fires with `[]` when this site loses access
@@ -307,26 +324,26 @@ var WalletConnection = class {
   }
   /** Send CSD (always prompts with clear-signing; wallet picks inputs + returns change to itself). */
   send(params) {
-    return Promise.resolve(this.provider.send(params)).then(unwrapWrite);
+    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. */
   propose(params) {
-    return Promise.resolve(this.provider.propose(params)).then(unwrapWrite);
+    return this.call(() => this.provider.propose(params), "propose").then(unwrapWrite);
   }
   /** Attest/support a proposal (always prompts). */
   attest(params) {
-    return Promise.resolve(this.provider.attest(params)).then(unwrapWrite);
+    return this.call(() => this.provider.attest(params), "attest").then(unwrapWrite);
   }
   /** Seal a commit-reveal claim (always prompts; salt stays inside the wallet). */
   sealClaim(params) {
-    return Promise.resolve(this.provider.sealClaim(params)).then(unwrapWrite);
+    return this.call(() => this.provider.sealClaim(params), "sealClaim").then(unwrapWrite);
   }
   /** Reveal a previously sealed claim by its sealing txid (always prompts). */
   revealClaim(txid) {
     if (typeof txid !== "string" || !txid) {
       return Promise.reject(new UnsupportedMethodError("revealClaim requires the sealing txid"));
     }
-    return Promise.resolve(this.provider.revealClaim(txid)).then(unwrapWrite);
+    return this.call(() => this.provider.revealClaim(txid), "revealClaim").then(unwrapWrite);
   }
 };
 async function getWallet(opts = {}) {

package/dist/react.js

@@ -1,8 +1,8 @@
 import {
   CairnController
-} from "./chunk-UMXLWUEF.js";
-import "./chunk-QV2GIXO7.js";
-import "./chunk-E2Z3XSCW.js";
+} from "./chunk-GTTLMWGY.js";
+import "./chunk-RKR3JMIA.js";
+import "./chunk-MREZG2HN.js";
 
 // src/react.ts
 function createCairnHooks(React, controllerOrOpts) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inversealtruism/cairn-sdk",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "The Compute Substrate dApp kit — one cohesive toolkit to connect the Cairn Wallet, read the chain/board, publish self-certifying content, and resolve registries. Composes the published csd-* primitives.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -58,21 +58,8 @@
     "LICENSE",
     "README.md"
   ],
-  "scripts": {
-    "build": "tsup src/index.ts src/connect.ts src/board.ts src/indexer.ts src/content.ts src/registry.ts src/chain.ts src/controller.ts src/react.ts --format esm,cjs --dts --clean",
-    "test": "tsx test/sdk.test.ts && tsx test/connect.test.ts && tsx test/errors.test.ts && tsx test/controller.test.ts && tsx test/react.test.ts && tsx test/hardening.test.ts && tsx test/spv-checkpoint.test.ts && tsx test/names-b10.test.ts && tsx test/fillverify.test.ts",
-    "test:live": "node examples/read-only.mjs",
-    "build:example": "node scripts/build-example.mjs",
-    "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
-    "test:e2e:read": "node test/e2e/e2e-read.mjs",
-    "test:e2e:wallet": "xvfb-run -a node test/e2e/e2e-wallet-connect.mjs",
-    "test:e2e:write": "node test/e2e/e2e-write.mjs",
-    "test:e2e": "node test/e2e/e2e-read.mjs && xvfb-run -a node test/e2e/e2e-wallet-connect.mjs",
-    "test:all": "pnpm test && pnpm test:e2e",
-    "prepublishOnly": "npm run build && npm test"
-  },
   "dependencies": {
-    "@inversealtruism/cairnx-core": "0.1.38",
+    "@inversealtruism/cairnx-core": "0.1.40",
     "@inversealtruism/csd-client": "0.1.15",
     "@inversealtruism/csd-codec": "0.1.15",
     "@inversealtruism/csd-crypto": "0.1.15",
@@ -81,20 +68,14 @@
     "@inversealtruism/csd-tx": "0.1.17"
   },
   "devDependencies": {
+    "@inversealtruism/csd-siwc": "0.1.15",
     "esbuild": "^0.27.0",
     "playwright-core": "^1.49.0",
     "tsup": "^8.5.1",
     "tsx": "^4.19.2",
-    "typescript": "^5.6.0",
-    "@inversealtruism/csd-siwc": "0.1.15"
+    "typescript": "^5.6.0"
   },
   "sideEffects": false,
-  "packageManager": "pnpm@10.32.1",
-  "pnpm": {
-    "onlyBuiltDependencies": [
-      "esbuild"
-    ]
-  },
   "license": "MIT",
   "publishConfig": {
     "access": "public"
@@ -112,5 +93,17 @@
     "dapp",
     "sdk",
     "blockchain"
-  ]
-}
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts src/connect.ts src/board.ts src/indexer.ts src/content.ts src/registry.ts src/chain.ts src/controller.ts src/react.ts --format esm,cjs --dts --clean",
+    "test": "node test/run.mjs",
+    "test:live": "node examples/read-only.mjs",
+    "build:example": "node scripts/build-example.mjs",
+    "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
+    "test:e2e:read": "node test/e2e/e2e-read.mjs",
+    "test:e2e:wallet": "xvfb-run -a node test/e2e/e2e-wallet-connect.mjs",
+    "test:e2e:write": "node test/e2e/e2e-write.mjs",
+    "test:e2e": "node test/e2e/e2e-read.mjs && xvfb-run -a node test/e2e/e2e-wallet-connect.mjs",
+    "test:all": "pnpm test && pnpm test:e2e"
+  }
+}