@arkade-os/boltz-swap 0.3.23 → 0.3.25

package/README.md

@@ -191,6 +191,28 @@ const unsubscribe = manager.subscribeToSwapUpdates(
 );
 ```
 
+### Submarine Fund Recovery
+
+If a Lightning payment fails and funds get stranded in a VHTLC, you can recover them manually:
+
+```typescript
+// Scan all local swaps for recoverable funds
+const candidates = await swaps.scanRecoverableSubmarineSwaps();
+// candidates[i].status: "recoverable" | "pre_cltv" | "none" | "already_spent" | "invalid_swap"
+
+// Recover all at once
+const results = await swaps.recoverAllSubmarineFunds(candidates.map(c => c.swap));
+
+// Or inspect / recover a single swap
+const info = await swaps.inspectSubmarineRecovery(swap);
+if (info.status === 'recoverable') {
+  await swaps.recoverSubmarineFunds(swap);
+}
+```
+
+> [!NOTE]
+> This only scans swaps stored in your local repository. It does not discover swaps that exist on Boltz but are missing locally.
+
 ### Cleanup
 
 ```typescript

package/dist/{arkade-swaps-DEvf-2g2.d.ts → arkade-swaps-CZF9XoFR.d.cts}

@@ -1,7 +1,25 @@
 import { IWallet, ArkProvider, IndexerProvider, ArkInfo, Identity, ArkTxInput, VHTLC } from '@arkade-os/sdk';
-import { m as BoltzSwapProvider, V as SwapManager, j as SwapRepository, X as ArkadeSwapsCreateConfig, A as ArkadeSwapsConfig, k as SwapManagerClient, C as CreateLightningInvoiceRequest, e as CreateLightningInvoiceResponse, b as BoltzReverseSwap, S as SendLightningPaymentRequest, f as SendLightningPaymentResponse, c as BoltzSubmarineSwap, h as ArkToBtcResponse, a as BoltzChainSwap, i as BtcToArkResponse, d as Chain, F as FeesResponse, g as ChainFeesResponse, L as LimitsResponse, G as GetSwapStatusResponse, B as BoltzSwap } from './types-OyAdK824.js';
+import { p as BoltzSwapProvider, Y as SwapManager, m as SwapRepository, _ as ArkadeSwapsCreateConfig, A as ArkadeSwapsConfig, n 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, l as BtcToArkResponse, d as Chain, F as FeesResponse, j as ChainFeesResponse, L as LimitsResponse, G as GetSwapStatusResponse, B as BoltzSwap } from './types-LCXS1AVA.cjs';
 import { TransactionOutput } from '@scure/btc-signer/psbt.js';
 
+/**
+ * Boltz-Ark VHTLC timeouts. The shape matches Boltz's `timeoutBlockHeights`
+ * API field, but the legacy name is misleading — these are not all block
+ * heights:
+ * - `refund` is an absolute Unix timestamp in seconds (CLTV with timestamp
+ *   semantics, BIP65 threshold ≥ 500_000_000).
+ * - `unilateralClaim`, `unilateralRefund`, `unilateralRefundWithoutReceiver`
+ *   are BIP68 *relative* delays measured from the lockup confirmation. Values
+ *   ≥ 512 are interpreted as seconds (BIP68 type-flag). For Boltz Ark mainnet
+ *   they're always seconds.
+ */
+type VhtlcTimeouts = {
+    refund: number;
+    unilateralClaim: number;
+    unilateralRefund: number;
+    unilateralRefundWithoutReceiver: number;
+};
+
 /**
  * Unified entry point for Lightning and chain swaps between Arkade, Lightning Network, and Bitcoin.
  *
@@ -129,13 +147,86 @@ declare class ArkadeSwaps {
      * @throws {SwapError} If invoice is missing or key retrieval fails.
      */
     createSubmarineSwap(args: SendLightningPaymentRequest): Promise<BoltzSubmarineSwap>;
