@arkade-os/sdk 0.4.24 → 0.4.25

package/dist/cjs/contracts/contractManager.js

@@ -373,6 +373,46 @@ class ContractManager {
                 : undefined,
         });
     }
+    async refreshOutpoints(outpoints) {
+        if (outpoints.length === 0)
+            return;
+        const { vtxos } = await this.config.indexerProvider.getVtxos({
+            outpoints,
+        });
+        if (vtxos.length === 0)
+            return;
+        // Filter to outputs whose script we own. Map them to their owning
+        // contract so we can write through to the right per-address entry
+        // in the wallet repository.
+        const scripts = Array.from(new Set(vtxos.map((v) => v.script)));
+        const contracts = await this.config.contractRepository.getContracts({
+            script: scripts,
+        });
+        const scriptToContract = new Map(contracts.map((c) => [c.script, c]));
+        const owned = vtxos.filter((v) => scriptToContract.has(v.script));
+        if (owned.length === 0)
+            return;
+        const annotated = await this.annotateVtxos(owned);
+        const byAddress = new Map();
+        for (const vtxo of annotated) {
+            const contract = scriptToContract.get(vtxo.script);
+            if (!contract)
+                continue;
+            const address = contract.address;
+            const arr = byAddress.get(address) ?? [];
+            arr.push(vtxo);
+            byAddress.set(address, arr);
+        }
+        for (const [address, addressVtxos] of byAddress) {
+            const contract = contracts.find((c) => c.address === address);
+            if (contract) {
+                await (0, vtxoOwnership_1.saveVtxosForContract)(this.config.walletRepository, contract, addressVtxos);
+            }
+            else {
+                await this.config.walletRepository.saveVtxos(address, addressVtxos);
+            }
+        }
+    }
     /**
      * Check if currently watching.
      */
