@arkade-os/sdk 0.4.24 → 0.4.26

package/dist/esm/script/delegate.js

@@ -1,6 +1,6 @@
-import { DefaultVtxo } from './default.js';
-import { MultisigTapscript } from './tapscript.js';
-import { VtxoScript } from './base.js';
+import { DefaultVtxo } from "./default.js";
+import { MultisigTapscript } from "./tapscript.js";
+import { VtxoScript } from "./base.js";
 import { hex } from "@scure/base";
 /**
  * DelegateVtxo extends DefaultVtxo with an extra delegator path

package/dist/esm/script/tapscript.js

@@ -1,6 +1,6 @@
 import { Script, ScriptNum, p2tr_ms } from "@scure/btc-signer";
 import { hex } from "@scure/base";
-import { sequenceToTimelock, timelockToSequence } from '../utils/timelock.js';
+import { sequenceToTimelock, timelockToSequence } from "../utils/timelock.js";
 const MinimalScriptNum = ScriptNum(undefined, true);
 export var TapscriptType;
 (function (TapscriptType) {

package/dist/esm/script/vhtlc.js

@@ -1,7 +1,7 @@
 import { Script } from "@scure/btc-signer";
-import { CLTVMultisigTapscript, ConditionCSVMultisigTapscript, ConditionMultisigTapscript, CSVMultisigTapscript, MultisigTapscript, } from './tapscript.js';
+import { CLTVMultisigTapscript, ConditionCSVMultisigTapscript, ConditionMultisigTapscript, CSVMultisigTapscript, MultisigTapscript, } from "./tapscript.js";
 import { hex } from "@scure/base";
-import { VtxoScript } from './base.js';
+import { VtxoScript } from "./base.js";
 /** Virtual Hash Time Lock Contract (VHTLC) namespace. */
 export var VHTLC;
 (function (VHTLC) {

package/dist/esm/storage/indexedDB.js

@@ -1,4 +1,4 @@
-import { DB_VERSION } from '../repositories/indexedDB/db.js';
+import { DB_VERSION } from "../repositories/indexedDB/db.js";
 /**
  * @deprecated Use repository implementations via `StorageConfig` instead.
  */

package/dist/esm/tree/signingSession.js

@@ -1,10 +1,10 @@
-import * as musig2 from '../musig2/index.js';
+import * as musig2 from "../musig2/index.js";
 import { Script } from "@scure/btc-signer/script.js";
 import { SigHash } from "@scure/btc-signer/transaction.js";
 import { hex } from "@scure/base";
 import { schnorr, secp256k1 } from "@noble/curves/secp256k1.js";
 import { randomPrivateKeyBytes } from "@scure/btc-signer/utils.js";
-import { CosignerPublicKey, getArkPsbtFields } from '../utils/unknownFields.js';
+import { CosignerPublicKey, getArkPsbtFields } from "../utils/unknownFields.js";
 export const ErrMissingVtxoGraph = new Error("missing vtxo graph");
 export const ErrMissingAggregateKey = new Error("missing aggregate key");
 export class TreeSignerSession {

package/dist/esm/tree/validation.js

@@ -1,8 +1,8 @@
 import { hex } from "@scure/base";
 import { Transaction } from "@scure/btc-signer/transaction.js";
 import { base64 } from "@scure/base";
-import { aggregateKeys } from '../musig2/index.js';
-import { CosignerPublicKey, getArkPsbtFields } from '../utils/unknownFields.js';
+import { aggregateKeys } from "../musig2/index.js";
+import { CosignerPublicKey, getArkPsbtFields } from "../utils/unknownFields.js";
 export const ErrInvalidSettlementTx = (tx) => new Error(`invalid settlement transaction: ${tx}`);
 export const ErrInvalidSettlementTxOutputs = new Error("invalid settlement transaction outputs");
 export const ErrEmptyTree = new Error("empty tree");

package/dist/esm/utils/arkTransaction.js

@@ -2,13 +2,13 @@ import { schnorr } from "@noble/curves/secp256k1.js";
 import { hex } from "@scure/base";
 import { DEFAULT_SEQUENCE, Script, SigHash } from "@scure/btc-signer";
 import { tapLeafHash } from "@scure/btc-signer/payment.js";
-import { CLTVMultisigTapscript, decodeTapscript, } from '../script/tapscript.js';
-import { scriptFromTapLeafScript, VtxoScript, } from '../script/base.js';
-import { P2A } from './anchor.js';
-import { setArkPsbtField, VtxoTaprootTree } from './unknownFields.js';
-import { Transaction } from './transaction.js';
-import { ArkAddress } from '../script/address.js';
-import { Extension } from '../extension/index.js';
+import { CLTVMultisigTapscript, decodeTapscript, } from "../script/tapscript.js";
+import { scriptFromTapLeafScript, VtxoScript, } from "../script/base.js";
+import { P2A } from "./anchor.js";
+import { setArkPsbtField, VtxoTaprootTree } from "./unknownFields.js";
+import { Transaction } from "./transaction.js";
+import { ArkAddress } from "../script/address.js";
+import { Extension } from "../extension/index.js";
 /**
  * Builds an offchain transaction with checkpoint transactions.
  *

package/dist/esm/utils/transactionHistory.js

@@ -1,4 +1,4 @@
-import { TxType } from '../wallet/index.js';
+import { TxType } from "../wallet/index.js";
 const txKey = {
     commitmentTxid: "",
     boardingTxid: "",

package/dist/esm/utils/unknownFields.js

@@ -1,6 +1,6 @@
 import { RawWitness, ScriptNum } from "@scure/btc-signer";
 import { hex } from "@scure/base";
-import { sequenceToTimelock } from './timelock.js';
+import { sequenceToTimelock } from "./timelock.js";
 /**
  * ArkPsbtFieldKey are the available key names for the Arkade PSBT custom fields.
  */

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

@@ -1,8 +1,8 @@
-import { AssetGroup, AssetId, AssetInput, AssetOutput, AssetRef, Metadata, Packet, } from '../extension/asset/index.js';
-import { ArkAddress } from '../script/address.js';
-import { selectedCoinsToAssetInputs, selectCoinsWithAsset } from './asset.js';
-import { Extension } from '../extension/index.js';
-import { selectVirtualCoins } from './wallet.js';
+import { AssetGroup, AssetId, AssetInput, AssetOutput, AssetRef, Metadata, Packet, } from "../extension/asset/index.js";
+import { ArkAddress } from "../script/address.js";
+import { selectedCoinsToAssetInputs, selectCoinsWithAsset } from "./asset.js";
+import { Extension } from "../extension/index.js";
+import { selectVirtualCoins } from "./wallet.js";
 export class ReadonlyAssetManager {
     constructor(indexer) {
         this.indexer = indexer;

package/dist/esm/wallet/asset.js

@@ -1,4 +1,4 @@
-import { AssetGroup, AssetId, AssetInput, AssetOutput, Packet, } from '../extension/asset/index.js';
+import { AssetGroup, AssetId, AssetInput, AssetOutput, Packet, } from "../extension/asset/index.js";
 /**
  * Creates an asset packet from asset inputs and receivers.
  * Groups inputs and outputs by asset ID and creates the Packet object

package/dist/esm/wallet/batch.js

@@ -1,5 +1,5 @@
-import { SettlementEventType } from '../providers/ark.js';
-import { TxTree } from '../tree/txTree.js';
+import { SettlementEventType } from "../providers/ark.js";
+import { TxTree } from "../tree/txTree.js";
 import { hex } from "@scure/base";
 /**
  * Batch namespace provides utilities for joining and processing batch session.

package/dist/esm/wallet/delegator.js

@@ -1,12 +1,12 @@
-import { ArkAddress, decodeTapscript, Estimator, Intent, isRecoverable, MultisigTapscript, VtxoScript, } from '../index.js';
+import { ArkAddress, decodeTapscript, Estimator, Intent, isRecoverable, MultisigTapscript, VtxoScript, } from "../index.js";
 import { base64, hex } from "@scure/base";
-import { scriptFromTapLeafScript } from '../script/base.js';
-import { buildForfeitTxWithOutput } from '../forfeit.js';
+import { scriptFromTapLeafScript } from "../script/base.js";
+import { buildForfeitTxWithOutput } from "../forfeit.js";
 import { Address, OutScript, SigHash } from "@scure/btc-signer";
 import { equalBytes } from "@scure/btc-signer/utils.js";
-import { getNetwork } from '../networks.js';
-import { createAssetPacket } from './asset.js';
-import { Extension } from '../extension/index.js';
+import { getNetwork } from "../networks.js";
+import { createAssetPacket } from "./asset.js";
+import { Extension } from "../extension/index.js";
 export class DelegatorManagerImpl {
     /** Create a delegator manager from the configured provider, Arkade info source, and wallet identity. */
     constructor(delegatorProvider, arkInfoProvider, identity) {

package/dist/esm/wallet/expo/background.js

@@ -1,8 +1,8 @@
-import { runTasks, createTaskDependencies } from '../../worker/expo/taskRunner.js';
-import { contractPollProcessor, CONTRACT_POLL_TASK_TYPE, } from '../../worker/expo/processors/index.js';
-import { ExpoArkProvider } from '../../providers/expoArk.js';
-import { ExpoIndexerProvider } from '../../providers/expoIndexer.js';
-import { getRandomId } from '../utils.js';
+import { runTasks, createTaskDependencies } from "../../worker/expo/taskRunner.js";
+import { contractPollProcessor, CONTRACT_POLL_TASK_TYPE, } from "../../worker/expo/processors/index.js";
+import { ExpoArkProvider } from "../../providers/expoArk.js";
+import { ExpoIndexerProvider } from "../../providers/expoIndexer.js";
+import { getRandomId } from "../utils.js";
 function requireTaskManager() {
     try {
         return require("expo-task-manager");

package/dist/esm/wallet/expo/index.js

@@ -1,2 +1,2 @@
-export { ExpoWallet } from './wallet.js';
-export { defineExpoBackgroundTask, registerExpoBackgroundTask, unregisterExpoBackgroundTask, } from './background.js';
+export { ExpoWallet } from "./wallet.js";
+export { defineExpoBackgroundTask, registerExpoBackgroundTask, unregisterExpoBackgroundTask, } from "./background.js";

package/dist/esm/wallet/expo/wallet.js

@@ -1,10 +1,10 @@
 import { hex } from "@scure/base";
-import { Wallet } from '../wallet.js';
-import { RestArkProvider } from '../../providers/ark.js';
-import { runTasks } from '../../worker/expo/taskRunner.js';
-import { contractPollProcessor, CONTRACT_POLL_TASK_TYPE, } from '../../worker/expo/processors/index.js';
-import { extendVirtualCoinForContract, getRandomId } from '../utils.js';
-import { DefaultVtxo } from '../../script/default.js';
+import { Wallet } from "../wallet.js";
+import { RestArkProvider } from "../../providers/ark.js";
+import { runTasks } from "../../worker/expo/taskRunner.js";
+import { contractPollProcessor, CONTRACT_POLL_TASK_TYPE, } from "../../worker/expo/processors/index.js";
+import { extendVirtualCoinForContract, getRandomId } from "../utils.js";
+import { DefaultVtxo } from "../../script/default.js";
 /**
  * Expo/React Native wallet with built-in background task processing.
  *
@@ -96,7 +96,7 @@ export class ExpoWallet {
         // Activate OS-level background scheduling
         if (config.background.minimumBackgroundInterval) {
             try {
-                const { registerExpoBackgroundTask } = await import("./background");
+                const { registerExpoBackgroundTask } = await import("./background.js");
                 await registerExpoBackgroundTask(config.background.taskName, {
                     minimumInterval: config.background.minimumBackgroundInterval,
                 });
@@ -145,7 +145,7 @@ export class ExpoWallet {
             this.foregroundIntervalId = undefined;
         }
         try {
-            const { unregisterExpoBackgroundTask } = await import("./background");
+            const { unregisterExpoBackgroundTask } = await import("./background.js");
             await unregisterExpoBackgroundTask(this.taskName);
         }
         catch {

package/dist/esm/wallet/hdDescriptorProvider.js

@@ -1,6 +1,6 @@
 import { expand, networks } from "@bitcoinerlab/descriptors-scure";
-import { isMainnetDescriptor } from '../identity/descriptor.js';
-import { updateWalletState } from '../utils/syncCursors.js';
+import { isMainnetDescriptor } from "../identity/descriptor.js";
+import { updateWalletState } from "../utils/syncCursors.js";
 /** Settings key under {@link WalletState.settings} where HD state lives. */
 const HD_SETTINGS_KEY = "hd";
 /**

package/dist/esm/wallet/onchain.js

@@ -1,11 +1,11 @@
 import { p2tr } from "@scure/btc-signer";
-import { DEFAULT_NETWORK_NAME } from './index.js';
-import { getNetwork } from '../networks.js';
-import { ESPLORA_URL, EsploraProvider, } from '../providers/onchain.js';
-import { findP2AOutput, P2A } from '../utils/anchor.js';
-import { TxWeightEstimator } from '../utils/txSizeEstimator.js';
-import { Transaction } from '../utils/transaction.js';
-import { DUST_AMOUNT } from './utils.js';
+import { DEFAULT_NETWORK_NAME } from "./index.js";
+import { getNetwork } from "../networks.js";
+import { ESPLORA_URL, EsploraProvider, } from "../providers/onchain.js";
+import { findP2AOutput, P2A } from "../utils/anchor.js";
+import { TxWeightEstimator } from "../utils/txSizeEstimator.js";
+import { Transaction } from "../utils/transaction.js";
+import { DUST_AMOUNT } from "./utils.js";
 /**
  * Onchain Bitcoin wallet implementation for traditional Bitcoin transactions.
  *

package/dist/esm/wallet/ramps.js

@@ -1,8 +1,8 @@
-import { Estimator } from '../arkfee/index.js';
+import { Estimator } from "../arkfee/index.js";
 import { Address, OutScript } from "@scure/btc-signer";
 import { hex } from "@scure/base";
-import { networks } from '../networks.js';
-import { ArkAddress } from '../script/address.js';
+import { networks } from "../networks.js";
+import { ArkAddress } from "../script/address.js";
 /**
  * Ramps is a class wrapping `settle` method to provide a more convenient interface for onboarding and offboarding operations.
  *

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

@@ -1,9 +1,9 @@
-import { RestIndexerProvider } from '../../providers/indexer.js';
-import { isExpired, isRecoverable, isSpendable, isSubdust, } from '../index.js';
-import { extendCoin } from '../utils.js';
-import { buildTransactionHistory } from '../../utils/transactionHistory.js';
-import { filterVtxosForScript, warnAndFilterVtxosForScript, } from '../../contracts/vtxoOwnership.js';
-import { scriptFromArkAddress } from '../../repositories/scriptFromAddress.js';
+import { RestIndexerProvider } from "../../providers/indexer.js";
+import { isExpired, isRecoverable, isSpendable, isSubdust, } from "../index.js";
+import { extendCoin } from "../utils.js";
+import { buildTransactionHistory } from "../../utils/transactionHistory.js";
+import { filterVtxosForScript, getVtxosForContract, saveVtxosForContract, warnAndFilterVtxosForScript, } from "../../contracts/vtxoOwnership.js";
+import { scriptFromArkAddress } from "../../repositories/scriptFromAddress.js";
 export class WalletNotInitializedError extends Error {
     constructor() {
         super("Wallet handler not initialized");
@@ -313,6 +313,16 @@ export 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);
@@ -620,7 +630,9 @@ export class WalletMessageHandler {
                             : addrByScript.get(script);
                         if (!targetAddress)
                             continue;
-                        await this.walletRepository?.saveVtxos(targetAddress, filtered);
+                        if (this.walletRepository) {
+                            await saveVtxosForContract(this.walletRepository, { script, address: targetAddress }, filtered);
+                        }
                     }
                     // notify all clients about the virtual output state update
                     this.scheduleForNextTick(() => this.tagged({
@@ -840,8 +852,7 @@ export 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(filterVtxosForScript(vtxos, contract.script));
+            addVtxos(await 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/esm/wallet/serviceWorker/wallet.js

@@ -1,11 +1,11 @@
 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';
-import { getRandomId } from '../utils.js';
-import { MESSAGE_BUS_NOT_INITIALIZED, ServiceWorkerTimeoutError, } from '../../worker/errors.js';
-import { getArkadeServerUrl } from '../wallet.js';
+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";
+import { getRandomId } from "../utils.js";
+import { MESSAGE_BUS_NOT_INITIALIZED, ServiceWorkerTimeoutError, } from "../../worker/errors.js";
+import { getArkadeServerUrl } from "../wallet.js";
 // Check by error message content instead of instanceof because postMessage uses the
 // structured clone algorithm which strips the prototype chain — the page
 // receives a plain Error, not the original MessageBusNotInitializedError.
@@ -57,6 +57,7 @@ export const DEFAULT_MESSAGE_TIMEOUTS = {
     UPDATE_CONTRACT: 30000,
     DELETE_CONTRACT: 10000,
     REFRESH_VTXOS: 30000,
+    REFRESH_OUTPOINTS: 30000,
 };
 const DEDUPABLE_REQUEST_TYPES = new Set([
     "GET_ADDRESS",
@@ -821,6 +822,15 @@ export class ServiceWorkerReadonlyWallet {
                 };
                 await sendContractMessage(message);
             },
+            async refreshOutpoints(outpoints) {
+                const message = {
+                    type: "REFRESH_OUTPOINTS",
+                    id: getRandomId(),
+                    tag: messageTag,
+                    payload: { outpoints },
+                };
+                await sendContractMessage(message);
+            },
             async isWatching() {
                 const message = {
                     type: "IS_CONTRACT_MANAGER_WATCHING",

package/dist/esm/wallet/unroll.js

@@ -1,12 +1,12 @@
 import { base64, hex } from "@scure/base";
 import { SigHash, TaprootControlBlock } from "@scure/btc-signer";
-import { timelockToSequence } from '../utils/timelock.js';
-import { ChainTxType } from '../providers/indexer.js';
-import { VtxoScript } from '../script/base.js';
-import { TxWeightEstimator } from '../utils/txSizeEstimator.js';
-import { Wallet } from './wallet.js';
-import { Transaction } from '../utils/transaction.js';
-import { DUST_AMOUNT } from './utils.js';
+import { timelockToSequence } from "../utils/timelock.js";
+import { ChainTxType } from "../providers/indexer.js";
+import { VtxoScript } from "../script/base.js";
+import { TxWeightEstimator } from "../utils/txSizeEstimator.js";
+import { Wallet } from "./wallet.js";
+import { Transaction } from "../utils/transaction.js";
+import { DUST_AMOUNT } from "./utils.js";
 export var Unroll;
 (function (Unroll) {
     let StepType;

package/dist/esm/wallet/utils.js

@@ -1,5 +1,5 @@
-import { ArkAddress, } from '../index.js';
-import { contractHandlers } from '../contracts/handlers/index.js';
+import { ArkAddress, } from "../index.js";
+import { contractHandlers } from "../contracts/handlers/index.js";
 import { hex } from "@scure/base";
 export const DUST_AMOUNT = 546; // sats
 export function extendCoin(wallet, utxo) {

package/dist/esm/wallet/validation.js

@@ -1,6 +1,6 @@
 import { equalBytes } from "@scure/btc-signer/utils.js";
-import { ArkAddress } from '../script/address.js';
-import { Extension } from '../extension/index.js';
+import { ArkAddress } from "../script/address.js";
+import { Extension } from "../extension/index.js";
 import { Address, OutScript } from "@scure/btc-signer";
 export const ErrOffchainOutputNotFound = (address) => new Error(`offchain send output not found: ${address}`);
 export const ErrInvalidAssetOutputAmount = (got, want, assetId) => new Error(`invalid asset output amount for ${assetId}: got ${got}, want ${want}`);

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

@@ -1,12 +1,13 @@
-import { isExpired, isRecoverable, isSpendable, isSubdust, } from './index.js';
-import { hasBoardingTxExpired } from '../utils/arkTransaction.js';
-import { CSVMultisigTapscript } from '../script/tapscript.js';
+import { isExpired, isRecoverable, isSpendable, isSubdust, } from "./index.js";
+import { maybeArkError } from "../providers/errors.js";
+import { hasBoardingTxExpired } from "../utils/arkTransaction.js";
+import { CSVMultisigTapscript } from "../script/tapscript.js";
 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';
+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.
  *
@@ -432,10 +433,22 @@ export 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
-                : DEFAULT_RENEWAL_CONFIG.thresholdMs);
+                : 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");
             }
@@ -684,9 +697,11 @@ export 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;
                             }
                         }
@@ -711,13 +726,20 @@ export 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;
         }
@@ -730,7 +752,13 @@ export 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);
@@ -741,6 +769,66 @@ export 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 = 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)
@@ -882,6 +970,13 @@ export 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.
@@ -973,11 +1068,12 @@ export 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;