@arkade-os/boltz-swap 0.3.39 → 0.3.41

package/README.md

@@ -61,6 +61,35 @@ console.log('Paid:', result.txid);
 // SwapManager auto-refunds if payment fails
 ```
 
+By default the call resolves only once the swap fully settles (`transaction.claimed`),
+i.e. after Boltz has swept the HTLC. To show an optimistic "sent" state as soon as the
+payment is in flight — like most Lightning wallets — pass `waitFor: 'funded'`:
+
+```typescript
+const result = await swaps.sendLightningPayment({
+  invoice: 'lnbc500u1pj...',
+  waitFor: 'funded',
+});
+// Resolves as soon as the lockup transaction is observed: the funds are
+// committed and the swap is refundable from here. result.preimage is not
+// reported on this path — the proof of payment is persisted to the stored
+// swap once it settles. Monitoring continues in the
+// background and keeps the stored swap up to date until a terminal status,
+// but a late failure no longer rejects — keep the SwapManager enabled so
+// auto-refunds are handled for you. With the SwapManager disabled, a late
+// failure is only persisted as refundable and the funds stay locked until
+// you recover them via restoreSwaps()/recoverSubmarineFunds().
+```
+
+The same milestone is exposed for a swap you already hold as
+`waitForSwapFunded(pendingSwap)`, alongside `waitForSwapSettlement(pendingSwap)`.
+
+If the app restarts before the swap settles, the in-process monitoring is gone — call
+`refreshSwapsStatus()` on startup to reconcile: it polls every pending swap and persists
+the latest status, including the preimage for swaps that settled while the app was
+closed. Read the swap back from the repository (e.g. `getSwapHistory()`) to flip a
+pending UI row to "completed".
+
 ### ARK to BTC
 
 ```typescript

package/dist/{arkade-swaps-Uet3tgN6.d.ts → arkade-swaps-C3sUFr5f.d.cts}

@@ -1,5 +1,5 @@
 import { IWallet, ArkProvider, IndexerProvider, ArkInfo, Identity, ArkTxInput, VHTLC } from '@arkade-os/sdk';
-import { r as BoltzSwapProvider, x as SwapManager, n as SwapRepository, q as ArkadeSwapsCreateConfig, A as ArkadeSwapsConfig, o as SwapManagerClient, C as CreateLightningInvoiceRequest, e as CreateLightningInvoiceResponse, b as BoltzReverseSwap, S as SendLightningPaymentRequest, f as SendLightningPaymentResponse, c as BoltzSubmarineSwap, g as SubmarineRefundOutcome, h as SubmarineRecoveryInfo, i as SubmarineRecoveryResult, k as ArkToBtcResponse, a as BoltzChainSwap, m as ChainArkRefundOutcome, l as BtcToArkResponse, d as Chain, F as FeesResponse, j as ChainFeesResponse, L as LimitsResponse, G as GetSwapStatusResponse, B as BoltzSwap } from './types-D97i1LFu.js';
+import { r as BoltzSwapProvider, y as SwapManager, m as SwapRepository, q as ArkadeSwapsCreateConfig, A as ArkadeSwapsConfig, n as SwapManagerClient, C as CreateLightningInvoiceRequest, e as CreateLightningInvoiceResponse, b as BoltzReverseSwap, S as SendLightningPaymentRequest, o as SendLightningPaymentResponse, O as OptimisticSendLightningPaymentResponse, c as BoltzSubmarineSwap, f as SubmarineRefundOutcome, g as SubmarineRecoveryInfo, h as SubmarineRecoveryResult, j as ArkToBtcResponse, a as BoltzChainSwap, l as ChainArkRefundOutcome, k as BtcToArkResponse, d as Chain, F as FeesResponse, i as ChainFeesResponse, L as LimitsResponse, G as GetSwapStatusResponse, B as BoltzSwap } from './types-8NrCdOpS.cjs';
 import { TransactionOutput } from '@scure/btc-signer/psbt.js';
 
 /**
@@ -134,12 +134,33 @@ declare class ArkadeSwaps {
     }>;
     /**
      * Sends a Lightning payment via a submarine swap (Arkade → Lightning).
-     * Creates the swap, sends funds, and waits for settlement. Auto-refunds on failure.
+     * Creates the swap, sends funds, and waits for settlement (or, with
+     * `waitFor: "funded"`, only until the lockup transaction is observed —
+     * see {@link SendLightningPaymentRequest.waitFor}). Auto-refunds on
+     * failures observed before the promise resolves.
      * @param args.invoice - BOLT11 Lightning invoice to pay.
-     * @returns The amount paid, preimage (proof of payment), and transaction ID.
+     * @param args.waitFor - "settled" (default) resolves with the preimage at
+     * "transaction.claimed"; "funded" resolves without a preimage as soon as
+     * the payment is in flight.
+     * @returns The amount paid, preimage (proof of payment, unless resolved
+     * at "funded"), and transaction ID.
      * @throws {TransactionFailedError} If the payment fails (auto-refunds if possible).
+     * @remarks With `waitFor: "funded"`, failures observed *after* the promise
+     * resolves are only persisted to the repository (refundable flag) — the
+     * active auto-refund in this method is no longer reachable. Keep the
+     * SwapManager enabled so late failures are refunded automatically;
+     * without it the caller must recover via {@link restoreSwaps} /
+     * {@link recoverSubmarineFunds}.
+     *
+     * Note on types: the overloads narrow on the `waitFor` literal, so a
+     * request stored in a variable typed as `SendLightningPaymentRequest`
+     * widens the result to {@link OptimisticSendLightningPaymentResponse}
+     * (optional preimage) even on the default settled path.
      */
