@inversealtruism/cairn-sdk 0.2.2 → 0.3.0

package/dist/index.d.cts

@@ -10,12 +10,12 @@ 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 { InclusionResult } from '@inversealtruism/csd-light';
 export { CairnController, CairnControllerOptions, CairnState } from './controller.cjs';
 import '@inversealtruism/csd-client';
 import '@inversealtruism/csd-tx';
 import '@inversealtruism/csd-codec';
 import '@inversealtruism/csd-crypto';
-import '@inversealtruism/csd-light';
 import '@inversealtruism/csd-registry';
 
 /** `/cairnx/resolve/:name` — the display-path name→address resolution. */
@@ -104,13 +104,64 @@ 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 {
+    ok: boolean;
+    /** "verified" = merkle-proven inclusion + on-chain author; "proof-consistent" = a proof that folds but the
+     *  header could not be PoW-verified (indexer-trusted); "unverified" = could not prove. */
+    trust: "verified" | "proof-consistent" | "unverified";
+    reason?: string;
+    transient?: boolean;
+    payto?: string;
+    seller?: string;
+    terms?: ProvenOfferTerms;
+    blockHeight?: number;
+}
+/** The treasury fee rate stamped on an offer at its creation height (resolve.ts: v11 ? (v16 ? 150 : 100) : 0). */
+declare const feeBpsAt: (height: number) => number;
+/** true iff any fee/rebate/partial-sizing field of the SERVED offer diverges from the merkle-proven terms `t`
+ *  (fail-closed: any divergence => the caller refuses). Byte-identical to cairnx-core `bindOfferTerms`. */
+declare function bindOfferTerms(servedOffer: unknown, t: ProvenOfferTerms): boolean;
+/**
+ * Pre-verify an offer on-chain before building a `fillOffer` payment. `light` is a PoW-verifying light client
+ * (its `verifyTxInclusion` surfaces the merkle-proven tx + committed appPayloadHash); `client` reads source txs
+ * for the prevout-owner author bind. Pass `servedOffer` (the resolver's offer object) to also bind its
+ * payto/seller/terms to the proven values. See the module header for the trust posture.
+ */
+declare function preverifyOffer(opts: {
+    light: {
+        verifyTxInclusion(txidHex: string): Promise<InclusionResult>;
+    };
+    client: {
+        tx(id: string): Promise<unknown>;
+    };
+    offerId: string;
+    servedOffer?: unknown;
+}): 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" | "UNKNOWN";
-declare const SDK_VERSION = "0.2.2";
+type CairnErrorCode = "NOT_INSTALLED" | "USER_REJECTED" | "WALLET_LOCKED" | "UNSUPPORTED_METHOD" | "HTTP_ERROR" | "CONTENT_VERIFICATION" | "ACCOUNT_CHANGED" | "FIRST_PARTY_ONLY" | "RATE_LIMITED" | "APPROVAL_CLOSED" | "FORBIDDEN" | "INTERNAL" | "GHOST_INPUTS_SKIPPED" | "VERIFY_UNAVAILABLE" | "VERIFY_TAMPER" | "INSUFFICIENT" | "TOO_MANY_INPUTS" | "FEE_TOO_LOW" | "FEE_CAP" | "BAD_FEE" | "ZERO_ADDR_REFUSED" | "BAD_OUTPUTS" | "NO_OUTPUTS" | "BAD_REQUEST" | "OFFER_UNKNOWN" | "FILL_UNSAFE" | "FILL_WRONG_TARGET" | "SOURCE_DIVERGENCE" | "SUBMIT_REJECTED" | "SUBMIT_MAYBE_INFLIGHT" | "SUBMIT_DUPLICATE" | "NOTHING_TO_CONSOLIDATE" | "UNKNOWN";
+declare const SDK_VERSION = "0.3.0";
 interface CairnErrorOptions {
     code?: CairnErrorCode;
     docsPath?: string;
     cause?: unknown;
+    /**
+     * Whether a dApp may safely AUTO-retry this failure without fresh user intent. Transient infra faults
+     * (e.g. a node that was briefly unreachable, nothing signed) are `true`; fund-safety refusals are `false`.
+     * Defaults to `false` (fail-closed: never invite a retry unless the error is provably transient).
+     */
+    retryable?: boolean;
 }
 declare class CairnError extends Error {
     /** Stable machine code for programmatic branching. */
@@ -120,7 +171,13 @@ 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.2.2";
+    readonly version = "0.3.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.
+     * A `SubmitInFlightError` is `false` too: reconcile its `txid`, never blind-retry.
+     */
+    readonly retryable: boolean;
     constructor(shortMessage: string, opts?: CairnErrorOptions);
     /**
      * Walk the `cause` chain. With a predicate, returns the FIRST matching error (or null). Without one,
@@ -156,7 +213,40 @@ declare class ContentVerificationError extends CairnError {
     expected: string;
     constructor(expected: string);
 }
+/**
+ * The wallet SUBMITTED but the outcome is AMBIGUOUS: the tx MAY already be in the mempool. Thrown by the
+ * write wrappers for the nested `SUBMIT_MAYBE_INFLIGHT` (request threw / timed out / 5xx gateway / unreadable
+ * body) and `SUBMIT_DUPLICATE` (node answered "already present or mempool conflict") codes. It CARRIES the
+ * locally-computed consensus `txid` so a dApp can RECONCILE (check the explorer / balance) instead of blindly
+ * re-broadcasting, which would re-invite the double-broadcast this contract exists to prevent (F14). It is NOT
+ * retryable (`retryable === false`); `maybeSent === true` distinguishes it from a definitely-not-sent terminal
+ * refusal. See WALLET-ERROR-CODES.md in the cairn-wallet repo.
+ */
+declare class SubmitInFlightError extends CairnError {
+    /** The locally-computed consensus txid to reconcile against the chain (may be undefined if the wallet omitted it). */
+    readonly txid?: string;
+    /** Always true: the tx MAY be in the mempool. Reconcile via `txid`; never blind-retry. */
+    readonly maybeSent = true;
+    constructor(message: string, code: "SUBMIT_MAYBE_INFLIGHT" | "SUBMIT_DUPLICATE", txid?: string);
+}
 declare function mapProviderError(error: string, code?: string): CairnError;
+/**
+ * F14: map a NESTED SubmitResult refusal (`{ ok:false, code, error, txid }`, ridden inside an outer-ok reply)
+ * onto a typed error the write wrappers THROW. Without this a fund-safety refusal would RESOLVE with a phantom
+ * `txid:undefined`, so a dApp doing `const { txid } = await fillOffer(...); markPaid(txid)` marks a REFUSED
+ * fill as paid. Three buckets:
+ *   - AMBIGUOUS-INFLIGHT (`SUBMIT_MAYBE_INFLIGHT` / `SUBMIT_DUPLICATE`): a `SubmitInFlightError` that CARRIES
+ *     the locally-computed `txid` to reconcile (never blind-retry).
+ *   - TRANSIENT (`VERIFY_UNAVAILABLE` / `OFFER_UNKNOWN`): `retryable === true` (nothing signed; retry shortly).
+ *   - DEFINITIVE fund-safety refusal (everything else, incl. an unknown / absent code): `retryable === false`.
+ * Fail-closed: an explicit `ok:false` with no recognized code still throws a non-retryable refusal.
+ */
+declare function mapSubmitResultError(result: {
+    ok?: boolean;
+    code?: string;
+    error?: string;
+    txid?: string;
+}): CairnError;
 /** Convenience: the stable code of any error (or "UNKNOWN" for a non-CairnError). */
 declare function errorCode(err: unknown): CairnErrorCode;
 
@@ -232,6 +322,22 @@ declare class Cairn {
      * header chain is cached across calls; the first call near tip syncs the post-checkpoint span.
      */
     private verifiedHeaderMerkleAt;
+    /** 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;
+    /**
+     * 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.
+     */
+    verifyOfferForFill(offerId: string, servedOffer?: unknown): Promise<OfferFillCheck>;
     /**
      * Detect + connect the Cairn Wallet (browser only). Wires the wallet into
      * `cairn.board` for signed writes. Resolves to the connected address.
@@ -243,4 +349,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 PrimaryName, RegistryClient, SDK_VERSION, type TokenInfo, UnsupportedMethodError, UserRejectedError, WalletConnection, WalletLockedError, errorCode, mapProviderError };
+export { BoardClient, Cairn, type CairnBaseUrls, type CairnConfig, CairnError, type CairnErrorCode, type CairnErrorOptions, Chain, ContentClient, ContentVerificationError, DEFAULT_SPV_CHECKPOINT, DetectOptions, FetchLike, Http, HttpError, IndexerClient, type NameDetail, type NameResolution, NamesClient, NotInstalledError, type OfferFillCheck, type PrimaryName, type ProvenOfferTerms, RegistryClient, SDK_VERSION, SubmitInFlightError, type TokenInfo, UnsupportedMethodError, UserRejectedError, WalletConnection, WalletLockedError, bindOfferTerms, errorCode, feeBpsAt, mapProviderError, mapSubmitResultError, preverifyOffer };

package/dist/index.d.ts

@@ -10,12 +10,12 @@ 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 { InclusionResult } from '@inversealtruism/csd-light';
 export { CairnController, CairnControllerOptions, CairnState } from './controller.js';
 import '@inversealtruism/csd-client';
 import '@inversealtruism/csd-tx';
 import '@inversealtruism/csd-codec';
 import '@inversealtruism/csd-crypto';
-import '@inversealtruism/csd-light';
 import '@inversealtruism/csd-registry';
 
 /** `/cairnx/resolve/:name` — the display-path name→address resolution. */
@@ -104,13 +104,64 @@ 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 {
+    ok: boolean;
+    /** "verified" = merkle-proven inclusion + on-chain author; "proof-consistent" = a proof that folds but the
+     *  header could not be PoW-verified (indexer-trusted); "unverified" = could not prove. */
+    trust: "verified" | "proof-consistent" | "unverified";
+    reason?: string;
+    transient?: boolean;
+    payto?: string;
+    seller?: string;
+    terms?: ProvenOfferTerms;
+    blockHeight?: number;
+}
+/** The treasury fee rate stamped on an offer at its creation height (resolve.ts: v11 ? (v16 ? 150 : 100) : 0). */
+declare const feeBpsAt: (height: number) => number;
+/** true iff any fee/rebate/partial-sizing field of the SERVED offer diverges from the merkle-proven terms `t`
+ *  (fail-closed: any divergence => the caller refuses). Byte-identical to cairnx-core `bindOfferTerms`. */
+declare function bindOfferTerms(servedOffer: unknown, t: ProvenOfferTerms): boolean;
+/**
+ * Pre-verify an offer on-chain before building a `fillOffer` payment. `light` is a PoW-verifying light client
+ * (its `verifyTxInclusion` surfaces the merkle-proven tx + committed appPayloadHash); `client` reads source txs
+ * for the prevout-owner author bind. Pass `servedOffer` (the resolver's offer object) to also bind its
+ * payto/seller/terms to the proven values. See the module header for the trust posture.
+ */
+declare function preverifyOffer(opts: {
+    light: {
+        verifyTxInclusion(txidHex: string): Promise<InclusionResult>;
+    };
+    client: {
+        tx(id: string): Promise<unknown>;
+    };
+    offerId: string;
+    servedOffer?: unknown;
+}): 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" | "UNKNOWN";
-declare const SDK_VERSION = "0.2.2";
+type CairnErrorCode = "NOT_INSTALLED" | "USER_REJECTED" | "WALLET_LOCKED" | "UNSUPPORTED_METHOD" | "HTTP_ERROR" | "CONTENT_VERIFICATION" | "ACCOUNT_CHANGED" | "FIRST_PARTY_ONLY" | "RATE_LIMITED" | "APPROVAL_CLOSED" | "FORBIDDEN" | "INTERNAL" | "GHOST_INPUTS_SKIPPED" | "VERIFY_UNAVAILABLE" | "VERIFY_TAMPER" | "INSUFFICIENT" | "TOO_MANY_INPUTS" | "FEE_TOO_LOW" | "FEE_CAP" | "BAD_FEE" | "ZERO_ADDR_REFUSED" | "BAD_OUTPUTS" | "NO_OUTPUTS" | "BAD_REQUEST" | "OFFER_UNKNOWN" | "FILL_UNSAFE" | "FILL_WRONG_TARGET" | "SOURCE_DIVERGENCE" | "SUBMIT_REJECTED" | "SUBMIT_MAYBE_INFLIGHT" | "SUBMIT_DUPLICATE" | "NOTHING_TO_CONSOLIDATE" | "UNKNOWN";
+declare const SDK_VERSION = "0.3.0";
 interface CairnErrorOptions {
     code?: CairnErrorCode;
     docsPath?: string;
     cause?: unknown;
+    /**
+     * Whether a dApp may safely AUTO-retry this failure without fresh user intent. Transient infra faults
+     * (e.g. a node that was briefly unreachable, nothing signed) are `true`; fund-safety refusals are `false`.
+     * Defaults to `false` (fail-closed: never invite a retry unless the error is provably transient).
+     */
+    retryable?: boolean;
 }
 declare class CairnError extends Error {
     /** Stable machine code for programmatic branching. */
@@ -120,7 +171,13 @@ 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.2.2";
+    readonly version = "0.3.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.
+     * A `SubmitInFlightError` is `false` too: reconcile its `txid`, never blind-retry.
+     */
+    readonly retryable: boolean;
     constructor(shortMessage: string, opts?: CairnErrorOptions);
     /**
      * Walk the `cause` chain. With a predicate, returns the FIRST matching error (or null). Without one,
@@ -156,7 +213,40 @@ declare class ContentVerificationError extends CairnError {
     expected: string;
     constructor(expected: string);
 }
+/**
+ * The wallet SUBMITTED but the outcome is AMBIGUOUS: the tx MAY already be in the mempool. Thrown by the
+ * write wrappers for the nested `SUBMIT_MAYBE_INFLIGHT` (request threw / timed out / 5xx gateway / unreadable
+ * body) and `SUBMIT_DUPLICATE` (node answered "already present or mempool conflict") codes. It CARRIES the
+ * locally-computed consensus `txid` so a dApp can RECONCILE (check the explorer / balance) instead of blindly
+ * re-broadcasting, which would re-invite the double-broadcast this contract exists to prevent (F14). It is NOT
+ * retryable (`retryable === false`); `maybeSent === true` distinguishes it from a definitely-not-sent terminal
+ * refusal. See WALLET-ERROR-CODES.md in the cairn-wallet repo.
+ */
+declare class SubmitInFlightError extends CairnError {
+    /** The locally-computed consensus txid to reconcile against the chain (may be undefined if the wallet omitted it). */
+    readonly txid?: string;
+    /** Always true: the tx MAY be in the mempool. Reconcile via `txid`; never blind-retry. */
+    readonly maybeSent = true;
+    constructor(message: string, code: "SUBMIT_MAYBE_INFLIGHT" | "SUBMIT_DUPLICATE", txid?: string);
+}
 declare function mapProviderError(error: string, code?: string): CairnError;
+/**
+ * F14: map a NESTED SubmitResult refusal (`{ ok:false, code, error, txid }`, ridden inside an outer-ok reply)
+ * onto a typed error the write wrappers THROW. Without this a fund-safety refusal would RESOLVE with a phantom
+ * `txid:undefined`, so a dApp doing `const { txid } = await fillOffer(...); markPaid(txid)` marks a REFUSED
+ * fill as paid. Three buckets:
+ *   - AMBIGUOUS-INFLIGHT (`SUBMIT_MAYBE_INFLIGHT` / `SUBMIT_DUPLICATE`): a `SubmitInFlightError` that CARRIES
+ *     the locally-computed `txid` to reconcile (never blind-retry).
+ *   - TRANSIENT (`VERIFY_UNAVAILABLE` / `OFFER_UNKNOWN`): `retryable === true` (nothing signed; retry shortly).
+ *   - DEFINITIVE fund-safety refusal (everything else, incl. an unknown / absent code): `retryable === false`.
+ * Fail-closed: an explicit `ok:false` with no recognized code still throws a non-retryable refusal.
+ */
+declare function mapSubmitResultError(result: {
+    ok?: boolean;
+    code?: string;
+    error?: string;
+    txid?: string;
+}): CairnError;
 /** Convenience: the stable code of any error (or "UNKNOWN" for a non-CairnError). */
 declare function errorCode(err: unknown): CairnErrorCode;
 
@@ -232,6 +322,22 @@ declare class Cairn {
      * header chain is cached across calls; the first call near tip syncs the post-checkpoint span.
      */
     private verifiedHeaderMerkleAt;
+    /** 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;
+    /**
+     * 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.
+     */
+    verifyOfferForFill(offerId: string, servedOffer?: unknown): Promise<OfferFillCheck>;
     /**
      * Detect + connect the Cairn Wallet (browser only). Wires the wallet into
      * `cairn.board` for signed writes. Resolves to the connected address.
@@ -243,4 +349,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 PrimaryName, RegistryClient, SDK_VERSION, type TokenInfo, UnsupportedMethodError, UserRejectedError, WalletConnection, WalletLockedError, errorCode, mapProviderError };
+export { BoardClient, Cairn, type CairnBaseUrls, type CairnConfig, CairnError, type CairnErrorCode, type CairnErrorOptions, Chain, ContentClient, ContentVerificationError, DEFAULT_SPV_CHECKPOINT, DetectOptions, FetchLike, Http, HttpError, IndexerClient, type NameDetail, type NameResolution, NamesClient, NotInstalledError, type OfferFillCheck, type PrimaryName, type ProvenOfferTerms, RegistryClient, SDK_VERSION, SubmitInFlightError, type TokenInfo, UnsupportedMethodError, UserRejectedError, WalletConnection, WalletLockedError, bindOfferTerms, errorCode, feeBpsAt, mapProviderError, mapSubmitResultError, preverifyOffer };

package/dist/index.js

@@ -3,20 +3,20 @@ import {
 } from "./chunk-BGJZF7S2.js";
 import {
   BoardClient
-} from "./chunk-HI5STMH3.js";
+} from "./chunk-NLCF5T2F.js";
 import {
   Chain,
   LightClient
 } from "./chunk-C452UODV.js";
 import {
   ContentClient
-} from "./chunk-3EXZQPPT.js";
+} from "./chunk-4RDXEW35.js";
 import {
   IndexerClient
 } from "./chunk-J5J4JEJ6.js";
 import {
   CairnController
-} from "./chunk-LCE4IWMW.js";
+} from "./chunk-UMXLWUEF.js";
 import {
   WalletConnection,
   connect,
@@ -24,19 +24,21 @@ import {
   discoverProviders,
   getWallet,
   isInstalled
-} from "./chunk-QRVMYGSL.js";
+} from "./chunk-QV2GIXO7.js";
 import {
   CairnError,
   ContentVerificationError,
   HttpError,
   NotInstalledError,
   SDK_VERSION,
+  SubmitInFlightError,
   UnsupportedMethodError,
   UserRejectedError,
   WalletLockedError,
   errorCode,
-  mapProviderError
-} from "./chunk-ZJURNM5P.js";
+  mapProviderError,
+  mapSubmitResultError
+} from "./chunk-E2Z3XSCW.js";
 
 // src/http.ts
 var DEFAULT_MAX_BYTES = 16 * 1024 * 1024;
@@ -267,6 +269,106 @@ var NamesClient = class {
   }
 };
 
+// src/fillverify.ts
+import { rpcTxToTx } from "@inversealtruism/csd-client";
+import { txid, payloadHash } from "@inversealtruism/csd-codec";
+import { parseRecord, V11_HEIGHT, V16_HEIGHT, FEE_BPS, FEE_BPS_V16 } from "@inversealtruism/cairnx-core";
+var ADDR = /^0x[0-9a-f]{40}$/;
+var HASH = /^0x[0-9a-f]{64}$/;
+var COINBASE = "0x" + "00".repeat(32);
+var feeBpsAt = (height) => height >= V11_HEIGHT ? height >= V16_HEIGHT ? FEE_BPS_V16 : FEE_BPS : 0;
+function bindOfferTerms(servedOffer, t) {
+  const o = servedOffer;
+  const s = (v) => v === void 0 || v === null ? "" : String(v).toLowerCase();
+  if (Number(o?.height) !== t.height) return true;
+  if (Number(o?.feeBps) !== t.feeBps) return true;
+  if (t.value !== void 0 && String(o?.want?.value) !== t.value) return true;
+  if (s(o?.taker) !== s(t.taker)) return true;
+  if (s(o?.bid) !== s(t.bid)) return true;
+  const om = o?.min;
+  if ((om !== void 0 && om !== null) !== (t.min !== void 0)) return true;
+  if (t.min !== void 0 && String(om) !== t.min) return true;
+  return false;
+}
+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 = rpcTxToTx(body);
+  } catch {
+    return null;
+  }
+  if (String(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 = rpcTxToTx(incl.tx);
+    provenId = 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 = 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(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/index.ts
 var DEFAULT_SPV_CHECKPOINT = { height: 38142, hash: "0x00000000000140f023cc0ee1457a40833f2fcb4de44291b9d373e50f17b97232" };
 var DEFAULT_CAIRN = "https://cairn-substrate.com";
@@ -319,18 +421,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 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 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.
@@ -366,15 +489,20 @@ export {
   NotInstalledError,
   RegistryClient,
   SDK_VERSION,
+  SubmitInFlightError,
   UnsupportedMethodError,
   UserRejectedError,
   WalletConnection,
   WalletLockedError,
+  bindOfferTerms,
   connect,
   detectProvider,
   discoverProviders,
   errorCode,
+  feeBpsAt,
   getWallet,
   isInstalled,
-  mapProviderError
+  mapProviderError,
+  mapSubmitResultError,
+  preverifyOffer
 };