@arkade-os/sdk 0.4.18 → 0.4.20

package/dist/cjs/wallet/ramps.js

@@ -142,7 +142,7 @@ class Ramps {
                 weight: 0,
                 birth: vtxo.createdAt,
                 expiry: vtxo.virtualStatus.batchExpiry
-                    ? new Date(vtxo.virtualStatus.batchExpiry * 1000)
+                    ? new Date(vtxo.virtualStatus.batchExpiry)
                     : undefined,
             });
             if (inputFee.satoshis >= vtxo.value) {

package/dist/cjs/wallet/serviceWorker/wallet-message-handler.js

@@ -103,6 +103,16 @@ class WalletMessageHandler {
             tag: this.messageTag,
         };
     }
+    // Flows that surrender control to the Ark server and the other participants
+    // in a batch round: quiet gaps between protocol events can easily exceed
+    // the bus-level messageTimeoutMs. Liveness is covered out-of-band by the
+    // page-side PING / MESSAGE_BUS_NOT_INITIALIZED path triggered by concurrent
+    // short requests (GET_STATUS, GET_BALANCE, ...).
+    isLongRunning(message) {
+        return (message.type === "SETTLE" ||
+            message.type === "RECOVER_VTXOS" ||
+            message.type === "RENEW_VTXOS");
+    }
     async handleMessage(message) {
         const id = message.id;
         if (message.type === "INIT_WALLET") {

package/dist/cjs/wallet/serviceWorker/wallet.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ServiceWorkerWallet = exports.ServiceWorkerReadonlyWallet = exports.DEFAULT_MESSAGE_TIMEOUTS = void 0;
 const base_1 = require("@scure/base");
+const identity_1 = require("../../identity");
 const utils_1 = require("../../worker/browser/utils");
 const repositories_1 = require("../../repositories");
 const wallet_message_handler_1 = require("./wallet-message-handler");
@@ -36,7 +37,10 @@ exports.DEFAULT_MESSAGE_TIMEOUTS = {
     GET_EXPIRED_BOARDING_UTXOS: 20000,
     GET_RECOVERABLE_BALANCE: 20000,
     RELOAD_WALLET: 20000,
-    // Transactions — need more headroom
+    // Transactions — need more headroom.
+    // SETTLE / RECOVER_VTXOS / RENEW_VTXOS go through the streaming path and
+    // are treated as long-running on both sides of the bus: the values below
+    // are retained only for type completeness and are never enforced.
     SEND_BITCOIN: 50000,
     SEND: 50000,
     SETTLE: 50000,
@@ -81,9 +85,12 @@ function getRequestDedupKey(request) {
     const { id, tag, ...rest } = request;
     return JSON.stringify(rest);
 }
-const isPrivateKeyIdentity = (identity) => {
-    return typeof identity.toHex === "function";
-};
+function isSigningCapable(identity) {
+    const candidate = identity;
+    return (typeof candidate.signMessage === "function" &&
+        typeof candidate.sign === "function" &&
+        typeof candidate.signerSession === "function");
+}
 class ServiceWorkerReadonlyAssetManager {
     constructor(sendMessage, messageTag) {
         this.sendMessage = sendMessage;
@@ -199,55 +206,54 @@ class ServiceWorkerReadonlyWallet {
         const messageTag = options.walletUpdaterTag ?? wallet_message_handler_1.DEFAULT_MESSAGE_TAG;
         // Create the wallet instance
         const wallet = new ServiceWorkerReadonlyWallet(options.serviceWorker, options.identity, walletRepository, contractRepository, messageTag);
+        const serializedWallet = await (0, identity_1.serializeReadonlyIdentity)(options.identity);
+        // INIT_WALLET retains the legacy `key` payload for wire compatibility
+        // with older workers; the current handler does not read it.
         const publicKey = await options.identity
             .compressedPublicKey()
             .then(base_1.hex.encode);
-        const initConfig = {
+        const initWalletPayload = {
             key: { publicKey },
             arkServerUrl: options.arkServerUrl,
             arkServerPublicKey: options.arkServerPublicKey,
             delegatorUrl: options.delegatorUrl,
         };
-        // Bootstrap the MessageBus in the service worker
-        await initializeMessageBus(options.serviceWorker, {
-            wallet: initConfig.key,
+        // Precompute the merged timeout map so page-side waiting and
+        // worker-side enforcement are derived from the same source.
+        const messageTimeouts = options.messageTimeouts
+            ? {
+                ...exports.DEFAULT_MESSAGE_TIMEOUTS,
+                ...options.messageTimeouts,
+            }
+            : exports.DEFAULT_MESSAGE_TIMEOUTS;
+        const busInitConfig = {
+            wallet: serializedWallet,
             arkServer: {
-                url: initConfig.arkServerUrl,
-                publicKey: initConfig.arkServerPublicKey,
+                url: options.arkServerUrl,
+                publicKey: options.arkServerPublicKey,
             },
-            delegatorUrl: initConfig.delegatorUrl,
+            delegatorUrl: options.delegatorUrl,
             indexerUrl: options.indexerUrl,
             esploraUrl: options.esploraUrl,
-            timeoutMs: options.messageBusTimeoutMs,
             watcherConfig: options.watcherConfig,
-        }, options.messageBusTimeoutMs);
+            messageTimeouts,
+        };
+        // Bootstrap the MessageBus in the service worker
+        await initializeMessageBus(options.serviceWorker, { ...busInitConfig, timeoutMs: options.messageBusTimeoutMs }, options.messageBusTimeoutMs);
         // Initialize the wallet handler
         const initMessage = {
             tag: messageTag,
             type: "INIT_WALLET",
             id: (0, utils_2.getRandomId)(),
-            payload: initConfig,
+            payload: initWalletPayload,
         };
         await wallet.sendMessage(initMessage);
-        wallet.initConfig = {
-            wallet: initConfig.key,
-            arkServer: {
-                url: initConfig.arkServerUrl,
-                publicKey: initConfig.arkServerPublicKey,
-            },
-            delegatorUrl: initConfig.delegatorUrl,
-            indexerUrl: options.indexerUrl,
-            esploraUrl: options.esploraUrl,
-            watcherConfig: options.watcherConfig,
-        };
-        wallet.initWalletPayload = initConfig;
+        // Persist the full init config (including messageTimeouts) so
+        // reinitialize() re-sends the same map to a restarted worker.
+        wallet.initConfig = busInitConfig;
+        wallet.initWalletPayload = initWalletPayload;
         wallet.messageBusTimeoutMs = options.messageBusTimeoutMs;
-        if (options.messageTimeouts) {
-            wallet.messageTimeouts = {
-                ...exports.DEFAULT_MESSAGE_TIMEOUTS,
-                ...options.messageTimeouts,
-            };
-        }
+        wallet.messageTimeouts = messageTimeouts;
         return wallet;
     }
     /**
@@ -306,24 +312,16 @@ class ServiceWorkerReadonlyWallet {
     }
     // Like sendMessageDirect but supports streaming responses: intermediate
     // messages are forwarded via onEvent while the promise resolves on the
-    // first response for which isComplete returns true. The timeout resets
-    // on every intermediate event so long-running but progressing operations
-    // don't time out prematurely.
-    sendMessageStreaming(request, onEvent, isComplete, timeoutMs) {
+    // first response for which isComplete returns true. No inactivity deadline:
+    // settlement-class flows surrender control to remote peers and can sit
+    // idle for long stretches between protocol events. Service-worker death
+    // is detected out-of-band via concurrent short requests that surface
+    // MESSAGE_BUS_NOT_INITIALIZED.
+    sendMessageStreaming(request, onEvent, isComplete) {
         return new Promise((resolve, reject) => {
-            const resetTimeout = () => {
-                clearTimeout(timeoutId);
-                timeoutId = setTimeout(() => {
-                    cleanup();
-                    reject(new errors_1.ServiceWorkerTimeoutError(`Service worker message timed out (${request.type})`));
-                }, timeoutMs);
-            };
             const cleanup = () => {
-                clearTimeout(timeoutId);
                 navigator.serviceWorker.removeEventListener("message", messageHandler);
             };
-            let timeoutId;
-            resetTimeout();
             const messageHandler = (event) => {
                 const response = event.data;
                 if (request.id !== response.id)
@@ -338,7 +336,6 @@ class ServiceWorkerReadonlyWallet {
                     resolve(response);
                 }
                 else {
-                    resetTimeout();
                     onEvent(response);
                 }
             };
@@ -428,11 +425,10 @@ class ServiceWorkerReadonlyWallet {
                 await this.reinitialize();
             }
         }
-        const timeoutMs = this.getTimeoutForRequest(request);
         const maxRetries = 2;
         for (let attempt = 0;; attempt++) {
             try {
-                return await this.sendMessageStreaming(request, onEvent, isComplete, timeoutMs);
+                return await this.sendMessageStreaming(request, onEvent, isComplete);
             }
             catch (error) {
                 if (!isMessageBusNotInitializedError(error) ||
@@ -443,19 +439,68 @@ class ServiceWorkerReadonlyWallet {
             }
         }
     }
+    /**
+     * Produce a serialized envelope for the wallet's identity. The base
+     * class always emits a readonly envelope; `ServiceWorkerWallet`
+     * overrides to emit a signing envelope.
+     */
+    async serializeIdentity() {
+        return (0, identity_1.serializeReadonlyIdentity)(this.identity);
+    }
+    /**
+     * Return the cached init config, or rebuild one from live instance
+     * state when the cache was never populated. Recovery path for
+     * SDK-factory-created wallets; manual constructor bypasses do not
+     * retain enough state here and will hit the "never initialized" throw.
+     */
+    async buildInitConfig() {
+        if (this.initConfig)
+            return this.initConfig;
+        if (!this.arkServerUrl) {
+            throw new Error("Cannot re-initialize: wallet was not initialized via the SDK factory");
+        }
+        const wallet = await this.serializeIdentity();
+        this.initConfig = {
+            wallet,
+            arkServer: {
+                url: this.arkServerUrl,
+                publicKey: this.arkServerPublicKey,
+            },
+            delegatorUrl: this.delegatorUrl,
+            indexerUrl: this.indexerUrl,
+            esploraUrl: this.esploraUrl,
+            watcherConfig: this.watcherConfig,
+            settlementConfig: this.settlementConfig,
+        };
+        return this.initConfig;
+    }
+    /** Minimal INIT_WALLET payload used on reinitialize when the cache is gone. */
+    buildInitWalletPayload() {
+        if (this.initWalletPayload)
+            return this.initWalletPayload;
+        if (!this.arkServerUrl) {
+            throw new Error("Cannot re-initialize: wallet was not initialized via the SDK factory");
+        }
+        this.initWalletPayload = {
+            // `key` is deprecated and ignored by the current handler.
+            key: {},
+            arkServerUrl: this.arkServerUrl,
+            arkServerPublicKey: this.arkServerPublicKey,
+        };
+        return this.initWalletPayload;
+    }
     async reinitialize() {
         if (this.reinitPromise)
             return this.reinitPromise;
         this.reinitPromise = (async () => {
-            if (!this.initConfig || !this.initWalletPayload) {
-                throw new Error("Cannot re-initialize: missing configuration");
-            }
-            await initializeMessageBus(this.serviceWorker, this.initConfig, this.messageBusTimeoutMs);
+            const config = await this.buildInitConfig();
+            const payload = this.buildInitWalletPayload();
+            await initializeMessageBus(this.serviceWorker, config, this.messageBusTimeoutMs);
             const initMessage = {
                 tag: this.messageTag,
                 type: "INIT_WALLET",
                 id: (0, utils_2.getRandomId)(),
-                payload: this.initWalletPayload,
+                payload,
             };
             await this.sendMessageDirect(initMessage, this.getTimeoutForRequest(initMessage));
         })().finally(() => {
@@ -818,71 +863,72 @@ class ServiceWorkerWallet extends ServiceWorkerReadonlyWallet {
     get assetManager() {
         return this._assetManager;
     }
+    async serializeIdentity() {
+        return (0, identity_1.serializeSigningIdentity)(this.identity);
+    }
     static async create(options) {
         const walletRepository = options.storage?.walletRepository ??
             new repositories_1.IndexedDBWalletRepository();
         const contractRepository = options.storage?.contractRepository ??
             new repositories_1.IndexedDBContractRepository();
-        // Extract identity and check if it can expose private key
-        const identity = isPrivateKeyIdentity(options.identity)
-            ? options.identity
-            : null;
-        if (!identity) {
-            throw new Error("ServiceWorkerWallet.create() requires a Identity that can expose a single private key");
+        if (!isSigningCapable(options.identity)) {
+            throw new Error("ServiceWorkerWallet.create() requires a signing Identity; got a ReadonlyIdentity");
         }
-        // Extract private key for service worker initialization
-        const privateKey = identity.toHex();
+        const identity = options.identity;
+        const serializedWallet = (0, identity_1.serializeSigningIdentity)(identity);
         const messageTag = options.walletUpdaterTag ?? wallet_message_handler_1.DEFAULT_MESSAGE_TAG;
         // Create the wallet instance
         const wallet = new ServiceWorkerWallet(options.serviceWorker, identity, walletRepository, contractRepository, messageTag, !!options.delegatorUrl);
-        const initConfig = {
-            key: { privateKey },
+        // INIT_WALLET retains the legacy `key` payload for wire compatibility
+        // with older workers; the current handler does not read it, and only
+        // SingleKey-style identities can populate it. Kept optional so seed /
+        // mnemonic identities simply omit it.
+        const legacyPrivateKey = serializedWallet.type === "single-key"
+            ? serializedWallet.privateKey
+            : null;
+        const initWalletPayload = {
+            key: legacyPrivateKey ? { privateKey: legacyPrivateKey } : {},
             arkServerUrl: options.arkServerUrl,
             arkServerPublicKey: options.arkServerPublicKey,
             delegatorUrl: options.delegatorUrl,
         };
-        await initializeMessageBus(options.serviceWorker, {
-            wallet: initConfig.key,
+        // Precompute the merged timeout map so page-side waiting and
+        // worker-side enforcement are derived from the same source.
+        const messageTimeouts = options.messageTimeouts
+            ? {
+                ...exports.DEFAULT_MESSAGE_TIMEOUTS,
+                ...options.messageTimeouts,
+            }
+            : exports.DEFAULT_MESSAGE_TIMEOUTS;
+        const busInitConfig = {
+            wallet: serializedWallet,
             arkServer: {
-                url: initConfig.arkServerUrl,
-                publicKey: initConfig.arkServerPublicKey,
+                url: options.arkServerUrl,
+                publicKey: options.arkServerPublicKey,
             },
-            delegatorUrl: initConfig.delegatorUrl,
+            delegatorUrl: options.delegatorUrl,
             indexerUrl: options.indexerUrl,
             esploraUrl: options.esploraUrl,
-            timeoutMs: options.messageBusTimeoutMs,
             settlementConfig: options.settlementConfig,
             watcherConfig: options.watcherConfig,
-        }, options.messageBusTimeoutMs);
+            messageTimeouts,
+        };
+        await initializeMessageBus(options.serviceWorker, { ...busInitConfig, timeoutMs: options.messageBusTimeoutMs }, options.messageBusTimeoutMs);
         // Initialize the service worker with the config
         const initMessage = {
             tag: messageTag,
             type: "INIT_WALLET",
             id: (0, utils_2.getRandomId)(),
-            payload: initConfig,
+            payload: initWalletPayload,
         };
         // Initialize the service worker
         await wallet.sendMessage(initMessage);
-        wallet.initConfig = {
-            wallet: initConfig.key,
-            arkServer: {
-                url: initConfig.arkServerUrl,
-                publicKey: initConfig.arkServerPublicKey,
-            },
-            delegatorUrl: initConfig.delegatorUrl,
-            indexerUrl: options.indexerUrl,
-            esploraUrl: options.esploraUrl,
-            settlementConfig: options.settlementConfig,
-            watcherConfig: options.watcherConfig,
-        };
-        wallet.initWalletPayload = initConfig;
+        // Persist the full init config (including messageTimeouts) so
+        // reinitialize() re-sends the same map to a restarted worker.
+        wallet.initConfig = busInitConfig;
+        wallet.initWalletPayload = initWalletPayload;
         wallet.messageBusTimeoutMs = options.messageBusTimeoutMs;
-        if (options.messageTimeouts) {
-            wallet.messageTimeouts = {
-                ...exports.DEFAULT_MESSAGE_TIMEOUTS,
-                ...options.messageTimeouts,
-            };
-        }
+        wallet.messageTimeouts = messageTimeouts;
         return wallet;
     }
     /**

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

@@ -10,6 +10,8 @@ const base_1 = require("@scure/base");
 const base_2 = require("../script/base");
 const transaction_1 = require("../utils/transaction");
 const txSizeEstimator_1 = require("../utils/txSizeEstimator");
+const arkfee_1 = require("../arkfee");
+const address_1 = require("../script/address");
 /**
  * Return whether a wallet exposes the properties required for boarding input sweep operations.
  *
@@ -19,6 +21,7 @@ const txSizeEstimator_1 = require("../utils/txSizeEstimator");
 function isSweepCapable(wallet) {
     return ("boardingTapscript" in wallet &&
         "onchainProvider" in wallet &&
+        "arkProvider" in wallet &&
         "network" in wallet);
 }
 /**
@@ -29,7 +32,7 @@ function isSweepCapable(wallet) {
  */
 function assertSweepCapable(wallet) {
     if (!isSweepCapable(wallet)) {
-        throw new Error("Boarding UTXO sweep requires a Wallet instance with boardingTapscript, onchainProvider, and network");
+        throw new Error("Boarding UTXO sweep requires a Wallet instance with boardingTapscript, onchainProvider, arkProvider, and network");
     }
 }
 /**
@@ -232,6 +235,11 @@ class VtxoManager {
         // 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;
@@ -622,6 +630,10 @@ class VtxoManager {
     getOnchainProvider() {
         return this.getSweepWallet().onchainProvider;
     }
+    /** Returns the Ark provider for intent fee and server info lookups. */
+    getArkProvider() {
+        return this.getSweepWallet().arkProvider;
+    }
     /** Returns the Bitcoin network configuration from the wallet. */
     getNetwork() {
         return this.getSweepWallet().network;
@@ -667,7 +679,6 @@ 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
@@ -675,6 +686,14 @@ 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);
                     });
@@ -692,6 +711,39 @@ 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)
@@ -824,7 +876,8 @@ class VtxoManager {
         catch (e) {
             throw e instanceof Error ? e : new Error(String(e));
         }
-        const unsettledBoarding = 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}`));
         // Collect near-expiry VTXOs unless the event-driven path is mid-renewal.
         // Skipping when renewalInProgress avoids double-submitting the same VTXOs.
@@ -850,13 +903,54 @@ class VtxoManager {
             return;
         }
         const dustAmount = getDustAmount(this.wallet);
-        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)
+        // Fetch server intent-fee config so each input/output can be priced.
+        // Without this, settle sends `outputAmount = sum(inputs)` and the
+        // server rejects with INTENT_INSUFFICIENT_FEE whenever the operator
+        // charges non-zero intent fees.
+        const { fees } = await this.getArkProvider().getInfo();
+        const estimator = new arkfee_1.Estimator(fees.intentFee);
+        let totalAmount = 0n;
+        const filteredBoarding = [];
+        for (const u of unsettledBoarding) {
+            const inputFee = estimator.evalOnchainInput({
+                amount: BigInt(u.value),
+            });
+            if (inputFee.value >= BigInt(u.value)) {
+                // Fee exceeds input value — including it would drain the output.
+                continue;
+            }
+            filteredBoarding.push(u);
+            totalAmount += BigInt(u.value) - BigInt(inputFee.satoshis);
+        }
+        const filteredVtxos = [];
+        for (const v of expiringVtxos) {
+            const inputFee = estimator.evalOffchainInput({
+                amount: BigInt(v.value),
+                type: v.virtualStatus.state === "swept" ? "recoverable" : "vtxo",
+                weight: 0,
+                birth: v.createdAt,
+                expiry: v.virtualStatus.batchExpiry
+                    ? new Date(v.virtualStatus.batchExpiry)
+                    : undefined,
+            });
+            if (inputFee.satoshis >= v.value) {
+                continue;
+            }
+            filteredVtxos.push(v);
+            totalAmount += BigInt(v.value) - BigInt(inputFee.satoshis);
+        }
+        if (filteredBoarding.length === 0 && filteredVtxos.length === 0) {
             return;
+        }
         const arkAddress = await this.wallet.getAddress();
-        const includesVtxos = expiringVtxos.length > 0;
+        const outputFee = estimator.evalOffchainOutput({
+            amount: totalAmount,
+            script: base_1.hex.encode(address_1.ArkAddress.decode(arkAddress).pkScript),
+        });
+        totalAmount -= BigInt(outputFee.satoshis);
+        if (totalAmount < dustAmount)
+            return;
+        const includesVtxos = filteredVtxos.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.
@@ -864,16 +958,34 @@ class VtxoManager {
             this.renewalInProgress = true;
         }
         let success = false;
+        let staleCacheSkip = false;
         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}`);
+            try {
+                await this.wallet.settle({
+                    inputs: [...filteredBoarding, ...filteredVtxos],
+                    outputs: [{ address: arkAddress, amount: totalAmount }],
+                });
+                // Mark boarding inputs as known only after successful settle.
+                for (const u of filteredBoarding) {
+                    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;
+                }
             }
-            success = true;
         }
         finally {
             this.lastPeriodicSettleTimestamp = Date.now();
@@ -888,7 +1000,10 @@ class VtxoManager {
             if (success) {
                 this.consecutivePeriodicSettleFailures = 0;
             }
-            else {
+            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++;
             }
         }
@@ -926,3 +1041,4 @@ 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;