@inversealtruism/cairn-sdk 0.3.2 → 0.4.0

package/dist/index.cjs

@@ -46,16 +46,21 @@ __export(index_exports, {
   discoverProviders: () => discoverProviders,
   errorCode: () => errorCode,
   feeBpsAt: () => import_cairnx_core2.feeBpsAt,
+  fillEndorsement: () => import_cairnx_core2.fillEndorsement,
+  fillIsSafe: () => import_cairnx_core2.fillIsSafe,
+  fillOutputPlan: () => import_cairnx_core2.fillOutputPlan,
   getWallet: () => getWallet,
   isInstalled: () => isInstalled,
   mapProviderError: () => mapProviderError,
   mapSubmitResultError: () => mapSubmitResultError,
-  preverifyOffer: () => preverifyOffer
+  preverifyOffer: () => preverifyOffer,
+  previewFill: () => import_cairnx_core2.previewFill,
+  requiredFillOutputs: () => import_cairnx_core2.requiredFillOutputs
 });
 module.exports = __toCommonJS(index_exports);
 
 // src/errors.ts
-var SDK_VERSION = "0.3.2";
+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. */
@@ -147,7 +152,7 @@ var SubmitInFlightError = class extends CairnError {
     this.txid = txid3;
   }
 };
-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",
@@ -1015,6 +1020,7 @@ var NamesClient = class {
 };
 
 // src/connect.ts
+var DEFAULT_PROVIDER_TIMEOUT_MS = 10 * 6e4;
 function discoverProviders(opts = {}) {
   const timeoutMs = opts.timeoutMs ?? 1e3;
   return new Promise((resolve) => {
@@ -1094,8 +1100,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() {
@@ -1107,13 +1129,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;
   }
@@ -1126,7 +1148,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.
@@ -1142,7 +1164,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() {
@@ -1152,7 +1174,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;
     }
@@ -1168,24 +1190,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
@@ -1201,26 +1223,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(txid3) {
     if (typeof txid3 !== "string" || !txid3) {
       return Promise.reject(new UnsupportedMethodError("revealClaim requires the sealing txid"));
     }
-    return Promise.resolve(this.provider.revealClaim(txid3)).then(unwrapWrite);
+    return this.call(() => this.provider.revealClaim(txid3), "revealClaim").then(unwrapWrite);
   }
 };
 async function getWallet(opts = {}) {
@@ -1239,6 +1261,23 @@ var import_cairnx_core2 = require("@inversealtruism/cairnx-core");
 var ADDR = /^0x[0-9a-f]{40}$/;
 var HASH = /^0x[0-9a-f]{64}$/;
 var COINBASE = "0x" + "00".repeat(32);
+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];
   if (!in0 || String(in0.prevTxid).toLowerCase() === COINBASE && Number(in0.vout) === 4294967295) return null;
@@ -1294,17 +1333,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: (0, import_cairnx_core2.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 = (0, import_cairnx_core2.provenOfferTerms)(offerRec, blockHeight);
+  let outputPlan;
+  let sumsMismatch;
+  if (opts.pay !== void 0 && opts.pay !== null && !(0, import_cairnx_core2.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 = (0, import_cairnx_core2.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() : "";
@@ -1312,9 +1369,10 @@ 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 ((0, import_cairnx_core2.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 ((0, import_cairnx_core2.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 };
 }
 
@@ -1410,6 +1468,10 @@ var CairnController = class {
 // 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;
@@ -1425,6 +1487,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;
@@ -1433,6 +1497,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;
@@ -1469,13 +1534,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 import_csd_light.LightClient({ client: this.chain.client, checkpoints: { [this._spvCp.height]: this._spvCp.hash } });
+    if (!this._spvLight) this._spvLight = new import_csd_light.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
@@ -1539,9 +1660,14 @@ var Cairn = class {
   discoverProviders,
   errorCode,
   feeBpsAt,
+  fillEndorsement,
+  fillIsSafe,
+  fillOutputPlan,
   getWallet,
   isInstalled,
   mapProviderError,
   mapSubmitResultError,
-  preverifyOffer
+  preverifyOffer,
+  previewFill,
+  requiredFillOutputs
 });

package/dist/index.d.cts

@@ -10,9 +10,10 @@ export { ContentClientOptions, PreparedContent } from './content.cjs';
 import { RegistryClient } from './registry.cjs';
 import { WalletConnection, DetectOptions } from './connect.cjs';
 export { AttestParams, CairnProvider, ConnectResult, FillParams, ProposeParams, ProviderDetail, ProviderInfo, SealClaimParams, SendParams, SignInResult, SiwcParams, SiwcResult, TxResult, WalletCapabilities, WalletPermission, connect, detectProvider, discoverProviders, getWallet, isInstalled } from './connect.cjs';
+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.cjs';
-export { bindOfferTerms, feeBpsAt } from '@inversealtruism/cairnx-core';
 import '@inversealtruism/csd-client';
 import '@inversealtruism/csd-tx';
 import '@inversealtruism/csd-codec';
@@ -105,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 {
@@ -127,6 +119,15 @@ 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;
+    }[];
 }
 
 /**
@@ -144,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.2";
+declare const SDK_VERSION = "0.4.0";
 interface CairnErrorOptions {
     code?: CairnErrorCode;
     docsPath?: string;
@@ -168,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.2";
+    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.
@@ -309,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
@@ -322,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
@@ -346,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, errorCode, 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.d.ts

@@ -10,9 +10,10 @@ 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';
-export { bindOfferTerms, feeBpsAt } from '@inversealtruism/cairnx-core';
 import '@inversealtruism/csd-client';
 import '@inversealtruism/csd-tx';
 import '@inversealtruism/csd-codec';
@@ -105,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 {
@@ -127,6 +119,15 @@ 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;
+    }[];
 }
 
 /**
@@ -144,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.2";
+declare const SDK_VERSION = "0.4.0";
 interface CairnErrorOptions {
     code?: CairnErrorCode;
     docsPath?: string;
@@ -168,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.2";
+    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.
@@ -309,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
@@ -322,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
@@ -346,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, errorCode, 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 };