@inversealtruism/cairn-sdk 0.2.2 → 0.3.0

package/dist/controller.cjs

@@ -25,7 +25,7 @@ __export(controller_exports, {
 module.exports = __toCommonJS(controller_exports);
 
 // src/errors.ts
-var SDK_VERSION = "0.2.2";
+var SDK_VERSION = "0.3.0";
 var DOCS_BASE = "https://cairn-substrate.com/docs/sdk";
 var CairnError = class extends Error {
   /** Stable machine code for programmatic branching. */
@@ -36,6 +36,12 @@ var CairnError = class extends Error {
   docsPath;
   /** The cairn-sdk version that produced this error. */
   version = SDK_VERSION;
+  /**
+   * 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.
+   * A `SubmitInFlightError` is `false` too: reconcile its `txid`, never blind-retry.
+   */
+  retryable;
   constructor(shortMessage, opts = {}) {
     const docs = opts.docsPath;
     super(
@@ -46,6 +52,7 @@ var CairnError = class extends Error {
     this.code = opts.code ?? "UNKNOWN";
     this.shortMessage = shortMessage;
     this.docsPath = docs;
+    this.retryable = opts.retryable ?? false;
   }
   /**
    * Walk the `cause` chain. With a predicate, returns the FIRST matching error (or null). Without one,
@@ -82,11 +89,43 @@ var UnsupportedMethodError = class extends CairnError {
     super(message, { code: "UNSUPPORTED_METHOD", docsPath: "/errors#unsupported-method" });
   }
 };
+var SubmitInFlightError = class extends CairnError {
+  /** The locally-computed consensus txid to reconcile against the chain (may be undefined if the wallet omitted it). */
+  txid;
+  /** Always true: the tx MAY be in the mempool. Reconcile via `txid`; never blind-retry. */
+  maybeSent = true;
+  constructor(message, code, txid) {
+    super(message, { code, docsPath: "/errors#submit-inflight", retryable: false });
+    this.txid = txid;
+  }
+};
 var NATIVE_CODES = /* @__PURE__ */ new Set(["ACCOUNT_CHANGED", "FIRST_PARTY_ONLY", "RATE_LIMITED", "APPROVAL_CLOSED", "FORBIDDEN", "INTERNAL"]);
+var NESTED_TRANSIENT = /* @__PURE__ */ new Set(["VERIFY_UNAVAILABLE", "OFFER_UNKNOWN"]);
+var NESTED_TERMINAL = /* @__PURE__ */ new Set([
+  "FILL_UNSAFE",
+  "FILL_WRONG_TARGET",
+  "SOURCE_DIVERGENCE",
+  "VERIFY_TAMPER",
+  "SUBMIT_REJECTED",
+  "BAD_REQUEST",
+  "BAD_FEE",
+  "BAD_OUTPUTS",
+  "NO_OUTPUTS",
+  "ZERO_ADDR_REFUSED",
+  "TOO_MANY_INPUTS",
+  "INSUFFICIENT",
+  "FEE_CAP",
+  "FEE_TOO_LOW",
+  "ACCOUNT_CHANGED",
+  "GHOST_INPUTS_SKIPPED",
+  "NOTHING_TO_CONSOLIDATE"
+]);
 function mapProviderError(error, code) {
   if (code === "USER_REJECTED" || code === "APPROVAL_CLOSED") return new UserRejectedError(error);
   if (code === "WALLET_LOCKED") return new WalletLockedError(error);
   if (code === "UNSUPPORTED_METHOD" || code === "UNKNOWN_KIND") return new UnsupportedMethodError(error);
+  if (code && NESTED_TRANSIENT.has(code)) return new CairnError(error || code, { code, retryable: true });
+  if (code && NESTED_TERMINAL.has(code)) return new CairnError(error || code, { code, retryable: false });
   if (code && NATIVE_CODES.has(code)) return new CairnError(error || code, { code });
   const e = String(error || "").toLowerCase();
   if (e.includes("rejected by user")) return new UserRejectedError(error);
@@ -94,6 +133,14 @@ function mapProviderError(error, code) {
   if (e.includes("unsupported dapp method") || e.includes("predates") || e.includes("too old")) return new UnsupportedMethodError(error);
   return new CairnError(error || "Unknown wallet error");
 }
+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") {
+    return new SubmitInFlightError(msg, code, typeof result?.txid === "string" ? result.txid : void 0);
+  }
+  return mapProviderError(msg, code);
+}
 
 // src/connect.ts
 function detectProvider(opts = {}) {
@@ -142,6 +189,13 @@ function unwrap(reply) {
   if (reply && reply.ok) return reply.result;
   throw mapProviderError(reply?.error ?? "Unknown wallet error", reply?.code);
 }
+function unwrapWrite(reply) {
+  const result = unwrap(reply);
+  if (result && typeof result === "object" && result.ok === false) {
+    throw mapSubmitResultError(result);
+  }
+  return result;
+}
 var WalletConnection = class {
   provider;
   _addr = null;
@@ -208,12 +262,18 @@ var WalletConnection = class {
       return null;
     }
   }
-  /** Atomic fill (CairnX DvP): pay + attest in ONE tx. Always prompts with clear-signing. */
+  /**
+   * CairnX fill: pay + attest in ONE tx (atomic SETTLEMENT SHAPE, both revert together). Always prompts with
+   * clear-signing. The payment recipient in `params.outputs` is RESOLVER-TRUSTED here: this SDK does NOT
+   * SPV-verify it, so a lying resolver can redirect the payment. A dApp settling real value MUST corroborate
+   * the offer on-chain before building `outputs` (F13). The wallet's own fill-SPV boundary (cairn-wallet
+   * 0.2.60+, which binds payment/rebate/fee to the merkle-proven offer) is the payment-grade check; see FillParams.
+   */
   fillOffer(params) {
     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(unwrap);
+    return Promise.resolve(this.provider.fillOffer(params)).then(unwrapWrite);
   }
   /** This origin's current permission grant (EIP-2255-style). Silent; [] if none / unsupported. */
   async getPermissions() {
@@ -246,26 +306,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(unwrap);
+    return Promise.resolve(this.provider.send(params)).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(unwrap);
+    return Promise.resolve(this.provider.propose(params)).then(unwrapWrite);
   }
   /** Attest/support a proposal (always prompts). */
   attest(params) {
-    return Promise.resolve(this.provider.attest(params)).then(unwrap);
+    return Promise.resolve(this.provider.attest(params)).then(unwrapWrite);
   }
   /** Seal a commit-reveal claim (always prompts; salt stays inside the wallet). */
   sealClaim(params) {
-    return Promise.resolve(this.provider.sealClaim(params)).then(unwrap);
+    return Promise.resolve(this.provider.sealClaim(params)).then(unwrapWrite);
   }
   /** Reveal a previously sealed claim by its sealing txid (always prompts). */
   revealClaim(txid) {
     if (typeof txid !== "string" || !txid) {
       return Promise.reject(new UnsupportedMethodError("revealClaim requires the sealing txid"));
     }
-    return Promise.resolve(this.provider.revealClaim(txid)).then(unwrap);
+    return Promise.resolve(this.provider.revealClaim(txid)).then(unwrapWrite);
   }
 };
 async function getWallet(opts = {}) {

package/dist/controller.js

@@ -1,8 +1,8 @@
 import {
   CairnController
-} from "./chunk-LCE4IWMW.js";
-import "./chunk-QRVMYGSL.js";
-import "./chunk-ZJURNM5P.js";
+} from "./chunk-UMXLWUEF.js";
+import "./chunk-QV2GIXO7.js";
+import "./chunk-E2Z3XSCW.js";
 export {
   CairnController
 };

package/dist/index.cjs

@@ -35,22 +35,27 @@ __export(index_exports, {
   NotInstalledError: () => NotInstalledError,
   RegistryClient: () => RegistryClient,
   SDK_VERSION: () => SDK_VERSION,
+  SubmitInFlightError: () => SubmitInFlightError,
   UnsupportedMethodError: () => UnsupportedMethodError,
   UserRejectedError: () => UserRejectedError,
   WalletConnection: () => WalletConnection,
   WalletLockedError: () => WalletLockedError,
+  bindOfferTerms: () => bindOfferTerms,
   connect: () => connect,
   detectProvider: () => detectProvider,
   discoverProviders: () => discoverProviders,
   errorCode: () => errorCode,
+  feeBpsAt: () => feeBpsAt,
   getWallet: () => getWallet,
   isInstalled: () => isInstalled,
-  mapProviderError: () => mapProviderError
+  mapProviderError: () => mapProviderError,
+  mapSubmitResultError: () => mapSubmitResultError,
+  preverifyOffer: () => preverifyOffer
 });
 module.exports = __toCommonJS(index_exports);
 
 // src/errors.ts
-var SDK_VERSION = "0.2.2";
+var SDK_VERSION = "0.3.0";
 var DOCS_BASE = "https://cairn-substrate.com/docs/sdk";
 var CairnError = class extends Error {
   /** Stable machine code for programmatic branching. */
@@ -61,6 +66,12 @@ var CairnError = class extends Error {
   docsPath;
   /** The cairn-sdk version that produced this error. */
   version = SDK_VERSION;
+  /**
+   * 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.
+   * A `SubmitInFlightError` is `false` too: reconcile its `txid`, never blind-retry.
+   */
+  retryable;
   constructor(shortMessage, opts = {}) {
     const docs = opts.docsPath;
     super(
@@ -71,6 +82,7 @@ var CairnError = class extends Error {
     this.code = opts.code ?? "UNKNOWN";
     this.shortMessage = shortMessage;
     this.docsPath = docs;
+    this.retryable = opts.retryable ?? false;
   }
   /**
    * Walk the `cause` chain. With a predicate, returns the FIRST matching error (or null). Without one,
@@ -125,11 +137,43 @@ var ContentVerificationError = class extends CairnError {
     this.expected = expected;
   }
 };
+var SubmitInFlightError = class extends CairnError {
+  /** The locally-computed consensus txid to reconcile against the chain (may be undefined if the wallet omitted it). */
+  txid;
+  /** Always true: the tx MAY be in the mempool. Reconcile via `txid`; never blind-retry. */
+  maybeSent = true;
+  constructor(message, code, txid3) {
+    super(message, { code, docsPath: "/errors#submit-inflight", retryable: false });
+    this.txid = txid3;
+  }
+};
 var NATIVE_CODES = /* @__PURE__ */ new Set(["ACCOUNT_CHANGED", "FIRST_PARTY_ONLY", "RATE_LIMITED", "APPROVAL_CLOSED", "FORBIDDEN", "INTERNAL"]);
+var NESTED_TRANSIENT = /* @__PURE__ */ new Set(["VERIFY_UNAVAILABLE", "OFFER_UNKNOWN"]);
+var NESTED_TERMINAL = /* @__PURE__ */ new Set([
+  "FILL_UNSAFE",
+  "FILL_WRONG_TARGET",
+  "SOURCE_DIVERGENCE",
+  "VERIFY_TAMPER",
+  "SUBMIT_REJECTED",
+  "BAD_REQUEST",
+  "BAD_FEE",
+  "BAD_OUTPUTS",
+  "NO_OUTPUTS",
+  "ZERO_ADDR_REFUSED",
+  "TOO_MANY_INPUTS",
+  "INSUFFICIENT",
+  "FEE_CAP",
+  "FEE_TOO_LOW",
+  "ACCOUNT_CHANGED",
+  "GHOST_INPUTS_SKIPPED",
+  "NOTHING_TO_CONSOLIDATE"
+]);
 function mapProviderError(error, code) {
   if (code === "USER_REJECTED" || code === "APPROVAL_CLOSED") return new UserRejectedError(error);
   if (code === "WALLET_LOCKED") return new WalletLockedError(error);
   if (code === "UNSUPPORTED_METHOD" || code === "UNKNOWN_KIND") return new UnsupportedMethodError(error);
+  if (code && NESTED_TRANSIENT.has(code)) return new CairnError(error || code, { code, retryable: true });
+  if (code && NESTED_TERMINAL.has(code)) return new CairnError(error || code, { code, retryable: false });
   if (code && NATIVE_CODES.has(code)) return new CairnError(error || code, { code });
   const e = String(error || "").toLowerCase();
   if (e.includes("rejected by user")) return new UserRejectedError(error);
@@ -137,6 +181,14 @@ function mapProviderError(error, code) {
   if (e.includes("unsupported dapp method") || e.includes("predates") || e.includes("too old")) return new UnsupportedMethodError(error);
   return new CairnError(error || "Unknown wallet error");
 }
+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") {
+    return new SubmitInFlightError(msg, code, typeof result?.txid === "string" ? result.txid : void 0);
+  }
+  return mapProviderError(msg, code);
+}
 function errorCode(err) {
   return err instanceof CairnError ? err.code : "UNKNOWN";
 }
@@ -442,23 +494,23 @@ var BoardClient = class {
     const expiresEpoch = Math.floor(height / import_csd_codec3.EPOCH_LEN) + lifetime;
     const fee = input.fee ?? import_csd_codec3.MIN_FEE_PROPOSE;
     const r = await wallet.propose({ domain: content.domain, payloadHash: ph, uri, expiresEpoch, fee });
-    const txid2 = String(r.txid ?? "");
-    if (!txid2) throw new CairnError("Propose submitted but no txid was returned by the wallet.");
-    const reg = await this.tryRegister(content, txid2);
-    return { txid: txid2, payloadHash: ph, content, registered: reg.ok, registerError: reg.error };
+    const txid3 = String(r.txid ?? "");
+    if (!txid3) throw new CairnError("Propose submitted but no txid was returned by the wallet.");
+    const reg = await this.tryRegister(content, txid3);
+    return { txid: txid3, payloadHash: ph, content, registered: reg.ok, registerError: reg.error };
   }
   /**
    * Register off-chain content for an already-submitted proposal txid. Idempotent.
    * Returns { ok } — the cairn server verifies sha256(canonical) == on-chain payload_hash.
    */
-  async registerContent(content, txid2) {
+  async registerContent(content, txid3) {
     try {
       const res = await this.http.postJson("/api/content", {
         domain: content.domain,
         title: content.title,
         body: content.body,
         links: content.links,
-        txid: txid2
+        txid: txid3
       });
       return { ok: !!res.ok, error: res.ok ? void 0 : res.error };
     } catch (e) {
@@ -482,12 +534,12 @@ var BoardClient = class {
     if (!Number.isFinite(h)) throw new CairnError("Could not read chain tip height for expiry computation.");
     return h;
   }
-  async tryRegister(content, txid2) {
+  async tryRegister(content, txid3) {
     const delays = [0, 1500, 3e3, 5e3];
     let last = { ok: false, error: "not attempted" };
     for (const d of delays) {
       if (d) await sleep(d);
-      last = await this.registerContent(content, txid2);
+      last = await this.registerContent(content, txid3);
       if (last.ok) return last;
       if (!/not found yet|not found/i.test(last.error ?? "")) return last;
     }
@@ -594,10 +646,10 @@ var IndexerClient = class {
    * same-origin RPC safe is the forward PoW re-verification, not an origin gate (which no longer exists).
    * Fails closed: a malformed proof or a chain-disagreement returns "not-found" (the latter with equivocation:true).
    */
-  async verifyInclusion(txid2) {
+  async verifyInclusion(txid3) {
     let proof;
     try {
-      proof = await this.txMerkleProof(txid2);
+      proof = await this.txMerkleProof(txid3);
     } catch {
       return { included: false, trustLevel: "not-found", reason: "no merkle proof (tx not indexed)" };
     }
@@ -606,7 +658,7 @@ var IndexerClient = class {
     }
     let folds = false;
     try {
-      folds = (0, import_csd_codec4.verifyMerkleProof)(txid2, proof.pos, proof.merkle, proof.merkle_root);
+      folds = (0, import_csd_codec4.verifyMerkleProof)(txid3, proof.pos, proof.merkle, proof.merkle_root);
     } catch {
       return { included: false, trustLevel: "not-found", blockHeight: proof.block_height, reason: "malformed merkle proof" };
     }
@@ -1031,6 +1083,13 @@ function unwrap(reply) {
   if (reply && reply.ok) return reply.result;
   throw mapProviderError(reply?.error ?? "Unknown wallet error", reply?.code);
 }
+function unwrapWrite(reply) {
+  const result = unwrap(reply);
+  if (result && typeof result === "object" && result.ok === false) {
+    throw mapSubmitResultError(result);
+  }
+  return result;
+}
 var WalletConnection = class {
   provider;
   _addr = null;
@@ -1097,12 +1156,18 @@ var WalletConnection = class {
       return null;
     }
   }
-  /** Atomic fill (CairnX DvP): pay + attest in ONE tx. Always prompts with clear-signing. */
+  /**
+   * CairnX fill: pay + attest in ONE tx (atomic SETTLEMENT SHAPE, both revert together). Always prompts with
+   * clear-signing. The payment recipient in `params.outputs` is RESOLVER-TRUSTED here: this SDK does NOT
+   * SPV-verify it, so a lying resolver can redirect the payment. A dApp settling real value MUST corroborate
+   * the offer on-chain before building `outputs` (F13). The wallet's own fill-SPV boundary (cairn-wallet
+   * 0.2.60+, which binds payment/rebate/fee to the merkle-proven offer) is the payment-grade check; see FillParams.
+   */
   fillOffer(params) {
     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(unwrap);
+    return Promise.resolve(this.provider.fillOffer(params)).then(unwrapWrite);
   }
   /** This origin's current permission grant (EIP-2255-style). Silent; [] if none / unsupported. */
   async getPermissions() {
@@ -1135,26 +1200,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(unwrap);
+    return Promise.resolve(this.provider.send(params)).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(unwrap);
+    return Promise.resolve(this.provider.propose(params)).then(unwrapWrite);
   }
   /** Attest/support a proposal (always prompts). */
   attest(params) {
-    return Promise.resolve(this.provider.attest(params)).then(unwrap);
+    return Promise.resolve(this.provider.attest(params)).then(unwrapWrite);
   }
   /** Seal a commit-reveal claim (always prompts; salt stays inside the wallet). */
   sealClaim(params) {
-    return Promise.resolve(this.provider.sealClaim(params)).then(unwrap);
+    return Promise.resolve(this.provider.sealClaim(params)).then(unwrapWrite);
   }
   /** Reveal a previously sealed claim by its sealing txid (always prompts). */
-  revealClaim(txid2) {
-    if (typeof txid2 !== "string" || !txid2) {
+  revealClaim(txid3) {
+    if (typeof txid3 !== "string" || !txid3) {
       return Promise.reject(new UnsupportedMethodError("revealClaim requires the sealing txid"));
     }
-    return Promise.resolve(this.provider.revealClaim(txid2)).then(unwrap);
+    return Promise.resolve(this.provider.revealClaim(txid3)).then(unwrapWrite);
   }
 };
 async function getWallet(opts = {}) {
@@ -1166,6 +1231,106 @@ async function connect(opts = {}) {
   return { wallet, address };
 }
 
+// src/fillverify.ts
+var import_csd_client3 = require("@inversealtruism/csd-client");
+var import_csd_codec6 = require("@inversealtruism/csd-codec");
+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);
+var feeBpsAt = (height) => height >= import_cairnx_core2.V11_HEIGHT ? height >= import_cairnx_core2.V16_HEIGHT ? import_cairnx_core2.FEE_BPS_V16 : import_cairnx_core2.FEE_BPS : 0;
+function bindOfferTerms(servedOffer, t) {
+  const o = servedOffer;
+  const s = (v) => v === void 0 || v === null ? "" : String(v).toLowerCase();
+  if (Number(o?.height) !== t.height) return true;
+  if (Number(o?.feeBps) !== t.feeBps) return true;
+  if (t.value !== void 0 && String(o?.want?.value) !== t.value) return true;
+  if (s(o?.taker) !== s(t.taker)) return true;
+  if (s(o?.bid) !== s(t.bid)) return true;
+  const om = o?.min;
+  if ((om !== void 0 && om !== null) !== (t.min !== void 0)) return true;
+  if (t.min !== void 0 && String(om) !== t.min) return true;
+  return false;
+}
+async function provenAuthor(client, provenTx) {
+  const in0 = provenTx.inputs?.[0];
+  if (!in0 || String(in0.prevTxid).toLowerCase() === COINBASE && Number(in0.vout) === 4294967295) return null;
+  let info;
+  try {
+    info = await client.tx(String(in0.prevTxid));
+  } catch {
+    return null;
+  }
+  const body = info?.tx ?? info;
+  if (!body || !Array.isArray(body.outputs) || !Array.isArray(body.inputs)) return null;
+  let src;
+  try {
+    src = (0, import_csd_client3.rpcTxToTx)(body);
+  } catch {
+    return null;
+  }
+  if (String((0, import_csd_codec6.txid)(src)).toLowerCase() !== String(in0.prevTxid).toLowerCase()) return null;
+  const out = src.outputs?.[Number(in0.vout)];
+  const spk = out?.scriptPubkey ? String(out.scriptPubkey).toLowerCase() : null;
+  return spk && ADDR.test(spk) ? spk : null;
+}
+async function preverifyOffer(opts) {
+  const id = String(opts.offerId).toLowerCase();
+  if (!HASH.test(id)) return { ok: false, trust: "unverified", reason: "invalid offer id" };
+  let incl;
+  try {
+    incl = await opts.light.verifyTxInclusion(id);
+  } catch (e) {
+    return { ok: false, trust: "unverified", transient: true, reason: `couldn't reach the chain to verify the offer (${e?.message ?? e})` };
+  }
+  if (!incl.included || incl.trustLevel !== "verified-inclusion" || !incl.tx || !incl.appPayloadHash)
+    return { ok: false, trust: "unverified", transient: true, blockHeight: incl.blockHeight, reason: incl.reason ?? `offer not merkle-proven on-chain (${incl.trustLevel})` };
+  const blockHeight = Number(incl.blockHeight);
+  let provenTx, provenId;
+  try {
+    provenTx = (0, import_csd_client3.rpcTxToTx)(incl.tx);
+    provenId = (0, import_csd_codec6.txid)(provenTx);
+  } catch {
+    return { ok: false, trust: "unverified", reason: "the on-chain offer tx couldn't be re-derived" };
+  }
+  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" };
+  let rec;
+  try {
+    rec = (0, import_cairnx_core2.parseRecord)(app.uri, incl.appPayloadHash);
+  } catch {
+    rec = null;
+  }
+  if (!rec || rec.t !== "offer") return { ok: false, trust: "unverified", reason: "the offer record doesn't bind to its on-chain commitment" };
+  if (String((0, import_csd_codec6.payloadHash)(rec)).toLowerCase() !== String(incl.appPayloadHash).toLowerCase())
+    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 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 };
+  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)
+      return { ok: false, trust: "verified", reason: "the served payment recipient doesn't match the offer's on-chain author/record", ...base };
+    if (so?.seller !== void 0 && so?.seller !== null && String(so.seller).toLowerCase() !== seller)
+      return { ok: false, trust: "verified", reason: "the served seller doesn't match the offer's on-chain author (a lying resolver may be redirecting your payment)", ...base };
+    if (bindOfferTerms(opts.servedOffer, terms))
+      return { ok: false, trust: "verified", reason: "the served fee/rebate/partial terms don't match the offer's on-chain record (a lying resolver could mis-size the fill, causing a rejected fill after your payment)", ...base };
+  }
+  return { ok: true, trust: "verified", ...base };
+}
+
 // src/controller.ts
 var DISCONNECTED = Object.freeze({ status: "disconnected", account: null, error: null });
 var CairnController = class {
@@ -1307,18 +1472,39 @@ var Cairn = class {
   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)`);
-    if (!this._spvLight) this._spvLight = new import_csd_light.LightClient({ client: this.chain.client, checkpoints: { [this._spvCp.height]: this._spvCp.hash } });
-    const lc = this._spvLight;
-    if (!this._spvSeeded) {
-      await lc.syncFromCheckpoint(this._spvCp.height, this._spvCp.hash);
-      this._spvSeeded = true;
-    }
+    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);
   }
+  /** 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._spvSeeded) {
+      await this._spvLight.syncFromCheckpoint(this._spvCp.height, this._spvCp.hash);
+      this._spvSeeded = true;
+    }
+    return this._spvLight;
+  }
+  /**
+   * 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
+   * 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).
+   *
+   * 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.
+   */
+  async verifyOfferForFill(offerId, servedOffer) {
+    const light = await this.seededSpvLight();
+    return preverifyOffer({ light, client: this.chain.client, offerId, servedOffer });
+  }
   /**
    * Detect + connect the Cairn Wallet (browser only). Wires the wallet into
    * `cairn.board` for signed writes. Resolves to the connected address.
@@ -1355,15 +1541,20 @@ var Cairn = class {
   NotInstalledError,
   RegistryClient,
   SDK_VERSION,
+  SubmitInFlightError,
   UnsupportedMethodError,
   UserRejectedError,
   WalletConnection,
   WalletLockedError,
+  bindOfferTerms,
   connect,
   detectProvider,
   discoverProviders,
   errorCode,
+  feeBpsAt,
   getWallet,
   isInstalled,
-  mapProviderError
+  mapProviderError,
+  mapSubmitResultError,
+  preverifyOffer
 });