@arkade-os/swap 0.0.9 → 0.0.11

package/dist/{repository-DEHLtD9l.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-hbzhTWHT.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.
@@ -227,12 +227,15 @@ interface LockupVtxo {
      * It is still the trader's money and it is still visible, which is why
      * {@link findLockupVtxos} returns it. What it is not is refundable by
      * {@link pushRefundWithoutReceiver}: that builds an offchain Ark
-     * transaction, and the SDK's own predicates make the two states mutually
-     * exclusive — `canSpendOffchain` is false exactly when `canRecoverOnchain`
-     * is true (`wallet/vtxo.ts`), and the latter is documented as "must be
-     * recovered into a fresh batch rather than spent offchain". Holding the
-     * trader's `sender` key does not change that; a sweep removes the leaf from
-     * the live tree, not the signature from the trader.
+     * transaction, and the SDK's own predicates put the two states on opposite
+     * sides — `canSpendOffchain` is false whenever `canRecoverOnchain` is true
+     * (`wallet/vtxo.ts`), and the latter is documented as "must be recovered
+     * into a fresh batch rather than spent offchain". Holding the trader's
+     * `sender` key does not change that; a sweep removes the leaf from the live
+     * tree, not the signature from the trader.
+     *
+     * Opposite, but not exhaustive: an unrolled output satisfies neither, and
+     * {@link findLockupVtxos} drops those before they reach this type at all.
      *
      * `packages/boltz-swap` splits on exactly this fact rather than working
      * around it: `settleRefundWithoutReceiver` sends a live VTXO through an
@@ -321,6 +324,20 @@ declare class LockupNeedsRecoveryError extends Error {
  * That function refuses the recoverable ones by name rather than submitting a
  * spend the server must reject.
  *
+ * **Unrolled outputs are the one exception, and are dropped.** A unilaterally
+ * exited output lives onchain behind its CSV; no offchain spend of any leaf can
+ * reach it, and `LockupVtxo` carries no field to say so, so a caller could not
+ * tell it apart from a live one. Whether arkd returns such an output under
+ * `spendableOnly` is not determinable from here, so the exclusion is made
+ * 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 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.
  *
@@ -374,6 +391,29 @@ type LockupFate =
     fate: "returned";
     spends: readonly LockupSpend[];
 }
+/**
+ * At least one output was unilaterally exited: it sits onchain under the
+ * VHTLC script, where no offchain claim or refund can reach it.
+ *
+ * Not terminal, and not a loss. The money is still under the same script
+ * with the same leaves, so `completeUnroll` plus an onchain spend can still
+ * end the swap either way — which is why this outranks `open`: an output
+ * that is "still unspent" but unreachable is not a swap that is merely
+ * running.
+ *
+ * It outranks a verdict too, on a lockup where a sibling output was claimed
+ * or returned. That is the rule `open` already sets, not a new one: the
+ * unspent test short-circuits before any witness is read, so a partially
+ * resolved lockup has never reported `claimed`/`returned`. What changes is
+ * only that such a lockup now says why it is unresolved.
+ */
+ | {
+    fate: "exited";
+    outpoints: readonly {
+        txid: string;
+        vout: number;
+    }[];
+}
 /** Nothing was learned: no outputs visible, an output spent by nothing the
  * indexer names, a spend it could not produce, or a blob that would not
  * decode. Never an answer. */
@@ -409,6 +449,11 @@ type LockupFate =
  * response to `unknown` is the same as to `open`: keep watching, and let the
  * refund timelock — which no outage can move — be what ends the wait.
  *
+ * **An exit is read before anything else, and over the whole set.** It is the
+ * one fact that makes an unspent output unreachable, so it outranks `open`; and
+ * it is scanned across every output rather than in outpoint order, so which
+ * output happens to come first cannot change the answer.
+ *
  * Ask-the-indexer, don't-trust-local-state: read fresh on every poll, never
  * cached, the same posture {@link findLockupVtxos} already establishes.
  */
@@ -447,9 +492,9 @@ declare function readLockupFate(indexer: LockupSpendIndexer, input: {
  * {@link refundIfUnresolved}, which retries.
  *
  * **Swept outputs are refused, not attempted.** This is an OFFCHAIN spend, and
- * a swept output is no longer a live leaf: `canSpendOffchain` and
- * `canRecoverOnchain` are mutually exclusive by construction, so a recoverable
- * input cannot be spent this way whatever key signs it (see
+ * a swept output is no longer a live leaf: `canSpendOffchain` is false wherever
+ * `canRecoverOnchain` is true, so a recoverable input cannot be spent this way
+ * whatever key signs it (see
  * {@link LockupVtxo.recoverable}). Because every input lands in ONE aggregate
  * transaction, a single swept output would take the live ones down with it —
  * so the whole push is refused with {@link LockupNeedsRecoveryError} naming the
@@ -512,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
@@ -540,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. */
@@ -1162,7 +1242,9 @@ interface RfqSwapManagerDeps {
  *    `settled`; a lockup fully spent by anything else ends it `refunded`.
  *    Anything the indexer could not answer is `unknown`, which is NOT an
  *    answer: the pass carries on to the steps below, whose deadlines an indexer
- *    outage has no bearing on.
+ *    outage has no bearing on. `exited` — an output unilaterally taken onchain
+ *    — ends neither the swap nor the pass: it blocks the Arkade half below,
+ *    with the L1 half left running.
  * 2. **Drive the trader's claim.** On an onchain send that is the L1 fill — see
  *    {@link nextOnchainAction}. On a receive it is the lockup itself, and it
  *    ends the pass: that leg has no step 3.
@@ -1493,6 +1575,18 @@ declare class RfqSwapManager {
     private arm;
     private pollSwap;
     private runPass;
+    /**
+     * The lockup was unilaterally exited: its outputs sit onchain under the
+     * VHTLC script, where no offchain claim or refund can reach them.
+     *
+     * `needs_counterparty` rather than a terminal state, because the money still
+     * needs action and the swap can still end either way — an onchain claim can
+     * reveal the preimage, an onchain refund can return it — and that state is
+     * documented as re-checked every pass. It must be set from HERE and not from
+     * inside `driveArkadeRefund`, whose two `unblock` calls would lift it again
+     * on the very next pass.
+     */
+    private blockExitedLockup;
     /**
      * The receive leg's whole state machine: claim the solver-funded lockup
      * while the window is open, and recognise the shapes in which it can be

package/dist/{repository-DIAr5XYk.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-hbzhTWHT.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.
@@ -227,12 +227,15 @@ interface LockupVtxo {
      * It is still the trader's money and it is still visible, which is why
      * {@link findLockupVtxos} returns it. What it is not is refundable by
      * {@link pushRefundWithoutReceiver}: that builds an offchain Ark
-     * transaction, and the SDK's own predicates make the two states mutually
-     * exclusive — `canSpendOffchain` is false exactly when `canRecoverOnchain`
-     * is true (`wallet/vtxo.ts`), and the latter is documented as "must be
-     * recovered into a fresh batch rather than spent offchain". Holding the
-     * trader's `sender` key does not change that; a sweep removes the leaf from
-     * the live tree, not the signature from the trader.
+     * transaction, and the SDK's own predicates put the two states on opposite
+     * sides — `canSpendOffchain` is false whenever `canRecoverOnchain` is true
+     * (`wallet/vtxo.ts`), and the latter is documented as "must be recovered
+     * into a fresh batch rather than spent offchain". Holding the trader's
+     * `sender` key does not change that; a sweep removes the leaf from the live
+     * tree, not the signature from the trader.
+     *
+     * Opposite, but not exhaustive: an unrolled output satisfies neither, and
+     * {@link findLockupVtxos} drops those before they reach this type at all.
      *
      * `packages/boltz-swap` splits on exactly this fact rather than working
      * around it: `settleRefundWithoutReceiver` sends a live VTXO through an
@@ -321,6 +324,20 @@ declare class LockupNeedsRecoveryError extends Error {
  * That function refuses the recoverable ones by name rather than submitting a
  * spend the server must reject.
  *
+ * **Unrolled outputs are the one exception, and are dropped.** A unilaterally
+ * exited output lives onchain behind its CSV; no offchain spend of any leaf can
+ * reach it, and `LockupVtxo` carries no field to say so, so a caller could not
+ * tell it apart from a live one. Whether arkd returns such an output under
+ * `spendableOnly` is not determinable from here, so the exclusion is made
+ * 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 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.
  *
@@ -374,6 +391,29 @@ type LockupFate =
     fate: "returned";
     spends: readonly LockupSpend[];
 }
+/**
+ * At least one output was unilaterally exited: it sits onchain under the
+ * VHTLC script, where no offchain claim or refund can reach it.
+ *
+ * Not terminal, and not a loss. The money is still under the same script
+ * with the same leaves, so `completeUnroll` plus an onchain spend can still
+ * end the swap either way — which is why this outranks `open`: an output
+ * that is "still unspent" but unreachable is not a swap that is merely
+ * running.
+ *
+ * It outranks a verdict too, on a lockup where a sibling output was claimed
+ * or returned. That is the rule `open` already sets, not a new one: the
+ * unspent test short-circuits before any witness is read, so a partially
+ * resolved lockup has never reported `claimed`/`returned`. What changes is
+ * only that such a lockup now says why it is unresolved.
+ */
+ | {
+    fate: "exited";
+    outpoints: readonly {
+        txid: string;
+        vout: number;
+    }[];
+}
 /** Nothing was learned: no outputs visible, an output spent by nothing the
  * indexer names, a spend it could not produce, or a blob that would not
  * decode. Never an answer. */
@@ -409,6 +449,11 @@ type LockupFate =
  * response to `unknown` is the same as to `open`: keep watching, and let the
  * refund timelock — which no outage can move — be what ends the wait.
  *
+ * **An exit is read before anything else, and over the whole set.** It is the
+ * one fact that makes an unspent output unreachable, so it outranks `open`; and
+ * it is scanned across every output rather than in outpoint order, so which
+ * output happens to come first cannot change the answer.
+ *
  * Ask-the-indexer, don't-trust-local-state: read fresh on every poll, never
  * cached, the same posture {@link findLockupVtxos} already establishes.
  */
@@ -447,9 +492,9 @@ declare function readLockupFate(indexer: LockupSpendIndexer, input: {
  * {@link refundIfUnresolved}, which retries.
  *
  * **Swept outputs are refused, not attempted.** This is an OFFCHAIN spend, and
- * a swept output is no longer a live leaf: `canSpendOffchain` and
- * `canRecoverOnchain` are mutually exclusive by construction, so a recoverable
- * input cannot be spent this way whatever key signs it (see
+ * a swept output is no longer a live leaf: `canSpendOffchain` is false wherever
+ * `canRecoverOnchain` is true, so a recoverable input cannot be spent this way
+ * whatever key signs it (see
  * {@link LockupVtxo.recoverable}). Because every input lands in ONE aggregate
  * transaction, a single swept output would take the live ones down with it —
  * so the whole push is refused with {@link LockupNeedsRecoveryError} naming the
@@ -512,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
@@ -540,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. */
@@ -1162,7 +1242,9 @@ interface RfqSwapManagerDeps {
  *    `settled`; a lockup fully spent by anything else ends it `refunded`.
  *    Anything the indexer could not answer is `unknown`, which is NOT an
  *    answer: the pass carries on to the steps below, whose deadlines an indexer
- *    outage has no bearing on.
+ *    outage has no bearing on. `exited` — an output unilaterally taken onchain
+ *    — ends neither the swap nor the pass: it blocks the Arkade half below,
+ *    with the L1 half left running.
  * 2. **Drive the trader's claim.** On an onchain send that is the L1 fill — see
  *    {@link nextOnchainAction}. On a receive it is the lockup itself, and it
  *    ends the pass: that leg has no step 3.
@@ -1493,6 +1575,18 @@ declare class RfqSwapManager {
     private arm;
     private pollSwap;
     private runPass;
+    /**
+     * The lockup was unilaterally exited: its outputs sit onchain under the
+     * VHTLC script, where no offchain claim or refund can reach them.
+     *
+     * `needs_counterparty` rather than a terminal state, because the money still
+     * needs action and the swap can still end either way — an onchain claim can
+     * reveal the preimage, an onchain refund can return it — and that state is
+     * documented as re-checked every pass. It must be set from HERE and not from
+     * inside `driveArkadeRefund`, whose two `unblock` calls would lift it again
+     * on the very next pass.
+     */
+    private blockExitedLockup;
     /**
      * The receive leg's whole state machine: claim the solver-funded lockup
      * while the window is open, and recognise the shapes in which it can be

package/dist/{rfq-hbzhTWHT.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. */
@@ -487,12 +513,11 @@ interface InvoiceFacts {
  * throws while nothing is funded. `RfqSwapManager` re-registers as a backstop
  * for older records; a repeat write is a no-op.
  *
- * The `sender` key comes from the wallet — a fresh HD descriptor per call, or
- * the wallet's static key — and is returned as `senderPubkey` plus `secrets`.
- * `secrets` holds only a public descriptor; the signer re-derives from the
- * wallet, so nothing secret is at rest. Persist `secrets` with the record
- * anyway: it is how the refund signer is found again. `nonInteractiveRefund`
- * recovers the funds even without it — but it needs the SOLVER's active
+ * The `sender` key is the wallet's identity key, reused by {@link
+ * provisionRefundKey} — returned as `senderPubkey` plus `secrets`. `secrets`
+ * holds only a public descriptor; the signer re-derives from the wallet, so
+ * nothing secret is at rest. Persist `secrets` with the record anyway: it is
+ * how the refund signer is found again. `nonInteractiveRefund` recovers the funds even without it — but it needs the SOLVER's active
  * cooperation, not just infrastructure uptime.
  */
 declare function requestLightningSend(wallet: IWallet, arkServerUrl: string, transport: RfqTransport, params: {
@@ -515,7 +540,8 @@ declare function requestLightningSend(wallet: IWallet, arkServerUrl: string, tra
      * `lockup` (with `address`): without it the manager can only poll, and
      * cannot retire the row this call just wrote. */
     script: InstanceType<typeof VHTLC.ScriptV2>;
-    /** Where a failed swap refunds. */
+    /** Where a failed swap refunds — the same address `secrets.pkScript` was
+     * decoded from, so the quote and the covenant always name one script. */
     refundAddress: string;
     /** The VHTLC `sender` x-only key, bound into the covenant. Public. */
     senderPubkey: Uint8Array;
@@ -528,7 +554,9 @@ declare function requestLightningSend(wallet: IWallet, arkServerUrl: string, tra
      * Returned so a consumer can persist the swap without re-deriving any of
      * it. Half of these are not on the quote: `serverPubkey` and `claimDelay`
      * come from this wallet's own `getInfo()`, `emulatorPubkey` from a
-     * per-network pin, `refundPkScript` from decoding an address.
+     * per-network pin, `refundPkScript` from `secrets` — decoded from the
+     * refund address at provisioning time, the same address this call returns
+     * as `refundAddress`.
      *
      * All public. Persisting them is optional: this call also registers the
      * lockup as a contract, and that row is where `rebuildRfqSwap` takes its
@@ -784,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
@@ -815,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}. */