@arkade-os/swap 0.0.10 → 0.0.11

package/dist/{repository-C8FXlmHY.d.cts → repository-B02vsgcV.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 { x as RfqStatus, y as RfqTransport, a as OnchainHtlc, e as ChainUtxo, C as ChainSource, t as OnchainHtlcPhase } from './rfq-DkckzRKK.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. */

package/dist/{repository-Cw2EvvZG.d.ts → repository-CfE18Fif.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 { x as RfqStatus, y as RfqTransport, a as OnchainHtlc, e as ChainUtxo, C as ChainSource, t as OnchainHtlcPhase } from './rfq-DkckzRKK.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. */

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

@@ -255,11 +255,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 +327,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
@@ -413,15 +432,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 +460,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 +471,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 +812,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 +843,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}. */

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

@@ -255,11 +255,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 +327,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
@@ -413,15 +432,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 +460,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 +471,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 +812,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 +843,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}. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arkade-os/swap",
-  "version": "0.0.10",
+  "version": "0.0.11",
   "type": "module",
   "description": "Client-side Arkade Intents asset swaps: discover markets, quote, create/track/cancel offers, restore from chain.",
   "repository": {
@@ -70,7 +70,7 @@
     "@noble/hashes": "2.0.1",
     "@scure/base": "2.0.0",
     "@scure/btc-signer": "2.0.1",
-    "@arkade-os/sdk": "0.4.67"
+    "@arkade-os/sdk": "0.4.68"
   },
   "peerDependencies": {
     "nostr-tools": "^2.12.0"