@arkade-os/sdk 0.4.18 → 0.4.20

package/dist/esm/wallet/ramps.js

@@ -139,7 +139,7 @@ export 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/esm/wallet/serviceWorker/wallet-message-handler.js

@@ -97,6 +97,16 @@ export 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/esm/wallet/serviceWorker/wallet.js

@@ -1,4 +1,5 @@
 import { hex } from "@scure/base";
+import { serializeReadonlyIdentity, serializeSigningIdentity, } from '../../identity/index.js';
 import { setupServiceWorker } from '../../worker/browser/utils.js';
 import { IndexedDBContractRepository, IndexedDBWalletRepository, } from '../../repositories/index.js';
 import { DEFAULT_MESSAGE_TAG, } from './wallet-message-handler.js';
@@ -33,7 +34,10 @@ export const 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,
@@ -78,9 +82,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;
@@ -196,55 +203,54 @@ export class ServiceWorkerReadonlyWallet {
         const messageTag = options.walletUpdaterTag ?? DEFAULT_MESSAGE_TAG;
         // Create the wallet instance
         const wallet = new ServiceWorkerReadonlyWallet(options.serviceWorker, options.identity, walletRepository, contractRepository, messageTag);
+        const serializedWallet = await 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(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
+            ? {
+                ...DEFAULT_MESSAGE_TIMEOUTS,
+                ...options.messageTimeouts,
+            }
+            : 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: 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 = {
-                ...DEFAULT_MESSAGE_TIMEOUTS,
-                ...options.messageTimeouts,
-            };
-        }
+        wallet.messageTimeouts = messageTimeouts;
         return wallet;
     }
     /**
@@ -303,24 +309,16 @@ export 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 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)
@@ -335,7 +333,6 @@ export class ServiceWorkerReadonlyWallet {
                     resolve(response);
                 }
                 else {
-                    resetTimeout();
                     onEvent(response);
                 }
             };
@@ -425,11 +422,10 @@ export 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) ||
@@ -440,19 +436,68 @@ export 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 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: getRandomId(),
-                payload: this.initWalletPayload,
+                payload,
             };
             await this.sendMessageDirect(initMessage, this.getTimeoutForRequest(initMessage));
         })().finally(() => {
@@ -814,71 +859,72 @@ export class ServiceWorkerWallet extends ServiceWorkerReadonlyWallet {
     get assetManager() {
         return this._assetManager;
     }
+    async serializeIdentity() {
+        return serializeSigningIdentity(this.identity);
+    }
     static async create(options) {
         const walletRepository = options.storage?.walletRepository ??
             new IndexedDBWalletRepository();
         const contractRepository = options.storage?.contractRepository ??
             new 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 = serializeSigningIdentity(identity);
         const messageTag = options.walletUpdaterTag ?? 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
+            ? {
+                ...DEFAULT_MESSAGE_TIMEOUTS,
+                ...options.messageTimeouts,
+            }
+            : 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: 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 = {
-                ...DEFAULT_MESSAGE_TIMEOUTS,
-                ...options.messageTimeouts,
-            };
-        }
+        wallet.messageTimeouts = messageTimeouts;
         return wallet;
     }
     /**

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

@@ -5,6 +5,8 @@ import { hex } from "@scure/base";
 import { getSequence } from '../script/base.js';
 import { Transaction } from '../utils/transaction.js';
 import { TxWeightEstimator } from '../utils/txSizeEstimator.js';
+import { Estimator } from '../arkfee/index.js';
+import { ArkAddress } from '../script/address.js';
 /**
  * Return whether a wallet exposes the properties required for boarding input sweep operations.
  *
@@ -14,6 +16,7 @@ import { TxWeightEstimator } from '../utils/txSizeEstimator.js';
 function isSweepCapable(wallet) {
     return ("boardingTapscript" in wallet &&
         "onchainProvider" in wallet &&
+        "arkProvider" in wallet &&
         "network" in wallet);
 }
 /**
@@ -24,7 +27,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");
     }
 }
 /**
@@ -227,6 +230,11 @@ export 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;
@@ -617,6 +625,10 @@ export 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;
@@ -662,7 +674,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
@@ -670,6 +681,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);
                     });
@@ -687,6 +706,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)
@@ -819,7 +871,8 @@ export 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.
@@ -845,13 +898,54 @@ export 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 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: hex.encode(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.
@@ -859,16 +953,34 @@ export 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();
@@ -883,7 +995,10 @@ export 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++;
             }
         }
@@ -920,3 +1035,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;