@arkade-os/sdk 0.4.18 → 0.4.19

package/dist/cjs/providers/ark.js

@@ -231,28 +231,21 @@ class RestArkProvider {
         const queryParams = topics.length > 0
             ? `?${topics.map((topic) => `topics=${encodeURIComponent(topic)}`).join("&")}`
             : "";
-        // Create first EventSource eagerly so events are buffered
-        // before the caller starts iterating, preventing race conditions
-        // where the server emits events before iteration begins.
-        const eagerEventSource = new EventSource(url + queryParams);
-        const eagerIterator = (0, utils_1.eventSourceIterator)(eagerEventSource);
+        // The EventSource is allocated inside the generator body so that
+        // abandoning the returned iterator before iteration starts does not
+        // leak the underlying SSE connection. `return()` is overridden below
+        // so that closing the generator also closes the connection even when
+        // the body is currently suspended at an await point.
+        let eventSource = null;
         // eslint-disable-next-line @typescript-eslint/no-this-alias
         const self = this;
-        return (async function* () {
-            let firstIteration = true;
-            while (!signal?.aborted) {
-                const eventSource = firstIteration
-                    ? eagerEventSource
-                    : new EventSource(url + queryParams);
-                const iterator = firstIteration
-                    ? eagerIterator
-                    : (0, utils_1.eventSourceIterator)(eventSource);
-                firstIteration = false;
-                try {
-                    const abortHandler = () => {
-                        eventSource.close();
-                    };
-                    signal?.addEventListener("abort", abortHandler);
+        const gen = (async function* () {
+            const abortHandler = () => eventSource?.close();
+            signal?.addEventListener("abort", abortHandler);
+            try {
+                while (!signal?.aborted) {
+                    eventSource = new EventSource(url + queryParams);
+                    const iterator = (0, utils_1.eventSourceIterator)(eventSource);
                     try {
                         for await (const event of iterator) {
                             if (signal?.aborted)
@@ -270,25 +263,35 @@ class RestArkProvider {
                             }
                         }
                     }
+                    catch (error) {
+                        if (error instanceof Error &&
+                            error.name === "AbortError") {
+                            break;
+                        }
+                        // ignore timeout errors, they're expected when the server is not sending anything for 5 min
+                        if (isFetchTimeoutError(error)) {
+                            console.debug("Timeout error ignored");
+                            continue;
+                        }
+                        console.error("Event stream error:", error);
+                        throw error;
+                    }
                     finally {
-                        signal?.removeEventListener("abort", abortHandler);
                         eventSource.close();
                     }
                 }
-                catch (error) {
-                    if (error instanceof Error && error.name === "AbortError") {
-                        break;
-                    }
-                    // ignore timeout errors, they're expected when the server is not sending anything for 5 min
-                    if (isFetchTimeoutError(error)) {
-                        console.debug("Timeout error ignored");
-                        continue;
-                    }
-                    console.error("Event stream error:", error);
-                    throw error;
-                }
+            }
+            finally {
+                signal?.removeEventListener("abort", abortHandler);
+                eventSource?.close();
             }
         })();
+        const origReturn = gen.return.bind(gen);
+        gen.return = (value) => {
+            eventSource?.close();
+            return origReturn(value);
+        };
+        return gen;
     }
     async *getTransactionsStream(signal) {
         const url = `${this.serverUrl}/v1/txs`;

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

@@ -232,6 +232,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;
@@ -667,7 +672,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 +679,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 +704,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 +869,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.
@@ -864,16 +910,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: [...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;
+                }
             }
-            success = true;
         }
         finally {
             this.lastPeriodicSettleTimestamp = Date.now();
@@ -888,7 +952,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 +993,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;

package/dist/cjs/wallet/wallet.js

@@ -68,6 +68,12 @@ class ReadonlyWallet {
         this.walletRepository = walletRepository;
         this.contractRepository = contractRepository;
         this.delegatorProvider = delegatorProvider;
+        // Outpoints ("txid:vout") committed to an in-flight settle/send. Filtered
+        // from getVtxos() so concurrent callers (UI, VtxoManager auto-renewal,
+        // another send/settle racing the _txLock) can't reselect coins that are
+        // already on their way out. The set is in-memory only: a process crash
+        // clears it, and a stale entry only hides a VTXO (never spends one).
+        this._pendingSpendOutpoints = new Set();
         // Guard: detect identity/server network mismatch for descriptor-based identities.
         // This duplicates the check in setupWalletConfig() so that subclasses
         // bypassing the factory still get the safety net.
@@ -308,6 +314,9 @@ class ReadonlyWallet {
         return vtxos
             .flatMap((_) => _.vtxos)
             .filter((vtxo) => {
+            if (this._pendingSpendOutpoints.has(`${vtxo.txid}:${vtxo.vout}`)) {
+                return false;
+            }
             if ((0, _1.isSpendable)(vtxo)) {
                 if (!f.withRecoverable &&
                     ((0, _1.isRecoverable)(vtxo) || (0, _1.isExpired)(vtxo))) {
@@ -760,6 +769,20 @@ exports.ReadonlyWallet = ReadonlyWallet;
  * ```
  */
 class Wallet extends ReadonlyWallet {
+    _addPendingSpends(inputs) {
+        for (const input of inputs) {
+            if ("virtualStatus" in input) {
+                this._pendingSpendOutpoints.add(`${input.txid}:${input.vout}`);
+            }
+        }
+    }
+    _removePendingSpends(inputs) {
+        for (const input of inputs) {
+            if ("virtualStatus" in input) {
+                this._pendingSpendOutpoints.delete(`${input.txid}:${input.vout}`);
+            }
+        }
+    }
     _withTxLock(fn) {
         let release;
         const lock = new Promise((r) => (release = r));
@@ -975,9 +998,15 @@ class Wallet extends ReadonlyWallet {
                         amount: BigInt(selected.changeAmount),
                     });
                 }
-                const { arkTxid, signedCheckpointTxs } = await this.buildAndSubmitOffchainTx(selected.inputs, outputs);
-                await this.updateDbAfterOffchainTx(selected.inputs, arkTxid, signedCheckpointTxs, params.amount, selected.changeAmount, selected.changeAmount > 0n ? outputs.length - 1 : 0);
-                return arkTxid;
+                this._addPendingSpends(selected.inputs);
+                try {
+                    const { arkTxid, signedCheckpointTxs } = await this.buildAndSubmitOffchainTx(selected.inputs, outputs);
+                    await this.updateDbAfterOffchainTx(selected.inputs, arkTxid, signedCheckpointTxs, params.amount, selected.changeAmount, selected.changeAmount > 0n ? outputs.length - 1 : 0);
+                    return arkTxid;
+                }
+                finally {
+                    this._removePendingSpends(selected.inputs);
+                }
             });
         }
         return this.send({
@@ -1023,7 +1052,8 @@ class Wallet extends ReadonlyWallet {
                 const tip = await this.onchainProvider.getChainTip();
                 chainTipHeight = tip.height;
             }
-            const boardingUtxos = (await this.getBoardingUtxos()).filter((utxo) => !(0, arkTransaction_1.hasBoardingTxExpired)(utxo, boardingTimelock, chainTipHeight));
+            const boardingUtxos = (await this.getBoardingUtxos()).filter((utxo) => utxo.status.confirmed &&
+                !(0, arkTransaction_1.hasBoardingTxExpired)(utxo, boardingTimelock, chainTipHeight));
             const filteredBoardingUtxos = [];
             for (const utxo of boardingUtxos) {
                 const inputFee = estimator.evalOnchainInput({
@@ -1158,11 +1188,29 @@ class Wallet extends ReadonlyWallet {
             ...params.inputs.map((input) => `${input.txid}:${input.vout}`),
         ];
         const abortController = new AbortController();
+        let stream;
+        // Optimistically hide these inputs from concurrent getVtxos() callers
+        // while the settlement is in flight. Set before safeRegisterIntent so
+        // there's no window between intent registration and coin-visibility.
+        this._addPendingSpends(params.inputs);
         try {
-            const stream = this.arkProvider.getEventStream(abortController.signal, topics);
+            stream = this.arkProvider.getEventStream(abortController.signal, topics);
+            // Prime the iterator so the provider opens the SSE subscription
+            // before safeRegisterIntent can trigger server-side batch events.
+            const firstNext = stream.next();
+            // If settle exits before Batch.join consumes the primed result,
+            // keep the orphaned promise from surfacing as an unhandled rejection.
+            void firstNext.catch(() => { });
+            const primedStream = (async function* () {
+                const first = await firstNext;
+                if (!first.done) {
+                    yield first.value;
+                }
+                yield* stream;
+            })();
             const intentId = await this.safeRegisterIntent(intent, params.inputs);
             const handler = this.createBatchHandler(intentId, params.inputs, recipients, session);
-            const commitmentTxid = await batch_1.Batch.join(stream, handler, {
+            const commitmentTxid = await batch_1.Batch.join(primedStream, handler, {
                 abortController,
                 skipVtxoTreeSigning: !hasOffchainOutputs,
                 eventCallback: eventCallback
@@ -1186,23 +1234,28 @@ class Wallet extends ReadonlyWallet {
             throw error;
         }
         finally {
-            // close the stream
+            // Clear state first so a synchronous handler firing from abort()
+            // never observes a stale pending-spend set.
+            this._removePendingSpends(params.inputs);
+            // close the stream — abort() fires the in-body handler if the
+            // generator has started iterating; return() also releases the
+            // eager resource if the body is still suspended or never ran
+            // (e.g. safeRegisterIntent threw before Batch.join was called).
             abortController.abort();
+            await stream?.return?.().catch(() => { });
         }
     }
     async handleSettlementFinalizationEvent(event, inputs, forfeitOutputScript, connectorsGraph) {
         // the signed forfeits transactions to submit
         const signedForfeits = [];
-        const vtxos = await this.getVtxos();
+        const isVtxo = (input) => "virtualStatus" in input;
         let settlementPsbt = btc_signer_1.Transaction.fromPSBT(base_1.base64.decode(event.commitmentTx));
         let hasBoardingUtxos = false;
         let connectorIndex = 0;
         const connectorsLeaves = connectorsGraph?.leaves() || [];
         for (const input of inputs) {
-            // check if the input is an offchain "virtual" coin
-            const vtxo = vtxos.find((vtxo) => vtxo.txid === input.txid && vtxo.vout === input.vout);
             // boarding input, we need to sign the settlement tx
-            if (!vtxo) {
+            if (!isVtxo(input)) {
                 for (let i = 0; i < settlementPsbt.inputsLength; i++) {
                     const settlementInput = settlementPsbt.getInput(i);
                     if (!settlementInput.txid ||
@@ -1226,7 +1279,7 @@ class Wallet extends ReadonlyWallet {
                 }
                 continue;
             }
-            if ((0, _1.isRecoverable)(vtxo) || (0, _1.isSubdust)(vtxo, this.dustAmount)) {
+            if ((0, _1.isRecoverable)(input) || (0, _1.isSubdust)(input, this.dustAmount)) {
                 // recoverable or subdust coin, we don't need to create a forfeit tx
                 continue;
             }
@@ -1253,7 +1306,7 @@ class Wallet extends ReadonlyWallet {
                     txid: input.txid,
                     index: input.vout,
                     witnessUtxo: {
-                        amount: BigInt(vtxo.value),
+                        amount: BigInt(input.value),
                         script: base_2.VtxoScript.decode(input.tapTree).pkScript,
                     },
                     sighashType: btc_signer_1.SigHash.DEFAULT,
@@ -1682,9 +1735,17 @@ class Wallet extends ReadonlyWallet {
             outputs.push(extension_1.Extension.create([assetPacket]).txOut());
         }
         const sentAmount = recipients.reduce((sum, r) => sum + r.amount, 0);
-        const { arkTxid, signedCheckpointTxs } = await this.buildAndSubmitOffchainTx(selectedCoins, outputs);
-        await this.updateDbAfterOffchainTx(selectedCoins, arkTxid, signedCheckpointTxs, sentAmount, BigInt(changeAmount), changeReceiver ? changeIndex : 0, changeReceiver?.assets);
-        return arkTxid;
+        // Optimistically hide selected coins from concurrent getVtxos() while
+        // the offchain tx is in flight.
+        this._addPendingSpends(selectedCoins);
+        try {
+            const { arkTxid, signedCheckpointTxs } = await this.buildAndSubmitOffchainTx(selectedCoins, outputs);
+            await this.updateDbAfterOffchainTx(selectedCoins, arkTxid, signedCheckpointTxs, sentAmount, BigInt(changeAmount), changeReceiver ? changeIndex : 0, changeReceiver?.assets);
+            return arkTxid;
+        }
+        finally {
+            this._removePendingSpends(selectedCoins);
+        }
     }
     /**
      * Build an offchain transaction from the given inputs and outputs,

package/dist/esm/providers/ark.js

@@ -227,28 +227,21 @@ export class RestArkProvider {
         const queryParams = topics.length > 0
             ? `?${topics.map((topic) => `topics=${encodeURIComponent(topic)}`).join("&")}`
             : "";
-        // Create first EventSource eagerly so events are buffered
-        // before the caller starts iterating, preventing race conditions
-        // where the server emits events before iteration begins.
-        const eagerEventSource = new EventSource(url + queryParams);
-        const eagerIterator = eventSourceIterator(eagerEventSource);
+        // The EventSource is allocated inside the generator body so that
+        // abandoning the returned iterator before iteration starts does not
+        // leak the underlying SSE connection. `return()` is overridden below
+        // so that closing the generator also closes the connection even when
+        // the body is currently suspended at an await point.
+        let eventSource = null;
         // eslint-disable-next-line @typescript-eslint/no-this-alias
         const self = this;
-        return (async function* () {
-            let firstIteration = true;
-            while (!signal?.aborted) {
-                const eventSource = firstIteration
-                    ? eagerEventSource
-                    : new EventSource(url + queryParams);
-                const iterator = firstIteration
-                    ? eagerIterator
-                    : eventSourceIterator(eventSource);
-                firstIteration = false;
-                try {
-                    const abortHandler = () => {
-                        eventSource.close();
-                    };
-                    signal?.addEventListener("abort", abortHandler);
+        const gen = (async function* () {
+            const abortHandler = () => eventSource?.close();
+            signal?.addEventListener("abort", abortHandler);
+            try {
+                while (!signal?.aborted) {
+                    eventSource = new EventSource(url + queryParams);
+                    const iterator = eventSourceIterator(eventSource);
                     try {
                         for await (const event of iterator) {
                             if (signal?.aborted)
@@ -266,25 +259,35 @@ export class RestArkProvider {
                             }
                         }
                     }
+                    catch (error) {
+                        if (error instanceof Error &&
+                            error.name === "AbortError") {
+                            break;
+                        }
+                        // ignore timeout errors, they're expected when the server is not sending anything for 5 min
+                        if (isFetchTimeoutError(error)) {
+                            console.debug("Timeout error ignored");
+                            continue;
+                        }
+                        console.error("Event stream error:", error);
+                        throw error;
+                    }
                     finally {
-                        signal?.removeEventListener("abort", abortHandler);
                         eventSource.close();
                     }
                 }
-                catch (error) {
-                    if (error instanceof Error && error.name === "AbortError") {
-                        break;
-                    }
-                    // ignore timeout errors, they're expected when the server is not sending anything for 5 min
-                    if (isFetchTimeoutError(error)) {
-                        console.debug("Timeout error ignored");
-                        continue;
-                    }
-                    console.error("Event stream error:", error);
-                    throw error;
-                }
+            }
+            finally {
+                signal?.removeEventListener("abort", abortHandler);
+                eventSource?.close();
             }
         })();
+        const origReturn = gen.return.bind(gen);
+        gen.return = (value) => {
+            eventSource?.close();
+            return origReturn(value);
+        };
+        return gen;
     }
     async *getTransactionsStream(signal) {
         const url = `${this.serverUrl}/v1/txs`;

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

@@ -227,6 +227,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;
@@ -662,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
@@ -670,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);
                     });
@@ -687,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)
@@ -819,7 +864,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.
@@ -859,16 +905,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: [...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;
+                }
             }
-            success = true;
         }
         finally {
             this.lastPeriodicSettleTimestamp = Date.now();
@@ -883,7 +947,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 +987,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;

package/dist/esm/wallet/wallet.js

@@ -63,6 +63,12 @@ export class ReadonlyWallet {
         this.walletRepository = walletRepository;
         this.contractRepository = contractRepository;
         this.delegatorProvider = delegatorProvider;
+        // Outpoints ("txid:vout") committed to an in-flight settle/send. Filtered
+        // from getVtxos() so concurrent callers (UI, VtxoManager auto-renewal,
+        // another send/settle racing the _txLock) can't reselect coins that are
+        // already on their way out. The set is in-memory only: a process crash
+        // clears it, and a stale entry only hides a VTXO (never spends one).
+        this._pendingSpendOutpoints = new Set();
         // Guard: detect identity/server network mismatch for descriptor-based identities.
         // This duplicates the check in setupWalletConfig() so that subclasses
         // bypassing the factory still get the safety net.
@@ -303,6 +309,9 @@ export class ReadonlyWallet {
         return vtxos
             .flatMap((_) => _.vtxos)
             .filter((vtxo) => {
+            if (this._pendingSpendOutpoints.has(`${vtxo.txid}:${vtxo.vout}`)) {
+                return false;
+            }
             if (isSpendable(vtxo)) {
                 if (!f.withRecoverable &&
                     (isRecoverable(vtxo) || isExpired(vtxo))) {
@@ -754,6 +763,20 @@ export class ReadonlyWallet {
  * ```
  */
 export class Wallet extends ReadonlyWallet {
+    _addPendingSpends(inputs) {
+        for (const input of inputs) {
+            if ("virtualStatus" in input) {
+                this._pendingSpendOutpoints.add(`${input.txid}:${input.vout}`);
+            }
+        }
+    }
+    _removePendingSpends(inputs) {
+        for (const input of inputs) {
+            if ("virtualStatus" in input) {
+                this._pendingSpendOutpoints.delete(`${input.txid}:${input.vout}`);
+            }
+        }
+    }
     _withTxLock(fn) {
         let release;
         const lock = new Promise((r) => (release = r));
@@ -969,9 +992,15 @@ export class Wallet extends ReadonlyWallet {
                         amount: BigInt(selected.changeAmount),
                     });
                 }
-                const { arkTxid, signedCheckpointTxs } = await this.buildAndSubmitOffchainTx(selected.inputs, outputs);
-                await this.updateDbAfterOffchainTx(selected.inputs, arkTxid, signedCheckpointTxs, params.amount, selected.changeAmount, selected.changeAmount > 0n ? outputs.length - 1 : 0);
-                return arkTxid;
+                this._addPendingSpends(selected.inputs);
+                try {
+                    const { arkTxid, signedCheckpointTxs } = await this.buildAndSubmitOffchainTx(selected.inputs, outputs);
+                    await this.updateDbAfterOffchainTx(selected.inputs, arkTxid, signedCheckpointTxs, params.amount, selected.changeAmount, selected.changeAmount > 0n ? outputs.length - 1 : 0);
+                    return arkTxid;
+                }
+                finally {
+                    this._removePendingSpends(selected.inputs);
+                }
             });
         }
         return this.send({
@@ -1017,7 +1046,8 @@ export class Wallet extends ReadonlyWallet {
                 const tip = await this.onchainProvider.getChainTip();
                 chainTipHeight = tip.height;
             }
-            const boardingUtxos = (await this.getBoardingUtxos()).filter((utxo) => !hasBoardingTxExpired(utxo, boardingTimelock, chainTipHeight));
+            const boardingUtxos = (await this.getBoardingUtxos()).filter((utxo) => utxo.status.confirmed &&
+                !hasBoardingTxExpired(utxo, boardingTimelock, chainTipHeight));
             const filteredBoardingUtxos = [];
             for (const utxo of boardingUtxos) {
                 const inputFee = estimator.evalOnchainInput({
@@ -1152,11 +1182,29 @@ export class Wallet extends ReadonlyWallet {
             ...params.inputs.map((input) => `${input.txid}:${input.vout}`),
         ];
         const abortController = new AbortController();
+        let stream;
+        // Optimistically hide these inputs from concurrent getVtxos() callers
+        // while the settlement is in flight. Set before safeRegisterIntent so
+        // there's no window between intent registration and coin-visibility.
+        this._addPendingSpends(params.inputs);
         try {
-            const stream = this.arkProvider.getEventStream(abortController.signal, topics);
+            stream = this.arkProvider.getEventStream(abortController.signal, topics);
+            // Prime the iterator so the provider opens the SSE subscription
+            // before safeRegisterIntent can trigger server-side batch events.
+            const firstNext = stream.next();
+            // If settle exits before Batch.join consumes the primed result,
+            // keep the orphaned promise from surfacing as an unhandled rejection.
+            void firstNext.catch(() => { });
+            const primedStream = (async function* () {
+                const first = await firstNext;
+                if (!first.done) {
+                    yield first.value;
+                }
+                yield* stream;
+            })();
             const intentId = await this.safeRegisterIntent(intent, params.inputs);
             const handler = this.createBatchHandler(intentId, params.inputs, recipients, session);
-            const commitmentTxid = await Batch.join(stream, handler, {
+            const commitmentTxid = await Batch.join(primedStream, handler, {
                 abortController,
                 skipVtxoTreeSigning: !hasOffchainOutputs,
                 eventCallback: eventCallback
@@ -1180,23 +1228,28 @@ export class Wallet extends ReadonlyWallet {
             throw error;
         }
         finally {
-            // close the stream
+            // Clear state first so a synchronous handler firing from abort()
+            // never observes a stale pending-spend set.
+            this._removePendingSpends(params.inputs);
+            // close the stream — abort() fires the in-body handler if the
+            // generator has started iterating; return() also releases the
+            // eager resource if the body is still suspended or never ran
+            // (e.g. safeRegisterIntent threw before Batch.join was called).
             abortController.abort();
+            await stream?.return?.().catch(() => { });
         }
     }
     async handleSettlementFinalizationEvent(event, inputs, forfeitOutputScript, connectorsGraph) {
         // the signed forfeits transactions to submit
         const signedForfeits = [];
-        const vtxos = await this.getVtxos();
+        const isVtxo = (input) => "virtualStatus" in input;
         let settlementPsbt = Transaction.fromPSBT(base64.decode(event.commitmentTx));
         let hasBoardingUtxos = false;
         let connectorIndex = 0;
         const connectorsLeaves = connectorsGraph?.leaves() || [];
         for (const input of inputs) {
-            // check if the input is an offchain "virtual" coin
-            const vtxo = vtxos.find((vtxo) => vtxo.txid === input.txid && vtxo.vout === input.vout);
             // boarding input, we need to sign the settlement tx
-            if (!vtxo) {
+            if (!isVtxo(input)) {
                 for (let i = 0; i < settlementPsbt.inputsLength; i++) {
                     const settlementInput = settlementPsbt.getInput(i);
                     if (!settlementInput.txid ||
@@ -1220,7 +1273,7 @@ export class Wallet extends ReadonlyWallet {
                 }
                 continue;
             }
-            if (isRecoverable(vtxo) || isSubdust(vtxo, this.dustAmount)) {
+            if (isRecoverable(input) || isSubdust(input, this.dustAmount)) {
                 // recoverable or subdust coin, we don't need to create a forfeit tx
                 continue;
             }
@@ -1247,7 +1300,7 @@ export class Wallet extends ReadonlyWallet {
                     txid: input.txid,
                     index: input.vout,
                     witnessUtxo: {
-                        amount: BigInt(vtxo.value),
+                        amount: BigInt(input.value),
                         script: VtxoScript.decode(input.tapTree).pkScript,
                     },
                     sighashType: SigHash.DEFAULT,
@@ -1676,9 +1729,17 @@ export class Wallet extends ReadonlyWallet {
             outputs.push(Extension.create([assetPacket]).txOut());
         }
         const sentAmount = recipients.reduce((sum, r) => sum + r.amount, 0);
-        const { arkTxid, signedCheckpointTxs } = await this.buildAndSubmitOffchainTx(selectedCoins, outputs);
-        await this.updateDbAfterOffchainTx(selectedCoins, arkTxid, signedCheckpointTxs, sentAmount, BigInt(changeAmount), changeReceiver ? changeIndex : 0, changeReceiver?.assets);
-        return arkTxid;
+        // Optimistically hide selected coins from concurrent getVtxos() while
+        // the offchain tx is in flight.
+        this._addPendingSpends(selectedCoins);
+        try {
+            const { arkTxid, signedCheckpointTxs } = await this.buildAndSubmitOffchainTx(selectedCoins, outputs);
+            await this.updateDbAfterOffchainTx(selectedCoins, arkTxid, signedCheckpointTxs, sentAmount, BigInt(changeAmount), changeReceiver ? changeIndex : 0, changeReceiver?.assets);
+            return arkTxid;
+        }
+        finally {
+            this._removePendingSpends(selectedCoins);
+        }
     }
     /**
      * Build an offchain transaction from the given inputs and outputs,

package/dist/types/wallet/vtxo-manager.d.ts

@@ -224,6 +224,9 @@ export declare class VtxoManager implements AsyncDisposable, IVtxoManager {
     private consecutivePeriodicSettleFailures;
     private static readonly PERIODIC_SETTLE_COOLDOWN_MS;
     private static readonly PERIODIC_SETTLE_MAX_BACKOFF_MS;
+    private lastVtxoSpentRefreshTimestamp;
+    private vtxoSpentRefreshPromise?;
+    private static readonly VTXO_SPENT_REFRESH_COOLDOWN_MS;
     constructor(wallet: IWallet, 
     /** @deprecated Use settlementConfig instead */
     renewalConfig?: RenewalConfig | undefined, settlementConfig?: SettlementConfig | false);
@@ -402,6 +405,16 @@ export declare class VtxoManager implements AsyncDisposable, IVtxoManager {
     /** Returns the wallet's identity for transaction signing. */
     private getIdentity;
     private initializeSubscription;
+    /**
+     * 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.
+     */
+    private maybeRefreshAfterVtxoSpent;
     /** Computes the next poll delay, applying exponential backoff on failures. */
     private getNextPollDelay;
     /**

package/dist/types/wallet/wallet.d.ts

@@ -44,6 +44,7 @@ export declare class ReadonlyWallet implements IReadonlyWallet {
     protected readonly watcherConfig?: ReadonlyWalletConfig["watcherConfig"];
     private readonly _assetManager;
     private _syncVtxosInflight?;
+    protected _pendingSpendOutpoints: Set<string>;
     get assetManager(): IReadonlyAssetManager;
     protected constructor(identity: ReadonlyIdentity, network: Network, onchainProvider: OnchainProvider, indexerProvider: IndexerProvider, arkServerPublicKey: Bytes, offchainTapscript: DefaultVtxo.Script | DelegateVtxo.Script, boardingTapscript: DefaultVtxo.Script, dustAmount: bigint, walletRepository: WalletRepository, contractRepository: ContractRepository, delegatorProvider?: DelegatorProvider | undefined, watcherConfig?: ReadonlyWalletConfig["watcherConfig"]);
     /**
@@ -217,6 +218,8 @@ export declare class Wallet extends ReadonlyWallet implements IWallet {
      * same VTXO inputs.
      */
     private _txLock;
+    private _addPendingSpends;
+    private _removePendingSpends;
     private _withTxLock;
     /** @deprecated Use settlementConfig instead */
     readonly renewalConfig: Required<Omit<WalletConfig["renewalConfig"], "enabled">> & {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arkade-os/sdk",
-  "version": "0.4.18",
+  "version": "0.4.19",
   "description": "TypeScript SDK for building Bitcoin wallets using the Arkade protocol",
   "type": "module",
   "main": "./dist/cjs/index.js",