-    sendLightningPayment(args: SendLightningPaymentRequest): Promise<SendLightningPaymentResponse>;
+    sendLightningPayment(args: SendLightningPaymentRequest & {
+        waitFor?: "settled";
+    }): Promise<SendLightningPaymentResponse>;
+    sendLightningPayment(args: SendLightningPaymentRequest): Promise<OptimisticSendLightningPaymentResponse>;
     /**
      * Creates a submarine swap (Arkade → Lightning) and saves it to storage.
      * @param args.invoice - BOLT11 Lightning invoice to pay.
@@ -229,6 +250,9 @@ declare class ArkadeSwaps {
     recoverAllSubmarineFunds(swaps: BoltzSubmarineSwap[]): Promise<SubmarineRecoveryResult[]>;
     /**
      * Waits for a submarine swap's Lightning payment to settle.
+     * Resolves only at the terminal "transaction.claimed" status, once Boltz
+     * has swept the HTLC. To resolve as soon as the payment is in flight, use
+     * {@link waitForSwapFunded} instead.
      * @param pendingSwap - The submarine swap to monitor.
      * @returns The preimage from the settled Lightning payment (proof of payment).
      * @throws {SwapExpiredError} If the swap expires.
@@ -238,6 +262,32 @@ declare class ArkadeSwaps {
     waitForSwapSettlement(pendingSwap: BoltzSubmarineSwap): Promise<{
         preimage: string;
     }>;
+    /**
+     * Waits until a submarine swap is funded: resolves as soon as the lockup
+     * transaction is observed ("transaction.mempool" or any later status in
+     * the lifecycle — statuses can be skipped since subscriptions report only
+     * the current one). The sender's funds are committed and the swap is
+     * refundable from this point, which is when most Lightning wallets show
+     * a payment as "sent".
+     *
+     * Monitoring continues in the background until the swap reaches a
+     * terminal status, persisting updates to the repository (the preimage on
+     * claim, the refundable flag on failure), but this promise no longer
+     * rejects once resolved — acting on a late failure is the caller's
+     * responsibility (the SwapManager handles it automatically when enabled).
+     * @param pendingSwap - The submarine swap to monitor.
+     * @throws {SwapExpiredError} If the swap expires before funding.
+     * @throws {InvoiceFailedToPayError} If Boltz fails to route the payment.
+     * @throws {TransactionLockupFailedError} If the lockup transaction fails.
+     */
+    waitForSwapFunded(pendingSwap: BoltzSubmarineSwap): Promise<void>;
+    /**
+     * Shared wait machinery: monitors the swap and resolves at the terminal
+     * "transaction.claimed" status (with the preimage) or, when `resolveAt`
+     * is given, as soon as that status — or any later one in the successful
+     * progression — is observed (without a preimage).
+     */
+    private waitForSubmarineSwap;
     /**
      * Creates a chain swap from ARK to BTC.
      * @param args.btcAddress - Destination Bitcoin address.
@@ -428,6 +478,23 @@ declare class ArkadeSwaps {
         vhtlcScript: VHTLC.Script;
         vhtlcAddress: string;
     };
+    /**
+     * Reconstruct a swap's VHTLC by matching the persisted `lockupAddress`
+     * against the current and deprecated server signers, returning the matched
+     * script together with the server key it was minted under.
+     *
+     * Recovery paths (claim/refund/lookup) must use this instead of building the
+     * VHTLC from the current signer alone: a swap created before a planned arkd
+     * signer rotation is locked to a now-deprecated signer, so the current key
+     * would yield the wrong address and strand the funds. The returned
+     * `serverXOnlyPublicKey` is the original (possibly deprecated) key and MUST
+     * be threaded into downstream signing/verification.
+     *
+     * Throws a descriptive mismatch error when no candidate reproduces the
+     * lockup address (e.g. the swap predates an already-pruned deprecated
+     * signer) — replacing the previous current-signer-only equality check.
+     */
+    private resolveVHTLCForLockup;
     /**
      * Retrieves fees for swaps.
      * - No arguments: returns lightning (submarine/reverse) fees
@@ -511,7 +578,10 @@ interface IArkadeSwaps extends AsyncDisposable {
     stopSwapManager(): Promise<void>;
     getSwapManager(): SwapManagerClient | null;
     createLightningInvoice(args: CreateLightningInvoiceRequest): Promise<CreateLightningInvoiceResponse>;
-    sendLightningPayment(args: SendLightningPaymentRequest): Promise<SendLightningPaymentResponse>;
+    sendLightningPayment(args: SendLightningPaymentRequest & {
+        waitFor?: "settled";
+    }): Promise<SendLightningPaymentResponse>;
+    sendLightningPayment(args: SendLightningPaymentRequest): Promise<OptimisticSendLightningPaymentResponse>;
     createSubmarineSwap(args: SendLightningPaymentRequest): Promise<BoltzSubmarineSwap>;
     createReverseSwap(args: CreateLightningInvoiceRequest): Promise<BoltzReverseSwap>;
     claimVHTLC(pendingSwap: BoltzReverseSwap): Promise<void>;
@@ -526,6 +596,7 @@ interface IArkadeSwaps extends AsyncDisposable {
     waitForSwapSettlement(pendingSwap: BoltzSubmarineSwap): Promise<{
         preimage: string;
     }>;
+    waitForSwapFunded(pendingSwap: BoltzSubmarineSwap): Promise<void>;
     restoreSwaps(boltzFees?: FeesResponse): Promise<{
         chainSwaps: BoltzChainSwap[];
         reverseSwaps: BoltzReverseSwap[];

package/dist/{arkade-swaps-DG9UepoS.d.cts → arkade-swaps-LvsGHtre.d.ts}

@@ -1,5 +1,5 @@
 import { IWallet, ArkProvider, IndexerProvider, ArkInfo, Identity, ArkTxInput, VHTLC } from '@arkade-os/sdk';
-import { r as BoltzSwapProvider, x as SwapManager, n as SwapRepository, q as ArkadeSwapsCreateConfig, A as ArkadeSwapsConfig, o as SwapManagerClient, C as CreateLightningInvoiceRequest, e as CreateLightningInvoiceResponse, b as BoltzReverseSwap, S as SendLightningPaymentRequest, f as SendLightningPaymentResponse, c as BoltzSubmarineSwap, g as SubmarineRefundOutcome, h as SubmarineRecoveryInfo, i as SubmarineRecoveryResult, k as ArkToBtcResponse, a as BoltzChainSwap, m as ChainArkRefundOutcome, l as BtcToArkResponse, d as Chain, F as FeesResponse, j as ChainFeesResponse, L as LimitsResponse, G as GetSwapStatusResponse, B as BoltzSwap } from './types-D97i1LFu.cjs';
+import { r as BoltzSwapProvider, y as SwapManager, m as SwapRepository, q as ArkadeSwapsCreateConfig, A as ArkadeSwapsConfig, n as SwapManagerClient, C as CreateLightningInvoiceRequest, e as CreateLightningInvoiceResponse, b as BoltzReverseSwap, S as SendLightningPaymentRequest, o as SendLightningPaymentResponse, O as OptimisticSendLightningPaymentResponse, c as BoltzSubmarineSwap, f as SubmarineRefundOutcome, g as SubmarineRecoveryInfo, h as SubmarineRecoveryResult, j as ArkToBtcResponse, a as BoltzChainSwap, l as ChainArkRefundOutcome, k as BtcToArkResponse, d as Chain, F as FeesResponse, i as ChainFeesResponse, L as LimitsResponse, G as GetSwapStatusResponse, B as BoltzSwap } from './types-8NrCdOpS.js';
 import { TransactionOutput } from '@scure/btc-signer/psbt.js';
 
 /**
@@ -134,12 +134,33 @@ declare class ArkadeSwaps {
     }>;
     /**
      * Sends a Lightning payment via a submarine swap (Arkade → Lightning).
-     * Creates the swap, sends funds, and waits for settlement. Auto-refunds on failure.
+     * Creates the swap, sends funds, and waits for settlement (or, with
+     * `waitFor: "funded"`, only until the lockup transaction is observed —
+     * see {@link SendLightningPaymentRequest.waitFor}). Auto-refunds on
+     * failures observed before the promise resolves.
      * @param args.invoice - BOLT11 Lightning invoice to pay.
-     * @returns The amount paid, preimage (proof of payment), and transaction ID.
+     * @param args.waitFor - "settled" (default) resolves with the preimage at
+     * "transaction.claimed"; "funded" resolves without a preimage as soon as
+     * the payment is in flight.
+     * @returns The amount paid, preimage (proof of payment, unless resolved
+     * at "funded"), and transaction ID.
      * @throws {TransactionFailedError} If the payment fails (auto-refunds if possible).
+     * @remarks With `waitFor: "funded"`, failures observed *after* the promise
+     * resolves are only persisted to the repository (refundable flag) — the
+     * active auto-refund in this method is no longer reachable. Keep the
+     * SwapManager enabled so late failures are refunded automatically;
+     * without it the caller must recover via {@link restoreSwaps} /
+     * {@link recoverSubmarineFunds}.
+     *
+     * Note on types: the overloads narrow on the `waitFor` literal, so a
+     * request stored in a variable typed as `SendLightningPaymentRequest`
+     * widens the result to {@link OptimisticSendLightningPaymentResponse}
+     * (optional preimage) even on the default settled path.
      */
