@inversealtruism/cairn-sdk 0.3.2 → 0.4.1

package/dist/index.js

@@ -1,22 +1,24 @@
 import {
-  RegistryClient
-} from "./chunk-BGJZF7S2.js";
+  Http,
+  RegistryClient,
+  readCapped
+} from "./chunk-7UOTIAYK.js";
 import {
   BoardClient
-} from "./chunk-CZWDA3A5.js";
+} from "./chunk-DUTVUIQF.js";
 import {
   Chain,
   LightClient
 } from "./chunk-C452UODV.js";
 import {
   ContentClient
-} from "./chunk-JKC5K253.js";
+} from "./chunk-OCEHXK6A.js";
 import {
   IndexerClient
 } from "./chunk-J5J4JEJ6.js";
 import {
   CairnController
-} from "./chunk-AGU6K5EZ.js";
+} from "./chunk-QATE6AIP.js";
 import {
   WalletConnection,
   connect,
@@ -24,7 +26,7 @@ import {
   discoverProviders,
   getWallet,
   isInstalled
-} from "./chunk-BN3PFJDY.js";
+} from "./chunk-PIPN6FSA.js";
 import {
   CairnError,
   ContentVerificationError,
@@ -38,147 +40,7 @@ import {
   errorCode,
   mapProviderError,
   mapSubmitResultError
-} from "./chunk-FMXNJQWL.js";
-
-// src/http.ts
-var DEFAULT_MAX_BYTES = 16 * 1024 * 1024;
-var ERR_TEXT_CAP = 8 * 1024;
-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})`);
-  const body = res.body;
-  if (!body || typeof body.getReader !== "function") {
-    const buf = new Uint8Array(await res.arrayBuffer());
-    if (buf.byteLength > maxBytes) throw new HttpError(res.status, res.url, `response too large (${buf.byteLength} > ${maxBytes})`);
-    return buf;
-  }
-  const reader = body.getReader();
-  const chunks = [];
-  let total = 0;
-  for (; ; ) {
-    const { done, value } = await reader.read();
-    if (done) break;
-    if (value) {
-      total += value.byteLength;
-      if (total > maxBytes) {
-        try {
-          await reader.cancel();
-        } catch {
-        }
-        throw new HttpError(res.status, res.url, `response exceeded ${maxBytes} bytes`);
-      }
-      chunks.push(value);
-    }
-  }
-  const out = new Uint8Array(total);
-  let off = 0;
-  for (const c of chunks) {
-    out.set(c, off);
-    off += c.byteLength;
-  }
-  return out;
-}
-var Http = class {
-  baseUrl;
-  _fetch;
-  timeoutMs;
-  maxBytes;
-  headers;
-  retries;
-  constructor(opts) {
-    this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
-    const f = opts.fetch ?? globalThis.fetch;
-    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.headers = opts.headers ?? {};
-    this.retries = Math.min(10, Math.max(0, Math.floor(opts.retries ?? 0)));
-  }
-  /** Build an absolute URL from a path + optional query params. */
-  url(path, query) {
-    const p = path.startsWith("/") ? path : `/${path}`;
-    const u = new URL(this.baseUrl + p);
-    const basePath = new URL(this.baseUrl + "/").pathname;
-    if (basePath !== "/" && !(u.pathname + "/").startsWith(basePath)) {
-      throw new Error(`illegal path '${path}' \u2014 escapes base ${basePath}`);
-    }
-    if (query) {
-      for (const [k, v] of Object.entries(query)) {
-        if (v !== void 0 && v !== null) u.searchParams.set(k, String(v));
-      }
-    }
-    return u.toString();
-  }
-  async raw(method, path, opts) {
-    const url = this.url(path, opts?.query);
-    const ctrl = new AbortController();
-    const timer = setTimeout(() => ctrl.abort(), this.timeoutMs);
-    try {
-      const res = await this._fetch(url, {
-        method,
-        signal: ctrl.signal,
-        headers: {
-          ...opts?.body !== void 0 ? { "content-type": "application/json" } : {},
-          ...this.headers,
-          ...opts?.headers ?? {}
-        },
-        body: opts?.body !== void 0 ? JSON.stringify(opts.body) : void 0
-      });
-      return res;
-    } finally {
-      clearTimeout(timer);
-    }
-  }
-  // A malformed 2xx body must surface as a TYPED HttpError, not a leaked SyntaxError (B10: dApp
-  // code branches on `instanceof CairnError`; a raw parse error escaped that contract).
-  parseJson(res, text, url) {
-    try {
-      return JSON.parse(text);
-    } catch (e) {
-      throw new HttpError(res.status, url, `invalid JSON body: ${text.slice(0, 120)}`);
-    }
-  }
-  async getJson(path, query) {
-    const url = this.url(path, query);
-    for (let attempt = 0; ; attempt++) {
-      try {
-        const res = await this.raw("GET", path, { query });
-        if (!res.ok) {
-          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);
-        }
-      } catch (e) {
-        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))));
-    }
-  }
-  async postJson(path, body, headers) {
-    const url = this.url(path);
-    const res = await this.raw("POST", path, { body, headers });
-    if (!res.ok) throw new HttpError(res.status, url, await safeText(res));
-    return this.parseJson(res, new TextDecoder().decode(await readCapped(res, this.maxBytes)), url);
-  }
-  /** GET raw bytes (for content retrieval). Returns null on 404. */
-  async getBytes(path) {
-    const res = await this.raw("GET", path);
-    if (res.status === 404) return null;
-    if (!res.ok) throw new HttpError(res.status, this.url(path), await safeText(res));
-    return { bytes: await readCapped(res, this.maxBytes), headers: res.headers };
-  }
-};
-async function safeText(res) {
-  try {
-    return new TextDecoder().decode(await readCapped(res, ERR_TEXT_CAP));
-  } catch {
-    return "";
-  }
-}
+} from "./chunk-ERBT4DFD.js";
 
 // src/names.ts
 import { NAME_RE, RESERVED_NAMES } from "@inversealtruism/cairnx-core";
@@ -273,10 +135,39 @@ var NamesClient = class {
 // src/fillverify.ts
 import { rpcTxToTx } from "@inversealtruism/csd-client";
 import { txid, payloadHash } from "@inversealtruism/csd-codec";
-import { parseRecord, feeBpsAt, bindOfferTerms } from "@inversealtruism/cairnx-core";
+import {
+  DOMAIN,
+  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);
+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;
@@ -321,6 +212,8 @@ async function preverifyOffer(opts) {
   if (String(provenId).toLowerCase() !== id) return { ok: false, trust: "unverified", reason: "the merkle-proven tx doesn't match the offer id" };
   const app = incl.tx.app;
   if (!app || app.type !== "Propose") return { ok: false, trust: "unverified", reason: "the offer tx is not a Propose" };
+  if (String(app.domain) !== DOMAIN)
+    return { ok: false, trust: "unverified", reason: `the offer tx is not a ${DOMAIN} Propose (wrong settlement domain)` };
   let rec;
   try {
     rec = parseRecord(app.uri, incl.appPayloadHash);
@@ -332,33 +225,73 @@ 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 servedStatus = opts.servedOffer?.status;
+    const provenState = {
+      id,
+      seller,
+      give: offerRec.give,
+      want: { ...offerRec.want, payto },
+      taker: offerRec.taker,
+      bid: offerRec.bid,
+      status: typeof servedStatus === "string" ? servedStatus : "open",
+      expiresEpoch: 0,
+      height: blockHeight,
+      feeBps: terms.feeBps
+    };
+    try {
+      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)`;
+      }
+    } 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 } : {} };
   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() : "";