+    /**
+     * Reconstruct a submarine swap's VHTLC script from stored data. This does
+     * not query the indexer, so bulk scans can build every script first and
+     * then use batched VTXO lookups.
+     *
+     * @throws {Error} If preimage hash is unavailable, the swap response is
+     *   incomplete, the script can't be built, or the reconstructed address
+     *   doesn't match the one Boltz returned.
+     */
+    private buildSubmarineVHTLCContext;
+    /**
+     * Reconstruct a submarine swap's VHTLC script from stored data and look
+     * up its VTXOs at the indexer. Side-effect free; shared by `refundVHTLC`
+     * (spending path) and `inspectSubmarineRecovery` (diagnostic path).
+     *
+     * `refundableVtxos` merges spendable + recoverable indexer queries
+     * (deduped by outpoint). When that set is empty, a third query
+     * populates `diagnostic` so callers can distinguish "never funded",
+     * "already spent", and "preconfirmed-only".
+     */
+    private lookupSubmarineVHTLC;
+    private submarineRecoveryInfoFromLookup;
     /**
      * Refunds the VHTLC for a failed submarine swap, returning locked funds to the wallet.
      * Uses multi-party signatures (user + Boltz + server) for non-recoverable VTXOs.
      * @param pendingSwap - The submarine swap to refund.
+     * @returns Counts of VTXOs swept vs. deferred. A return value of `{ swept: 0, skipped: N }`
+     *          means the call was a no-op — callers should not treat it as a successful refund.
      * @throws {Error} If preimage hash is unavailable, VHTLC not found, or already spent.
      */
