@arkade-os/boltz-swap 0.3.22 → 0.3.24

package/dist/expo/index.cjs

@@ -118,7 +118,7 @@ var init_errors = __esm({
 });
 
 // src/boltz-swap-provider.ts
-var import_sdk, import_base, isSubmarineFinalStatus, isSubmarineRefundableStatus, isReverseFinalStatus, isReverseClaimableStatus, isChainClaimableStatus, isChainFinalStatus, isChainRefundableStatus, isChainSignableStatus, isPendingReverseSwap, isPendingSubmarineSwap, isPendingChainSwap, isSubmarineSwapRefundable, isTimeoutBlockHeights, isGetReverseSwapTxIdResponse, isGetSwapStatusResponse, isGetSubmarinePairsResponse, isGetReversePairsResponse, isCreateSubmarineSwapResponse, isGetSwapPreimageResponse, isCreateReverseSwapResponse, isRefundSubmarineSwapResponse, isRefundChainSwapResponse, isGetChainPairsResponse, isSwapTree, isChainSwapDetailsResponse, isCreateChainSwapResponse, isGetChainClaimDetailsResponse, isPostChainClaimDetailsResponse, isGetChainQuoteResponse, isPostChainQuoteResponse, isPostBtcTransactionResponse, isLeaf, isTree, isDetails, isRestoredChainSwap, isRestoredSubmarineSwap, isRestoredReverseSwap, isCreateSwapsRestoreResponse, BASE_URLS, BoltzSwapProvider;
+var import_sdk, import_base, isSubmarineFinalStatus, isSubmarineRefundableStatus, isSubmarineSuccessStatus, isReverseFinalStatus, isReverseClaimableStatus, isChainClaimableStatus, isChainFinalStatus, isChainRefundableStatus, isChainSignableStatus, isPendingReverseSwap, isPendingSubmarineSwap, isPendingChainSwap, isSubmarineSwapRefundable, isTimeoutBlockHeights, isGetReverseSwapTxIdResponse, isGetSwapStatusResponse, isGetSubmarinePairsResponse, isGetReversePairsResponse, isCreateSubmarineSwapResponse, isGetSwapPreimageResponse, isCreateReverseSwapResponse, isRefundSubmarineSwapResponse, isRefundChainSwapResponse, isGetChainPairsResponse, isSwapTree, isChainSwapDetailsResponse, isCreateChainSwapResponse, isGetChainClaimDetailsResponse, isPostChainClaimDetailsResponse, isGetChainQuoteResponse, isPostChainQuoteResponse, isPostBtcTransactionResponse, isLeaf, isTree, isDetails, isRestoredChainSwap, isRestoredSubmarineSwap, isRestoredReverseSwap, isCreateSwapsRestoreResponse, BASE_URLS, BoltzSwapProvider;
 var init_boltz_swap_provider = __esm({
   "src/boltz-swap-provider.ts"() {
     "use strict";
@@ -139,6 +139,9 @@ var init_boltz_swap_provider = __esm({
         "swap.expired"
       ].includes(status);
     };
+    isSubmarineSuccessStatus = (status) => {
+      return status === "transaction.claimed";
+    };
     isReverseFinalStatus = (status) => {
       return [
         "transaction.refunded",
@@ -2672,7 +2675,7 @@ var init_batch = __esm({
 function scriptFromTapLeafScript(leaf) {
   return leaf[1].subarray(0, leaf[1].length - 1);
 }
-var import_sdk7, import_base8, import_legacy, import_btc_signer4, import_payment3, createVHTLCScript, joinBatch, claimVHTLCwithOffchainTx, refundVHTLCwithOffchainTx;
+var import_sdk7, import_base8, import_legacy, import_btc_signer4, import_payment3, toBip68RelativeTimelock, createVHTLCScript, joinBatch, claimVHTLCwithOffchainTx, refundVHTLCwithOffchainTx;
 var init_vhtlc = __esm({
   "src/utils/vhtlc.ts"() {
     "use strict";
@@ -2685,6 +2688,10 @@ var init_vhtlc = __esm({
     import_btc_signer4 = require("@scure/btc-signer");
     import_payment3 = require("@scure/btc-signer/payment.js");
     init_signatures();
+    toBip68RelativeTimelock = (value) => ({
+      type: value < 512 ? "blocks" : "seconds",
+      value: BigInt(value)
+    });
     createVHTLCScript = (args) => {
       const {
         network,
@@ -2692,7 +2699,7 @@ var init_vhtlc = __esm({
         receiverPubkey,
         senderPubkey,
         serverPubkey,
-        timeoutBlockHeights
+        timeoutBlockHeights: vhtlcTimeouts
       } = args;
       const receiverXOnlyPublicKey = normalizeToXOnlyKey(
         import_base8.hex.decode(receiverPubkey),
@@ -2706,27 +2713,21 @@ var init_vhtlc = __esm({
         import_base8.hex.decode(serverPubkey),
         "server"
       );
-      const delayType = (num) => num < 512 ? "blocks" : "seconds";
       const vhtlcScript = new import_sdk7.VHTLC.Script({
         preimageHash: (0, import_legacy.ripemd160)(preimageHash),
         sender: senderXOnlyPublicKey,
         receiver: receiverXOnlyPublicKey,
         server: serverXOnlyPublicKey,
-        refundLocktime: BigInt(timeoutBlockHeights.refund),
-        unilateralClaimDelay: {
-          type: delayType(timeoutBlockHeights.unilateralClaim),
-          value: BigInt(timeoutBlockHeights.unilateralClaim)
-        },
-        unilateralRefundDelay: {
-          type: delayType(timeoutBlockHeights.unilateralRefund),
-          value: BigInt(timeoutBlockHeights.unilateralRefund)
-        },
-        unilateralRefundWithoutReceiverDelay: {
-          type: delayType(
-            timeoutBlockHeights.unilateralRefundWithoutReceiver
-          ),
-          value: BigInt(timeoutBlockHeights.unilateralRefundWithoutReceiver)
-        }
+        refundLocktime: BigInt(vhtlcTimeouts.refund),
+        unilateralClaimDelay: toBip68RelativeTimelock(
+          vhtlcTimeouts.unilateralClaim
+        ),
+        unilateralRefundDelay: toBip68RelativeTimelock(
+          vhtlcTimeouts.unilateralRefund
+        ),
+        unilateralRefundWithoutReceiverDelay: toBip68RelativeTimelock(
+          vhtlcTimeouts.unilateralRefundWithoutReceiver
+        )
       });
       if (!vhtlcScript.claimScript)
         throw new Error("Failed to create VHTLC script");
@@ -2964,7 +2965,7 @@ var init_vhtlc = __esm({
 });
 
 // src/arkade-swaps.ts
-var import_sdk8, import_sha23, import_base9, import_secp256k13, import_utils3, import_btc_signer5, import_utils4, CLAIM_VTXO_RETRY_ATTEMPTS, CLAIM_VTXO_RETRY_DELAY_MS, ArkadeSwaps;
+var import_sdk8, import_sha23, import_base9, import_secp256k13, import_utils3, import_btc_signer5, import_utils4, dedupeVtxos, hasNonEmptyString, canRecoverViaBoltz3of3, isSubmarineRefundLocktimeReached, CLAIM_VTXO_RETRY_ATTEMPTS, CLAIM_VTXO_RETRY_DELAY_MS, ArkadeSwaps;
 var init_arkade_swaps = __esm({
   "src/arkade-swaps.ts"() {
     "use strict";
@@ -2988,6 +2989,20 @@ var init_arkade_swaps = __esm({
     init_swap_repository();
     init_identity();
     init_vhtlc();
+    dedupeVtxos = (vtxos) => [
+      ...new Map(
+        vtxos.map((vtxo) => [`${vtxo.txid}:${vtxo.vout}`, vtxo])
+      ).values()
+    ];
+    hasNonEmptyString = (value) => typeof value === "string" && value.length > 0;
+    canRecoverViaBoltz3of3 = (refundableVtxos, swap) => {
+      const hasRequiredSwapMetadata = hasNonEmptyString(swap.id) && hasNonEmptyString(swap.request.refundPublicKey) && hasNonEmptyString(swap.response.address) && hasNonEmptyString(swap.response.claimPublicKey) && !!swap.response.timeoutBlockHeights;
+      if (!hasRequiredSwapMetadata) return false;
+      return refundableVtxos.some(
+        (vtxo) => !vtxo.isSpent && !(0, import_sdk8.isRecoverable)(vtxo)
+      );
+    };
+    isSubmarineRefundLocktimeReached = (refundTimestamp) => Math.floor(Date.now() / 1e3) >= refundTimestamp;
     CLAIM_VTXO_RETRY_ATTEMPTS = 3;
     CLAIM_VTXO_RETRY_DELAY_MS = 500;
     ArkadeSwaps = class _ArkadeSwaps {
@@ -3255,8 +3270,12 @@ var init_arkade_swaps = __esm({
           throw new Error(
             `Swap ${pendingSwap.id}: preimage is required to claim VHTLC`
           );
-        const { refundPublicKey, lockupAddress, timeoutBlockHeights } = pendingSwap.response;
-        if (!refundPublicKey || !lockupAddress || !timeoutBlockHeights)
+        const {
+          refundPublicKey,
+          lockupAddress,
+          timeoutBlockHeights: vhtlcTimeouts
+        } = pendingSwap.response;
+        if (!refundPublicKey || !lockupAddress || !vhtlcTimeouts)
           throw new Error(
             `Swap ${pendingSwap.id}: incomplete reverse swap response`
           );
@@ -3284,7 +3303,7 @@ var init_arkade_swaps = __esm({
           receiverPubkey: import_base9.hex.encode(receiverXOnly),
           senderPubkey: import_base9.hex.encode(senderXOnly),
           serverPubkey: import_base9.hex.encode(serverXOnly),
-          timeoutBlockHeights
+          timeoutBlockHeights: vhtlcTimeouts
         });
         if (!vhtlcScript.claimScript)
           throw new Error(
@@ -3512,84 +3531,184 @@ var init_arkade_swaps = __esm({
         return pendingSwap;
       }
       /**
-       * 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.
-       * @throws {Error} If preimage hash is unavailable, VHTLC not found, or already spent.
+       * 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.
        */
-      async refundVHTLC(pendingSwap) {
-        const preimageHash = pendingSwap.request.invoice ? getInvoicePaymentHash(pendingSwap.request.invoice) : pendingSwap.preimageHash;
+      async buildSubmarineVHTLCContext(swap, arkInfo) {
+        const preimageHash = swap.request.invoice ? getInvoicePaymentHash(swap.request.invoice) : swap.preimageHash;
         if (!preimageHash)
           throw new Error(
-            `Swap ${pendingSwap.id}: preimage hash is required to refund VHTLC`
+            `Swap ${swap.id}: preimage hash is required to refund VHTLC`
           );
-        const arkInfo = await this.arkProvider.getInfo();
-        const address = await this.wallet.getAddress();
-        if (!address) throw new Error("Failed to get ark address from wallet");
+        const resolvedArkInfo = arkInfo ?? await this.arkProvider.getInfo();
         const ourXOnlyPublicKey = normalizeToXOnlyKey(
           await this.wallet.identity.xOnlyPublicKey(),
           "our",
-          pendingSwap.id
+          swap.id
         );
         const serverXOnlyPublicKey = normalizeToXOnlyKey(
-          import_base9.hex.decode(arkInfo.signerPubkey),
+          import_base9.hex.decode(resolvedArkInfo.signerPubkey),
           "server",
-          pendingSwap.id
+          swap.id
         );
-        const { claimPublicKey, timeoutBlockHeights } = pendingSwap.response;
-        if (!claimPublicKey || !timeoutBlockHeights)
+        const { claimPublicKey, timeoutBlockHeights: vhtlcTimeouts } = swap.response;
+        if (!claimPublicKey || !vhtlcTimeouts)
           throw new Error(
-            `Swap ${pendingSwap.id}: incomplete submarine swap response`
+            `Swap ${swap.id}: incomplete submarine swap response`
           );
         const boltzXOnlyPublicKey = normalizeToXOnlyKey(
           import_base9.hex.decode(claimPublicKey),
           "boltz",
-          pendingSwap.id
+          swap.id
         );
         const { vhtlcScript, vhtlcAddress } = this.createVHTLCScript({
-          network: arkInfo.network,
+          network: resolvedArkInfo.network,
           preimageHash: import_base9.hex.decode(preimageHash),
           receiverPubkey: import_base9.hex.encode(boltzXOnlyPublicKey),
           senderPubkey: import_base9.hex.encode(ourXOnlyPublicKey),
           serverPubkey: import_base9.hex.encode(serverXOnlyPublicKey),
-          timeoutBlockHeights
+          timeoutBlockHeights: vhtlcTimeouts
         });
         if (!vhtlcScript.claimScript)
           throw new Error(
-            `Swap ${pendingSwap.id}: failed to create VHTLC script for submarine swap`
+            `Swap ${swap.id}: failed to create VHTLC script for submarine swap`
           );
-        if (vhtlcAddress !== pendingSwap.response.address)
+        if (vhtlcAddress !== swap.response.address)
           throw new Error(
-            `VHTLC address mismatch for swap ${pendingSwap.id}: expected ${pendingSwap.response.address}, got ${vhtlcAddress}`
+            `VHTLC address mismatch for swap ${swap.id}: expected ${swap.response.address}, got ${vhtlcAddress}`
           );
         const vhtlcPkScriptHex = import_base9.hex.encode(vhtlcScript.pkScript);
+        return {
+          arkInfo: resolvedArkInfo,
+          vhtlcScript,
+          vhtlcAddress,
+          vhtlcPkScriptHex,
+          vhtlcTimeouts,
+          ourXOnlyPublicKey,
+          serverXOnlyPublicKey,
+          boltzXOnlyPublicKey
+        };
+      }
+      /**
+       * 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".
+       */
+      async lookupSubmarineVHTLC(swap, arkInfo) {
+        const context = await this.buildSubmarineVHTLCContext(swap, arkInfo);
         const [spendableResult, recoverableResult] = await Promise.all([
           this.indexerProvider.getVtxos({
-            scripts: [vhtlcPkScriptHex],
+            scripts: [context.vhtlcPkScriptHex],
             spendableOnly: true
           }),
           this.indexerProvider.getVtxos({
-            scripts: [vhtlcPkScriptHex],
+            scripts: [context.vhtlcPkScriptHex],
             recoverableOnly: true
           })
         ]);
-        const refundableVtxos = [
-          ...new Map(
-            [...spendableResult.vtxos, ...recoverableResult.vtxos].map(
-              (vtxo) => [`${vtxo.txid}:${vtxo.vout}`, vtxo]
-            )
-          ).values()
-        ];
+        const refundableVtxos = dedupeVtxos([
+          ...spendableResult.vtxos,
+          ...recoverableResult.vtxos
+        ]);
+        let diagnostic;
         if (refundableVtxos.length === 0) {
           const { vtxos: allVtxos } = await this.indexerProvider.getVtxos({
-            scripts: [vhtlcPkScriptHex]
+            scripts: [context.vhtlcPkScriptHex]
           });
-          if (allVtxos.length === 0) {
+          diagnostic = {
+            totalVtxoCount: allVtxos.length,
+            allSpent: allVtxos.length > 0 && allVtxos.every((vtxo) => vtxo.isSpent)
+          };
+        }
+        return {
+          ...context,
+          refundableVtxos,
+          diagnostic
+        };
+      }
+      submarineRecoveryInfoFromLookup(swap, lookup) {
+        const { refundableVtxos, diagnostic, vhtlcTimeouts } = lookup;
+        if (refundableVtxos.length > 0) {
+          const cltvSatisfied = isSubmarineRefundLocktimeReached(
+            vhtlcTimeouts.refund
+          );
+          const amountSats = refundableVtxos.reduce(
+            (sum, vtxo) => sum + Number(vtxo.value),
+            0
+          );
+          const isRecoverable2 = cltvSatisfied || canRecoverViaBoltz3of3(refundableVtxos, swap);
+          return {
+            swap,
+            status: isRecoverable2 ? "recoverable" : "pre_cltv",
+            vtxoCount: refundableVtxos.length,
+            amountSats,
+            refundLocktime: vhtlcTimeouts.refund
+          };
+        }
+        if (!diagnostic || diagnostic.totalVtxoCount === 0) {
+          return {
+            swap,
+            status: "none",
+            vtxoCount: 0,
+            amountSats: 0,
+            refundLocktime: vhtlcTimeouts.refund
+          };
+        }
+        if (diagnostic.allSpent) {
+          return {
+            swap,
+            status: "already_spent",
+            vtxoCount: 0,
+            amountSats: 0,
+            refundLocktime: vhtlcTimeouts.refund
+          };
+        }
+        return {
+          swap,
+          status: "none",
+          vtxoCount: 0,
+          amountSats: 0,
+          refundLocktime: vhtlcTimeouts.refund
+        };
+      }
+      /**
+       * 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.
+       */
+      async refundVHTLC(pendingSwap, cachedArkInfo) {
+        const address = await this.wallet.getAddress();
+        if (!address) throw new Error("Failed to get ark address from wallet");
+        const {
+          arkInfo,
+          vhtlcScript,
+          vhtlcTimeouts,
+          ourXOnlyPublicKey,
+          serverXOnlyPublicKey,
+          boltzXOnlyPublicKey,
+          refundableVtxos,
+          diagnostic
+        } = await this.lookupSubmarineVHTLC(pendingSwap, cachedArkInfo);
+        if (refundableVtxos.length === 0) {
+          if (!diagnostic || diagnostic.totalVtxoCount === 0) {
             throw new Error(
               `Swap ${pendingSwap.id}: VHTLC not found for address ${pendingSwap.response.address}`
             );
           }
-          if (allVtxos.every((vtxo) => vtxo.isSpent)) {
+          if (diagnostic.allSpent) {
             throw new Error(
               `Swap ${pendingSwap.id}: VHTLC is already spent`
             );
@@ -3600,10 +3719,11 @@ var init_arkade_swaps = __esm({
         }
         const outputScript = import_sdk8.ArkAddress.decode(address).pkScript;
         const refundWithoutReceiverLeaf = vhtlcScript.refundWithoutReceiver();
-        const refundLocktime = BigInt(timeoutBlockHeights.refund);
-        const currentBlockHeight = await this.swapProvider.getChainHeight();
-        const cltvSatisfied = BigInt(currentBlockHeight) >= refundLocktime;
+        const cltvSatisfied = isSubmarineRefundLocktimeReached(
+          vhtlcTimeouts.refund
+        );
         let boltzCallCount = 0;
+        let sweptCount = 0;
         let skippedCount = 0;
         for (const vtxo of refundableVtxos) {
           const isRecoverableVtxo = (0, import_sdk8.isRecoverable)(vtxo);
@@ -3624,11 +3744,12 @@ var init_arkade_swaps = __esm({
               arkInfo,
               isRecoverableVtxo
             );
+            sweptCount++;
             continue;
           }
           if (isRecoverableVtxo) {
             logger.error(
-              `Swap ${pendingSwap.id}: recoverable VTXO ${vtxo.txid}:${vtxo.vout} cannot be refunded yet \u2014 refundWithoutReceiver locktime has not passed (refundLocktime=${timeoutBlockHeights.refund}, currentBlockHeight=${currentBlockHeight}). Refund will be retried after locktime.`
+              `Swap ${pendingSwap.id}: recoverable VTXO ${vtxo.txid}:${vtxo.vout} cannot be refunded yet \u2014 refundWithoutReceiver locktime has not passed (refundLocktime=${vhtlcTimeouts.refund}, currentTimestamp=${Math.floor(Date.now() / 1e3)}). Refund will be retried after locktime.`
             );
             skippedCount++;
             continue;
@@ -3657,14 +3778,14 @@ var init_arkade_swaps = __esm({
               )
             );
             boltzCallCount++;
+            sweptCount++;
           } catch (error) {
             if (!(error instanceof BoltzRefundError)) {
               throw error;
             }
-            const tipNow = await this.swapProvider.getChainHeight();
-            if (BigInt(tipNow) < refundLocktime) {
+            if (!isSubmarineRefundLocktimeReached(vhtlcTimeouts.refund)) {
               logger.error(
-                `Swap ${pendingSwap.id}: Boltz rejected VTXO outpoint and refundWithoutReceiver locktime has not passed yet (currentBlockHeight=${tipNow}, locktime=${timeoutBlockHeights.refund}). Refund will be retried after locktime.`
+                `Swap ${pendingSwap.id}: Boltz rejected VTXO outpoint and refundWithoutReceiver locktime has not passed yet (currentTimestamp=${Math.floor(Date.now() / 1e3)}, locktime=${vhtlcTimeouts.refund}). Refund will be retried after locktime.`
               );
               skippedCount++;
               continue;
@@ -3684,16 +3805,218 @@ var init_arkade_swaps = __esm({
               arkInfo,
               false
             );
+            sweptCount++;
           }
         }
-        const fullyRefunded = skippedCount === 0;
-        await updateSubmarineSwapStatus(
-          pendingSwap,
-          pendingSwap.status,
-          // Keep current status
-          this.savePendingSubmarineSwap.bind(this),
-          { refundable: true, refunded: fullyRefunded }
+        if (!isSubmarineSuccessStatus(pendingSwap.status)) {
+          const fullyRefunded = skippedCount === 0;
+          await updateSubmarineSwapStatus(
+            pendingSwap,
+            pendingSwap.status,
+            // Keep current status
+            this.savePendingSubmarineSwap.bind(this),
+            { refundable: true, refunded: fullyRefunded }
+          );
+        }
+        return { swept: sweptCount, skipped: skippedCount };
+      }
+      /**
+       * 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.
+       */
+      async inspectSubmarineRecovery(swap) {
+        if (!isSubmarineSuccessStatus(swap.status) && !isSubmarineRefundableStatus(swap.status)) {
+          return {
+            swap,
+            status: "invalid_swap",
+            vtxoCount: 0,
+            amountSats: 0,
+            refundLocktime: swap.response.timeoutBlockHeights?.refund,
+            error: `Swap status ${swap.status} is not a recovery candidate`
+          };
+        }
+        let lookup;
+        try {
+          lookup = await this.lookupSubmarineVHTLC(swap);
+        } catch (err) {
+          return {
+            swap,
+            status: "invalid_swap",
+            vtxoCount: 0,
+            amountSats: 0,
+            refundLocktime: swap.response.timeoutBlockHeights?.refund,
+            error: err instanceof Error ? err.message : String(err)
+          };
+        }
+        return this.submarineRecoveryInfoFromLookup(swap, lookup);
+      }
+      /**
+       * 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.
+       */
+      async scanRecoverableSubmarineSwaps() {
+        const submarineSwaps = await this.swapRepository.getAllSwaps({
+          type: "submarine"
+        });
+        const candidates = submarineSwaps.filter(
+          (swap) => isSubmarineSuccessStatus(swap.status) || isSubmarineRefundableStatus(swap.status)
+        );
+        let arkInfo;
+        let arkInfoError;
+        if (candidates.length > 0) {
+          try {
+            arkInfo = await this.arkProvider.getInfo();
+          } catch (err) {
+            arkInfoError = err instanceof Error ? err.message : String(err);
+          }
+        }
+        const prepared = await Promise.all(
+          candidates.map(async (swap) => {
+            if (arkInfoError) {
+              return {
+                swap,
+                error: arkInfoError
+              };
+            }
+            try {
+              return {
+                swap,
+                context: await this.buildSubmarineVHTLCContext(
+                  swap,
+                  arkInfo
+                )
+              };
+            } catch (err) {
+              return {
+                swap,
+                error: err instanceof Error ? err.message : String(err)
+              };
+            }
+          })
+        );
+        const valid = prepared.filter(
+          (item) => "context" in item
         );
+        const scripts = [
+          ...new Set(valid.map(({ context }) => context.vhtlcPkScriptHex))
+        ];
+        const refundableByScript = /* @__PURE__ */ new Map();
+        if (scripts.length > 0) {
+          const [spendableResult, recoverableResult] = await Promise.all([
+            this.indexerProvider.getVtxos({
+              scripts,
+              spendableOnly: true
+            }),
+            this.indexerProvider.getVtxos({
+              scripts,
+              recoverableOnly: true
+            })
+          ]);
+          for (const vtxo of dedupeVtxos([
+            ...spendableResult.vtxos,
+            ...recoverableResult.vtxos
+          ])) {
+            const script = vtxo.script?.toLowerCase();
+            if (!script) continue;
+            const existing = refundableByScript.get(script) ?? [];
+            existing.push(vtxo);
+            refundableByScript.set(script, existing);
+          }
+        }
+        return prepared.map((item) => {
+          if ("error" in item) {
+            return {
+              swap: item.swap,
+              status: "invalid_swap",
+              vtxoCount: 0,
+              amountSats: 0,
+              refundLocktime: item.swap.response.timeoutBlockHeights?.refund,
+              error: item.error
+            };
+          }
+          const refundableVtxos = refundableByScript.get(
+            item.context.vhtlcPkScriptHex.toLowerCase()
+          ) ?? [];
+          return this.submarineRecoveryInfoFromLookup(item.swap, {
+            ...item.context,
+            refundableVtxos
+          });
+        });
+      }
+      /**
+       * 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).
+       */
+      async recoverSubmarineFunds(swap, arkInfo) {
+        return this.refundVHTLC(swap, arkInfo);
+      }
+      /**
+       * 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.
+       */
+      async recoverAllSubmarineFunds(swaps) {
+        const results = [];
+        let arkInfo;
+        try {
+          if (swaps.length > 0) {
+            arkInfo = await this.arkProvider.getInfo();
+          }
+        } catch (err) {
+          const error = err instanceof Error ? err.message : String(err);
+          return swaps.map((swap) => ({
+            swapId: swap.id,
+            recovered: false,
+            skipped: false,
+            error
+          }));
+        }
+        for (const swap of swaps) {
+          try {
+            const outcome = await this.recoverSubmarineFunds(swap, arkInfo);
+            results.push({
+              swapId: swap.id,
+              recovered: outcome.swept > 0,
+              skipped: outcome.skipped > 0
+            });
+          } catch (err) {
+            results.push({
+              swapId: swap.id,
+              recovered: false,
+              skipped: false,
+              error: err instanceof Error ? err.message : String(err)
+            });
+          }
+        }
+        return results;
       }
       /**
        * Waits for a submarine swap's Lightning payment to settle.
@@ -4475,14 +4798,14 @@ var init_arkade_swaps = __esm({
         const serverPubkey = import_base9.hex.encode(
           normalizeToXOnlyKey(arkInfo.signerPubkey, "server")
         );
-        const timeoutBlockHeights = to === "ARK" ? swap.response.claimDetails.timeouts : swap.response.lockupDetails.timeouts;
+        const vhtlcTimeouts = to === "ARK" ? swap.response.claimDetails.timeouts : swap.response.lockupDetails.timeouts;
         const { vhtlcAddress } = this.createVHTLCScript({
           network: arkInfo.network,
           preimageHash: import_base9.hex.decode(swap.request.preimageHash),
           receiverPubkey,
           senderPubkey,
           serverPubkey,
-          timeoutBlockHeights
+          timeoutBlockHeights: vhtlcTimeouts
         });
         if (lockupAddress !== vhtlcAddress) {
           throw new SwapError({
@@ -5262,6 +5585,18 @@ var ExpoArkadeSwaps = class _ExpoArkadeSwaps {
   refundVHTLC(pendingSwap) {
     return this.inner.refundVHTLC(pendingSwap);
   }
+  inspectSubmarineRecovery(swap) {
+    return this.inner.inspectSubmarineRecovery(swap);
+  }
+  scanRecoverableSubmarineSwaps() {
+    return this.inner.scanRecoverableSubmarineSwaps();
+  }
+  recoverSubmarineFunds(swap) {
+    return this.inner.recoverSubmarineFunds(swap);
+  }
+  recoverAllSubmarineFunds(swaps) {
+    return this.inner.recoverAllSubmarineFunds(swaps);
+  }
   waitAndClaim(pendingSwap) {
     return this.inner.waitAndClaim(pendingSwap);
   }