@arkade-os/sdk 0.4.17 → 0.4.19

package/dist/esm/wallet/vtxo-manager.js

@@ -27,6 +27,38 @@ function assertSweepCapable(wallet) {
         throw new Error("Boarding UTXO sweep requires a Wallet instance with boardingTapscript, onchainProvider, and network");
     }
 }
+/**
+ * Web Locks name used to serialize boarding-poll work across same-origin
+ * browser contexts (tabs, service worker). Static because the goal is to
+ * deduplicate polls for the *same* wallet — two distinct wallets on the
+ * same origin will take turns, which is acceptable.
+ */
+const BOARDING_POLL_LOCK_NAME = "arkade-boarding-poll";
+/**
+ * Run `fn` under an exclusive Web Lock when the runtime provides one
+ * (browser main thread, service worker). In environments without
+ * `navigator.locks` (Node, React Native) the callback runs immediately
+ * with no coordination.
+ *
+ * Uses `ifAvailable: true`: if another context already holds the lock,
+ * skip this cycle entirely rather than queueing — the other context will
+ * do the work and the next poll will re-check.
+ */
+async function runWithCrossInstanceLock(name, fn) {
+    const locks = typeof globalThis !== "undefined" &&
+        typeof globalThis.navigator !== "undefined"
+        ? globalThis.navigator.locks
+        : undefined;
+    if (!locks) {
+        await fn();
+        return;
+    }
+    await locks.request(name, { ifAvailable: true, mode: "exclusive" }, async (lock) => {
+        if (lock === null)
+            return;
+        await fn();
+    });
+}
 /** Default renewal threshold in seconds (3 days). */
 export const DEFAULT_THRESHOLD_SECONDS = 3 * 24 * 60 * 60;
 /**
@@ -186,6 +218,20 @@ export class VtxoManager {
         // server emits new VTXOs → vtxo_received → renewVtxos() again → infinite loop.
         this.renewalInProgress = false;
         this.lastRenewalTimestamp = 0;
+        // Guards against a retry treadmill on the periodic-settle path: a failing
+        // settle would otherwise re-submit identical intents on every 60s poll,
+        // producing per-minute DeleteIntent RPCs forever. Mirrors the renewal
+        // cooldown but with exponential backoff on consecutive failures, so a
+        // persistently broken input eventually drops to the backoff cap instead
+        // of hammering the server. Shared across boarding + expiring-VTXO work
+        // because they now ride on the same settle intent.
+        this.lastPeriodicSettleTimestamp = 0;
+        this.consecutivePeriodicSettleFailures = 0;
+        // Throttle for the VTXO_ALREADY_SPENT -> refreshVtxos() reconciliation.
+        // The server's authoritative view says our local cache is stale, so we
+        // trigger a full refresh to advance the global sync cursor. Rate-limit
+        // to guard against a buggy indexer cycling us into a refresh storm.
+        this.lastVtxoSpentRefreshTimestamp = 0;
         // Normalize: prefer settlementConfig, fall back to renewalConfig, default to enabled
         if (settlementConfig !== undefined) {
             this.settlementConfig = settlementConfig;
@@ -407,10 +453,15 @@ export class VtxoManager {
                     },
                 ],
             }, eventCallback);
-            this.lastRenewalTimestamp = Date.now();
             return txid;
         }
         finally {
+            // Update cooldown on EVERY attempt (success or failure) so transient
+            // settle failures (stream close, connector mismatch, duplicated input)
+            // don't allow the next vtxo_received event to re-enter renewal
+            // immediately. Without this, a failed settle leaves lastRenewalTimestamp
+            // at its previous value and the cooldown check becomes a no-op.
+            this.lastRenewalTimestamp = Date.now();
             this.renewalInProgress = false;
         }
     }
@@ -616,7 +667,6 @@ export class VtxoManager {
                                 return;
                             }
                             if (e.message.includes("VTXO_ALREADY_REGISTERED") ||
-                                e.message.includes("VTXO_ALREADY_SPENT") ||
                                 e.message.includes("duplicated input")) {
                                 // Virtual output is already being used in a concurrent
                                 // user-initiated operation. Skip silently — the
@@ -624,6 +674,14 @@ export class VtxoManager {
                                 // renewal will retry on the next cycle.
                                 return;
                             }
+                            if (e.message.includes("VTXO_ALREADY_SPENT")) {
+                                // Our local VTXO cache is stale vs. the
+                                // server's authoritative view. Trigger a
+                                // throttled refresh to reconcile, then skip
+                                // — the next cycle will see fresh data.
+                                void this.maybeRefreshAfterVtxoSpent();
+                                return;
+                            }
                         }
                         console.error("Error renewing VTXOs:", e);
                     });
@@ -641,6 +699,39 @@ export class VtxoManager {
             return undefined;
         }
     }
+    /**
+     * VTXO_ALREADY_SPENT means the server's authoritative view of VTXO state
+     * is ahead of ours — cross-instance race, pre-lock snapshot drift, or an
+     * SSE gap left stale data in the local cache. Silent-swallowing guarantees
+     * the same error on the next cycle because nothing reconciles the cache,
+     * so instead we trigger a full refreshVtxos() to advance the global sync
+     * cursor. Throttled to prevent a buggy indexer from causing a refresh
+     * storm.
+     */
+    maybeRefreshAfterVtxoSpent() {
+        if (this.vtxoSpentRefreshPromise) {
+            return this.vtxoSpentRefreshPromise;
+        }
+        const now = Date.now();
+        if (now - this.lastVtxoSpentRefreshTimestamp <
+            VtxoManager.VTXO_SPENT_REFRESH_COOLDOWN_MS) {
+            return Promise.resolve();
+        }
+        this.lastVtxoSpentRefreshTimestamp = now;
+        this.vtxoSpentRefreshPromise = (async () => {
+            try {
+                const contractManager = await this.wallet.getContractManager();
+                await contractManager.refreshVtxos();
+            }
+            catch (e) {
+                console.error("Error refreshing VTXOs after VTXO_ALREADY_SPENT:", e);
+            }
+            finally {
+                this.vtxoSpentRefreshPromise = undefined;
+            }
+        })();
+        return this.vtxoSpentRefreshPromise;
+    }
     /** Computes the next poll delay, applying exponential backoff on failures. */
     getNextPollDelay() {
         if (this.settlementConfig === false)
@@ -688,33 +779,42 @@ export class VtxoManager {
         this.pollDone = { promise, resolve: resolve };
         let hadError = false;
         try {
-            // Fetch boarding inputs once for the entire poll cycle so that
-            // settle and sweep don't each hit the network independently.
-            const boardingUtxos = await this.wallet.getBoardingUtxos();
-            // Settle new (unexpired) boarding inputs first, then sweep expired ones.
-            // Sequential to avoid racing for the same inputs.
-            try {
-                await this.settleBoardingUtxos(boardingUtxos);
-            }
-            catch (e) {
-                hadError = true;
-                console.error("Error auto-settling boarding UTXOs:", e);
-            }
-            const sweepEnabled = this.settlementConfig !== false &&
-                (this.settlementConfig?.boardingUtxoSweep ??
-                    DEFAULT_SETTLEMENT_CONFIG.boardingUtxoSweep);
-            if (sweepEnabled) {
+            // Cross-instance guard: in browser / service worker environments,
+            // serialize the poll body across tabs and SW contexts so only one
+            // of them registers intents per interval. Without this, every tab
+            // submits a parallel RegisterIntent for the same boarding input
+            // and N-1 of them collide on the server's duplicated-input check,
+            // each producing a DeleteIntent RPC. No-op outside the browser.
+            await runWithCrossInstanceLock(BOARDING_POLL_LOCK_NAME, async () => {
+                // Fetch boarding inputs once for the entire poll cycle so that
+                // settle and sweep don't each hit the network independently.
+                const boardingUtxos = await this.wallet.getBoardingUtxos();
+                // Settle new (unexpired) boarding inputs + any near-expiry
+                // VTXOs in a single intent, then sweep expired boarding
+                // inputs. Sequential to avoid racing for the same inputs.
                 try {
-                    await this.sweepExpiredBoardingUtxos(boardingUtxos);
+                    await this.runPeriodicSettle(boardingUtxos);
                 }
                 catch (e) {
-                    if (!(e instanceof Error) ||
-                        !e.message.includes("No expired boarding UTXOs")) {
-                        hadError = true;
-                        console.error("Error auto-sweeping boarding UTXOs:", e);
+                    hadError = true;
+                    console.error("Error during periodic settle:", e);
+                }
+                const sweepEnabled = this.settlementConfig !== false &&
+                    (this.settlementConfig?.boardingUtxoSweep ??
+                        DEFAULT_SETTLEMENT_CONFIG.boardingUtxoSweep);
+                if (sweepEnabled) {
+                    try {
+                        await this.sweepExpiredBoardingUtxos(boardingUtxos);
+                    }
+                    catch (e) {
+                        if (!(e instanceof Error) ||
+                            !e.message.includes("No expired boarding UTXOs")) {
+                            hadError = true;
+                            console.error("Error auto-sweeping boarding UTXOs:", e);
+                        }
                     }
                 }
-            }
+            });
         }
         catch (e) {
             hadError = true;
@@ -734,13 +834,19 @@ export class VtxoManager {
         }
     }
     /**
-     * Auto-settle new (unexpired) boarding inputs into Arkade.
-     * Skips UTXOs that are already expired (those are handled by sweep).
-     * Only settles UTXOs not already in-flight (tracked in knownBoardingUtxos).
-     * UTXOs are marked as known only after a successful settle, so failed
-     * attempts will be retried on the next poll.
+     * Auto-settle new (unexpired) boarding inputs AND near-expiry VTXOs into
+     * Arkade in a single intent. Skips boarding UTXOs that are already expired
+     * (those are handled by sweep) and those already in-flight (tracked in
+     * knownBoardingUtxos). If the event-driven renewal path is currently
+     * running, VTXOs are omitted from this cycle to avoid double-spending.
+     *
+     * Failure bookkeeping: after every settle *attempt*, lastPeriodicSettleTimestamp
+     * is armed and consecutive failures are counted so the next attempt is
+     * blocked by an exponentially growing cooldown (capped). This stops a
+     * persistently failing input from producing identical RegisterIntent +
+     * DeleteIntent retries on every 60s poll.
      */
-    async settleBoardingUtxos(boardingUtxos) {
+    async runPeriodicSettle(boardingUtxos) {
         // Exclude expired boarding inputs — those should be swept, not settled.
         // If we can't determine expired status, bail out entirely to avoid
         // accidentally settling expired inputs (which would conflict with sweep).
@@ -758,22 +864,95 @@ export class VtxoManager {
         catch (e) {
             throw e instanceof Error ? e : new Error(String(e));
         }
-        const unsettledUtxos = boardingUtxos.filter((u) => !this.knownBoardingUtxos.has(`${u.txid}:${u.vout}`) &&
+        const unsettledBoarding = boardingUtxos.filter((u) => u.status.confirmed &&
+            !this.knownBoardingUtxos.has(`${u.txid}:${u.vout}`) &&
             !expiredSet.has(`${u.txid}:${u.vout}`));
-        if (unsettledUtxos.length === 0)
+        // Collect near-expiry VTXOs unless the event-driven path is mid-renewal.
+        // Skipping when renewalInProgress avoids double-submitting the same VTXOs.
+        let expiringVtxos = [];
+        if (!this.renewalInProgress) {
+            try {
+                expiringVtxos = await this.getExpiringVtxos();
+            }
+            catch (e) {
+                // Non-fatal: fall back to boarding-only settle.
+                console.error("Error fetching expiring VTXOs:", e);
+            }
+        }
+        if (unsettledBoarding.length === 0 && expiringVtxos.length === 0) {
             return;
+        }
+        // Respect the cooldown armed by the previous attempt. Cooldown grows
+        // exponentially with consecutive failures and is capped by
+        // PERIODIC_SETTLE_MAX_BACKOFF_MS.
+        const cooldownMs = Math.min(VtxoManager.PERIODIC_SETTLE_COOLDOWN_MS *
+            Math.pow(2, this.consecutivePeriodicSettleFailures), VtxoManager.PERIODIC_SETTLE_MAX_BACKOFF_MS);
+        if (Date.now() - this.lastPeriodicSettleTimestamp < cooldownMs) {
+            return;
+        }
         const dustAmount = getDustAmount(this.wallet);
-        const totalAmount = unsettledUtxos.reduce((sum, u) => sum + BigInt(u.value), 0n);
+        const boardingTotal = unsettledBoarding.reduce((sum, u) => sum + BigInt(u.value), 0n);
+        const vtxoTotal = expiringVtxos.reduce((sum, v) => sum + BigInt(v.value), 0n);
+        const totalAmount = boardingTotal + vtxoTotal;
         if (totalAmount < dustAmount)
             return;
         const arkAddress = await this.wallet.getAddress();
-        await this.wallet.settle({
-            inputs: unsettledUtxos,
-            outputs: [{ address: arkAddress, amount: totalAmount }],
-        });
-        // Mark as known only after successful settle
-        for (const u of unsettledUtxos) {
-            this.knownBoardingUtxos.add(`${u.txid}:${u.vout}`);
+        const includesVtxos = expiringVtxos.length > 0;
+        // Block the event-driven renewal path while this settle is in flight
+        // when VTXOs are part of the intent. Mirrors renewVtxos()'s guard so
+        // the two paths can't race on the same VTXO inputs.
+        if (includesVtxos) {
+            this.renewalInProgress = true;
+        }
+        let success = false;
+        let staleCacheSkip = false;
+        try {
+            try {
+                await this.wallet.settle({
+                    inputs: [...unsettledBoarding, ...expiringVtxos],
+                    outputs: [{ address: arkAddress, amount: totalAmount }],
+                });
+                // Mark boarding inputs as known only after successful settle.
+                for (const u of unsettledBoarding) {
+                    this.knownBoardingUtxos.add(`${u.txid}:${u.vout}`);
+                }
+                success = true;
+            }
+            catch (e) {
+                if (e instanceof Error &&
+                    e.message.includes("VTXO_ALREADY_SPENT")) {
+                    // Local VTXO cache is stale vs. the server's
+                    // authoritative view — not a transient failure.
+                    // Trigger a throttled refresh and skip this cycle
+                    // without bumping the failure counter, so the next
+                    // poll can retry once the cache reconciles.
+                    staleCacheSkip = true;
+                    void this.maybeRefreshAfterVtxoSpent();
+                }
+                else {
+                    throw e;
+                }
+            }
+        }
+        finally {
+            this.lastPeriodicSettleTimestamp = Date.now();
+            if (includesVtxos) {
+                // Match event-path semantics: bump the renewal cooldown
+                // whether we succeeded or failed so a failed periodic settle
+                // doesn't let the next vtxo_received event re-enter renewal
+                // immediately.
+                this.lastRenewalTimestamp = Date.now();
+                this.renewalInProgress = false;
+            }
+            if (success) {
+                this.consecutivePeriodicSettleFailures = 0;
+            }
+            else if (!staleCacheSkip) {
+                // Don't bump on stale-cache skip: it's not a transient
+                // failure, and the next cycle should try immediately
+                // after the refresh lands.
+                this.consecutivePeriodicSettleFailures++;
+            }
         }
     }
     async dispose() {
@@ -806,3 +985,6 @@ export class VtxoManager {
 }
 VtxoManager.MAX_BACKOFF_MS = 5 * 60 * 1000; // 5 minutes
 VtxoManager.RENEWAL_COOLDOWN_MS = 30000; // 30 seconds
+VtxoManager.PERIODIC_SETTLE_COOLDOWN_MS = 30000;
+VtxoManager.PERIODIC_SETTLE_MAX_BACKOFF_MS = 5 * 60 * 1000;
+VtxoManager.VTXO_SPENT_REFRESH_COOLDOWN_MS = 30000;