@@ -413,13 +453,9 @@ class ContractManager {
         this.emitEvent(event);
     }
     async getVtxosForContracts(contracts) {
-        const res = await Promise.all(contracts.map(({ script, address }) => this.config.walletRepository.getVtxos(address).then((vtxos) => 
-        // Address buckets may carry legacy duplicate rows from
-        // other contracts that once shared the same address —
-        // gate by script so the wrong-script row never wins.
-        (0, vtxoOwnership_1.filterVtxosForScript)(vtxos, script).map((vtxo) => ({
+        const res = await Promise.all(contracts.map((contract) => (0, vtxoOwnership_1.getVtxosForContract)(this.config.walletRepository, contract).then((vtxos) => vtxos.map((vtxo) => ({
             ...vtxo,
-            contractScript: script,
+            contractScript: contract.script,
         })))));
         return res.flat();
     }
@@ -492,7 +528,7 @@ class ContractManager {
             const filtered = (0, vtxoOwnership_1.warnAndFilterVtxosForScript)(contractVtxos, contract.script, "ContractManager.reconcilePendingFrontier");
             if (filtered.length === 0)
                 continue;
-            await this.config.walletRepository.saveVtxos(addr, filtered);
+            await (0, vtxoOwnership_1.saveVtxosForContract)(this.config.walletRepository, contract, filtered);
         }
     }
     async fetchContractVxosFromIndexer(contracts, pageSize, syncWindow) {
@@ -505,7 +541,7 @@ class ContractManager {
                 const filtered = (0, vtxoOwnership_1.warnAndFilterVtxosForScript)(vtxos, contract.script, "ContractManager.fetchContractVxosFromIndexer");
                 if (filtered.length === 0)
                     continue;
-                await this.config.walletRepository.saveVtxos(contract.address, filtered);
+                await (0, vtxoOwnership_1.saveVtxosForContract)(this.config.walletRepository, contract, filtered);
             }
         }
         return result;

package/dist/cjs/contracts/contractWatcher.js

@@ -94,7 +94,7 @@ class ContractWatcher {
             // Apply the same script gate used by getContractVtxos so a legacy
             // wrong-script row in the address bucket can't seed the baseline
             // and then look "spent" on the first poll.
-            const cached = (0, vtxoOwnership_1.filterVtxosForScript)(await this.config.walletRepository.getVtxos(state.contract.address), state.contract.script);
+            const cached = await (0, vtxoOwnership_1.getVtxosForContract)(this.config.walletRepository, state.contract);
             for (const vtxo of cached) {
                 if (vtxo.isSpent)
                     continue;
@@ -176,7 +176,7 @@ class ContractWatcher {
             // Use contract address as cache key. Legacy address buckets
             // can contain rows from other contracts; gate by script before
             // converting so a wrong-script row never reaches the watcher.
-            const cached = (0, vtxoOwnership_1.filterVtxosForScript)(await repo.getVtxos(state.contract.address), state.contract.script);
+            const cached = await (0, vtxoOwnership_1.getVtxosForContract)(repo, state.contract);
             if (cached.length > 0) {
                 // Convert to ContractVtxo with contractScript
                 const contractVtxos = cached.map((v) => ({

package/dist/cjs/contracts/vtxoOwnership.js

@@ -5,6 +5,8 @@ exports.isVtxoForScript = isVtxoForScript;
 exports.filterVtxosForScript = filterVtxosForScript;
 exports.warnAndFilterVtxosForScript = warnAndFilterVtxosForScript;
 exports.validateVtxosForScript = validateVtxosForScript;
+exports.getVtxosForContract = getVtxosForContract;
+exports.saveVtxosForContract = saveVtxosForContract;
 /**
  * Tier 1 helpers that enforce VTXO ownership at call sites that already know
  * the intended contract script. Address-keyed repositories may still hand back
@@ -58,3 +60,19 @@ function validateVtxosForScript(vtxos, script, context) {
         .join(", ");
     throw new Error(`${context}: refusing to persist ${mismatches.length} VTXO(s) whose script does not match ${script}: ${detail}`);
 }
+/**
+ * Tier 2 dispatch helpers: route to script-scoped repository methods when
+ * available, falling back to Tier 1 address-based filtering otherwise.
+ */
+async function getVtxosForContract(repo, contract) {
+    return repo.getVtxosForScript
+        ? repo.getVtxosForScript(contract.script)
+        : filterVtxosForScript(await repo.getVtxos(contract.address), contract.script);
+}
+async function saveVtxosForContract(repo, contract, vtxos) {
+    if (repo.saveVtxosForScript) {
+        return repo.saveVtxosForScript({ script: contract.script, address: contract.address }, vtxos);
+    }
+    validateVtxosForScript(vtxos, contract.script, "saveVtxosForContract");
+    return repo.saveVtxos(contract.address, vtxos);
+}

package/dist/cjs/repositories/inMemory/walletRepository.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.InMemoryWalletRepository = void 0;
+const vtxoOwnership_1 = require("../../contracts/vtxoOwnership");
 /**
  * In-memory implementation of WalletRepository.
  * Data is ephemeral and scoped to the instance.
@@ -24,6 +25,40 @@ class InMemoryWalletRepository {
     async deleteVtxos(address) {
         this.vtxosByAddress.delete(address);
     }
+    async getVtxosForScript(script) {
+        const allMatches = [];
+        for (const bucket of this.vtxosByAddress.values()) {
+            for (const vtxo of bucket) {
+                if ((0, vtxoOwnership_1.isVtxoForScript)(vtxo, script)) {
+                    allMatches.push(vtxo);
+                }
+            }
+        }
+        // Dedup by outpoint (last-write-wins across address buckets)
+        return mergeByKey([], allMatches, (item) => `${item.txid}:${item.vout}`);
+    }
+    async saveVtxosForScript(key, vtxos) {
+        if (!key.address) {
+            throw new Error("InMemoryWalletRepository requires an address");
+        }
+        for (const vtxo of vtxos) {
+            if (!(0, vtxoOwnership_1.isVtxoForScript)(vtxo, key.script)) {
+                throw new Error(`VTXO ${vtxo.txid}:${vtxo.vout} script mismatch: expected ${key.script}, got ${vtxo.script}`);
+            }
+        }
+        return this.saveVtxos(key.address, vtxos);
+    }
+    async deleteVtxosForScript(script) {
+        for (const [address, bucket] of this.vtxosByAddress.entries()) {
+            const next = bucket.filter((v) => !(0, vtxoOwnership_1.isVtxoForScript)(v, script));
+            if (next.length === 0) {
+                this.vtxosByAddress.delete(address);
+            }
+            else {
+                this.vtxosByAddress.set(address, next);
+            }
+        }
+    }
     async getUtxos(address) {
         return this.utxosByAddress.get(address) ?? [];
     }

package/dist/cjs/repositories/indexedDB/walletRepository.js

@@ -6,6 +6,7 @@ const manager_1 = require("./manager");
 const schema_1 = require("./schema");
 const scriptFromAddress_1 = require("../scriptFromAddress");
 const utils_1 = require("../../worker/browser/utils");
+const vtxoOwnership_1 = require("../../contracts/vtxoOwnership");
 /**
  * IndexedDB-based implementation of WalletRepository.
  */
@@ -144,6 +145,85 @@ class IndexedDBWalletRepository {
             throw error;
         }
     }
+    async getVtxosForScript(script) {
+        try {
+            const db = await this.getDB();
+            return new Promise((resolve, reject) => {
+                const transaction = db.transaction([db_1.STORE_VTXOS], "readonly");
+                const store = transaction.objectStore(db_1.STORE_VTXOS);
+                const index = store.index("script");
+                const request = index.getAll(script);
+                request.onerror = () => reject(request.error);
+                request.onsuccess = () => {
+                    const results = request.result || [];
+                    try {
+                        // Defensive filter: only rows whose script matches.
+                        const matching = results.filter((r) => r.script === script);
+                        // Dedup same outpoint rows across address buckets.
+                        // Work on raw rows so the address field is available
+                        // for the canonicality tiebreaker.
+                        const byOutpoint = new Map();
+                        for (const row of matching) {
+                            const outpoint = `${row.txid}:${row.vout}`;
+                            const existing = byOutpoint.get(outpoint);
+                            if (!existing) {
+                                byOutpoint.set(outpoint, row);
+                                continue;
+                            }
+                            if (shouldReplaceVtxo(existing, row)) {
+                                byOutpoint.set(outpoint, row);
+                            }
+                        }
+                        resolve(Array.from(byOutpoint.values()).map(deserializeVtxoWithBackfill));
+                    }
+                    catch (err) {
+                        reject(err);
+                    }
+                };
+            });
+        }
+        catch (error) {
+            console.error(`Failed to get VTXOs for script ${script}:`, error);
+            throw error;
+        }
+    }
+    async saveVtxosForScript(key, vtxos) {
+        if (!key.address) {
+            throw new Error("IndexedDBWalletRepository requires an address");
+        }
+        for (const vtxo of vtxos) {
+            if (!(0, vtxoOwnership_1.isVtxoForScript)(vtxo, key.script)) {
+                throw new Error(`VTXO ${vtxo.txid}:${vtxo.vout} script mismatch: expected ${key.script}, got ${vtxo.script}`);
+            }
+        }
+        return this.saveVtxos(key.address, vtxos);
+    }
+    async deleteVtxosForScript(script) {
+        try {
+            const db = await this.getDB();
+            return new Promise((resolve, reject) => {
+                const transaction = db.transaction([db_1.STORE_VTXOS], "readwrite");
+                const store = transaction.objectStore(db_1.STORE_VTXOS);
+                const index = store.index("script");
+                const request = index.openCursor(IDBKeyRange.only(script));
+                request.onerror = () => reject(request.error);
+                request.onsuccess = () => {
+                    const cursor = request.result;
+                    if (cursor) {
+                        cursor.delete();
+                        cursor.continue();
+                    }
+                    else {
+                        resolve();
+                    }
+                };
+            });
+        }
+        catch (error) {
+            console.error(`Failed to clear VTXOs for script ${script}:`, error);
+            throw error;
+        }
+    }
     async getUtxos(address) {
         try {
             const db = await this.getDB();
@@ -355,3 +435,40 @@ function deserializeVtxoWithBackfill(o) {
     }
     return (0, db_1.deserializeVtxo)(o);
 }
+function isCanonicalRow(row) {
+    try {
+        return (0, scriptFromAddress_1.scriptFromArkAddress)(row.address) === row.script;
+    }
+    catch {
+        return false;
+    }
+}
+function shouldReplaceVtxo(existing, incoming) {
+    const existingCanonical = isCanonicalRow(existing);
+    const incomingCanonical = isCanonicalRow(incoming);
+    if (incomingCanonical && !existingCanonical)
+        return true;
+    if (existingCanonical && !incomingCanonical)
+        return false;
+    // Tie on canonicality, check lifecycle completeness
+    const existingWeight = getLifecycleWeight(existing);
+    const incomingWeight = getLifecycleWeight(incoming);
+    if (incomingWeight > existingWeight)
+        return true;
+    if (existingWeight > incomingWeight)
+        return false;
+    // Tie on weight, stable sort by address
+    return incoming.address < existing.address;
+}
+function getLifecycleWeight(v) {
+    let weight = 0;
+    if (v.isSpent !== undefined)
+        weight += 1;
+    if (v.spentBy)
+        weight += 2;
+    if (v.settledBy)
+        weight += 2;
+    if (v.arkTxId)
+        weight += 2;
+    return weight;
+}

package/dist/cjs/repositories/realm/walletRepository.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.RealmWalletRepository = void 0;
 const serialization_1 = require("../serialization");
 const scriptFromAddress_1 = require("../scriptFromAddress");
+const vtxoOwnership_1 = require("../../contracts/vtxoOwnership");
 /**
  * Realm-based implementation of WalletRepository.
  *
@@ -88,6 +89,33 @@ class RealmWalletRepository {
             this.realm.delete(toDelete);
         });
     }
+    async getVtxosForScript(script) {
+        await this.ensureInit();
+        const results = this.realm
+            .objects("ArkVtxo")
+            .filtered("script == $0", script);
+        return [...results].map(vtxoObjectToDomain);
+    }
+    async saveVtxosForScript(key, vtxos) {
+        if (!key.address) {
+            throw new Error("RealmWalletRepository requires an address");
+        }
+        for (const vtxo of vtxos) {
+            if (!(0, vtxoOwnership_1.isVtxoForScript)(vtxo, key.script)) {
+                throw new Error(`VTXO ${vtxo.txid}:${vtxo.vout} script mismatch: expected ${key.script}, got ${vtxo.script}`);
+            }
+        }
+        return this.saveVtxos(key.address, vtxos);
+    }
+    async deleteVtxosForScript(script) {
+        await this.ensureInit();
+        this.realm.write(() => {
+            const toDelete = this.realm
+                .objects("ArkVtxo")
+                .filtered("script == $0", script);
+            this.realm.delete(toDelete);
+        });
+    }
     // ── UTXO management ────────────────────────────────────────────────
     async getUtxos(address) {
         await this.ensureInit();

package/dist/cjs/repositories/sqlite/walletRepository.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.SQLiteWalletRepository = void 0;
 const serialization_1 = require("../serialization");
 const scriptFromAddress_1 = require("../scriptFromAddress");
+const vtxoOwnership_1 = require("../../contracts/vtxoOwnership");
 /**
  * SQLite-based implementation of WalletRepository.
  *
@@ -245,6 +246,28 @@ class SQLiteWalletRepository {
         await this.ensureInit();
         await this.db.run(`DELETE FROM ${this.tables.vtxos} WHERE address = ?`, [address]);
     }
+    async getVtxosForScript(script) {
+        await this.ensureInit();
+        const rows = await this.db.all(`SELECT * FROM ${this.tables.vtxos} WHERE script = ?`, [script]);
+        return rows.map(vtxoRowToDomain);
+    }
+    async saveVtxosForScript(key, vtxos) {
+        if (!key.address) {
+            throw new Error("SQLiteWalletRepository requires an address");
+        }
+        for (const vtxo of vtxos) {
+            if (!(0, vtxoOwnership_1.isVtxoForScript)(vtxo, key.script)) {
+                throw new Error(`VTXO ${vtxo.txid}:${vtxo.vout} script mismatch: expected ${key.script}, got ${vtxo.script}`);
+            }
+        }
+        return this.saveVtxos(key.address, vtxos);
+    }
+    async deleteVtxosForScript(script) {
+        await this.ensureInit();
+        await this.db.run(`DELETE FROM ${this.tables.vtxos} WHERE script = ?`, [
+            script,
+        ]);
+    }
     // ── UTXO management ────────────────────────────────────────────────
     async getUtxos(address) {
         await this.ensureInit();

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

@@ -319,6 +319,16 @@ class WalletMessageHandler {
                         type: "REFRESH_VTXOS_SUCCESS",
                     });
                 }
+                case "REFRESH_OUTPOINTS": {
+                    const manager = await this.readonlyWallet.getContractManager();
+                    const { outpoints } = message
+                        .payload;
+                    await manager.refreshOutpoints(outpoints);
+                    return this.tagged({
+                        id,
+                        type: "REFRESH_OUTPOINTS_SUCCESS",
+                    });
+                }
                 case "SEND": {
                     const { recipients } = message.payload;
                     const txid = await this.wallet.send(...recipients);
@@ -626,7 +636,9 @@ class WalletMessageHandler {
                             : addrByScript.get(script);
                         if (!targetAddress)
                             continue;
-                        await this.walletRepository?.saveVtxos(targetAddress, filtered);
+                        if (this.walletRepository) {
+                            await (0, vtxoOwnership_1.saveVtxosForContract)(this.walletRepository, { script, address: targetAddress }, filtered);
+                        }
                     }
                     // notify all clients about the virtual output state update
                     this.scheduleForNextTick(() => this.tagged({
@@ -846,8 +858,7 @@ class WalletMessageHandler {
         const manager = await this.readonlyWallet.getContractManager();
         const contracts = await manager.getContracts();
         for (const contract of contracts) {
-            const vtxos = await this.walletRepository.getVtxos(contract.address);
-            addVtxos((0, vtxoOwnership_1.filterVtxosForScript)(vtxos, contract.script));
+            addVtxos(await (0, vtxoOwnership_1.getVtxosForContract)(this.walletRepository, contract));
         }
         // Also check the wallet's primary address. Decode it to its script
         // and apply the same script gate. Failing to decode the wallet's own

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

@@ -60,6 +60,7 @@ exports.DEFAULT_MESSAGE_TIMEOUTS = {
     UPDATE_CONTRACT: 30000,
     DELETE_CONTRACT: 10000,
     REFRESH_VTXOS: 30000,
+    REFRESH_OUTPOINTS: 30000,
 };
 const DEDUPABLE_REQUEST_TYPES = new Set([
     "GET_ADDRESS",
@@ -824,6 +825,15 @@ class ServiceWorkerReadonlyWallet {
                 };
                 await sendContractMessage(message);
             },
+            async refreshOutpoints(outpoints) {
+                const message = {
+                    type: "REFRESH_OUTPOINTS",
+                    id: (0, utils_2.getRandomId)(),
+                    tag: messageTag,
+                    payload: { outpoints },
+                };
+                await sendContractMessage(message);
+            },
             async isWatching() {
                 const message = {
                     type: "IS_CONTRACT_MANAGER_WATCHING",

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

@@ -4,6 +4,7 @@ exports.VtxoManager = exports.DEFAULT_SETTLEMENT_CONFIG = exports.DEFAULT_RENEWA
 exports.isVtxoExpiringSoon = isVtxoExpiringSoon;
 exports.getExpiringAndRecoverableVtxos = getExpiringAndRecoverableVtxos;
 const _1 = require(".");
+const errors_1 = require("../providers/errors");
 const arkTransaction_1 = require("../utils/arkTransaction");
 const tapscript_1 = require("../script/tapscript");
 const base_1 = require("@scure/base");
@@ -437,10 +438,22 @@ class VtxoManager {
         try {
             // Get all virtual outputs (including recoverable ones)
             // Use default threshold to bypass settlementConfig gate (manual API should always work)
-            const vtxos = await this.getExpiringVtxos(this.settlementConfig !== false &&
+            const threshold = this.settlementConfig !== false &&
                 this.settlementConfig?.vtxoThreshold !== undefined
                 ? this.settlementConfig.vtxoThreshold * 1000
-                : exports.DEFAULT_RENEWAL_CONFIG.thresholdMs);
+                : exports.DEFAULT_RENEWAL_CONFIG.thresholdMs;
+            let vtxos = await this.getExpiringVtxos(threshold);
+            if (vtxos.length === 0) {
+                throw new Error("No VTXOs available to renew");
+            }
+            // Pre-flight: validate the chosen inputs against the indexer's
+            // authoritative state before submitting. The cursor-derived
+            // delta sync filters by `created_at`, so a VTXO created
+            // before the cursor and spent recently can sit in the local
+            // cache forever; settling against it yields a guaranteed
+            // VTXO_ALREADY_SPENT 400. Refreshing the candidates here
+            // catches that BEFORE the network round-trip.
+            vtxos = await this.revalidateBeforeSettle(vtxos, threshold);
             if (vtxos.length === 0) {
                 throw new Error("No VTXOs available to renew");
             }
@@ -689,9 +702,11 @@ class VtxoManager {
                             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();
+                                // throttled, targeted refresh on the
+                                // offending outpoint (if the server told
+                                // us which one), then skip — the next
+                                // cycle will see fresh data.
+                                void this.maybeRefreshAfterVtxoSpent(this.extractSpentOutpoint(e));
                                 return;
                             }
                         }
@@ -716,13 +731,20 @@ class VtxoManager {
     /**
      * 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.
+     * SSE gap left stale data in the local cache. Silent-swallowing
+     * guarantees the same error on the next cycle because nothing
+     * reconciles the cache.
+     *
+     * The cursor-derived delta sync filters by `created_at`, so a VTXO that
+     * was created before the cursor but spent recently can never be
+     * reconciled by `refreshVtxos()`. Use `refreshOutpoints` for surgical
+     * recovery: query the indexer for the specific stale outpoint and
+     * upsert its authoritative state into the wallet repository.
+     *
+     * Throttled because the same VTXO can fire repeatedly before the
+     * upsert observably propagates through the renewal selector.
      */
-    maybeRefreshAfterVtxoSpent() {
+    maybeRefreshAfterVtxoSpent(spentOutpoint) {
         if (this.vtxoSpentRefreshPromise) {
             return this.vtxoSpentRefreshPromise;
         }
@@ -735,7 +757,13 @@ class VtxoManager {
         this.vtxoSpentRefreshPromise = (async () => {
             try {
                 const contractManager = await this.wallet.getContractManager();
-                await contractManager.refreshVtxos();
+                if (spentOutpoint) {
+                    await contractManager.refreshOutpoints([spentOutpoint]);
+                }
+                else {
+                    // No outpoint metadata — fall back to the broader refresh.
+                    await contractManager.refreshVtxos();
+                }
             }
             catch (e) {
                 console.error("Error refreshing VTXOs after VTXO_ALREADY_SPENT:", e);
@@ -746,6 +774,66 @@ class VtxoManager {
         })();
         return this.vtxoSpentRefreshPromise;
     }
+    /**
+     * Extract the offending VTXO outpoint from a `VTXO_ALREADY_SPENT` error,
+     * if the server attached one in `metadata.vtxo_outpoint`. Returns
+     * `undefined` when the error isn't a parsed ArkError, isn't this code,
+     * or doesn't carry the metadata.
+     */
+    extractSpentOutpoint(error) {
+        const ark = (0, errors_1.maybeArkError)(error);
+        if (!ark || ark.name !== "VTXO_ALREADY_SPENT")
+            return undefined;
+        const raw = ark.metadata?.vtxo_outpoint;
+        if (typeof raw !== "string")
+            return undefined;
+        const [txid, voutStr] = raw.split(":");
+        if (!txid || !voutStr)
+            return undefined;
+        const vout = Number(voutStr);
+        if (!Number.isInteger(vout) || vout < 0)
+            return undefined;
+        return { txid, vout };
+    }
+    /**
+     * Reconcile the chosen VTXOs with the indexer's authoritative state
+     * before submitting a settle intent. Pulls the canonical record for
+     * each candidate outpoint via {@link IContractManager.refreshOutpoints}
+     * (which upserts the result into the wallet repository), then
+     * re-selects through the standard expiring-vtxo filter so anything
+     * the refresh flagged as spent is dropped.
+     *
+     * Best-effort: a failed refresh just falls back to the original
+     * candidates and lets the post-submit `VTXO_ALREADY_SPENT` recovery
+     * handle whatever slipped through.
+     */
+    async revalidateBeforeSettle(candidates, thresholdMs) {
+        if (candidates.length === 0)
+            return candidates;
+        try {
+            const cm = await this.wallet.getContractManager();
+            await cm.refreshOutpoints(candidates.map((v) => ({ txid: v.txid, vout: v.vout })));
+        }
+        catch (e) {
+            console.error("Error pre-validating VTXOs before settle:", e);
+            return candidates;
+        }
+        // Re-select from the now-fresh local cache. Anything previously
+        // selected but spent gets filtered out by the standard
+        // `isSpendable`/`isSpent` checks inside getVtxos / getExpiringVtxos.
+        try {
+            const refreshed = await this.getExpiringVtxos(thresholdMs);
+            const candidateKeys = new Set(candidates.map((v) => `${v.txid}:${v.vout}`));
+            // Restrict to vtxos that were also in the original candidate set
+            // — `getExpiringVtxos` may surface NEW vtxos and we don't want
+            // pre-flight to silently expand the input set.
+            return refreshed.filter((v) => candidateKeys.has(`${v.txid}:${v.vout}`));
+        }
+        catch (e) {
+            console.error("Error re-selecting VTXOs after pre-validate:", e);
+            return candidates;
+        }
+    }
     /** Computes the next poll delay, applying exponential backoff on failures. */
     getNextPollDelay() {
         if (this.settlementConfig === false)
@@ -887,6 +975,13 @@ class VtxoManager {
         if (!this.renewalInProgress) {
             try {
                 expiringVtxos = await this.getExpiringVtxos();
+                // Pre-flight validation: see comment in `renewVtxos`. The
+                // local cache may carry vtxos that the indexer already
+                // marks spent because the cursor-derived delta sync only
+                // catches `created_at`-recent updates, not status changes
+                // for older VTXOs.
+                expiringVtxos =
+                    await this.revalidateBeforeSettle(expiringVtxos);
             }
             catch (e) {
                 // Non-fatal: fall back to boarding-only settle.
@@ -978,11 +1073,12 @@ class VtxoManager {
                     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.
+                    // Trigger a throttled, targeted refresh on the
+                    // offending outpoint and skip this cycle without
+                    // bumping the failure counter, so the next poll
+                    // can retry once the cache reconciles.
                     staleCacheSkip = true;
-                    void this.maybeRefreshAfterVtxoSpent();
+                    void this.maybeRefreshAfterVtxoSpent(this.extractSpentOutpoint(e));
                 }
                 else {
                     throw e;