@inversealtruism/cairn-sdk 0.8.1 → 0.8.2

package/dist/index.cjs

@@ -58,7 +58,7 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/errors.ts
-var SDK_VERSION = "0.8.1";
+var SDK_VERSION = "0.8.2";
 var DOCS_BASE = "https://cairn-substrate.com/docs/sdk";
 var CairnError = class extends Error {
   /** Stable machine code for programmatic branching. */
@@ -141,17 +141,22 @@ var ContentVerificationError = class extends CairnError {
   }
 };
 var SubmitInFlightError = class extends CairnError {
-  /** The locally-computed consensus txid to reconcile against the chain (may be undefined if the wallet omitted it). */
+  /** The locally-computed consensus txid to reconcile against the chain (undefined when it is not known). */
   txid;
-  /** Always true: the tx MAY be in the mempool. Reconcile via `txid`; never blind-retry. */
+  /** The signed transaction, set only when `Chain.send` threw this (a wallet write keeps it in the wallet).
+   *  `chain.submit(nodeJson)` resends it unchanged: the same coins under the same txid, so it cannot pay twice,
+   *  where a new send may select other coins. */
+  nodeJson;
+  /** Always true: the tx MAY be in the mempool. Reconcile via `txid` or the balance; never blind-retry. */
   maybeSent = true;
-  constructor(message, code, txid3) {
-    super(message, { code, docsPath: "/errors#submit-inflight", retryable: false });
+  constructor(message, code, txid3, cause, nodeJson) {
+    super(message, { code, docsPath: "/errors#submit-inflight", retryable: false, cause });
     this.txid = txid3;
+    this.nodeJson = nodeJson;
   }
 };
 var NATIVE_CODES = /* @__PURE__ */ new Set(["FIRST_PARTY_ONLY", "RATE_LIMITED", "FORBIDDEN", "INTERNAL"]);
-var NESTED_TRANSIENT = /* @__PURE__ */ new Set(["VERIFY_UNAVAILABLE", "OFFER_UNKNOWN", "WALLET_UNAVAILABLE", "REVIEW_REQUIRED"]);
+var NESTED_TRANSIENT = /* @__PURE__ */ new Set(["VERIFY_UNAVAILABLE", "OFFER_UNKNOWN", "WALLET_UNAVAILABLE", "REVIEW_REQUIRED", "SEAL_NOT_MINED"]);
 var NESTED_TERMINAL = /* @__PURE__ */ new Set([
   "FILL_UNSAFE",
   "FILL_WRONG_TARGET",
@@ -173,7 +178,9 @@ var NESTED_TERMINAL = /* @__PURE__ */ new Set([
   "OFFER_SOURCE_CONFLICT",
   "FILL_LEGACY_SUNSET",
   "VERIFY_HORIZON",
-  "VERIFY_UNREPRESENTABLE"
+  "VERIFY_UNREPRESENTABLE",
+  "RESERVATION_DENIED",
+  "RPC_BLOCK_MISMATCH"
 ]);
 function mapProviderError(error, code) {
   if (code === "USER_REJECTED" || code === "APPROVAL_CLOSED") return new UserRejectedError(error);
@@ -191,11 +198,15 @@ function mapProviderError(error, code) {
 function mapSubmitResultError(result) {
   const code = result?.code;
   const msg = typeof result?.error === "string" && result.error || code || "The wallet refused the transaction.";
-  if (code === "SUBMIT_MAYBE_INFLIGHT" || code === "SUBMIT_DUPLICATE") {
+  if (code === "SUBMIT_MAYBE_INFLIGHT" || code === "SUBMIT_DUPLICATE" || code === "WALLET_UNAVAILABLE") {
     return new SubmitInFlightError(msg, code, typeof result?.txid === "string" ? result.txid : void 0);
   }
   return mapProviderError(msg, code);
 }
+function mapWriteProviderError(error, code) {
+  if (code === "WALLET_UNAVAILABLE") return new SubmitInFlightError(error || code, code);
+  return mapProviderError(error, code);
+}
 function errorCode(err) {
   return err instanceof CairnError ? err.code : "UNKNOWN";
 }
@@ -404,7 +415,11 @@ var Chain = class {
    * chain (`verifyInputValues` recomputes each source tx's txid, so a lying RPC can't under-report) and
    * computes change from the VERIFIED total — closing the UTXO-VALUE-1 implicit-fee-burn. Fail-closed:
    * if any source can't be verified it signs nothing. Prefer this over the pure `buildSend`. Pass
-   * `broadcast:false` to get the signed tx back without submitting.
+   * `broadcast:false` to get the signed tx back without submitting. A submit request that fails after signing
+   * throws a `SubmitInFlightError` carrying the signed `txid` and `nodeJson`: the node may have taken it, so check
+   * before resending, and resend that `nodeJson` with `submit` rather than a new send. A 4xx answer (a proxy's
+   * body cap or rate limit, or the node refusing the request) broadcast nothing and throws a final `CairnError`
+   * with code `SUBMIT_REJECTED`.
    */
   async send(p) {
     const from = (0, import_csd_crypto2.addrFromPriv)(p.priv);
@@ -418,10 +433,19 @@ var Chain = class {
       verify: (inputs) => (0, import_csd_client2.verifyInputValues)(this.client, inputs)
     });
     if (!built.ok || p.broadcast === false) return built;
-    const submitResult = await this.client.submit(built.nodeJson);
+    let submitResult;
+    try {
+      submitResult = await this.client.submit(built.nodeJson);
+    } catch (e) {
+      const what = e?.message ?? String(e);
+      if (e?.terminal === true)
+        throw new CairnError(`the submit request was refused (${what}), so nothing was broadcast; a 400 or 413 from a proxy is usually its request body cap (a transaction with many inputs), a 429 its rate limit`, { code: "SUBMIT_REJECTED", cause: e });
+      throw new SubmitInFlightError(`the submit request failed after signing (${what}); the node may have taken the transaction, so check ${built.txid} before sending again`, "SUBMIT_MAYBE_INFLIGHT", built.txid, e, built.nodeJson);
+    }
     return { ...built, ok: built.ok && submitResult.ok !== false, submitResult };
   }
-  /** A verifying light client over the same RPC (built once, reused). */
+  /** A light client over the same RPC (built once, reused), with no checkpoint and no batch header provider: it proves
+   *  nothing until seeded. The facade's seeded client backs `cairn.index.verifyInclusion` and `verifyOfferForFill`. */
   light() {
     if (!this._light) {
       this._light = new import_csd_light2.LightClient({ client: this.client });
@@ -434,6 +458,20 @@ var Chain = class {
 var import_csd_codec2 = require("@inversealtruism/csd-codec");
 var HEX64 = /^0x[0-9a-fA-F]{64}$/;
 var MAX_SSE_BUF = 1024 * 1024;
+var UTXO_PAGE = 1e3;
+var UTXO_MAX_PAGES = 100;
+var UTXO_CURSOR = /^\d{1,16}:0x[0-9a-fA-F]{64}:\d{1,10}$/;
+function utxoCursor(row) {
+  const r = row;
+  const c = `${String(r?.status?.block_height)}:${String(r?.txid)}:${String(r?.vout)}`;
+  return UTXO_CURSOR.test(c) ? c : null;
+}
+function cursorAfter(a, b) {
+  const [ha, ta, va] = a.split(":"), [hb2, tb, vb] = b.split(":");
+  if (Number(ha) !== Number(hb2)) return Number(ha) > Number(hb2);
+  if (ta.toLowerCase() !== tb.toLowerCase()) return ta.toLowerCase() > tb.toLowerCase();
+  return Number(va) > Number(vb);
+}
 function isValidMerkleProof(p) {
   if (!p || typeof p !== "object") return false;
   const m = p;
@@ -483,8 +521,29 @@ var IndexerClient = class {
   addressTxs(a) {
     return this.http.getJson(`/address/${encodeURIComponent(a)}/txs`);
   }
-  addressUtxo(a) {
-    return this.http.getJson(`/address/${encodeURIComponent(a)}/utxo`);
+  /** Every unspent output of an address. The indexer answers in pages of at most 1,000 rows; this follows its
+   *  `?after=` cursor until a short page, reading at most 100 pages: when the 100th is full (100,000 or more
+   *  outputs) it throws HttpError instead. An indexer that predates paging answers the whole set at once. */
+  async addressUtxo(a) {
+    const path = `/address/${encodeURIComponent(a)}/utxo`;
+    const first = await this.http.getJson(path);
+    if (!Array.isArray(first) || first.length !== UTXO_PAGE) return first;
+    const out = [...first];
+    let page = first;
+    let prev = null;
+    for (let pages = 1; page.length === UTXO_PAGE; pages++) {
+      if (pages === UTXO_MAX_PAGES)
+        throw new HttpError(200, this.http.url(path), `too many unspent outputs: addressUtxo reads at most ${UTXO_MAX_PAGES} pages of ${UTXO_PAGE} rows, and page ${UTXO_MAX_PAGES} is full`);
+      const after = utxoCursor(page[UTXO_PAGE - 1]);
+      if (!after) throw new HttpError(200, this.http.url(path), "malformed response: a utxo row has no block_height, txid and vout to page from");
+      if (prev !== null && !cursorAfter(after, prev)) throw new HttpError(200, this.http.url(path, { after }), "malformed response: the utxo pages do not advance");
+      page = await this.http.getJson(path, { after });
+      if (!Array.isArray(page)) throw new HttpError(200, this.http.url(path, { after }), "malformed response: a utxo page is not an array");
+      if (prev === null && page.length > 0 && utxoCursor(page[0]) === utxoCursor(first[0])) return first;
+      prev = after;
+      out.push(...page);
+    }
+    return out;
   }
   reputation(a) {
     return this.http.getJson(`/address/${encodeURIComponent(a)}/reputation`);
@@ -503,7 +562,8 @@ var IndexerClient = class {
   }
   // ---- trust-minimized inclusion ----------------------------------------
   /**
-   * Verify a tx is included in a block by folding its merkle branch to the root
+   * Verify that `txid` is a node of a block's merkle tree (an inner node or the root folds too, so pass an id you
+   * hashed from a transaction body you hold) by folding its merkle branch to the root
    * with csd-codec.verifyMerkleProof. If `headerMerkleAt` was provided, the
    * proof's root is cross-checked against the header merkle at that height →
    * trustLevel "verified-inclusion" (only as trustworthy as that header source —
@@ -987,7 +1047,8 @@ function unwrap(reply) {
   throw mapProviderError(reply?.error ?? "Unknown wallet error", reply?.code);
 }
 function unwrapWrite(reply) {
-  const result = unwrap(reply);
+  if (!reply || !reply.ok) throw mapWriteProviderError(reply?.error ?? "Unknown wallet error", reply?.code);
+  const result = reply.result;
   if (result && typeof result === "object" && result.ok === false) {
     throw mapSubmitResultError(result);
   }
@@ -1003,10 +1064,12 @@ var WalletConnection = class {
     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) {
+  // B7c: race a provider call against the per-call timeout. On timeout, throw a fail-closed error
+  // (retryable:false). A write's request stays open in the wallet and may still be approved and sent, so its
+  // timeout is a maybe-sent SubmitInFlightError (WALLET_TIMEOUT, no txid); while that request stays open, a resend
+  // opens a second one, and approving both sends twice. The genuine wallet resolves quickly
+  // once the user acts; this only fires on a truly hung/absent response.
+  call(op, label, write = false) {
     const ms = this._timeoutMs;
     const invoke = () => new Promise((resolve) => {
       resolve(op());
@@ -1014,7 +1077,7 @@ var WalletConnection = class {
     if (!Number.isFinite(ms) || ms <= 0) return invoke();
     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);
+      timer = setTimeout(() => reject(write ? new SubmitInFlightError(`the wallet did not respond to ${label} within ${ms}ms; the request may still be open in the wallet and be sent if approved, so reject it in the wallet and check the chain before sending it again`, "WALLET_TIMEOUT") : new CairnError(`the wallet did not respond to ${label} within ${ms}ms`, { retryable: false })), ms);
     });
     return Promise.race([invoke(), timeout]).finally(() => clearTimeout(timer));
   }
@@ -1090,7 +1153,7 @@ var WalletConnection = class {
       return Promise.reject(new UnsupportedMethodError("this wallet predates fillOffer() \u2014 ask the user to update the Cairn Wallet"));
     }
     this.adviseFillSpvCapability();
-    return this.call(() => this.provider.fillOffer(params), "fillOffer").then(unwrapWrite);
+    return this.call(() => this.provider.fillOffer(params), "fillOffer", true).then(unwrapWrite);
   }
   // P75-5 MF-10: ONE capability advisory per connection. The wallet's on-device fill-SPV (0.2.60+) is the
   // payment-grade fill boundary; when the provider SELF-REPORTS an older version, warn the integrator once
@@ -1138,26 +1201,26 @@ var WalletConnection = class {
   }
   /** Send CSD (always prompts with clear-signing; wallet picks inputs + returns change to itself). */
   send(params) {
-    return this.call(() => this.provider.send(params), "send").then(unwrapWrite);
+    return this.call(() => this.provider.send(params), "send", true).then(unwrapWrite);
   }
   /** Low-level Propose (always prompts). The caller computes the payload hash, uri and expiry epoch. */
   propose(params) {
-    return this.call(() => this.provider.propose(params), "propose").then(unwrapWrite);
+    return this.call(() => this.provider.propose(params), "propose", true).then(unwrapWrite);
   }
   /** Attest/support a proposal (always prompts). */
   attest(params) {
-    return this.call(() => this.provider.attest(params), "attest").then(unwrapWrite);
+    return this.call(() => this.provider.attest(params), "attest", true).then(unwrapWrite);
   }
   /** Seal a commit-reveal claim (always prompts; salt stays inside the wallet). */
   sealClaim(params) {
-    return this.call(() => this.provider.sealClaim(params), "sealClaim").then(unwrapWrite);
+    return this.call(() => this.provider.sealClaim(params), "sealClaim", true).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 this.call(() => this.provider.revealClaim(txid3), "revealClaim").then(unwrapWrite);
+    return this.call(() => this.provider.revealClaim(txid3), "revealClaim", true).then(unwrapWrite);
   }
 };
 async function getWallet(opts = {}) {
@@ -1215,9 +1278,114 @@ async function provenAuthor(client, provenTx) {
   if (String((0, import_csd_codec4.txid)(src)).toLowerCase() !== String(in0.prevTxid).toLowerCase()) return null;
   return (0, import_csd_crypto3.authorOf)(provenTx, src.outputs?.[Number(in0.vout)]?.scriptPubkey);
 }
+var has = (v) => v !== void 0 && v !== null;
+function fillInputs(o) {
+  const base = { pay: o.pay, plannedOutputs: o.plannedOutputs };
+  if (!has(o.me) && !has(o.tip) && !has(o.fillTargetId)) return base;
+  const me = typeof o.me === "string" ? o.me.toLowerCase() : "";
+  const target = has(o.fillTargetId) ? String(o.fillTargetId).toLowerCase() : void 0;
+  if (!ADDR.test(me) || !Number.isSafeInteger(o.tip) || o.tip < 0 || target !== void 0 && !HASH.test(target) || !has(o.pay))
+    return "invalid fill inputs: pass me (your 0x address), tip (the chain tip height) and pay together; fillTargetId, when given, is a 0x txid";
+  return { ...base, me, tip: o.tip, fillTargetId: target };
+}
+function judgeFill(rec, proven, served, f) {
+  const str = (v) => typeof v === "string" ? v : void 0;
+  const status = served?.status;
+  const terms = proven.terms;
+  const state = {
+    id: proven.id,
+    seller: proven.seller,
+    give: rec.give,
+    want: { ...rec.want, payto: proven.payto },
+    taker: rec.taker,
+    bid: rec.bid,
+    min: rec.min,
+    status,
+    expiresEpoch: proven.expiresEpoch,
+    height: terms.height,
+    feeBps: terms.feeBps,
+    paid: str(served?.paid),
+    delivered: str(served?.delivered),
+    claimedBy: str(served?.claimedBy),
+    claimUntilHeight: typeof served?.claimUntilHeight === "number" ? served.claimUntilHeight : void 0,
+    claimTxid: str(served?.claimTxid)
+  };
+  const j = { planBound: false };
+  const err = (e) => e?.message ?? String(e);
+  const token = (0, import_cairnx_core2.isTokenWant)(rec.want);
+  const progress = state.paid !== void 0 && state.delivered !== void 0;
+  if (typeof status === "string" && status !== "open")
+    j.refusal = `the resolver serves this offer as ${status}, not open - refusing (CairnX does not apply a fill of it)`;
+  if (token && has(f.plannedOutputs)) {
+    const legs = bindPlannedSums(f.plannedOutputs, []);
+    if (legs) j.refusal ??= `the offer is token-priced, so a fill moves no CSD: ${legs}`;
+  }
+  if (!has(f.pay)) j.planReason = "no `pay` was given, so no output plan was sized";
+  else if (j.refusal) j.planReason = "the fill is refused, so no output plan was sized";
+  else if (token) j.planReason = "the offer is token-priced: the payment is a token transfer, not CSD outputs";
+  else if (rec.min !== void 0) {
+    j.planReason = "the offer is partially fillable: its running paid/delivered is not provable here (the wallet's fill-SPV sizes it)";
+    if (typeof status === "string" && progress) {
+      try {
+        const p = (0, import_cairnx_core2.previewFill)(state, f.pay);
+        if (!p.deliverable) j.refusal = `this pay would not deliver against the offer's served progress (${p.reason}) - refusing (the CSD would be lost)`;
+      } catch (e) {
+        j.refusal = `couldn't size the fill against the offer (${err(e)}) - refusing`;
+      }
+    }
+  } else if (typeof status !== "string") j.planReason = "no served offer status: liveness is not provable here, so no output plan was sized (pass the resolver's offer object)";
+  else {
+    try {
+      const plan = (0, import_cairnx_core2.fillOutputPlan)(state, f.pay);
+      if (plan.kind === "csd-outputs") {
+        j.outputPlan = plan.outputs;
+        if (has(f.plannedOutputs)) {
+          j.refusal = bindPlannedSums(f.plannedOutputs, plan.outputs);
+          j.planBound = true;
+        }
+      } else if (plan.kind === "undeliverable") {
+        j.refusal = `this pay would not deliver against the proven offer (${plan.reason}) - refusing (the CSD would be lost)`;
+      } else {
+        j.planReason = `the proven offer settles without CSD outputs (${plan.kind})`;
+      }
+    } catch (e) {
+      j.refusal = `couldn't size the fill against the proven offer (${err(e)}) - refusing rather than sizing from served fields`;
+    }
+  }
+  if (f.me !== void 0 && f.tip !== void 0 && has(f.pay)) {
+    const unplan = () => {
+      delete j.outputPlan;
+      j.planBound = false;
+      j.planReason = "the fill is refused, so no output plan was sized";
+    };
+    if ((0, import_cairnx_core2.offerFillTooLate)(proven.expiresAt, f.tip)) {
+      j.refusal ??= `the offer's last live block ${proven.expiresAt - 1} leaves less than the ${import_cairnx_core2.FILL_TIP_MARGIN}-block cushion above tip ${f.tip}, so the fill is too close to the offer's expiry - do not sign it`;
+      unplan();
+    }
+    if (typeof status !== "string") j.refusal ??= "the fill endorsement needs the resolver's offer object (its status, claim and progress) - pass servedOffer";
+    else if (rec.min !== void 0 && !progress) j.refusal ??= "the served offer is missing paid or delivered (a partial offer's progress) - pass the resolver's full offer object";
+    else {
+      try {
+        const e = (0, import_cairnx_core2.fillEndorsement)(state, f.me, f.pay, f.tip, f.fillTargetId !== void 0 ? { fillTargetId: f.fillTargetId } : void 0);
+        j.endorsement = { verdict: e.verdict, reason: e.reason };
+        j.fillTarget = (0, import_cairnx_core2.fillTargetId)(state, f.tip);
+        if (e.verdict === "refused") {
+          j.refusal ??= `CairnX would refuse this fill (${e.reason}) - do not sign it`;
+          unplan();
+        }
+      } catch (e) {
+        j.refusal ??= `couldn't judge the fill against the offer (${err(e)}) - refusing`;
+        unplan();
+      }
+    }
+  }
+  return j;
+}
 async function preverifyOffer(opts) {
   const id = String(opts.offerId).toLowerCase();
   if (!HASH.test(id)) return { ok: false, trust: "unverified", reason: "invalid offer id" };
+  const fill = fillInputs(opts);
+  if (typeof fill === "string") return { ok: false, trust: "unverified", reason: fill };
   let incl;
   try {
     incl = await opts.light.verifyTxInclusion(id);
@@ -1259,52 +1427,17 @@ async function preverifyOffer(opts) {
   const w = rec.want ?? {};
   const payto = w.payto && ADDR.test(String(w.payto).toLowerCase()) ? String(w.payto).toLowerCase() : seller;
   const terms = (0, import_cairnx_core2.provenOfferTerms)(offerRec, blockHeight);
-  let outputPlan;
-  let sumsMismatch;
-  let planReason;
-  let planBound = false;
-  const has = (v) => v !== void 0 && v !== null;
-  const servedStatus = opts.servedOffer?.status;
-  if (!has(opts.pay)) planReason = "no `pay` was given, so no output plan was sized";
-  else if ((0, import_cairnx_core2.isTokenWant)(offerRec.want)) planReason = "the offer is token-priced: the payment is a token transfer, not CSD outputs";
-  else if (offerRec.min !== void 0) planReason = "the offer is partially fillable: its running paid/delivered is not provable here (the wallet's fill-SPV sizes it)";
-  else if (typeof servedStatus !== "string") planReason = "no served offer status: liveness is not provable here, so no output plan was sized (pass the resolver's offer object)";
-  else {
-    const provenState = {
-      id,
-      seller,
-      give: offerRec.give,
-      want: { ...offerRec.want, payto },
-      taker: offerRec.taker,
-      bid: offerRec.bid,
-      status: servedStatus,
-      expiresEpoch: 0,
-      height: blockHeight,
-      feeBps: terms.feeBps
-    };
-    try {
-      const plan = (0, import_cairnx_core2.fillOutputPlan)(provenState, opts.pay);
-      if (plan.kind === "csd-outputs") {
-        outputPlan = plan.outputs;
-        if (has(opts.plannedOutputs)) {
-          sumsMismatch = bindPlannedSums(opts.plannedOutputs, plan.outputs);
-          planBound = true;
-        }
-      } else if (plan.kind === "undeliverable") {
-        sumsMismatch = `this pay would not deliver against the proven offer (${plan.reason}) - refusing (the CSD would be lost)`;
-      } else {
-        planReason = `the proven offer settles without CSD outputs (${plan.kind})`;
-      }
-    } catch (e) {
-      sumsMismatch = `couldn't size the fill against the proven offer (${e?.message ?? e}) - refusing rather than sizing from served fields`;
-    }
-  }
+  const expiresEpoch = Number(ee);
+  const expiresAt = (0, import_cairnx_core2.offerExpiryHeightOf)(expiresEpoch, blockHeight);
+  const j = judgeFill(offerRec, { id, seller, payto, terms, expiresEpoch, expiresAt }, opts.servedOffer, fill);
   const planFields = {
-    ...outputPlan ? { outputPlan } : {},
-    ...has(opts.plannedOutputs) ? { planBound } : {},
-    ...!outputPlan && planReason && (has(opts.pay) || has(opts.plannedOutputs)) ? { planReason } : {}
+    ...j.outputPlan ? { outputPlan: j.outputPlan } : {},
+    ...has(opts.pay) ? { sized: j.outputPlan !== void 0 } : {},
+    ...has(opts.plannedOutputs) ? { planBound: j.planBound } : {},
+    ...!j.outputPlan && j.planReason && (has(opts.pay) || has(opts.plannedOutputs)) ? { planReason: j.planReason } : {},
+    ...j.endorsement ? { endorsement: j.endorsement, fillTarget: j.fillTarget } : {}
   };
-  const base = { payto, seller, terms, blockHeight, ...planFields };
+  const base = { payto, seller, terms, blockHeight, expiresEpoch, expiresAt, ...planFields };
   if (opts.servedOffer !== void 0 && opts.servedOffer !== null) {
     const so = opts.servedOffer;
     if (so?.want?.payto === void 0 || so?.want?.payto === null)
@@ -1318,7 +1451,7 @@ async function preverifyOffer(opts) {
     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's type or token price - a lying resolver could mis-size, re-price or re-route the fill, redirecting or burning your payment)", ...base };
   }
-  if (sumsMismatch) return { ok: false, trust: "verified", reason: sumsMismatch, ...base };
+  if (j.refusal) return { ok: false, trust: "verified", reason: j.refusal, ...base };
   return { ok: true, trust: "verified", ...base };
 }
 
@@ -1443,6 +1576,20 @@ var spvBackoffMs = (attempt) => Math.min(4e3, 700 * (attempt + 1));
 var SPV_RETRY_WAIT_BUDGET_MS = 16e3;
 var SPV_RECHECK_DEPTH = 12;
 var spvTipOf = (lc) => lc.baseHeight + lc.chain.length - 1;
+var SPV_BEYOND_TIP = /^tx at \d+ is \d+ blocks beyond tip; sync\(\d+\) first$/;
+var SpvLightClient = class extends import_csd_light.LightClient {
+  syncInFlight = null;
+  async sync(to, from) {
+    while (this.syncInFlight) await this.syncInFlight;
+    const run = super.sync(to, from);
+    this.syncInFlight = run;
+    try {
+      return await run;
+    } finally {
+      if (this.syncInFlight === run) this.syncInFlight = null;
+    }
+  }
+};
 var Cairn = class {
   config;
   chain;
@@ -1458,6 +1605,9 @@ var Cairn = class {
   // 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;
+  // The in-flight reseed of withSpvReseed, shared by callers whose structural failures overlap. Cleared when it
+  // settles; each caller still commits the fresh client only after its own retry succeeds.
+  _spvReseedInflight = null;
   _spvCp;
   // W12: the cairn base the SPV header-batch provider fetches /api/headers from (same base the rest of the SDK uses).
   _cairnBase;
@@ -1513,14 +1663,18 @@ var Cairn = class {
   // (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. recheckCachedHeader feeds this path: a near-tip
-  // cached header that the served chain no longer carries is a structural failure.
+  // cached header that the served chain no longer carries is a structural failure. Callers whose failures overlap
+  // (waiters on one shared sync) share one reseed.
   async withSpvReseed(op) {
     const lc = await this.seededSpvLight();
     try {
       return await op(lc);
     } catch (e) {
       if (spvIsTransient(e)) throw e;
-      const fresh = await this.seedFreshSpvLight();
+      this._spvReseedInflight ??= this.seedFreshSpvLight().finally(() => {
+        this._spvReseedInflight = null;
+      });
+      const fresh = await this._spvReseedInflight;
       const out = await op(fresh);
       this._spvLight = fresh;
       return out;
@@ -1540,7 +1694,7 @@ var Cairn = class {
   // 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 import_csd_light.LightClient({
+    const lc = new SpvLightClient({
       client: this.chain.client,
       checkpoints: { [this._spvCp.height]: this._spvCp.hash },
       headersBatchProvider: (from, count) => this.fetchHeadersBatch(from, count)
@@ -1582,11 +1736,7 @@ var Cairn = class {
    * 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.
+   * Cross-origin reach depends on the server's CORS mount on `/api/headers` (the cairn server mounts one).
    */
   async fetchHeadersBatch(from, count) {
     const g = this.config.fetch ?? globalThis.fetch;
@@ -1634,7 +1784,8 @@ var Cairn = class {
    * commitment, derives the payment recipient + seller from the offer's on-chain AUTHOR (the funding input's
    * prevout owner, txid-committed, NOT the malleable scriptSig), and, if you pass the resolver-SERVED `offer`
    * object, binds its payto/seller + fee/rebate/partial terms to the proven ones. Returns a TRUST-LABELED result
-   * (fail-closed on a positive mismatch, fail-soft `transient` on a lagging / below-checkpoint chain view).
+   * (fail-closed on a positive mismatch; `transient` on a lagging chain view; final, naming the anchor, for an
+   * offer mined below the SPV checkpoint).
    *
    * 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
@@ -1642,19 +1793,44 @@ var Cairn = class {
    *
    * 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.
+   * EXACTLY the outputPlan, never resolver-served outputs. Pass opts.me (your address) and opts.tip (the chain tip
+   * height) with pay to have cairnx-core's fillEndorsement and offerFillTooLate judge the fill for you at that tip; without them `ok`
+   * says the offer record is proven, not that you can fill it now.
    */
   async verifyOfferForFill(offerId, servedOffer, opts) {
     const light = {
       verifyTxInclusion: (txidHex) => this.withSpvReseed(async (lc) => {
         const haveTo = spvTipOf(lc);
-        const r = await lc.verifyTxInclusion(txidHex);
-        if (r.trustLevel === "verified-inclusion" && typeof r.blockHeight === "number" && r.blockHeight <= haveTo)
-          await this.recheckCachedHeader(lc, r.blockHeight, haveTo);
-        return r;
+        let r = await lc.verifyTxInclusion(txidHex);
+        if (r.trustLevel === "rpc-trusted" && SPV_BEYOND_TIP.test(r.reason ?? "")) {
+          let tipHeight;
+          try {
+            tipHeight = Number((await this.chain.tip()).height);
+          } catch (e) {
+            return { ...r, reason: `${r.reason} (the node tip read failed: ${e?.message ?? e})` };
+          }
+          if (Number.isSafeInteger(tipHeight) && tipHeight > spvTipOf(lc)) await lc.sync(tipHeight);
+          r = await lc.verifyTxInclusion(txidHex);
+        }
+        if (r.trustLevel !== "verified-inclusion") return r;
+        const height = Number(r.blockHeight);
+        if (!Number.isSafeInteger(height))
+          return { trustLevel: "rpc-trusted", included: false, reason: `the node's containing height for this tx is not a block height (${String(r.blockHeight)})` };
+        if (height <= haveTo) await this.recheckCachedHeader(lc, height, haveTo);
+        return { ...r, blockHeight: height };
       })
     };
-    return preverifyOffer({ light, client: this.chain.client, offerId, servedOffer, pay: opts?.pay, plannedOutputs: opts?.plannedOutputs });
+    return preverifyOffer({
+      light,
+      client: this.chain.client,
+      offerId,
+      servedOffer,
+      pay: opts?.pay,
+      plannedOutputs: opts?.plannedOutputs,
+      me: opts?.me,
+      tip: opts?.tip,
+      fillTargetId: opts?.fillTargetId
+    });
   }
   /**
    * Detect + connect the Cairn Wallet (browser only) and attach it as `cairn.wallet`.