-    refundVHTLC(pendingSwap: BoltzSubmarineSwap): Promise<void>;
+    refundVHTLC(pendingSwap: BoltzSubmarineSwap, cachedArkInfo?: ArkInfo): Promise<SubmarineRefundOutcome>;
+    /**
+     * Inspect a submarine swap's lockup address for recoverable funds.
+     *
+     * Side-effect free. Returns a structured snapshot the UI can use to
+     * decide whether to offer the user a recovery action — it will not
+     * trigger any signing or persistence.
+     *
+     * Only `transaction.claimed` (success with possible stranded extras)
+     * and refundable failure statuses are recovery candidates. Pending
+     * statuses (`invoice.set`, `transaction.mempool`, …) are returned as
+     * `invalid_swap`; this API is for recovery, not a generic VTXO probe.
+     *
+     * @param swap - The submarine swap to inspect.
+     */
+    inspectSubmarineRecovery(swap: BoltzSubmarineSwap): Promise<SubmarineRecoveryInfo>;
+    /**
+     * Scan all locally-known submarine swaps for recoverable VHTLC funds.
+     *
+     * Loads submarine swaps from the repository, filters to recovery
+     * candidates (`transaction.claimed` plus refundable failure
+     * statuses), reconstructs their scripts, and performs one batched
+     * spendable query plus one batched recoverable query. Pending swaps are
+     * skipped entirely — they appear in the local repository but cannot
+     * be in a recovery state yet.
+     *
+     * Side-effect free: does not mutate the repository, does not sign,
+     * and does not query Boltz swap status.
+     */
+    scanRecoverableSubmarineSwaps(): Promise<SubmarineRecoveryInfo[]>;
+    /**
+     * Recover funds locked at a single submarine swap's VHTLC address.
+     *
+     * Thin wrapper around `refundVHTLC` for callers that have already
+     * confirmed (e.g. via `inspectSubmarineRecovery`) that funds are
+     * present. Centralises the spending logic in one place — flag-write
+     * behavior matches `refundVHTLC` (no-op for `transaction.claimed`,
+     * normal flag updates for failure statuses).
+     */
+    recoverSubmarineFunds(swap: BoltzSubmarineSwap, arkInfo?: ArkInfo): Promise<SubmarineRefundOutcome>;
+    /**
+     * Recover funds for a batch of submarine swaps.
+     *
+     * Each swap's recovery is independent — a failure on one swap does
+     * not abort the rest, and the caller receives a per-swap result so
+     * they can present partial outcomes in the UI. Recovery runs
+     * sequentially to avoid hammering Boltz / the indexer with parallel
+     * batch joins.
+     */
+    recoverAllSubmarineFunds(swaps: BoltzSubmarineSwap[]): Promise<SubmarineRecoveryResult[]>;
     /**
      * Waits for a submarine swap's Lightning payment to settle.
      * @param pendingSwap - The submarine swap to monitor.
@@ -271,12 +362,7 @@ declare class ArkadeSwaps {
         receiverPubkey: string;
         senderPubkey: string;
         serverPubkey: string;
-        timeoutBlockHeights: {
-            refund: number;
-            unilateralClaim: number;
-            unilateralRefund: number;
-            unilateralRefundWithoutReceiver: number;
-        };
+        timeoutBlockHeights: VhtlcTimeouts;
     }): {
         vhtlcScript: VHTLC.Script;
         vhtlcAddress: string;
@@ -353,7 +439,11 @@ interface IArkadeSwaps extends AsyncDisposable {
     createSubmarineSwap(args: SendLightningPaymentRequest): Promise<BoltzSubmarineSwap>;
     createReverseSwap(args: CreateLightningInvoiceRequest): Promise<BoltzReverseSwap>;
     claimVHTLC(pendingSwap: BoltzReverseSwap): Promise<void>;
-    refundVHTLC(pendingSwap: BoltzSubmarineSwap): Promise<void>;
+    refundVHTLC(pendingSwap: BoltzSubmarineSwap): Promise<SubmarineRefundOutcome>;
+    inspectSubmarineRecovery(swap: BoltzSubmarineSwap): Promise<SubmarineRecoveryInfo>;
+    scanRecoverableSubmarineSwaps(): Promise<SubmarineRecoveryInfo[]>;
+    recoverSubmarineFunds(swap: BoltzSubmarineSwap): Promise<SubmarineRefundOutcome>;
+    recoverAllSubmarineFunds(swaps: BoltzSubmarineSwap[]): Promise<SubmarineRecoveryResult[]>;
     waitAndClaim(pendingSwap: BoltzReverseSwap): Promise<{
         txid: string;
     }>;
@@ -411,12 +501,7 @@ interface IArkadeSwaps extends AsyncDisposable {
         receiverPubkey: string;
         senderPubkey: string;
         serverPubkey: string;
-        timeoutBlockHeights: {
-            refund: number;
-            unilateralClaim: number;
-            unilateralRefund: number;
-            unilateralRefundWithoutReceiver: number;
-        };
+        timeoutBlockHeights: VhtlcTimeouts;
     }): {
         vhtlcScript: VHTLC.Script;
         vhtlcAddress: string;
@@ -443,4 +528,4 @@ interface IArkadeSwaps extends AsyncDisposable {
     dispose(): Promise<void>;
 }
 
-export { ArkadeSwaps as A, type IArkadeSwaps as I };
+export { ArkadeSwaps as A, type IArkadeSwaps as I, type VhtlcTimeouts as V };

package/dist/{arkade-swaps-CvA3RP7_.d.cts → arkade-swaps-pfAgQUMP.d.ts}

@@ -1,7 +1,25 @@
 import { IWallet, ArkProvider, IndexerProvider, ArkInfo, Identity, ArkTxInput, VHTLC } from '@arkade-os/sdk';
-import { m as BoltzSwapProvider, V as SwapManager, j as SwapRepository, X as ArkadeSwapsCreateConfig, A as ArkadeSwapsConfig, k as SwapManagerClient, C as CreateLightningInvoiceRequest, e as CreateLightningInvoiceResponse, b as BoltzReverseSwap, S as SendLightningPaymentRequest, f as SendLightningPaymentResponse, c as BoltzSubmarineSwap, h as ArkToBtcResponse, a as BoltzChainSwap, i as BtcToArkResponse, d as Chain, F as FeesResponse, g as ChainFeesResponse, L as LimitsResponse, G as GetSwapStatusResponse, B as BoltzSwap } from './types-OyAdK824.cjs';
+import { p as BoltzSwapProvider, Y as SwapManager, m as SwapRepository, _ as ArkadeSwapsCreateConfig, A as ArkadeSwapsConfig, n 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, l as BtcToArkResponse, d as Chain, F as FeesResponse, j as ChainFeesResponse, L as LimitsResponse, G as GetSwapStatusResponse, B as BoltzSwap } from './types-LCXS1AVA.js';
 import { TransactionOutput } from '@scure/btc-signer/psbt.js';
 
+/**
+ * Boltz-Ark VHTLC timeouts. The shape matches Boltz's `timeoutBlockHeights`
+ * API field, but the legacy name is misleading — these are not all block
+ * heights:
+ * - `refund` is an absolute Unix timestamp in seconds (CLTV with timestamp
+ *   semantics, BIP65 threshold ≥ 500_000_000).
+ * - `unilateralClaim`, `unilateralRefund`, `unilateralRefundWithoutReceiver`
+ *   are BIP68 *relative* delays measured from the lockup confirmation. Values
+ *   ≥ 512 are interpreted as seconds (BIP68 type-flag). For Boltz Ark mainnet
+ *   they're always seconds.
+ */
+type VhtlcTimeouts = {
+    refund: number;
+    unilateralClaim: number;
+    unilateralRefund: number;
+    unilateralRefundWithoutReceiver: number;
+};
+
 /**
  * Unified entry point for Lightning and chain swaps between Arkade, Lightning Network, and Bitcoin.
  *
@@ -129,13 +147,86 @@ declare class ArkadeSwaps {
      * @throws {SwapError} If invoice is missing or key retrieval fails.
      */
     createSubmarineSwap(args: SendLightningPaymentRequest): Promise<BoltzSubmarineSwap>;
