@arkade-os/boltz-swap 0.3.49 → 0.3.51

package/dist/repositories/sqlite/index.cjs

@@ -35,6 +35,7 @@ var SQLiteSwapRepository = class {
   constructor(executor) {
     this.executor = executor;
   }
+  executor;
   version = 1;
   initPromise = null;
   // ── Lifecycle ──────────────────────────────────────────────────────

package/dist/repositories/sqlite/index.d.cts

@@ -1,5 +1,5 @@
 import { SQLExecutor } from '@arkade-os/sdk/repositories/sqlite';
-import { m as SwapRepository, B as BoltzSwap, p as GetSwapsFilter } from '../../types-BKEkNZxK.cjs';
+import { m as SwapRepository, B as BoltzSwap, p as GetSwapsFilter } from '../../types-Db4JSdjk.cjs';
 import '@arkade-os/sdk';
 
 /**

package/dist/repositories/sqlite/index.d.ts

@@ -1,5 +1,5 @@
 import { SQLExecutor } from '@arkade-os/sdk/repositories/sqlite';
-import { m as SwapRepository, B as BoltzSwap, p as GetSwapsFilter } from '../../types-BKEkNZxK.js';
+import { m as SwapRepository, B as BoltzSwap, p as GetSwapsFilter } from '../../types-Db4JSdjk.js';
 import '@arkade-os/sdk';
 
 /**

package/dist/repositories/sqlite/index.js

@@ -7,6 +7,7 @@ var SQLiteSwapRepository = class {
   constructor(executor) {
     this.executor = executor;
   }
+  executor;
   version = 1;
   initPromise = null;
   // ── Lifecycle ──────────────────────────────────────────────────────

package/dist/{swapsPollProcessor-C4HQHP9Z.d.ts → swapsPollProcessor--BPV48QB.d.ts}

@@ -1,6 +1,6 @@
 import { AsyncStorageTaskQueue, TaskProcessor } from '@arkade-os/sdk/worker/expo';
 import { Identity, ArkProvider, IndexerProvider, IWallet } from '@arkade-os/sdk';
-import { m as SwapRepository, N as Network, r as BoltzSwapProvider, A as ArkadeSwapsConfig } from './types-BKEkNZxK.js';
+import { m as SwapRepository, N as Network, r as BoltzSwapProvider, A as ArkadeSwapsConfig } from './types-Db4JSdjk.js';
 
 /**
  * Dependencies injected into every swap processor at runtime.

package/dist/{swapsPollProcessor-CIqTFkV1.d.cts → swapsPollProcessor-DCtJYSbJ.d.cts}

@@ -1,6 +1,6 @@
 import { AsyncStorageTaskQueue, TaskProcessor } from '@arkade-os/sdk/worker/expo';
 import { Identity, ArkProvider, IndexerProvider, IWallet } from '@arkade-os/sdk';
-import { m as SwapRepository, N as Network, r as BoltzSwapProvider, A as ArkadeSwapsConfig } from './types-BKEkNZxK.cjs';
+import { m as SwapRepository, N as Network, r as BoltzSwapProvider, A as ArkadeSwapsConfig } from './types-Db4JSdjk.cjs';
 
 /**
  * Dependencies injected into every swap processor at runtime.

package/dist/{types-BKEkNZxK.d.cts → types-Db4JSdjk.d.cts}

@@ -499,7 +499,14 @@ interface SwapManagerClient {
 /** Internal callbacks wired by ArkadeSwaps to perform claim/refund/save operations. */
 interface SwapManagerCallbacks {
     claim: (swap: BoltzReverseSwap) => Promise<void>;
-    refund: (swap: BoltzSubmarineSwap) => Promise<void>;
+    /**
+     * Refund a submarine swap's VHTLC.
+     *
+     * Returns the outcome so the manager can re-arm a deferred refund: every
+     * refundable submarine status except `transaction.lockupFailed` is also
+     * final, so Boltz sends no further update to re-trigger one.
+     */
+    refund: (swap: BoltzSubmarineSwap) => Promise<SubmarineRefundOutcome>;
     /**
      * Claim the ARK side of a BTC→ARK chain swap.
      *
@@ -541,12 +548,20 @@ declare class SwapManager implements SwapManagerClient {
      */
     private static readonly NOT_FOUND_THRESHOLD;
     /**
-     * Delay between re-attempts of a chain refund that left VTXOs deferred
-     * (e.g. pre-CLTV recoverable VTXO, or Boltz 3-of-3 rejected before CLTV
-     * has elapsed). Boltz won't send another status update once the swap
-     * is `swap.expired`, so the manager owns the local retry cadence.
+     * Floor on the delay between re-attempts of a refund that left VTXOs
+     * deferred, and the delay used when the outcome names no retry time. Boltz
+     * won't send another status update once the swap is refundable-and-final,
+     * so the manager owns the local retry cadence.
      */
     private static readonly REFUND_RETRY_DELAY_MS;
+    /**
+     * Ceiling on that delay. A deferral can be hours out (a pre-CLTV VTXO waits
+     * out the whole refund locktime), and `setTimeout` fires *immediately* past
+     * its 32-bit millisecond range, so long waits are broken into re-armed
+     * hops. Re-attempting costs an indexer lookup and re-defers, which also lets
+     * the cadence recover from a suspended device or a clock jump.
+     */
+    private static readonly MAX_REFUND_RETRY_DELAY_MS;
     private readonly swapProvider;
     private readonly config;
     private swapUpdateListeners;
@@ -744,15 +759,35 @@ declare class SwapManager implements SwapManagerClient {
      * chain refund has finished its remaining work).
      */
     private finalizeMonitoredSwap;
+    private static isRefundRetryableSwap;
+    private static hasPendingRefundRetry;
+    private shouldMonitorOnStart;
+    /**
+     * How long to wait before re-attempting a refund, given the `retryAt`
+     * (Unix seconds) the outcome reported. Clamped at both ends: see
+     * {@link SwapManager.REFUND_RETRY_DELAY_MS} and
+     * {@link SwapManager.MAX_REFUND_RETRY_DELAY_MS}.
+     */
+    private static refundRetryDelayMs;
+    private static persistedRefundRetryDelayMs;
+    private static nextRefundRetryAt;
+    private clearRefundRetry;
+    private resumePersistedRefundRetries;
     /**
-     * Schedule another `executeAutonomousAction` run for a chain swap whose
-     * refund left VTXOs deferred. After the retry completes, if no further
-     * deferral was reported, finalize monitoring cleanup.
+     * Schedule another `executeAutonomousAction` run for a swap whose refund
+     * left VTXOs deferred. The pending retry and its next attempt time are saved
+     * with the swap so stop/start and application restart can re-arm it.
      */
     private scheduleRefundRetry;
+    private armRefundRetryTimer;
     /**
      * Execute autonomous action based on swap status
      * Uses locking to prevent race conditions with manual operations
+     *
+     * @returns `false` when another action for this swap already held the lock
+     * and this call did nothing, `true` when it ran. Callers that finalize on
+     * the result must not act on `false`: the in-flight action owns the swap's
+     * outcome and will re-arm or finalize from its own result.
      */
     private executeAutonomousAction;
     /**
@@ -761,6 +796,8 @@ declare class SwapManager implements SwapManagerClient {
     private executeClaimAction;
     /**
      * Execute refund action for submarine swap
+     *
+     * @returns The refund outcome, or `undefined` if no callback is wired.
      */
     private executeRefundAction;
     /**
@@ -991,6 +1028,13 @@ interface OptimisticSendLightningPaymentResponse {
     /** Transaction ID of the Arkade payment. */
     txid: string;
 }
+/** Persisted state for a locally deferred refund retry. */
+interface RefundRetryState {
+    /** True while SwapManager still needs to retry the local refund path. */
+    pending: true;
+    /** Unix timestamp (seconds) for the next retry attempt. */
+    nextRetryAt: number;
+}
 /** Tracks an in-progress reverse swap (Lightning → Arkade). */
 interface BoltzReverseSwap {
     /** Unique swap ID from Boltz. */
@@ -1024,6 +1068,8 @@ interface BoltzSubmarineSwap {
     refunded?: boolean;
     /** Whether the swap is eligible for refund. */
     refundable?: boolean;
+    /** Deferred local refund retry state, if any. */
+    refundRetry?: RefundRetryState;
     /** Current Boltz swap status. */
     status: BoltzSwapStatus;
     /** The original request sent to Boltz. */
@@ -1067,6 +1113,15 @@ interface SubmarineRecoveryInfo {
     /** Reason populated when `status === "invalid_swap"`. */
     error?: string;
 }
+/**
+ * Earliest Unix timestamp (seconds) at which retrying the deferred VTXOs could
+ * make progress, or `undefined` when nothing was deferred. Deferrals do not all
+ * last the same time — a server-side CLTV rejection clears as soon as a later
+ * block carries the locktime, whereas a pre-CLTV VTXO must wait out the whole
+ * refund locktime — so callers schedule from this instead of polling at a fixed
+ * interval. It is a lower bound, not a promise: a retry may defer again.
+ */
+type RefundRetryAt = number | undefined;
 /** Outcome of a single `refundVHTLC` call: how many VTXOs were swept vs. deferred. */
 interface SubmarineRefundOutcome {
     /** Number of VTXOs successfully refunded (joined a batch or via Boltz co-sign). */
@@ -1077,6 +1132,8 @@ interface SubmarineRefundOutcome {
      * is expected to retry these later.
      */
     skipped: number;
+    /** When a retry could first succeed; see {@link RefundRetryAt}. */
+    retryAt?: RefundRetryAt;
 }
 /** Outcome of a single `refundArk` call: how many VTXOs were swept vs. deferred. */
 interface ChainArkRefundOutcome {
@@ -1088,6 +1145,8 @@ interface ChainArkRefundOutcome {
      * is expected to retry these later.
      */
     skipped: number;
+    /** When a retry could first succeed; see {@link RefundRetryAt}. */
+    retryAt?: RefundRetryAt;
 }
 /** Per-swap outcome of a bulk recovery call. */
 interface SubmarineRecoveryResult {
@@ -1120,6 +1179,8 @@ interface BoltzChainSwap {
     feeSatsPerByte: number;
     /** Current Boltz swap status. */
     status: BoltzSwapStatus;
+    /** Deferred local ARK refund retry state, if any. */
+    refundRetry?: RefundRetryState;
     /** The original chain swap request sent to Boltz. */
     request: CreateChainSwapRequest;
     /** Boltz API response with lockup and claim details. */

package/dist/{types-BKEkNZxK.d.ts → types-Db4JSdjk.d.ts}

@@ -499,7 +499,14 @@ interface SwapManagerClient {
 /** Internal callbacks wired by ArkadeSwaps to perform claim/refund/save operations. */
 interface SwapManagerCallbacks {
     claim: (swap: BoltzReverseSwap) => Promise<void>;
-    refund: (swap: BoltzSubmarineSwap) => Promise<void>;
+    /**
+     * Refund a submarine swap's VHTLC.
+     *
+     * Returns the outcome so the manager can re-arm a deferred refund: every
+     * refundable submarine status except `transaction.lockupFailed` is also
+     * final, so Boltz sends no further update to re-trigger one.
+     */
+    refund: (swap: BoltzSubmarineSwap) => Promise<SubmarineRefundOutcome>;
     /**
      * Claim the ARK side of a BTC→ARK chain swap.
      *
@@ -541,12 +548,20 @@ declare class SwapManager implements SwapManagerClient {
      */
     private static readonly NOT_FOUND_THRESHOLD;
     /**
-     * Delay between re-attempts of a chain refund that left VTXOs deferred
-     * (e.g. pre-CLTV recoverable VTXO, or Boltz 3-of-3 rejected before CLTV
-     * has elapsed). Boltz won't send another status update once the swap
-     * is `swap.expired`, so the manager owns the local retry cadence.
+     * Floor on the delay between re-attempts of a refund that left VTXOs
+     * deferred, and the delay used when the outcome names no retry time. Boltz
+     * won't send another status update once the swap is refundable-and-final,
+     * so the manager owns the local retry cadence.
      */
     private static readonly REFUND_RETRY_DELAY_MS;
+    /**
+     * Ceiling on that delay. A deferral can be hours out (a pre-CLTV VTXO waits
+     * out the whole refund locktime), and `setTimeout` fires *immediately* past
+     * its 32-bit millisecond range, so long waits are broken into re-armed
+     * hops. Re-attempting costs an indexer lookup and re-defers, which also lets
+     * the cadence recover from a suspended device or a clock jump.
+     */
+    private static readonly MAX_REFUND_RETRY_DELAY_MS;
     private readonly swapProvider;
     private readonly config;
     private swapUpdateListeners;
@@ -744,15 +759,35 @@ declare class SwapManager implements SwapManagerClient {
      * chain refund has finished its remaining work).
      */
     private finalizeMonitoredSwap;
+    private static isRefundRetryableSwap;
+    private static hasPendingRefundRetry;
+    private shouldMonitorOnStart;
+    /**
+     * How long to wait before re-attempting a refund, given the `retryAt`
+     * (Unix seconds) the outcome reported. Clamped at both ends: see
+     * {@link SwapManager.REFUND_RETRY_DELAY_MS} and
+     * {@link SwapManager.MAX_REFUND_RETRY_DELAY_MS}.
+     */
+    private static refundRetryDelayMs;
+    private static persistedRefundRetryDelayMs;
+    private static nextRefundRetryAt;
+    private clearRefundRetry;
+    private resumePersistedRefundRetries;
     /**
-     * Schedule another `executeAutonomousAction` run for a chain swap whose
-     * refund left VTXOs deferred. After the retry completes, if no further
-     * deferral was reported, finalize monitoring cleanup.
+     * Schedule another `executeAutonomousAction` run for a swap whose refund
+     * left VTXOs deferred. The pending retry and its next attempt time are saved
+     * with the swap so stop/start and application restart can re-arm it.
      */
     private scheduleRefundRetry;
+    private armRefundRetryTimer;
     /**
      * Execute autonomous action based on swap status
      * Uses locking to prevent race conditions with manual operations
+     *
+     * @returns `false` when another action for this swap already held the lock
+     * and this call did nothing, `true` when it ran. Callers that finalize on
+     * the result must not act on `false`: the in-flight action owns the swap's
+     * outcome and will re-arm or finalize from its own result.
      */
     private executeAutonomousAction;
     /**
@@ -761,6 +796,8 @@ declare class SwapManager implements SwapManagerClient {
     private executeClaimAction;
     /**
      * Execute refund action for submarine swap
+     *
+     * @returns The refund outcome, or `undefined` if no callback is wired.
      */
     private executeRefundAction;
     /**
@@ -991,6 +1028,13 @@ interface OptimisticSendLightningPaymentResponse {
     /** Transaction ID of the Arkade payment. */
     txid: string;
 }
+/** Persisted state for a locally deferred refund retry. */
+interface RefundRetryState {
+    /** True while SwapManager still needs to retry the local refund path. */
+    pending: true;
+    /** Unix timestamp (seconds) for the next retry attempt. */
+    nextRetryAt: number;
+}
 /** Tracks an in-progress reverse swap (Lightning → Arkade). */
 interface BoltzReverseSwap {
     /** Unique swap ID from Boltz. */
@@ -1024,6 +1068,8 @@ interface BoltzSubmarineSwap {
     refunded?: boolean;
     /** Whether the swap is eligible for refund. */
     refundable?: boolean;
+    /** Deferred local refund retry state, if any. */
+    refundRetry?: RefundRetryState;
     /** Current Boltz swap status. */
     status: BoltzSwapStatus;
     /** The original request sent to Boltz. */
@@ -1067,6 +1113,15 @@ interface SubmarineRecoveryInfo {
     /** Reason populated when `status === "invalid_swap"`. */
     error?: string;
 }
+/**
+ * Earliest Unix timestamp (seconds) at which retrying the deferred VTXOs could
+ * make progress, or `undefined` when nothing was deferred. Deferrals do not all
+ * last the same time — a server-side CLTV rejection clears as soon as a later
+ * block carries the locktime, whereas a pre-CLTV VTXO must wait out the whole
+ * refund locktime — so callers schedule from this instead of polling at a fixed
+ * interval. It is a lower bound, not a promise: a retry may defer again.
+ */
+type RefundRetryAt = number | undefined;
 /** Outcome of a single `refundVHTLC` call: how many VTXOs were swept vs. deferred. */
 interface SubmarineRefundOutcome {
     /** Number of VTXOs successfully refunded (joined a batch or via Boltz co-sign). */
@@ -1077,6 +1132,8 @@ interface SubmarineRefundOutcome {
      * is expected to retry these later.
      */
     skipped: number;
+    /** When a retry could first succeed; see {@link RefundRetryAt}. */
+    retryAt?: RefundRetryAt;
 }
 /** Outcome of a single `refundArk` call: how many VTXOs were swept vs. deferred. */
 interface ChainArkRefundOutcome {
@@ -1088,6 +1145,8 @@ interface ChainArkRefundOutcome {
      * is expected to retry these later.
      */
     skipped: number;
+    /** When a retry could first succeed; see {@link RefundRetryAt}. */
+    retryAt?: RefundRetryAt;
 }
 /** Per-swap outcome of a bulk recovery call. */
 interface SubmarineRecoveryResult {
@@ -1120,6 +1179,8 @@ interface BoltzChainSwap {
     feeSatsPerByte: number;
     /** Current Boltz swap status. */
     status: BoltzSwapStatus;
+    /** Deferred local ARK refund retry state, if any. */
+    refundRetry?: RefundRetryState;
     /** The original chain swap request sent to Boltz. */
     request: CreateChainSwapRequest;
     /** Boltz API response with lockup and claim details. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arkade-os/boltz-swap",
-  "version": "0.3.49",
+  "version": "0.3.51",
   "type": "module",
   "description": "A production-ready TypeScript package that brings Boltz submarine-swaps to Arkade.",
   "main": "./dist/index.js",
@@ -76,7 +76,7 @@
     "@scure/btc-signer": "2.0.1",
     "bip68": "1.0.4",
     "light-bolt11-decoder": "3.2.0",
-    "@arkade-os/sdk": "0.4.44"
+    "@arkade-os/sdk": "0.4.46"
   },
   "peerDependencies": {
     "expo-task-manager": ">=3.0.0",
@@ -92,7 +92,7 @@
   },
   "devDependencies": {
     "@types/ws": "^8.18.1",
-    "vite": "^7.3.2"
+    "vite": "^7.3.6"
   },
   "publishConfig": {
     "access": "public",