@inversealtruism/cairn-sdk 0.8.0 → 0.8.2

package/dist/index.d.cts

@@ -11,8 +11,8 @@ 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 { NodeTxJson } from '@inversealtruism/csd-tx';
 import '@inversealtruism/csd-client';
-import '@inversealtruism/csd-tx';
 import '@inversealtruism/csd-codec';
 import '@inversealtruism/csd-crypto';
 
@@ -138,6 +138,9 @@ declare class NamesClient {
 /** 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 {
+    /** `true`: the offer record is proven and no check refused. Without `me` and `tip` it does not say the offer
+     *  is fillable by you now (it may be bound to another taker, held by someone else's live claim or
+     *  reservation, or too close to its expiry), and with `sized: false` it does not size your fill. */
     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. */
@@ -149,17 +152,37 @@ interface OfferFillCheck {
     /** Minted by cairnx-core's `provenOfferTerms`, so it can be passed back to `bindOfferTerms` without the opt-out. */
     terms?: MintedProvenOfferTerms;
     blockHeight?: number;
+    /** The proven Propose's `expires_epoch`. */
+    expiresEpoch?: number;
+    /** The first block height at which CairnX treats the offer as expired (cairnx-core `offerExpiryHeightOf` over the
+     *  proven expiry and anchor). A fill must be mined below it; with `me` and `tip` a fill with less than
+     *  cairnx-core's `FILL_TIP_MARGIN` blocks of cushion is refused, without them compare it with your tip. */
+    expiresAt?: number;
     /** B7b (REBIND W3/M1): the PROVEN CSD outputs to build for `pay` (a WHOLE fill of a non-partial offer),
      *  sized from the merkle-proven offer by the single-sourced `fillOutputPlan`. Present only when `pay` was
-     *  passed, the served offer carried a `status` and the offer could be sized. Build EXACTLY these; never the
-     *  resolver-served outputs a lying resolver could redirect. A partial (min-bearing) offer is left unsized
-     *  (its running paid/delivered is not provable at this corroboration layer; the wallet's fill-SPV is the
-     *  payment-grade sizer). Liveness is never proven here: the plan is sized only for the status the resolver
-     *  served, so an offer with no served status gets no plan. */
+     *  passed, the served offer carried a `status`, the offer could be sized, and neither the served status, the
+     *  endorsement nor the expiry cushion refuses the fill (other refusals keep the proven plan; branch on `ok`).
+     *  Build EXACTLY these; never the resolver-served outputs a lying resolver could redirect. A partial
+     *  (min-bearing) offer is left unsized (its running paid/delivered is not provable at this corroboration layer;
+     *  the wallet's fill-SPV is the payment-grade sizer). Liveness is never proven here: the plan is sized only
+     *  for the status the resolver served, so an offer with no served status gets no plan. */
     outputPlan?: {
         to: string;
         value: bigint;
     }[];
+    /** Present when `pay` was passed: `true` when `outputPlan` holds the proven outputs for this pay, `false` when
+     *  the fill could not be sized from proven data (`planReason` says why). `ok: true` with `sized: false` is a
+     *  verdict on the offer record, not on this fill. */
+    sized?: boolean;
+    /** Present when `me` and `tip` were passed: cairnx-core's `fillEndorsement` over the served state after the
+     *  binds. "refused" answers `ok: false`; "not-endorsable" (a token-priced want) is not a refusal. */
+    endorsement?: {
+        verdict: "endorsed" | "refused" | "not-endorsable";
+        reason: string;
+    };
+    /** Present with `endorsement`: the proposal id the fill's attest must target at `tip` (cairnx-core
+     *  `fillTargetId`: the offer id, or the fclaim txid while a live reservation routes the offer). */
+    fillTarget?: string;
     /** Present when `plannedOutputs` was passed: `true` when they were bound to `outputPlan` (a mismatch
      *  refuses with `ok: false`), `false` when there was no proven plan to bind them to (`planReason` says why).
      *  `ok: true` with `planBound: false` means your planned outputs were NOT checked. */
@@ -174,7 +197,7 @@ interface OfferFillCheck {
  * for the prevout-owner author bind. Pass `servedOffer` (the resolver's offer object) to also bind its
  * payto/seller/terms to the proven values. The FULL object is required: a served offer missing want.payto
  * or seller is refused (P75-5). A token-priced offer's served want.ticker/want.amount are bound verbatim to
- * the record. See the module header for the trust posture.
+ * the record. A served status other than open refuses. See the module header for the trust posture.
  */
 declare function preverifyOffer(opts: {
     light: {
@@ -188,17 +211,27 @@ declare function preverifyOffer(opts: {
     /** B7b (REBIND W3/M1): the CSD base units you intend to pay. When given, the result carries `outputPlan`
      *  (the PROVEN CSD outputs to build for a WHOLE fill of a non-partial offer, sized by the single-sourced
      *  `fillOutputPlan`) and, if you also pass `plannedOutputs`, binds them EXACTLY to that proven plan.
-     *  A partial (min-bearing) offer is left unsized here; the wallet's fill-SPV is its payment-grade sizer. */
+     *  A partial (min-bearing) offer is left unsized here (`sized: false`); with the served offer, a pay its
+     *  served progress says delivers nothing (below the minimum) is refused. The wallet's fill-SPV sizes it. */
     pay?: bigint | string | number;
     /** B7b: your planned per-address CSD sums (the outputs you WILL build), bound both ways to `outputPlan`.
      *  Requires `pay`. A missing/low leg is a doomed underpay; an extra/high leg is a W3 overpay or an N26
-     *  smuggled output - both refused. */
+     *  smuggled output - both refused. On a token-priced offer any positive CSD leg is refused. */
     plannedOutputs?: Record<string, bigint | string | number>;
+    /** Your address, the one that signs the fill. With `tip` (and `pay`), the result carries cairnx-core's
+     *  `fillEndorsement` over the served state: a taker bound to another address, an open CSD offer you hold no
+     *  live claim or reservation on, or an attest target the offer's routing rejects is refused, and so is a fill
+     *  that cairnx-core's `offerFillTooLate` says is too close to the offer's expiry. */
+    me?: string;
+    /** The chain tip height you sign at (for example `(await cairn.chain.tip()).height`). Goes with `me`. */
+    tip?: number;
+    /** The proposal id your attest will target: the offer id, or the fclaim txid while your reservation routes it. */
+    fillTargetId?: string;
 }): 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" | "CONTENT_NOT_JSON" | "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" | "OFFER_SOURCE_CONFLICT" | "FILL_LEGACY_SUNSET" | "VERIFY_HORIZON" | "VERIFY_UNREPRESENTABLE" | "WALLET_UNAVAILABLE" | "REVIEW_REQUIRED" | "UNKNOWN";
-declare const SDK_VERSION = "0.8.0";
+type CairnErrorCode = "NOT_INSTALLED" | "USER_REJECTED" | "WALLET_LOCKED" | "UNSUPPORTED_METHOD" | "HTTP_ERROR" | "CONTENT_VERIFICATION" | "CONTENT_NOT_JSON" | "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" | "OFFER_SOURCE_CONFLICT" | "FILL_LEGACY_SUNSET" | "VERIFY_HORIZON" | "VERIFY_UNREPRESENTABLE" | "WALLET_UNAVAILABLE" | "REVIEW_REQUIRED" | "SEAL_NOT_MINED" | "RESERVATION_DENIED" | "RPC_BLOCK_MISMATCH" | "WALLET_TIMEOUT" | "UNKNOWN";
+declare const SDK_VERSION = "0.8.2";
 interface CairnErrorOptions {
     code?: CairnErrorCode;
     docsPath?: string;
@@ -218,7 +251,7 @@ declare class CairnError extends Error {
     /** Relative docs path (under the SDK docs base), if any. */
     readonly docsPath?: string;
     /** The cairn-sdk version that produced this error. */
-    readonly version = "0.8.0";
+    readonly version = "0.8.2";
     /**
      * 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.
@@ -261,20 +294,28 @@ declare class ContentVerificationError extends CairnError {
     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.
+ * The outcome of a write 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, for `WALLET_UNAVAILABLE` on a
+ * write (the page lost the wallet's reply, which may come after the submit), for `WALLET_TIMEOUT` (the call
+ * outlasted the connection timeout while the request stays open in the wallet), and by `Chain.send` when the
+ * submit request fails after signing without a 4xx answer (a 4xx is `SUBMIT_REJECTED`). It CARRIES the
+ * locally-computed consensus `txid` when one is known 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). */
+    /** The locally-computed consensus txid to reconcile against the chain (undefined when it is not known). */
     readonly txid?: string;
-    /** 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. */
+    readonly nodeJson?: NodeTxJson;
+    /** Always true: the tx MAY be in the mempool. Reconcile via `txid` or the balance; never blind-retry. */
     readonly maybeSent = true;
-    constructor(message: string, code: "SUBMIT_MAYBE_INFLIGHT" | "SUBMIT_DUPLICATE", txid?: string);
+    constructor(message: string, code: "SUBMIT_MAYBE_INFLIGHT" | "SUBMIT_DUPLICATE" | "WALLET_UNAVAILABLE" | "WALLET_TIMEOUT", txid?: string, cause?: unknown, nodeJson?: NodeTxJson);
 }
 declare function mapProviderError(error: string, code?: string): CairnError;
 /**
@@ -282,9 +323,10 @@ declare function mapProviderError(error: string, code?: string): CairnError;
  * 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).
+ *   - AMBIGUOUS-INFLIGHT (`SUBMIT_MAYBE_INFLIGHT` / `SUBMIT_DUPLICATE` / `WALLET_UNAVAILABLE`): a
+ *     `SubmitInFlightError` that CARRIES the locally-computed `txid` when given, to reconcile (never blind-retry).
+ *   - TRANSIENT (`VERIFY_UNAVAILABLE` / `OFFER_UNKNOWN` / `REVIEW_REQUIRED`): `retryable === true` (nothing sent;
+ *     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.
  */
@@ -350,6 +392,7 @@ declare class Cairn {
     private readonly cairnHttp;
     private _spvLight;
     private _spvSeedInflight;
+    private _spvReseedInflight;
     private readonly _spvCp;
     private readonly _cairnBase;
     constructor(config?: CairnConfig);
@@ -386,11 +429,7 @@ declare class Cairn {
      * 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).
      */
     private fetchHeadersBatch;
     /**
@@ -399,7 +438,8 @@ declare class Cairn {
      * 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
@@ -407,11 +447,16 @@ declare class Cairn {
      *
      * 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.
      */
     verifyOfferForFill(offerId: string, servedOffer?: unknown, opts?: {
         pay?: bigint | string | number;
         plannedOutputs?: Record<string, bigint | string | number>;
+        me?: string;
+        tip?: number;
+        fillTargetId?: string;
     }): Promise<OfferFillCheck>;
     /**
      * Detect + connect the Cairn Wallet (browser only) and attach it as `cairn.wallet`.

package/dist/index.d.ts

@@ -11,8 +11,8 @@ 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 { NodeTxJson } from '@inversealtruism/csd-tx';
 import '@inversealtruism/csd-client';
-import '@inversealtruism/csd-tx';
 import '@inversealtruism/csd-codec';
 import '@inversealtruism/csd-crypto';
 
@@ -138,6 +138,9 @@ declare class NamesClient {
 /** 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 {
+    /** `true`: the offer record is proven and no check refused. Without `me` and `tip` it does not say the offer
+     *  is fillable by you now (it may be bound to another taker, held by someone else's live claim or
+     *  reservation, or too close to its expiry), and with `sized: false` it does not size your fill. */
     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. */
@@ -149,17 +152,37 @@ interface OfferFillCheck {
     /** Minted by cairnx-core's `provenOfferTerms`, so it can be passed back to `bindOfferTerms` without the opt-out. */
     terms?: MintedProvenOfferTerms;
     blockHeight?: number;
+    /** The proven Propose's `expires_epoch`. */
+    expiresEpoch?: number;
+    /** The first block height at which CairnX treats the offer as expired (cairnx-core `offerExpiryHeightOf` over the
+     *  proven expiry and anchor). A fill must be mined below it; with `me` and `tip` a fill with less than
+     *  cairnx-core's `FILL_TIP_MARGIN` blocks of cushion is refused, without them compare it with your tip. */
+    expiresAt?: number;
     /** B7b (REBIND W3/M1): the PROVEN CSD outputs to build for `pay` (a WHOLE fill of a non-partial offer),
      *  sized from the merkle-proven offer by the single-sourced `fillOutputPlan`. Present only when `pay` was
-     *  passed, the served offer carried a `status` and the offer could be sized. Build EXACTLY these; never the
-     *  resolver-served outputs a lying resolver could redirect. A partial (min-bearing) offer is left unsized
-     *  (its running paid/delivered is not provable at this corroboration layer; the wallet's fill-SPV is the
-     *  payment-grade sizer). Liveness is never proven here: the plan is sized only for the status the resolver
-     *  served, so an offer with no served status gets no plan. */
+     *  passed, the served offer carried a `status`, the offer could be sized, and neither the served status, the
+     *  endorsement nor the expiry cushion refuses the fill (other refusals keep the proven plan; branch on `ok`).
+     *  Build EXACTLY these; never the resolver-served outputs a lying resolver could redirect. A partial
+     *  (min-bearing) offer is left unsized (its running paid/delivered is not provable at this corroboration layer;
+     *  the wallet's fill-SPV is the payment-grade sizer). Liveness is never proven here: the plan is sized only
+     *  for the status the resolver served, so an offer with no served status gets no plan. */
     outputPlan?: {
         to: string;
         value: bigint;
     }[];
+    /** Present when `pay` was passed: `true` when `outputPlan` holds the proven outputs for this pay, `false` when
+     *  the fill could not be sized from proven data (`planReason` says why). `ok: true` with `sized: false` is a
+     *  verdict on the offer record, not on this fill. */
+    sized?: boolean;
+    /** Present when `me` and `tip` were passed: cairnx-core's `fillEndorsement` over the served state after the
+     *  binds. "refused" answers `ok: false`; "not-endorsable" (a token-priced want) is not a refusal. */
+    endorsement?: {
+        verdict: "endorsed" | "refused" | "not-endorsable";
+        reason: string;
+    };
+    /** Present with `endorsement`: the proposal id the fill's attest must target at `tip` (cairnx-core
+     *  `fillTargetId`: the offer id, or the fclaim txid while a live reservation routes the offer). */
+    fillTarget?: string;
     /** Present when `plannedOutputs` was passed: `true` when they were bound to `outputPlan` (a mismatch
      *  refuses with `ok: false`), `false` when there was no proven plan to bind them to (`planReason` says why).
      *  `ok: true` with `planBound: false` means your planned outputs were NOT checked. */
@@ -174,7 +197,7 @@ interface OfferFillCheck {
  * for the prevout-owner author bind. Pass `servedOffer` (the resolver's offer object) to also bind its
  * payto/seller/terms to the proven values. The FULL object is required: a served offer missing want.payto
  * or seller is refused (P75-5). A token-priced offer's served want.ticker/want.amount are bound verbatim to
- * the record. See the module header for the trust posture.
+ * the record. A served status other than open refuses. See the module header for the trust posture.
  */
 declare function preverifyOffer(opts: {
     light: {
@@ -188,17 +211,27 @@ declare function preverifyOffer(opts: {
     /** B7b (REBIND W3/M1): the CSD base units you intend to pay. When given, the result carries `outputPlan`
      *  (the PROVEN CSD outputs to build for a WHOLE fill of a non-partial offer, sized by the single-sourced
      *  `fillOutputPlan`) and, if you also pass `plannedOutputs`, binds them EXACTLY to that proven plan.
-     *  A partial (min-bearing) offer is left unsized here; the wallet's fill-SPV is its payment-grade sizer. */
+     *  A partial (min-bearing) offer is left unsized here (`sized: false`); with the served offer, a pay its
+     *  served progress says delivers nothing (below the minimum) is refused. The wallet's fill-SPV sizes it. */
     pay?: bigint | string | number;
     /** B7b: your planned per-address CSD sums (the outputs you WILL build), bound both ways to `outputPlan`.
      *  Requires `pay`. A missing/low leg is a doomed underpay; an extra/high leg is a W3 overpay or an N26
-     *  smuggled output - both refused. */
+     *  smuggled output - both refused. On a token-priced offer any positive CSD leg is refused. */
     plannedOutputs?: Record<string, bigint | string | number>;
+    /** Your address, the one that signs the fill. With `tip` (and `pay`), the result carries cairnx-core's
+     *  `fillEndorsement` over the served state: a taker bound to another address, an open CSD offer you hold no
+     *  live claim or reservation on, or an attest target the offer's routing rejects is refused, and so is a fill
+     *  that cairnx-core's `offerFillTooLate` says is too close to the offer's expiry. */
+    me?: string;
+    /** The chain tip height you sign at (for example `(await cairn.chain.tip()).height`). Goes with `me`. */
+    tip?: number;
+    /** The proposal id your attest will target: the offer id, or the fclaim txid while your reservation routes it. */
+    fillTargetId?: string;
 }): 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" | "CONTENT_NOT_JSON" | "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" | "OFFER_SOURCE_CONFLICT" | "FILL_LEGACY_SUNSET" | "VERIFY_HORIZON" | "VERIFY_UNREPRESENTABLE" | "WALLET_UNAVAILABLE" | "REVIEW_REQUIRED" | "UNKNOWN";
-declare const SDK_VERSION = "0.8.0";
+type CairnErrorCode = "NOT_INSTALLED" | "USER_REJECTED" | "WALLET_LOCKED" | "UNSUPPORTED_METHOD" | "HTTP_ERROR" | "CONTENT_VERIFICATION" | "CONTENT_NOT_JSON" | "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" | "OFFER_SOURCE_CONFLICT" | "FILL_LEGACY_SUNSET" | "VERIFY_HORIZON" | "VERIFY_UNREPRESENTABLE" | "WALLET_UNAVAILABLE" | "REVIEW_REQUIRED" | "SEAL_NOT_MINED" | "RESERVATION_DENIED" | "RPC_BLOCK_MISMATCH" | "WALLET_TIMEOUT" | "UNKNOWN";
+declare const SDK_VERSION = "0.8.2";
 interface CairnErrorOptions {
     code?: CairnErrorCode;
     docsPath?: string;
@@ -218,7 +251,7 @@ declare class CairnError extends Error {
     /** Relative docs path (under the SDK docs base), if any. */
     readonly docsPath?: string;
     /** The cairn-sdk version that produced this error. */
-    readonly version = "0.8.0";
+    readonly version = "0.8.2";
     /**
      * 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.
@@ -261,20 +294,28 @@ declare class ContentVerificationError extends CairnError {
     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.
+ * The outcome of a write 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, for `WALLET_UNAVAILABLE` on a
+ * write (the page lost the wallet's reply, which may come after the submit), for `WALLET_TIMEOUT` (the call
+ * outlasted the connection timeout while the request stays open in the wallet), and by `Chain.send` when the
+ * submit request fails after signing without a 4xx answer (a 4xx is `SUBMIT_REJECTED`). It CARRIES the
+ * locally-computed consensus `txid` when one is known 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). */
+    /** The locally-computed consensus txid to reconcile against the chain (undefined when it is not known). */
     readonly txid?: string;
-    /** 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. */
+    readonly nodeJson?: NodeTxJson;
+    /** Always true: the tx MAY be in the mempool. Reconcile via `txid` or the balance; never blind-retry. */
     readonly maybeSent = true;
-    constructor(message: string, code: "SUBMIT_MAYBE_INFLIGHT" | "SUBMIT_DUPLICATE", txid?: string);
+    constructor(message: string, code: "SUBMIT_MAYBE_INFLIGHT" | "SUBMIT_DUPLICATE" | "WALLET_UNAVAILABLE" | "WALLET_TIMEOUT", txid?: string, cause?: unknown, nodeJson?: NodeTxJson);
 }
 declare function mapProviderError(error: string, code?: string): CairnError;
 /**
@@ -282,9 +323,10 @@ declare function mapProviderError(error: string, code?: string): CairnError;
  * 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).
+ *   - AMBIGUOUS-INFLIGHT (`SUBMIT_MAYBE_INFLIGHT` / `SUBMIT_DUPLICATE` / `WALLET_UNAVAILABLE`): a
+ *     `SubmitInFlightError` that CARRIES the locally-computed `txid` when given, to reconcile (never blind-retry).
+ *   - TRANSIENT (`VERIFY_UNAVAILABLE` / `OFFER_UNKNOWN` / `REVIEW_REQUIRED`): `retryable === true` (nothing sent;
+ *     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.
  */
@@ -350,6 +392,7 @@ declare class Cairn {
     private readonly cairnHttp;
     private _spvLight;
     private _spvSeedInflight;
+    private _spvReseedInflight;
     private readonly _spvCp;
     private readonly _cairnBase;
     constructor(config?: CairnConfig);
@@ -386,11 +429,7 @@ declare class Cairn {
      * 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).
      */
     private fetchHeadersBatch;
     /**
@@ -399,7 +438,8 @@ declare class Cairn {
      * 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
@@ -407,11 +447,16 @@ declare class Cairn {
      *
      * 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.
      */
     verifyOfferForFill(offerId: string, servedOffer?: unknown, opts?: {
         pay?: bigint | string | number;
         plannedOutputs?: Record<string, bigint | string | number>;
+        me?: string;
+        tip?: number;
+        fillTargetId?: string;
     }): Promise<OfferFillCheck>;
     /**
      * Detect + connect the Cairn Wallet (browser only) and attach it as `cairn.wallet`.