+    /**
+     * Reconstruct a submarine swap's VHTLC script from stored data. This does
+     * not query the indexer, so bulk scans can build every script first and
+     * then use batched VTXO lookups.
+     *
+     * @throws {Error} If preimage hash is unavailable, the swap response is
+     *   incomplete, the script can't be built, or the reconstructed address
+     *   doesn't match the one Boltz returned.
+     */
+    private buildSubmarineVHTLCContext;
+    /**
+     * Reconstruct a submarine swap's VHTLC script from stored data and look
+     * up its VTXOs at the indexer. Side-effect free; shared by `refundVHTLC`
+     * (spending path) and `inspectSubmarineRecovery` (diagnostic path).
+     *
+     * `refundableVtxos` merges spendable + recoverable indexer queries
+     * (deduped by outpoint). When that set is empty, a third query
+     * populates `diagnostic` so callers can distinguish "never funded",
+     * "already spent", and "preconfirmed-only".
+     */
+    private lookupSubmarineVHTLC;
+    private submarineRecoveryInfoFromLookup;
     /**
      * Refunds the VHTLC for a failed submarine swap, returning locked funds to the wallet.
      * Uses multi-party signatures (user + Boltz + server) for non-recoverable VTXOs.
      * @param pendingSwap - The submarine swap to refund.
+     * @returns Counts of VTXOs swept vs. deferred. A return value of `{ swept: 0, skipped: N }`
+     *          means the call was a no-op — callers should not treat it as a successful refund.
      * @throws {Error} If preimage hash is unavailable, VHTLC not found, or already spent.
      */