-    if (servedPayto && servedPayto !== payto)
+    if (so?.want?.payto === void 0 || so?.want?.payto === null)
+      return { ok: false, trust: "verified", reason: "the served offer is missing want.payto (the payment recipient) - pass the resolver's full offer object, or omit servedOffer", ...base };
+    if (String(so.want.payto).toLowerCase() !== payto)
       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)
+    if (so?.seller === void 0 || so?.seller === null)
+      return { ok: false, trust: "verified", reason: "the served offer is missing seller (the rebate recipient) - pass the resolver's full offer object, or omit servedOffer", ...base };
+    if (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 (isTokenWant(offerRec.want) && (String(so?.want?.ticker) !== String(offerRec.want.ticker) || String(so?.want?.amount) !== String(offerRec.want.amount)))
+      return { ok: false, trust: "verified", reason: "the served want ticker/amount don't match the offer's on-chain record (a lying resolver could bait-and-switch the token price)", ...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 SPV_MAX_BATCH_BYTES = 2 * 1024 * 1024;
+var SPV_TRANSIENT_RE = /\b(429|50[0-9]|timeout|timed out|abort|aborted|headers|non-dense|failed to fetch|networkerror|load failed)\b/i;
+var SPV_TRANSIENT_JSON_RE = /unexpected (token|end)|json/i;
+var spvIsTransient = (e) => {
+  const msg = String(e?.message || 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 Cairn = class {
   config;
   chain;
@@ -372,8 +305,13 @@ var Cairn = class {
   cairnHttp;
   // Lazily-seeded SPV light client + its checkpoint (audit M3 — PoW-verified header source).
   _spvLight = null;
-  _spvSeeded = false;
+  // MF-14: the in-flight seed promise. Concurrent first callers share ONE seed instead of racing two
+  // syncFromCheckpoint calls onto the same client (the loser would hit "seedTrusted must be called on a
+  // fresh client"). Cleared when the seed settles; a failure leaves no cached state, so the next call retries.
+  _spvSeedInflight = null;
   _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;
@@ -382,6 +320,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;
@@ -394,7 +333,7 @@ var Cairn = class {
       headerMerkleAt: (h) => this.verifiedHeaderMerkleAt(h)
     });
     this.content = new ContentClient({ swarm: swarmHttp, indexer: indexerHttp, cairn: this.cairnHttp });
-    this.registry = new RegistryClient({ baseUrl: indexer, fetch });
+    this.registry = new RegistryClient(indexerHttp);
     this.names = new NamesClient(this.cairnHttp);
   }
   /**
@@ -404,26 +343,132 @@ var Cairn = class {
    * checkpoint (can't verify backward) or if verification fails — the IndexerClient then degrades
    * 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.
    */
   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;
+      if (haveTo < height) await lc.sync(height);
+      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);
+    });
+  }
+  // MF-03: run an SPV read; on a STRUCTURAL failure (a reorg orphaned our cached tip: broken
+  // prev-link / bad PoW / hash mismatch) reseed ONCE from the pinned checkpoint into a LOCAL fresh
+  // client, retry the read on it, and commit the fresh client ONLY when both succeed (never null
+  // 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.
+  async withSpvReseed(op) {
     const lc = await this.seededSpvLight();
-    const haveTo = lc.baseHeight + lc.chain.length - 1;
-    if (haveTo < height) await lc.sync(height);
-    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);
+    try {
+      return await op(lc);
+    } catch (e) {
+      if (spvIsTransient(e)) throw e;
+      const fresh = await this.seedFreshSpvLight();
+      const out = await op(fresh);
+      this._spvLight = fresh;
+      return out;
+    }
   }