-    sendLightningPayment(args: SendLightningPaymentRequest): Promise<SendLightningPaymentResponse>;
+    sendLightningPayment(args: SendLightningPaymentRequest & {
+        waitFor?: "settled";
+    }): Promise<SendLightningPaymentResponse>;
+    sendLightningPayment(args: SendLightningPaymentRequest): Promise<OptimisticSendLightningPaymentResponse>;
     /**
      * Creates a submarine swap (Arkade → Lightning) and saves it to storage.
      * @param args.invoice - BOLT11 Lightning invoice to pay.
@@ -229,6 +250,9 @@ declare class ArkadeSwaps {
     recoverAllSubmarineFunds(swaps: BoltzSubmarineSwap[]): Promise<SubmarineRecoveryResult[]>;
     /**
      * Waits for a submarine swap's Lightning payment to settle.
+     * Resolves only at the terminal "transaction.claimed" status, once Boltz
+     * has swept the HTLC. To resolve as soon as the payment is in flight, use
+     * {@link waitForSwapFunded} instead.
      * @param pendingSwap - The submarine swap to monitor.
      * @returns The preimage from the settled Lightning payment (proof of payment).
      * @throws {SwapExpiredError} If the swap expires.
@@ -238,6 +262,32 @@ declare class ArkadeSwaps {
     waitForSwapSettlement(pendingSwap: BoltzSubmarineSwap): Promise<{
         preimage: string;
     }>;
+    /**
+     * Waits until a submarine swap is funded: resolves as soon as the lockup
+     * transaction is observed ("transaction.mempool" or any later status in
+     * the lifecycle — statuses can be skipped since subscriptions report only
+     * the current one). The sender's funds are committed and the swap is
+     * refundable from this point, which is when most Lightning wallets show
+     * a payment as "sent".
+     *
+     * Monitoring continues in the background until the swap reaches a
+     * terminal status, persisting updates to the repository (the preimage on
+     * claim, the refundable flag on failure), but this promise no longer
+     * rejects once resolved — acting on a late failure is the caller's
+     * responsibility (the SwapManager handles it automatically when enabled).
+     * @param pendingSwap - The submarine swap to monitor.
+     * @throws {SwapExpiredError} If the swap expires before funding.
+     * @throws {InvoiceFailedToPayError} If Boltz fails to route the payment.
+     * @throws {TransactionLockupFailedError} If the lockup transaction fails.
+     */
+    waitForSwapFunded(pendingSwap: BoltzSubmarineSwap): Promise<void>;
+    /**
+     * Shared wait machinery: monitors the swap and resolves at the terminal
+     * "transaction.claimed" status (with the preimage) or, when `resolveAt`
+     * is given, as soon as that status — or any later one in the successful
+     * progression — is observed (without a preimage).
+     */
+    private waitForSubmarineSwap;
     /**
      * Creates a chain swap from ARK to BTC.
      * @param args.btcAddress - Destination Bitcoin address.
@@ -428,6 +478,23 @@ declare class ArkadeSwaps {
         vhtlcScript: VHTLC.Script;
         vhtlcAddress: string;
     };
+    /**
+     * Reconstruct a swap's VHTLC by matching the persisted `lockupAddress`
+     * against the current and deprecated server signers, returning the matched
+     * script together with the server key it was minted under.
+     *
+     * Recovery paths (claim/refund/lookup) must use this instead of building the
+     * VHTLC from the current signer alone: a swap created before a planned arkd
+     * signer rotation is locked to a now-deprecated signer, so the current key
+     * would yield the wrong address and strand the funds. The returned
+     * `serverXOnlyPublicKey` is the original (possibly deprecated) key and MUST
+     * be threaded into downstream signing/verification.
+     *
+     * Throws a descriptive mismatch error when no candidate reproduces the
+     * lockup address (e.g. the swap predates an already-pruned deprecated
+     * signer) — replacing the previous current-signer-only equality check.
+     */
+    private resolveVHTLCForLockup;
     /**
      * Retrieves fees for swaps.
      * - No arguments: returns lightning (submarine/reverse) fees
@@ -511,7 +578,10 @@ interface IArkadeSwaps extends AsyncDisposable {
     stopSwapManager(): Promise<void>;
     getSwapManager(): SwapManagerClient | null;
     createLightningInvoice(args: CreateLightningInvoiceRequest): Promise<CreateLightningInvoiceResponse>;
-    sendLightningPayment(args: SendLightningPaymentRequest): Promise<SendLightningPaymentResponse>;
+    sendLightningPayment(args: SendLightningPaymentRequest & {
+        waitFor?: "settled";
+    }): Promise<SendLightningPaymentResponse>;
+    sendLightningPayment(args: SendLightningPaymentRequest): Promise<OptimisticSendLightningPaymentResponse>;
     createSubmarineSwap(args: SendLightningPaymentRequest): Promise<BoltzSubmarineSwap>;
     createReverseSwap(args: CreateLightningInvoiceRequest): Promise<BoltzReverseSwap>;
     claimVHTLC(pendingSwap: BoltzReverseSwap): Promise<void>;
@@ -526,6 +596,7 @@ interface IArkadeSwaps extends AsyncDisposable {
     waitForSwapSettlement(pendingSwap: BoltzSubmarineSwap): Promise<{
         preimage: string;
     }>;
+    waitForSwapFunded(pendingSwap: BoltzSubmarineSwap): Promise<void>;
     restoreSwaps(boltzFees?: FeesResponse): Promise<{
         chainSwaps: BoltzChainSwap[];
         reverseSwaps: BoltzReverseSwap[];

package/dist/{chunk-DNCIVDU5.js → chunk-CWY37W4B.js}

@@ -7,7 +7,7 @@ import {
   isSubmarineFinalStatus,
   isSubmarineSwapRefundable,
   logger
-} from "./chunk-CFB2NNGT.js";
+} from "./chunk-UXYHW7KV.js";
 
 // src/expo/swapsPollProcessor.ts
 var SWAP_POLL_TASK_TYPE = "swap-poll";