-    refundVHTLC(pendingSwap: BoltzSubmarineSwap): Promise<void>;
+    refundVHTLC(pendingSwap: BoltzSubmarineSwap, cachedArkInfo?: ArkInfo): Promise<SubmarineRefundOutcome>;
+    /**
+     * Inspect a submarine swap's lockup address for recoverable funds.
+     *
+     * Side-effect free. Returns a structured snapshot the UI can use to
+     * decide whether to offer the user a recovery action — it will not
+     * trigger any signing or persistence.
+     *
+     * Only `transaction.claimed` (success with possible stranded extras)
+     * and refundable failure statuses are recovery candidates. Pending
+     * statuses (`invoice.set`, `transaction.mempool`, …) are returned as
+     * `invalid_swap`; this API is for recovery, not a generic VTXO probe.
+     *
+     * @param swap - The submarine swap to inspect.
+     */
+    inspectSubmarineRecovery(swap: BoltzSubmarineSwap): Promise<SubmarineRecoveryInfo>;
+    /**
+     * Scan all locally-known submarine swaps for recoverable VHTLC funds.
+     *
+     * Loads submarine swaps from the repository, filters to recovery
+     * candidates (`transaction.claimed` plus refundable failure
+     * statuses), reconstructs their scripts, and performs one batched
+     * spendable query plus one batched recoverable query. Pending swaps are
+     * skipped entirely — they appear in the local repository but cannot
+     * be in a recovery state yet.
+     *
+     * Side-effect free: does not mutate the repository, does not sign,
+     * and does not query Boltz swap status.
+     */
+    scanRecoverableSubmarineSwaps(): Promise<SubmarineRecoveryInfo[]>;
+    /**
+     * Recover funds locked at a single submarine swap's VHTLC address.
+     *
+     * Thin wrapper around `refundVHTLC` for callers that have already
+     * confirmed (e.g. via `inspectSubmarineRecovery`) that funds are
+     * present. Centralises the spending logic in one place — flag-write
+     * behavior matches `refundVHTLC` (no-op for `transaction.claimed`,
+     * normal flag updates for failure statuses).
+     */
+    recoverSubmarineFunds(swap: BoltzSubmarineSwap, arkInfo?: ArkInfo): Promise<SubmarineRefundOutcome>;
+    /**
+     * Recover funds for a batch of submarine swaps.
+     *
+     * Each swap's recovery is independent — a failure on one swap does
+     * not abort the rest, and the caller receives a per-swap result so
+     * they can present partial outcomes in the UI. Recovery runs
+     * sequentially to avoid hammering Boltz / the indexer with parallel
+     * batch joins.
+     */
+    recoverAllSubmarineFunds(swaps: BoltzSubmarineSwap[]): Promise<SubmarineRecoveryResult[]>;
     /**
      * Waits for a submarine swap's Lightning payment to settle.
      * @param pendingSwap - The submarine swap to monitor.
@@ -271,12 +362,7 @@ declare class ArkadeSwaps {
         receiverPubkey: string;
         senderPubkey: string;
         serverPubkey: string;
-        timeoutBlockHeights: {
-            refund: number;
-            unilateralClaim: number;
-            unilateralRefund: number;
-            unilateralRefundWithoutReceiver: number;
-        };
+        timeoutBlockHeights: VhtlcTimeouts;
     }): {
         vhtlcScript: VHTLC.Script;
         vhtlcAddress: string;
@@ -353,7 +439,11 @@ interface IArkadeSwaps extends AsyncDisposable {
     createSubmarineSwap(args: SendLightningPaymentRequest): Promise<BoltzSubmarineSwap>;
     createReverseSwap(args: CreateLightningInvoiceRequest): Promise<BoltzReverseSwap>;
     claimVHTLC(pendingSwap: BoltzReverseSwap): Promise<void>;
-    refundVHTLC(pendingSwap: BoltzSubmarineSwap): Promise<void>;
+    refundVHTLC(pendingSwap: BoltzSubmarineSwap): Promise<SubmarineRefundOutcome>;
+    inspectSubmarineRecovery(swap: BoltzSubmarineSwap): Promise<SubmarineRecoveryInfo>;
+    scanRecoverableSubmarineSwaps(): Promise<SubmarineRecoveryInfo[]>;
+    recoverSubmarineFunds(swap: BoltzSubmarineSwap): Promise<SubmarineRefundOutcome>;
+    recoverAllSubmarineFunds(swaps: BoltzSubmarineSwap[]): Promise<SubmarineRecoveryResult[]>;
     waitAndClaim(pendingSwap: BoltzReverseSwap): Promise<{
         txid: string;
     }>;
@@ -411,12 +501,7 @@ interface IArkadeSwaps extends AsyncDisposable {
         receiverPubkey: string;
         senderPubkey: string;
         serverPubkey: string;
-        timeoutBlockHeights: {
-            refund: number;
-            unilateralClaim: number;
-            unilateralRefund: number;
-            unilateralRefundWithoutReceiver: number;
-        };
+        timeoutBlockHeights: VhtlcTimeouts;
     }): {
         vhtlcScript: VHTLC.Script;
         vhtlcAddress: string;
@@ -443,4 +528,4 @@ interface IArkadeSwaps extends AsyncDisposable {
     dispose(): Promise<void>;
 }
 
-export { ArkadeSwaps as A, type IArkadeSwaps as I };
+export { ArkadeSwaps as A, type IArkadeSwaps as I, type VhtlcTimeouts as V };

package/dist/{background-EHOJZDKT.js → background-GCBCKLGY.js}

@@ -2,8 +2,8 @@ import {
   defineExpoSwapBackgroundTask,
   registerExpoSwapBackgroundTask,
   unregisterExpoSwapBackgroundTask
-} from "./chunk-EQK2BJQC.js";
-import "./chunk-K3QEFL7D.js";
+} from "./chunk-FEXQELYZ.js";
+import "./chunk-XC2ARJZO.js";
 import "./chunk-3RG5ZIWI.js";
 export {
   defineExpoSwapBackgroundTask,

package/dist/{chunk-EQK2BJQC.js → chunk-FEXQELYZ.js}

@@ -8,7 +8,7 @@ import {
   isSubmarineFinalStatus,
   isSubmarineSwapRefundable,
   logger
-} from "./chunk-K3QEFL7D.js";
+} from "./chunk-XC2ARJZO.js";
 import {
   __require
 } from "./chunk-3RG5ZIWI.js";