@arkade-os/swap 0.0.10 → 0.0.12

package/dist/nostr.d.cts

@@ -1,4 +1,4 @@
-import { y as RfqTransport } from './rfq-DglvHMNC.cjs';
+import { R as RfqTransport } from './rfq-DzsmhXX3.cjs';
 import { SimplePool } from 'nostr-tools';
 import '@arkade-os/sdk';
 

package/dist/nostr.d.ts

@@ -1,4 +1,4 @@
-import { y as RfqTransport } from './rfq-DglvHMNC.js';
+import { R as RfqTransport } from './rfq-DzsmhXX3.js';
 import { SimplePool } from 'nostr-tools';
 import '@arkade-os/sdk';
 

package/dist/nostr.js

@@ -1,7 +1,7 @@
 import {
   expectQuote,
   pairOf
-} from "./chunk-5NPYNQ5V.js";
+} from "./chunk-XXWOODUE.js";
 
 // src/nostr.ts
 import {

package/dist/repositories/realm/index.d.cts

@@ -1,8 +1,8 @@
 import { RealmLike } from '@arkade-os/sdk/repositories/realm';
-import { A as AssetSwapRepository, a as AssetSwap, R as RfqSwapRecord, M as MarketsCacheEntry } from '../../repository-C8FXlmHY.cjs';
+import { A as AssetSwapRepository, a as AssetSwap, R as RfqSwapRecord, M as MarketsCacheEntry } from '../../repository-DaK1RzRq.cjs';
 import '@arkade-os/solver-discovery';
 import '@arkade-os/sdk';
-import '../../rfq-DglvHMNC.cjs';
+import '../../rfq-DzsmhXX3.cjs';
 
 /**
  * Realm backend for React Native.

package/dist/repositories/realm/index.d.ts

@@ -1,8 +1,8 @@
 import { RealmLike } from '@arkade-os/sdk/repositories/realm';
-import { A as AssetSwapRepository, a as AssetSwap, R as RfqSwapRecord, M as MarketsCacheEntry } from '../../repository-Cw2EvvZG.js';
+import { A as AssetSwapRepository, a as AssetSwap, R as RfqSwapRecord, M as MarketsCacheEntry } from '../../repository-DlLvj_y6.js';
 import '@arkade-os/solver-discovery';
 import '@arkade-os/sdk';
-import '../../rfq-DglvHMNC.js';
+import '../../rfq-DzsmhXX3.js';
 
 /**
  * Realm backend for React Native.

package/dist/repositories/sqlite/index.d.cts

@@ -1,8 +1,8 @@
 import { SQLExecutor } from '@arkade-os/sdk/repositories/sqlite';
-import { A as AssetSwapRepository, a as AssetSwap, R as RfqSwapRecord, M as MarketsCacheEntry } from '../../repository-C8FXlmHY.cjs';
+import { A as AssetSwapRepository, a as AssetSwap, R as RfqSwapRecord, M as MarketsCacheEntry } from '../../repository-DaK1RzRq.cjs';
 import '@arkade-os/solver-discovery';
 import '@arkade-os/sdk';
-import '../../rfq-DglvHMNC.cjs';
+import '../../rfq-DzsmhXX3.cjs';
 
 /**
  * SQLite backend over the SDK's `SQLExecutor`, so any driver plugs in

package/dist/repositories/sqlite/index.d.ts

@@ -1,8 +1,8 @@
 import { SQLExecutor } from '@arkade-os/sdk/repositories/sqlite';
-import { A as AssetSwapRepository, a as AssetSwap, R as RfqSwapRecord, M as MarketsCacheEntry } from '../../repository-Cw2EvvZG.js';
+import { A as AssetSwapRepository, a as AssetSwap, R as RfqSwapRecord, M as MarketsCacheEntry } from '../../repository-DlLvj_y6.js';
 import '@arkade-os/solver-discovery';
 import '@arkade-os/sdk';
-import '../../rfq-DglvHMNC.js';
+import '../../rfq-DzsmhXX3.js';
 
 /**
  * SQLite backend over the SDK's `SQLExecutor`, so any driver plugs in

package/dist/{repository-C8FXlmHY.d.cts → repository-DaK1RzRq.d.cts}

@@ -1,6 +1,6 @@
 import { DiscoveredMarket } from '@arkade-os/solver-discovery';
 import { IWallet, ProvisionedKey, ProvisionedClaimSecret, RestArkProvider, RestIndexerProvider, VHTLC, Identity, IContractManager } from '@arkade-os/sdk';
-import { x as RfqStatus, y as RfqTransport, a as OnchainHtlc, e as ChainUtxo, C as ChainSource, t as OnchainHtlcPhase } from './rfq-DglvHMNC.cjs';
+import { B as RfqStatus, R as RfqTransport, a as OnchainHtlc, f as ChainUtxo, C as ChainSource, v as OnchainHtlcPhase } from './rfq-DzsmhXX3.cjs';
 
 type AssetSwapStatus = "pending" | "cancelling" | "fulfilled" | "cancelled" | "recoverable" | "awaiting_fill" | "claimable" | "claimed" | "refunded_l1";
 /** The sentinel asset id for BTC itself, as opposed to a 68-hex asset id.
@@ -332,9 +332,11 @@ declare class LockupNeedsRecoveryError extends Error {
  * defensively rather than assumed. It costs the two waiting callers nothing
  * they wanted: `awaitLockupFunding` keeps waiting for a claimable lockup
  * instead of publishing `P` into a spend that cannot land, and
- * `refundIfUnresolved` reports `nothing_to_refund` instead of grinding a doomed
- * push to its deadline. The manager reads the exit through
- * {@link readLockupFate}, which queries unfiltered and reports it as `exited`.
+ * `refundIfUnresolved` reports rather than grinding a doomed push to its
+ * deadline. Both that function and `RfqSwapManager` name the exit through
+ * {@link readLockupFate}, which queries unfiltered and reports it as `exited`;
+ * this drop is the second line, and what still refuses the push on a pass where
+ * the fate read learned nothing.
  *
  * This read — not the RFQ's reported state — is the authority on whether
  * there is anything left at the lockup.
@@ -555,6 +557,21 @@ type RefundOutcome =
     outpoints: string[];
     vtxos: LockupVtxo[];
     status: RfqStatus | null;
+}
+/**
+ * The lockup was unilaterally exited: its outputs sit onchain under the VHTLC
+ * script, where no offchain refund can reach them. Returned rather than
+ * retried: no amount of waiting changes where the money lives. Complete the
+ * unroll and spend the outputs onchain — then there is nothing left to refund.
+ *
+ * Distinct from {@link RefundOutcome} `needs_recovery` on purpose: that
+ * variant's remedy is recovery into a fresh batch, which is a spend no batch
+ * can make for an output that is already onchain.
+ */
+ | {
+    outcome: "exited";
+    outpoints: string[];
+    status: RfqStatus | null;
 };
 /**
  * Ask first, then fall back: watch the swap for the solver to resolve it, and
@@ -583,16 +600,36 @@ type RefundOutcome =
  *   is gone the CLTV refund is not "not yet" but "not this way", so it returns
  *   `needs_recovery` naming the outpoints rather than retrying until the
  *   deadline. Recover them and call again.
+ * - **An exited lockup ends it the same way, and is checked first.** Each pass
+ *   past the deadline asks {@link readLockupFate} before reading what is
+ *   refundable, so an output that has been unilaterally exited returns `exited`
+ *   instead of feeding a push that cannot land. It costs one extra `getVtxos`
+ *   per such pass (three where there were two), plus a `getVirtualTxs` on a
+ *   fully-spent lockup; only the pass that returns `exited` saves the other two.
+ *   Paid to prevent a push that would otherwise be retried to the deadline and
+ *   then rethrown. A failing fate read is swallowed, not raised: it is a
+ *   shortcut, and losing it must not end a wait the ordinary path could answer.
+ *
+ *   A lockup funded in two sends of which only one exited reports `exited` for
+ *   the whole thing and leaves the live half unrefunded. That is deliberate:
+ *   `RfqSwapManager` reports the same lockup `exited` on the same any-output
+ *   rule, and the two must not disagree.
  *
  * Safe to call late, and safe to call again: a caller recovering from a crash
  * well past the deadline skips straight to the push, and a lockup that is
  * already empty comes back as `nothing_to_refund` instead of an error.
  */
-declare function refundIfUnresolved(transport: RfqTransport, ark: RefundArkProvider, indexer: RefundIndexer, input: {
+declare function refundIfUnresolved(transport: RfqTransport, ark: RefundArkProvider, indexer: LockupSpendIndexer, input: {
     rfqId: string;
     script: InstanceType<typeof VHTLC.ScriptV2>;
     /** @see pushRefundWithoutReceiver */
     sender: Identity;
+    /**
+     * `sha256(P)`, hex — the quote's `payment_hash`, as {@link readLockupFate}
+     * takes it. Not derivable from `script`, whose `preimageHash` is a
+     * `hash160` of the same secret.
+     */
+    paymentHash: string;
     /** `refund_locktime` from the quote, unix seconds. */
     refundLocktime: number;
     /** Defaults to the contract's own committed refund destination. */
@@ -792,6 +829,9 @@ interface OnchainSendSwap extends RfqSwapCommon {
     htlc: OnchainHtlc;
     /** `profile.min_confirmations` from the quote. */
     minConfirmations: number;
+    /** Where {@link RfqSwapManagerCallbacks.claimOnchain} pays; optional only
+     * so records predating its profile slot still restore. */
+    payoutPkScript?: Uint8Array;
     /** The fill's outpoint, learned on first sighting. Without it a SPENT
      * HTLC reads as never funded — see {@link classifyOnchainHtlc}. */
     funding?: {

package/dist/{repository-Cw2EvvZG.d.ts → repository-DlLvj_y6.d.ts}

@@ -1,6 +1,6 @@
 import { DiscoveredMarket } from '@arkade-os/solver-discovery';
 import { IWallet, ProvisionedKey, ProvisionedClaimSecret, RestArkProvider, RestIndexerProvider, VHTLC, Identity, IContractManager } from '@arkade-os/sdk';
-import { x as RfqStatus, y as RfqTransport, a as OnchainHtlc, e as ChainUtxo, C as ChainSource, t as OnchainHtlcPhase } from './rfq-DglvHMNC.js';
+import { B as RfqStatus, R as RfqTransport, a as OnchainHtlc, f as ChainUtxo, C as ChainSource, v as OnchainHtlcPhase } from './rfq-DzsmhXX3.js';
 
 type AssetSwapStatus = "pending" | "cancelling" | "fulfilled" | "cancelled" | "recoverable" | "awaiting_fill" | "claimable" | "claimed" | "refunded_l1";
 /** The sentinel asset id for BTC itself, as opposed to a 68-hex asset id.
@@ -332,9 +332,11 @@ declare class LockupNeedsRecoveryError extends Error {
  * defensively rather than assumed. It costs the two waiting callers nothing
  * they wanted: `awaitLockupFunding` keeps waiting for a claimable lockup
  * instead of publishing `P` into a spend that cannot land, and
- * `refundIfUnresolved` reports `nothing_to_refund` instead of grinding a doomed
- * push to its deadline. The manager reads the exit through
- * {@link readLockupFate}, which queries unfiltered and reports it as `exited`.
+ * `refundIfUnresolved` reports rather than grinding a doomed push to its
+ * deadline. Both that function and `RfqSwapManager` name the exit through
+ * {@link readLockupFate}, which queries unfiltered and reports it as `exited`;
+ * this drop is the second line, and what still refuses the push on a pass where
+ * the fate read learned nothing.
  *
  * This read — not the RFQ's reported state — is the authority on whether
  * there is anything left at the lockup.
@@ -555,6 +557,21 @@ type RefundOutcome =
     outpoints: string[];
     vtxos: LockupVtxo[];
     status: RfqStatus | null;
+}
+/**
+ * The lockup was unilaterally exited: its outputs sit onchain under the VHTLC
+ * script, where no offchain refund can reach them. Returned rather than
+ * retried: no amount of waiting changes where the money lives. Complete the
+ * unroll and spend the outputs onchain — then there is nothing left to refund.
+ *
+ * Distinct from {@link RefundOutcome} `needs_recovery` on purpose: that
+ * variant's remedy is recovery into a fresh batch, which is a spend no batch
+ * can make for an output that is already onchain.
+ */
+ | {
+    outcome: "exited";
+    outpoints: string[];
+    status: RfqStatus | null;
 };
 /**
  * Ask first, then fall back: watch the swap for the solver to resolve it, and
@@ -583,16 +600,36 @@ type RefundOutcome =
  *   is gone the CLTV refund is not "not yet" but "not this way", so it returns
  *   `needs_recovery` naming the outpoints rather than retrying until the
  *   deadline. Recover them and call again.
+ * - **An exited lockup ends it the same way, and is checked first.** Each pass
+ *   past the deadline asks {@link readLockupFate} before reading what is
+ *   refundable, so an output that has been unilaterally exited returns `exited`
+ *   instead of feeding a push that cannot land. It costs one extra `getVtxos`
+ *   per such pass (three where there were two), plus a `getVirtualTxs` on a
+ *   fully-spent lockup; only the pass that returns `exited` saves the other two.
+ *   Paid to prevent a push that would otherwise be retried to the deadline and
+ *   then rethrown. A failing fate read is swallowed, not raised: it is a
+ *   shortcut, and losing it must not end a wait the ordinary path could answer.
+ *
+ *   A lockup funded in two sends of which only one exited reports `exited` for
+ *   the whole thing and leaves the live half unrefunded. That is deliberate:
+ *   `RfqSwapManager` reports the same lockup `exited` on the same any-output
+ *   rule, and the two must not disagree.
  *
  * Safe to call late, and safe to call again: a caller recovering from a crash
  * well past the deadline skips straight to the push, and a lockup that is
  * already empty comes back as `nothing_to_refund` instead of an error.
  */
-declare function refundIfUnresolved(transport: RfqTransport, ark: RefundArkProvider, indexer: RefundIndexer, input: {
+declare function refundIfUnresolved(transport: RfqTransport, ark: RefundArkProvider, indexer: LockupSpendIndexer, input: {
     rfqId: string;
     script: InstanceType<typeof VHTLC.ScriptV2>;
     /** @see pushRefundWithoutReceiver */
     sender: Identity;
+    /**
+     * `sha256(P)`, hex — the quote's `payment_hash`, as {@link readLockupFate}
+     * takes it. Not derivable from `script`, whose `preimageHash` is a
+     * `hash160` of the same secret.
+     */
+    paymentHash: string;
     /** `refund_locktime` from the quote, unix seconds. */
     refundLocktime: number;
     /** Defaults to the contract's own committed refund destination. */
@@ -792,6 +829,9 @@ interface OnchainSendSwap extends RfqSwapCommon {
     htlc: OnchainHtlc;
     /** `profile.min_confirmations` from the quote. */
     minConfirmations: number;
+    /** Where {@link RfqSwapManagerCallbacks.claimOnchain} pays; optional only
+     * so records predating its profile slot still restore. */
+    payoutPkScript?: Uint8Array;
     /** The fill's outpoint, learned on first sighting. Without it a SPENT
      * HTLC reads as never funded — see {@link classifyOnchainHtlc}. */
     funding?: {

package/dist/{rfq-DglvHMNC.d.ts → rfq-DzsmhXX3.d.cts}

@@ -1,4 +1,4 @@
-import { VHTLC, asset, IWallet, ProvisionedClaimSecret, ProvisionedKey } from '@arkade-os/sdk';
+import { VHTLC, IWallet, ProvisionedKey, ProvisionedClaimSecret, asset } from '@arkade-os/sdk';
 
 /** L1 confirmation-depth and reorg margin between dependent timelocks. */
 declare const ONCHAIN_ORDER_MARGIN_SECONDS: number;
@@ -46,6 +46,13 @@ declare const newPreimage: () => Uint8Array;
 /** `sha256(P)`, hex — the wire `payment_hash`, same convention as BOLT11. */
 declare const paymentHashOf: (preimage: Uint8Array) => string;
 type OnchainNetwork = "bitcoin" | "testnet" | "regtest";
+/**
+ * The `payoutPkScript` {@link buildHtlcClaim} pays the fill to. Resolved EARLY:
+ * the claim's output is the spender's own choice, so nothing that survives a
+ * send screen names it, and a destination that cannot be encoded must be
+ * refused before the swap is negotiated rather than at claim time.
+ */
+declare const l1ScriptForAddress: (address: string, network: OnchainNetwork) => Uint8Array;
 interface OnchainHtlcParams {
     /** `sha256(P)`, hex; the HASH160 commitment is derived internally. */
     paymentHash: string;
@@ -129,8 +136,9 @@ interface ChainUtxo extends HtlcUtxo {
 interface ChainSource {
     /** Confirmed+mempool outputs paying a script; used to detect the fill. */
     getScriptUtxos(pkScript: Uint8Array): Promise<ChainUtxo[]>;
-    /** The spend of an outpoint, if any — where P is extracted from. */
-    getSpendingTx(txid: string, vout: number): Promise<{
+    /** The spend of an outpoint, if any — where P is extracted from. A
+     * provider omitting the spender txid still lists it in `pkScript`'s history. */
+    getSpendingTx(txid: string, vout: number, pkScript: Uint8Array): Promise<{
         txHex: string;
     } | null>;
     broadcast(txHex: string): Promise<string>;
@@ -255,11 +263,15 @@ declare class SwapRefusal extends Error {
     readonly rfqId: string | undefined;
     constructor(reason: string, rfqId?: string);
 }
-/** The solver's address does not match the local derivation. NEVER fund past this. */
+/**
+ * The solver's address does not match the local derivation. NEVER fund past
+ * this. `derived` is every candidate address tried — more than one when the
+ * derivation itself is ambiguous, see {@link verifyLockupAddress}.
+ */
 declare class AddressMismatch extends Error {
-    readonly derived: string;
+    readonly derived: string | string[];
     readonly quoted: string | undefined;
-    constructor(derived: string, quoted?: string);
+    constructor(derived: string | string[], quoted?: string);
 }
 /** A fresh client-chosen negotiation id: 32 random bytes, lowercase hex. */
 declare const newRfqId: () => string;
@@ -323,9 +335,24 @@ declare const arkadeSwapRequest: (input: {
  * 90 because the refund CLTV matures against median-time-past (BIP-113),
  * which lags wall clock by ~1h — a smaller wall-clock margin is no margin. */
 declare const MIN_HEADROOM_SECONDS: number;
-/** Compare-only check of the solver's address against YOUR derivation.
- * Throws {@link AddressMismatch}; returns the address so calls chain. */
-declare const verifyLockupAddress: (quote: RfqQuote, derivedAddress: string) => string;
+/**
+ * Compare-only check of the solver's address against YOUR OWN derivation(s)
+ * — never extends trust, only narrows it.
+ *
+ * `derivedAddress` may be a single address or an array of candidates. Pass an
+ * array when your own derivation is ambiguous — as it is for the covenant
+ * lockups while solvers roll out the timelocked non-interactive refund leaf:
+ * nothing on the wire says whether a given quote's covenant carries it (the
+ * shape is fixed by the solver's own build, not negotiated per quote), so the
+ * only safe move is to derive BOTH shapes and accept whichever one the quote's
+ * own `lockup_address` matches. This loses no security: every candidate shape
+ * pins the refund to the trader's own refund destination, so a solver gains
+ * nothing by choosing which one to quote.
+ *
+ * Throws {@link AddressMismatch} only when NONE of the candidates match.
+ * Returns the address that matched, so calls chain exactly as before.
+ */
+declare const verifyLockupAddress: (quote: RfqQuote, derivedAddress: string | string[]) => string;
 /** The user's gates, checked immediately before funding — never at quote
  * time. Throws with a stable `reason` property. `invoiceExpiresAt` applies to
  * BOLT11 profiles only; `onchain` adds the L1-HTLC gates (§ guardrails of the
@@ -348,6 +375,25 @@ declare const assertFundable: (input: {
         /** "send" = arkade->onchain (the L1 timelock-order gate applies). */
         direction: "send" | "receive";
     };
+    /**
+     * The most this client will pay: the GREATER of the two bounds, because a
+     * flat fee is a large proportion of a small swap (420 sats is 8.4% of
+     * 5_000, 0.084% of 500_000). Absent means no ceiling. OMIT a bound rather
+     * than zeroing it: `{ bps: 0 }` alone is a ceiling of zero, indistinguishable
+     * from "free or nothing". `{}` IS refused.
+     */
+    maxFee?: {
+        /** Integer, 0..10_000 (10_000 = 100%). Out of range throws `max_fee_out_of_range`. */
+        bps?: number;
+        /** Non-negative integer. Out of range throws `max_fee_out_of_range`. */
+        sats?: number;
+        /**
+         * To-units per from-unit, required for a CROSS-ASSET pair. Must come
+         * from a source of YOUR OWN — the solver's own feed would check it
+         * against its own number. Needs a looser tolerance than same-asset.
+         */
+        referenceRate?: number;
+    };
 }) => void;
 interface RfqTransport {
     requestQuote(payload: Record<string, unknown>): Promise<RfqQuote>;
@@ -413,15 +459,17 @@ declare const unilateralRefundWithoutReceiverDelay: (claimDelay: number) => numb
  * hex); the script's HASH160 commitment is derived from it here, which is why
  * the trader never needs to see `P`.
  *
- * Every quote gets the full eight-leaf contract: VHTLC's own six
+ * Every quote gets the full emulator-covenant suite on top of VHTLC's own six
  * (`claim`/`refund`/`refundWithoutReceiver`/`unilateralClaim`/
- * `unilateralRefund`/`unilateralRefundWithoutReceiver`), plus two more the
- * emulator co-signs under a covenant pinning the payout to a pre-committed
- * destination — `nonInteractiveClaim` (server + emulator, pays the solver's
- * own `receiverPkScript`, no solver signature needed) and
- * `nonInteractiveRefund` (server + solver + emulator, pays the trader's own
- * `refundPkScript`, no timelock and no trader signature needed — see {@link
- * VHTLC.Options.nonInteractiveRefund}'s doc comment for why that matters).
+ * `unilateralRefund`/`unilateralRefundWithoutReceiver`): `nonInteractiveClaim`
+ * (server + emulator, pays the solver's own `receiverPkScript`, no solver
+ * signature needed), `nonInteractiveRefund` (server + solver + emulator, pays
+ * the trader's own `refundPkScript`, no timelock and no trader signature
+ * needed — see {@link VHTLC.Options.nonInteractiveParameters}'s doc comment for why
+ * that matters), and its timelocked twin `nonInteractiveRefundWithoutReceiver`
+ * (server + emulator alone, after `refundLocktime` — the only refund tier
+ * needing no participant at all). Nine leaves in all, unless `legacy` says
+ * otherwise.
  */
 declare function lightningSendVtxoScript(params: {
     /** Binding field #1: the solver's x-only key, from the quote. */
@@ -439,7 +487,7 @@ declare function lightningSendVtxoScript(params: {
     /** Emulator x-only key (32 bytes). */
     emulatorPubkey: Uint8Array;
     /** Where a refund must pay: the trader's P2TR pkScript (34 bytes). Also
-     * `nonInteractiveRefund`'s covenant destination. */
+     * the refund covenants' destination. */
     refundPkScript: Uint8Array;
     /** The trader's own key — VHTLC's `sender` role. Required on every
      * interactive refund-side leaf; the trader generates and persists it
@@ -450,6 +498,11 @@ declare function lightningSendVtxoScript(params: {
      * covenant key can be derived; the trader does not otherwise use or trust
      * this value. P2TR pkScript, 34 bytes. */
     receiverPkScript: Uint8Array;
+    /** LEGACY REBUILD ONLY — see {@link VHTLC.Options.nonInteractiveParameters}'s
+     * `legacy` field. Set only to re-derive a lockup funded before the
+     * timelocked refund leaf shipped; {@link matchQuotedLockup} passes it when
+     * the quote's own address says the solver quoted that shape. */
+    legacy?: "preTimelockedRefund";
 }): InstanceType<typeof VHTLC.ScriptV2>;
 /** Every input {@link lightningSendVtxoScript} builds from. Derived from the
  * builder rather than restated, so the two cannot drift. */
@@ -786,7 +839,7 @@ declare const assertReceivable: (input: {
     /** Absolute sats ceiling on `from_amount`. */
     maxPayAmount?: number;
 }) => void;
-/** Compile the RECEIVE-direction VHTLC: the same eight-leaf tree as {@link
+/** Compile the RECEIVE-direction VHTLC: the same suite-carrying tree as {@link
  * lightningSendVtxoScript} with the roles inverted — the trader is the
  * `receiver` (it generated `P` and claims the lockup with it), the solver is
  * the `sender` (it funds the lockup and holds the refund recourse). One
@@ -817,6 +870,8 @@ declare function receiveVtxoScript(params: {
     /** The trader's own Arkade payout pkScript (decoded from its payout
      * address) — `nonInteractiveClaim`'s pinned destination. */
     payoutPkScript: Uint8Array;
+    /** LEGACY REBUILD ONLY — see {@link lightningSendVtxoScript}'s `legacy`. */
+    legacy?: "preTimelockedRefund";
 }): InstanceType<typeof VHTLC.ScriptV2>;
 /** Every input {@link receiveVtxoScript} builds from; see
  * {@link LightningSendTreeParams}. */
@@ -1002,4 +1057,4 @@ declare function requestOnchainReceive(wallet: IWallet, arkServerUrl: string, tr
     secrets: ProvisionedClaimSecret;
 }>;
 
-export { newRfqId as $, ARKADE_ASSET as A, arkadeAssetLeg as B, type ChainSource as C, arkadeSwapRequest as D, assertFundable as E, assertReceivable as F, awaitOnchainFill as G, type HtlcUtxo as H, type InvoiceFacts as I, buildHtlcClaim as J, buildHtlcRefund as K, LIGHTNING_BTC as L, MAX_MIN_CONFIRMATIONS as M, claimOnchainFill as N, type OnchainNetwork as O, classifyOnchainHtlc as P, deriveLightningReceive as Q, RFQ_TERMINAL_STATES as R, SOLO_REFUND_HEADROOM_SECONDS as S, deriveOnchainReceive as T, deriveOnchainSend as U, extractPreimage as V, httpTransport as W, lightningReceiveRequest as X, lightningSendRequest as Y, lightningSendVtxoScript as Z, newPreimage as _, type OnchainHtlc as a, offerTermsFromQuote as a0, onchainHtlcScript as a1, onchainReceiveRequest as a2, onchainSendRequest as a3, paymentHashOf as a4, receiveVtxoScript as a5, relayTransport as a6, requestLightningReceive as a7, requestLightningSend as a8, requestOnchainReceive as a9, requestOnchainSend as aa, rfqPair as ab, unilateralClaimDelay as ac, unilateralRefundDelay as ad, unilateralRefundWithoutReceiverDelay as ae, verifyLockupAddress as af, verifyReceiveInvoice as ag, type OnchainHtlcParams as b, ARKADE_BTC as c, AddressMismatch as d, type ChainUtxo as e, LIGHTNING_RECEIVE_PAIR as f, LIGHTNING_SEND_PAIR as g, LOCKTIME_THRESHOLD as h, type LightningReceiveTreeParams as i, type LightningSendTreeParams as j, MIN_CLAIM_WINDOW_SECONDS as k, MIN_HEADROOM_SECONDS as l, ONCHAIN_BTC as m, ONCHAIN_CLAIM_MARGIN_SECONDS as n, ONCHAIN_DUST_SATS as o, ONCHAIN_ORDER_MARGIN_SECONDS as p, ONCHAIN_RECEIVE_PAIR as q, ONCHAIN_SECONDS_PER_BLOCK as r, ONCHAIN_SEND_PAIR as s, type OnchainHtlcPhase as t, type RelaySocket as u, type RfqQuote as v, type RfqRefusalReason as w, type RfqStatus as x, type RfqTransport as y, SwapRefusal as z };
+export { lightningSendRequest as $, ARKADE_ASSET as A, type RfqStatus as B, type ChainSource as C, SwapRefusal as D, arkadeAssetLeg as E, arkadeSwapRequest as F, assertFundable as G, type HtlcUtxo as H, type InvoiceFacts as I, assertReceivable as J, awaitOnchainFill as K, LIGHTNING_BTC as L, MAX_MIN_CONFIRMATIONS as M, buildHtlcClaim as N, type OnchainNetwork as O, buildHtlcRefund as P, claimOnchainFill as Q, type RfqTransport as R, SOLO_REFUND_HEADROOM_SECONDS as S, classifyOnchainHtlc as T, deriveLightningReceive as U, deriveOnchainReceive as V, deriveOnchainSend as W, extractPreimage as X, httpTransport as Y, l1ScriptForAddress as Z, lightningReceiveRequest as _, type OnchainHtlc as a, lightningSendVtxoScript as a0, newPreimage as a1, newRfqId as a2, offerTermsFromQuote as a3, onchainHtlcScript as a4, onchainReceiveRequest as a5, onchainSendRequest as a6, paymentHashOf as a7, receiveVtxoScript as a8, relayTransport as a9, requestLightningReceive as aa, requestOnchainReceive as ab, rfqPair as ac, unilateralClaimDelay as ad, unilateralRefundDelay as ae, unilateralRefundWithoutReceiverDelay as af, verifyLockupAddress as ag, verifyReceiveInvoice as ah, type OnchainHtlcParams as b, requestLightningSend as c, ARKADE_BTC as d, AddressMismatch as e, type ChainUtxo as f, LIGHTNING_RECEIVE_PAIR as g, LIGHTNING_SEND_PAIR as h, LOCKTIME_THRESHOLD as i, type LightningReceiveTreeParams as j, type LightningSendTreeParams as k, MIN_CLAIM_WINDOW_SECONDS as l, MIN_HEADROOM_SECONDS as m, ONCHAIN_BTC as n, ONCHAIN_CLAIM_MARGIN_SECONDS as o, ONCHAIN_DUST_SATS as p, ONCHAIN_ORDER_MARGIN_SECONDS as q, requestOnchainSend as r, ONCHAIN_RECEIVE_PAIR as s, ONCHAIN_SECONDS_PER_BLOCK as t, ONCHAIN_SEND_PAIR as u, type OnchainHtlcPhase as v, RFQ_TERMINAL_STATES as w, type RelaySocket as x, type RfqQuote as y, type RfqRefusalReason as z };

package/dist/{rfq-DglvHMNC.d.cts → rfq-DzsmhXX3.d.ts}

@@ -1,4 +1,4 @@
-import { VHTLC, asset, IWallet, ProvisionedClaimSecret, ProvisionedKey } from '@arkade-os/sdk';
+import { VHTLC, IWallet, ProvisionedKey, ProvisionedClaimSecret, asset } from '@arkade-os/sdk';
 
 /** L1 confirmation-depth and reorg margin between dependent timelocks. */
 declare const ONCHAIN_ORDER_MARGIN_SECONDS: number;
@@ -46,6 +46,13 @@ declare const newPreimage: () => Uint8Array;
 /** `sha256(P)`, hex — the wire `payment_hash`, same convention as BOLT11. */
 declare const paymentHashOf: (preimage: Uint8Array) => string;
 type OnchainNetwork = "bitcoin" | "testnet" | "regtest";
+/**
+ * The `payoutPkScript` {@link buildHtlcClaim} pays the fill to. Resolved EARLY:
+ * the claim's output is the spender's own choice, so nothing that survives a
+ * send screen names it, and a destination that cannot be encoded must be
+ * refused before the swap is negotiated rather than at claim time.
+ */
+declare const l1ScriptForAddress: (address: string, network: OnchainNetwork) => Uint8Array;
 interface OnchainHtlcParams {
     /** `sha256(P)`, hex; the HASH160 commitment is derived internally. */
     paymentHash: string;
@@ -129,8 +136,9 @@ interface ChainUtxo extends HtlcUtxo {
 interface ChainSource {
     /** Confirmed+mempool outputs paying a script; used to detect the fill. */
     getScriptUtxos(pkScript: Uint8Array): Promise<ChainUtxo[]>;
-    /** The spend of an outpoint, if any — where P is extracted from. */
-    getSpendingTx(txid: string, vout: number): Promise<{
+    /** The spend of an outpoint, if any — where P is extracted from. A
+     * provider omitting the spender txid still lists it in `pkScript`'s history. */
+    getSpendingTx(txid: string, vout: number, pkScript: Uint8Array): Promise<{
         txHex: string;
     } | null>;
     broadcast(txHex: string): Promise<string>;
@@ -255,11 +263,15 @@ declare class SwapRefusal extends Error {
     readonly rfqId: string | undefined;
     constructor(reason: string, rfqId?: string);
 }
-/** The solver's address does not match the local derivation. NEVER fund past this. */
+/**
+ * The solver's address does not match the local derivation. NEVER fund past
+ * this. `derived` is every candidate address tried — more than one when the
+ * derivation itself is ambiguous, see {@link verifyLockupAddress}.
+ */
 declare class AddressMismatch extends Error {
-    readonly derived: string;
+    readonly derived: string | string[];
     readonly quoted: string | undefined;
-    constructor(derived: string, quoted?: string);
+    constructor(derived: string | string[], quoted?: string);
 }
 /** A fresh client-chosen negotiation id: 32 random bytes, lowercase hex. */
 declare const newRfqId: () => string;
@@ -323,9 +335,24 @@ declare const arkadeSwapRequest: (input: {
  * 90 because the refund CLTV matures against median-time-past (BIP-113),
  * which lags wall clock by ~1h — a smaller wall-clock margin is no margin. */
 declare const MIN_HEADROOM_SECONDS: number;
-/** Compare-only check of the solver's address against YOUR derivation.
- * Throws {@link AddressMismatch}; returns the address so calls chain. */
-declare const verifyLockupAddress: (quote: RfqQuote, derivedAddress: string) => string;
+/**
+ * Compare-only check of the solver's address against YOUR OWN derivation(s)
+ * — never extends trust, only narrows it.
+ *
+ * `derivedAddress` may be a single address or an array of candidates. Pass an
+ * array when your own derivation is ambiguous — as it is for the covenant
+ * lockups while solvers roll out the timelocked non-interactive refund leaf:
+ * nothing on the wire says whether a given quote's covenant carries it (the
+ * shape is fixed by the solver's own build, not negotiated per quote), so the
+ * only safe move is to derive BOTH shapes and accept whichever one the quote's
+ * own `lockup_address` matches. This loses no security: every candidate shape
+ * pins the refund to the trader's own refund destination, so a solver gains
+ * nothing by choosing which one to quote.
+ *
+ * Throws {@link AddressMismatch} only when NONE of the candidates match.
+ * Returns the address that matched, so calls chain exactly as before.
+ */
+declare const verifyLockupAddress: (quote: RfqQuote, derivedAddress: string | string[]) => string;
 /** The user's gates, checked immediately before funding — never at quote
  * time. Throws with a stable `reason` property. `invoiceExpiresAt` applies to
  * BOLT11 profiles only; `onchain` adds the L1-HTLC gates (§ guardrails of the
@@ -348,6 +375,25 @@ declare const assertFundable: (input: {
         /** "send" = arkade->onchain (the L1 timelock-order gate applies). */
         direction: "send" | "receive";
     };
+    /**
+     * The most this client will pay: the GREATER of the two bounds, because a
+     * flat fee is a large proportion of a small swap (420 sats is 8.4% of
+     * 5_000, 0.084% of 500_000). Absent means no ceiling. OMIT a bound rather
+     * than zeroing it: `{ bps: 0 }` alone is a ceiling of zero, indistinguishable
+     * from "free or nothing". `{}` IS refused.
+     */
+    maxFee?: {
+        /** Integer, 0..10_000 (10_000 = 100%). Out of range throws `max_fee_out_of_range`. */
+        bps?: number;
+        /** Non-negative integer. Out of range throws `max_fee_out_of_range`. */
+        sats?: number;
+        /**
+         * To-units per from-unit, required for a CROSS-ASSET pair. Must come
+         * from a source of YOUR OWN — the solver's own feed would check it
+         * against its own number. Needs a looser tolerance than same-asset.
+         */
+        referenceRate?: number;
+    };
 }) => void;
 interface RfqTransport {
     requestQuote(payload: Record<string, unknown>): Promise<RfqQuote>;
@@ -413,15 +459,17 @@ declare const unilateralRefundWithoutReceiverDelay: (claimDelay: number) => numb
  * hex); the script's HASH160 commitment is derived from it here, which is why
  * the trader never needs to see `P`.
  *
- * Every quote gets the full eight-leaf contract: VHTLC's own six
+ * Every quote gets the full emulator-covenant suite on top of VHTLC's own six
  * (`claim`/`refund`/`refundWithoutReceiver`/`unilateralClaim`/
- * `unilateralRefund`/`unilateralRefundWithoutReceiver`), plus two more the
- * emulator co-signs under a covenant pinning the payout to a pre-committed
- * destination — `nonInteractiveClaim` (server + emulator, pays the solver's
- * own `receiverPkScript`, no solver signature needed) and
- * `nonInteractiveRefund` (server + solver + emulator, pays the trader's own
- * `refundPkScript`, no timelock and no trader signature needed — see {@link
- * VHTLC.Options.nonInteractiveRefund}'s doc comment for why that matters).
+ * `unilateralRefund`/`unilateralRefundWithoutReceiver`): `nonInteractiveClaim`
+ * (server + emulator, pays the solver's own `receiverPkScript`, no solver
+ * signature needed), `nonInteractiveRefund` (server + solver + emulator, pays
+ * the trader's own `refundPkScript`, no timelock and no trader signature
+ * needed — see {@link VHTLC.Options.nonInteractiveParameters}'s doc comment for why
+ * that matters), and its timelocked twin `nonInteractiveRefundWithoutReceiver`
+ * (server + emulator alone, after `refundLocktime` — the only refund tier
+ * needing no participant at all). Nine leaves in all, unless `legacy` says
+ * otherwise.
  */
 declare function lightningSendVtxoScript(params: {
     /** Binding field #1: the solver's x-only key, from the quote. */
@@ -439,7 +487,7 @@ declare function lightningSendVtxoScript(params: {
     /** Emulator x-only key (32 bytes). */
     emulatorPubkey: Uint8Array;
     /** Where a refund must pay: the trader's P2TR pkScript (34 bytes). Also
-     * `nonInteractiveRefund`'s covenant destination. */
+     * the refund covenants' destination. */
     refundPkScript: Uint8Array;
     /** The trader's own key — VHTLC's `sender` role. Required on every
      * interactive refund-side leaf; the trader generates and persists it
@@ -450,6 +498,11 @@ declare function lightningSendVtxoScript(params: {
      * covenant key can be derived; the trader does not otherwise use or trust
      * this value. P2TR pkScript, 34 bytes. */
     receiverPkScript: Uint8Array;
+    /** LEGACY REBUILD ONLY — see {@link VHTLC.Options.nonInteractiveParameters}'s
+     * `legacy` field. Set only to re-derive a lockup funded before the
+     * timelocked refund leaf shipped; {@link matchQuotedLockup} passes it when
+     * the quote's own address says the solver quoted that shape. */
+    legacy?: "preTimelockedRefund";
 }): InstanceType<typeof VHTLC.ScriptV2>;
 /** Every input {@link lightningSendVtxoScript} builds from. Derived from the
  * builder rather than restated, so the two cannot drift. */
@@ -786,7 +839,7 @@ declare const assertReceivable: (input: {
     /** Absolute sats ceiling on `from_amount`. */
     maxPayAmount?: number;
 }) => void;
-/** Compile the RECEIVE-direction VHTLC: the same eight-leaf tree as {@link
+/** Compile the RECEIVE-direction VHTLC: the same suite-carrying tree as {@link
  * lightningSendVtxoScript} with the roles inverted — the trader is the
  * `receiver` (it generated `P` and claims the lockup with it), the solver is
  * the `sender` (it funds the lockup and holds the refund recourse). One
@@ -817,6 +870,8 @@ declare function receiveVtxoScript(params: {
     /** The trader's own Arkade payout pkScript (decoded from its payout
      * address) — `nonInteractiveClaim`'s pinned destination. */
     payoutPkScript: Uint8Array;
+    /** LEGACY REBUILD ONLY — see {@link lightningSendVtxoScript}'s `legacy`. */
+    legacy?: "preTimelockedRefund";
 }): InstanceType<typeof VHTLC.ScriptV2>;
 /** Every input {@link receiveVtxoScript} builds from; see
  * {@link LightningSendTreeParams}. */
@@ -1002,4 +1057,4 @@ declare function requestOnchainReceive(wallet: IWallet, arkServerUrl: string, tr
     secrets: ProvisionedClaimSecret;
 }>;
 
-export { newRfqId as $, ARKADE_ASSET as A, arkadeAssetLeg as B, type ChainSource as C, arkadeSwapRequest as D, assertFundable as E, assertReceivable as F, awaitOnchainFill as G, type HtlcUtxo as H, type InvoiceFacts as I, buildHtlcClaim as J, buildHtlcRefund as K, LIGHTNING_BTC as L, MAX_MIN_CONFIRMATIONS as M, claimOnchainFill as N, type OnchainNetwork as O, classifyOnchainHtlc as P, deriveLightningReceive as Q, RFQ_TERMINAL_STATES as R, SOLO_REFUND_HEADROOM_SECONDS as S, deriveOnchainReceive as T, deriveOnchainSend as U, extractPreimage as V, httpTransport as W, lightningReceiveRequest as X, lightningSendRequest as Y, lightningSendVtxoScript as Z, newPreimage as _, type OnchainHtlc as a, offerTermsFromQuote as a0, onchainHtlcScript as a1, onchainReceiveRequest as a2, onchainSendRequest as a3, paymentHashOf as a4, receiveVtxoScript as a5, relayTransport as a6, requestLightningReceive as a7, requestLightningSend as a8, requestOnchainReceive as a9, requestOnchainSend as aa, rfqPair as ab, unilateralClaimDelay as ac, unilateralRefundDelay as ad, unilateralRefundWithoutReceiverDelay as ae, verifyLockupAddress as af, verifyReceiveInvoice as ag, type OnchainHtlcParams as b, ARKADE_BTC as c, AddressMismatch as d, type ChainUtxo as e, LIGHTNING_RECEIVE_PAIR as f, LIGHTNING_SEND_PAIR as g, LOCKTIME_THRESHOLD as h, type LightningReceiveTreeParams as i, type LightningSendTreeParams as j, MIN_CLAIM_WINDOW_SECONDS as k, MIN_HEADROOM_SECONDS as l, ONCHAIN_BTC as m, ONCHAIN_CLAIM_MARGIN_SECONDS as n, ONCHAIN_DUST_SATS as o, ONCHAIN_ORDER_MARGIN_SECONDS as p, ONCHAIN_RECEIVE_PAIR as q, ONCHAIN_SECONDS_PER_BLOCK as r, ONCHAIN_SEND_PAIR as s, type OnchainHtlcPhase as t, type RelaySocket as u, type RfqQuote as v, type RfqRefusalReason as w, type RfqStatus as x, type RfqTransport as y, SwapRefusal as z };
+export { lightningSendRequest as $, ARKADE_ASSET as A, type RfqStatus as B, type ChainSource as C, SwapRefusal as D, arkadeAssetLeg as E, arkadeSwapRequest as F, assertFundable as G, type HtlcUtxo as H, type InvoiceFacts as I, assertReceivable as J, awaitOnchainFill as K, LIGHTNING_BTC as L, MAX_MIN_CONFIRMATIONS as M, buildHtlcClaim as N, type OnchainNetwork as O, buildHtlcRefund as P, claimOnchainFill as Q, type RfqTransport as R, SOLO_REFUND_HEADROOM_SECONDS as S, classifyOnchainHtlc as T, deriveLightningReceive as U, deriveOnchainReceive as V, deriveOnchainSend as W, extractPreimage as X, httpTransport as Y, l1ScriptForAddress as Z, lightningReceiveRequest as _, type OnchainHtlc as a, lightningSendVtxoScript as a0, newPreimage as a1, newRfqId as a2, offerTermsFromQuote as a3, onchainHtlcScript as a4, onchainReceiveRequest as a5, onchainSendRequest as a6, paymentHashOf as a7, receiveVtxoScript as a8, relayTransport as a9, requestLightningReceive as aa, requestOnchainReceive as ab, rfqPair as ac, unilateralClaimDelay as ad, unilateralRefundDelay as ae, unilateralRefundWithoutReceiverDelay as af, verifyLockupAddress as ag, verifyReceiveInvoice as ah, type OnchainHtlcParams as b, requestLightningSend as c, ARKADE_BTC as d, AddressMismatch as e, type ChainUtxo as f, LIGHTNING_RECEIVE_PAIR as g, LIGHTNING_SEND_PAIR as h, LOCKTIME_THRESHOLD as i, type LightningReceiveTreeParams as j, type LightningSendTreeParams as k, MIN_CLAIM_WINDOW_SECONDS as l, MIN_HEADROOM_SECONDS as m, ONCHAIN_BTC as n, ONCHAIN_CLAIM_MARGIN_SECONDS as o, ONCHAIN_DUST_SATS as p, ONCHAIN_ORDER_MARGIN_SECONDS as q, requestOnchainSend as r, ONCHAIN_RECEIVE_PAIR as s, ONCHAIN_SECONDS_PER_BLOCK as t, ONCHAIN_SEND_PAIR as u, type OnchainHtlcPhase as v, RFQ_TERMINAL_STATES as w, type RelaySocket as x, type RfqQuote as y, type RfqRefusalReason as z };