-  /** 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._spvSeeded) {
-      await this._spvLight.syncFromCheckpoint(this._spvCp.height, this._spvCp.hash);
-      this._spvSeeded = true;
+  // 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).
+  async seedFreshSpvLight() {
+    const lc = new LightClient({
+      client: this.chain.client,
+      checkpoints: { [this._spvCp.height]: this._spvCp.hash },
+      headersBatchProvider: (from, count) => this.fetchHeadersBatch(from, count)
+    });
+    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;
+      if (Number.isFinite(tipHeight) && tipHeight > have) await lc.sync(tipHeight);
+    } catch {
+    }
+    return lc;
+  }
+  /** The PoW-verifying SPV light client, seeded from the pinned checkpoint and cached across calls
+   *  (shared by the M3 header-merkle bind and the F13 offer pre-verify). The client is committed to
+   *  the field ONLY after a fully successful seed (MF-14): a failed seed leaves NO cached state, so
+   *  the next call retries on a fresh client instead of wedging on "seedTrusted must be called on a
+   *  fresh client". Concurrent first callers share ONE in-flight seed. Re-seeded only when a
+   *  structural (reorg) break is detected, see withSpvReseed. */
+  seededSpvLight() {
+    if (this._spvLight) return Promise.resolve(this._spvLight);
+    if (!this._spvSeedInflight) {
+      this._spvSeedInflight = this.seedFreshSpvLight().then((lc) => {
+        this._spvLight = lc;
+        return lc;
+      }).finally(() => {
+        this._spvSeedInflight = null;
+      });
+    }
+    return this._spvSeedInflight;
+  }
+  /**
+   * 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), a transport/timeout error, or a body-read fault (an oversize stream past the
+   * SPV_MAX_BATCH_BYTES cap, or a non-JSON 200 body such as a CF interstitial) 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 terminally (never retried).
+   *
+   * 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;
+      let parsed;
+      const ctrl = new AbortController();
+      const timer = setTimeout(() => ctrl.abort(), SPV_HTTP_TIMEOUT_MS);
+      try {
+        res = await doFetch(url, { signal: ctrl.signal });
+        if (res.ok) {
+          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));
+        continue;
+      } finally {
+        clearTimeout(timer);
+      }
+      if (res.ok) {
+        const rows = parsed?.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}`);
     }
-    return this._spvLight;
   }
   /**
    * F13 — corroborate an offer ON-CHAIN before building a `fillOffer` payment's `outputs`. Merkle-proves the
@@ -436,10 +481,14 @@ var Cairn = class {
    * This is best-effort corroboration, NOT the payment-grade boundary: the Cairn Wallet's OWN on-device
    * fill-SPV (0.2.60+, fails-closed before signing) is that. A dApp settling real value should still clear this
    * before building `outputs`, so it never hands the wallet a payment a lying resolver would redirect.
+   *
+   * Pass opts.pay (the CSD base units you intend to pay) to receive the PROVEN outputPlan for a whole fill of a
+   * non-partial offer, and opts.plannedOutputs to bind your planned per-address sums to it before signing; build
+   * EXACTLY the outputPlan, never resolver-served outputs.
    */
-  async verifyOfferForFill(offerId, servedOffer) {
-    const light = await this.seededSpvLight();
-    return preverifyOffer({ light, client: this.chain.client, offerId, servedOffer });
+  async verifyOfferForFill(offerId, servedOffer, opts) {
+    const light = { verifyTxInclusion: (txidHex) => this.withSpvReseed((lc) => lc.verifyTxInclusion(txidHex)) };
+    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
@@ -487,9 +536,14 @@ export {
   discoverProviders,
   errorCode,
   feeBpsAt,
+  fillEndorsement,
+  fillIsSafe,
+  fillOutputPlan,
   getWallet,
   isInstalled,
   mapProviderError,
   mapSubmitResultError,
-  preverifyOffer
+  preverifyOffer,
+  previewFill,
+  requiredFillOutputs
 };