@arkade-os/sdk 0.4.24 → 0.4.25

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

@@ -1,4 +1,5 @@
 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";
@@ -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;

package/dist/esm/wallet/wallet.js

@@ -34,7 +34,7 @@ import { ContractManager } from '../contracts/contractManager.js';
 import { contractHandlers } from '../contracts/handlers/index.js';
 import { timelockToSequence } from '../utils/timelock.js';
 import { clearSyncCursor, updateWalletState } from '../utils/syncCursors.js';
-import { validateVtxosForScript } from '../contracts/vtxoOwnership.js';
+import { validateVtxosForScript, saveVtxosForContract, } from '../contracts/vtxoOwnership.js';
 export const getArkadeServerUrl = ({ arkServerUrl, }) => arkServerUrl || DEFAULT_ARKADE_SERVER_URL;
 // Historical unilateral exit delay for mainnet (~7 days in seconds).
 // Kept so existing wallets can still discover and spend VTXOs sent to the
@@ -1866,7 +1866,6 @@ export class Wallet extends ReadonlyWallet {
                 arr.push(v);
                 spentByScript.set(v.script, arr);
             }
-            const byAddress = new Map();
             for (const [script, vtxos] of spentByScript) {
                 // User-initiated send path: a wrong-script row here means the
                 // wallet is about to record ownership against the wrong
@@ -1876,18 +1875,11 @@ export class Wallet extends ReadonlyWallet {
                 if (!targetAddr) {
                     throw new Error(`Wallet.updateDbAfterOffchainTx: no contract owns script ${script}`);
                 }
-                const bucket = byAddress.get(targetAddr) ?? [];
-                bucket.push(...vtxos);
-                byAddress.set(targetAddr, bucket);
+                await saveVtxosForContract(this.walletRepository, { script, address: targetAddr }, vtxos);
             }
             // Change is always primary-script by construction.
             if (changeVtxo) {
-                const bucket = byAddress.get(primaryAddr) ?? [];
-                bucket.push(changeVtxo);
-                byAddress.set(primaryAddr, bucket);
-            }
-            for (const [addr, vtxos] of byAddress) {
-                await this.walletRepository.saveVtxos(addr, vtxos);
+                await saveVtxosForContract(this.walletRepository, { script: changeVtxo.script, address: primaryAddr }, [changeVtxo]);
             }
             await this.walletRepository.saveTransactions(primaryAddr, [
                 {
@@ -1950,7 +1942,6 @@ export class Wallet extends ReadonlyWallet {
                 // alongside the rest.
                 const contracts = await cm.getContracts();
                 const addrByScript = new Map(contracts.map((c) => [c.script, c.address]));
-                const byAddress = new Map();
                 const byScript = new Map();
                 for (const v of spentVtxos) {
                     if (!v.script) {
@@ -1968,12 +1959,7 @@ export class Wallet extends ReadonlyWallet {
                     if (!targetAddr) {
                         throw new Error(`Wallet.updateDbAfterSettle: no contract owns script ${script}`);
                     }
-                    const bucket = byAddress.get(targetAddr) ?? [];
-                    bucket.push(...vtxos);
-                    byAddress.set(targetAddr, bucket);
-                }
-                for (const [bucketAddr, vtxos] of byAddress) {
-                    await this.walletRepository.saveVtxos(bucketAddr, vtxos);
+                    await saveVtxosForContract(this.walletRepository, { script, address: targetAddr }, vtxos);
                 }
             }
             if (boardingUtxoToRemove.size > 0) {

package/dist/esm/worker/expo/processors/contractPollProcessor.js

@@ -1,4 +1,4 @@
-import { warnAndFilterVtxosForScript } from '../../../contracts/vtxoOwnership.js';
+import { warnAndFilterVtxosForScript, saveVtxosForContract, } from '../../../contracts/vtxoOwnership.js';
 export const CONTRACT_POLL_TASK_TYPE = "contract-poll";
 /**
  * Polls the indexer for the latest VTXO state of every contract and
@@ -45,7 +45,7 @@ export const contractPollProcessor = {
             // before persisting; the loop must keep going for the remaining
             // contracts even when one row is rejected.
             const filtered = warnAndFilterVtxosForScript(allVtxos, contract.script, "contractPollProcessor");
-            await walletRepository.saveVtxos(contract.address, filtered);
+            await saveVtxosForContract(walletRepository, contract, filtered);
             vtxosSaved += filtered.length;
             contractsProcessed++;
         }

package/dist/types/contracts/contractManager.d.ts

@@ -2,7 +2,7 @@ import { IndexerProvider } from "../providers/indexer";
 import { WalletRepository } from "../repositories/walletRepository";
 import { Contract, ContractEventCallback, ContractState, ContractWithVtxos, GetContractsFilter, PathSelection } from "./types";
 import { ContractWatcherConfig } from "./contractWatcher";
-import { ExtendedVirtualCoin, VirtualCoin } from "../wallet";
+import { ExtendedVirtualCoin, Outpoint, VirtualCoin } from "../wallet";
 import { ContractRepository } from "../repositories";
 export type RefreshVtxosOptions = {
     scripts?: string[];
@@ -88,6 +88,21 @@ export interface IContractManager extends Disposable {
      * With options, narrows the refresh to specific scripts and/or a time window.
      */
     refreshVtxos(opts?: RefreshVtxosOptions): Promise<void>;
+    /**
+     * Reconcile specific outpoints with the indexer's authoritative state and
+     * upsert the result into the wallet repository.
+     *
+     * The cursor-derived delta sync filters by `created_at`, so a VTXO that
+     * was created before the cursor but spent recently won't surface in a
+     * standard `refreshVtxos()` call. This method is the surgical recovery
+     * path for that case: when something hands us a stale outpoint (e.g. the
+     * server returns `VTXO_ALREADY_SPENT` with a `vtxo_outpoint` in its
+     * error metadata), call this to pull the latest state and unblock the
+     * caller — no full re-scan, no cursor change.
+     *
+     * Outpoints not owned by any tracked contract are silently dropped.
+     */
+    refreshOutpoints(outpoints: Outpoint[]): Promise<void>;
     /**
      * Whether the underlying watcher is currently active.
      */
@@ -310,6 +325,7 @@ export declare class ContractManager implements IContractManager {
      * Subset refreshes (scripts filter) intentionally do not advance the cursor.
      */
     refreshVtxos(opts?: RefreshVtxosOptions): Promise<void>;
+    refreshOutpoints(outpoints: Outpoint[]): Promise<void>;
     /**
      * Check if currently watching.
      */

package/dist/types/contracts/vtxoOwnership.d.ts

@@ -1,4 +1,6 @@
-import type { VirtualCoin } from "../wallet";
+import type { ExtendedVirtualCoin, VirtualCoin } from "../wallet";
+import type { WalletRepository } from "../repositories/walletRepository";
+import type { Contract } from "./types";
 /**
  * Tier 1 helpers that enforce VTXO ownership at call sites that already know
  * the intended contract script. Address-keyed repositories may still hand back
@@ -23,3 +25,9 @@ export declare function warnAndFilterVtxosForScript<T extends Pick<VirtualCoin,
  * serious bug in the wallet's spend path.
  */
 export declare function validateVtxosForScript(vtxos: Array<Pick<VirtualCoin, "txid" | "vout" | "script">>, script: string, context: string): void;
+/**
+ * Tier 2 dispatch helpers: route to script-scoped repository methods when
+ * available, falling back to Tier 1 address-based filtering otherwise.
+ */
+export declare function getVtxosForContract(repo: WalletRepository, contract: Pick<Contract, "script" | "address">): Promise<ExtendedVirtualCoin[]>;
+export declare function saveVtxosForContract(repo: WalletRepository, contract: Pick<Contract, "script" | "address">, vtxos: ExtendedVirtualCoin[]): Promise<void>;

package/dist/types/repositories/inMemory/walletRepository.d.ts

@@ -1,5 +1,5 @@
 import { ArkTransaction, ExtendedCoin, ExtendedVirtualCoin } from "../../wallet";
-import { WalletRepository, WalletState } from "../walletRepository";
+import { WalletRepository, WalletState, VtxoRepositoryKey } from "../walletRepository";
 /**
  * In-memory implementation of WalletRepository.
  * Data is ephemeral and scoped to the instance.
@@ -13,6 +13,9 @@ export declare class InMemoryWalletRepository implements WalletRepository {
     getVtxos(address: string): Promise<ExtendedVirtualCoin[]>;
     saveVtxos(address: string, vtxos: ExtendedVirtualCoin[]): Promise<void>;
     deleteVtxos(address: string): Promise<void>;
+    getVtxosForScript(script: string): Promise<ExtendedVirtualCoin[]>;
+    saveVtxosForScript(key: VtxoRepositoryKey, vtxos: ExtendedVirtualCoin[]): Promise<void>;
+    deleteVtxosForScript(script: string): Promise<void>;
     getUtxos(address: string): Promise<ExtendedCoin[]>;
     saveUtxos(address: string, utxos: ExtendedCoin[]): Promise<void>;
     deleteUtxos(address: string): Promise<void>;

package/dist/types/repositories/indexedDB/walletRepository.d.ts

@@ -1,5 +1,5 @@
 import { ExtendedCoin, ExtendedVirtualCoin, ArkTransaction } from "../../wallet";
-import { WalletRepository, WalletState } from "../walletRepository";
+import { WalletRepository, WalletState, VtxoRepositoryKey } from "../walletRepository";
 /**
  * IndexedDB-based implementation of WalletRepository.
  */
@@ -13,6 +13,9 @@ export declare class IndexedDBWalletRepository implements WalletRepository {
     getVtxos(address: string): Promise<ExtendedVirtualCoin[]>;
     saveVtxos(address: string, vtxos: ExtendedVirtualCoin[]): Promise<void>;
     deleteVtxos(address: string): Promise<void>;
+    getVtxosForScript(script: string): Promise<ExtendedVirtualCoin[]>;
+    saveVtxosForScript(key: VtxoRepositoryKey, vtxos: ExtendedVirtualCoin[]): Promise<void>;
+    deleteVtxosForScript(script: string): Promise<void>;
     getUtxos(address: string): Promise<ExtendedCoin[]>;
     saveUtxos(address: string, utxos: ExtendedCoin[]): Promise<void>;
     deleteUtxos(address: string): Promise<void>;

package/dist/types/repositories/realm/walletRepository.d.ts

@@ -1,5 +1,5 @@
 import { ArkTransaction, ExtendedCoin, ExtendedVirtualCoin } from "../../wallet";
-import { WalletRepository, WalletState } from "../walletRepository";
+import { WalletRepository, WalletState, VtxoRepositoryKey } from "../walletRepository";
 import { RealmLike } from "./types";
 /**
  * Realm-based implementation of WalletRepository.
@@ -20,6 +20,9 @@ export declare class RealmWalletRepository implements WalletRepository {
     getVtxos(address: string): Promise<ExtendedVirtualCoin[]>;
     saveVtxos(address: string, vtxos: ExtendedVirtualCoin[]): Promise<void>;
     deleteVtxos(address: string): Promise<void>;
+    getVtxosForScript(script: string): Promise<ExtendedVirtualCoin[]>;
+    saveVtxosForScript(key: VtxoRepositoryKey, vtxos: ExtendedVirtualCoin[]): Promise<void>;
+    deleteVtxosForScript(script: string): Promise<void>;
     getUtxos(address: string): Promise<ExtendedCoin[]>;
     saveUtxos(address: string, utxos: ExtendedCoin[]): Promise<void>;
     deleteUtxos(address: string): Promise<void>;

package/dist/types/repositories/sqlite/walletRepository.d.ts

@@ -1,5 +1,5 @@
 import { ArkTransaction, ExtendedCoin, ExtendedVirtualCoin } from "../../wallet";
-import { WalletRepository, WalletState } from "../walletRepository";
+import { WalletRepository, WalletState, VtxoRepositoryKey } from "../walletRepository";
 import { SQLExecutor } from "./types";
 interface SQLiteWalletRepositoryOptions {
     /** Table name prefix (default: "ark_") */
@@ -50,6 +50,9 @@ export declare class SQLiteWalletRepository implements WalletRepository {
     getVtxos(address: string): Promise<ExtendedVirtualCoin[]>;
     saveVtxos(address: string, vtxos: ExtendedVirtualCoin[]): Promise<void>;
     deleteVtxos(address: string): Promise<void>;
+    getVtxosForScript(script: string): Promise<ExtendedVirtualCoin[]>;
+    saveVtxosForScript(key: VtxoRepositoryKey, vtxos: ExtendedVirtualCoin[]): Promise<void>;
+    deleteVtxosForScript(script: string): Promise<void>;
     getUtxos(address: string): Promise<ExtendedCoin[]>;
     saveUtxos(address: string, utxos: ExtendedCoin[]): Promise<void>;
     deleteUtxos(address: string): Promise<void>;

package/dist/types/repositories/walletRepository.d.ts

@@ -20,6 +20,12 @@ export type CommitmentTxRecord = {
     /** Creation timestamp in milliseconds. */
     createdAt: number;
 };
+export interface VtxoRepositoryKey {
+    /** Authoritative ownership key. */
+    script: string;
+    /** Legacy storage bucket. Required by all current backends; throw if absent. */
+    address?: string;
+}
 export interface WalletRepository extends AsyncDisposable {
     readonly version: 1;
     /**
@@ -32,6 +38,21 @@ export interface WalletRepository extends AsyncDisposable {
     saveVtxos(address: string, vtxos: ExtendedVirtualCoin[]): Promise<void>;
     /** Delete stored virtual outputs for an address. */
     deleteVtxos(address: string): Promise<void>;
+    /**
+     * Fetch stored virtual outputs for a script.
+     * @optional SDK backends implement this; custom backends fall back to Tier 1.
+     */
+    getVtxosForScript?(script: string): Promise<ExtendedVirtualCoin[]>;
+    /**
+     * Save virtual outputs for a script.
+     * @optional SDK backends implement this; custom backends fall back to Tier 1.
+     */
+    saveVtxosForScript?(key: VtxoRepositoryKey, vtxos: ExtendedVirtualCoin[]): Promise<void>;
+    /**
+     * Delete stored virtual outputs for a script.
+     * @optional SDK backends implement this; custom backends fall back to Tier 1.
+     */
+    deleteVtxosForScript?(script: string): Promise<void>;
     /** Fetch stored boarding inputs for an address. */
     getUtxos(address: string): Promise<ExtendedCoin[]>;
     /** Save boarding inputs for an address. */

package/dist/types/wallet/serviceWorker/wallet-message-handler.d.ts

@@ -259,6 +259,18 @@ export type RequestRefreshVtxos = RequestEnvelope & {
 export type ResponseRefreshVtxos = ResponseEnvelope & {
     type: "REFRESH_VTXOS_SUCCESS";
 };
+export type RequestRefreshOutpoints = RequestEnvelope & {
+    type: "REFRESH_OUTPOINTS";
+    payload: {
+        outpoints: {
+            txid: string;
+            vout: number;
+        }[];
+    };
+};
+export type ResponseRefreshOutpoints = ResponseEnvelope & {
+    type: "REFRESH_OUTPOINTS_SUCCESS";
+};
 export type RequestGetAllSpendingPaths = RequestEnvelope & {
     type: "GET_ALL_SPENDING_PATHS";
     payload: {
@@ -463,8 +475,8 @@ export type ResponseSweepExpiredBoardingUtxos = ResponseEnvelope & {
         txid: string;
     };
 };
-export type WalletUpdaterRequest = RequestInitWallet | RequestSettle | RequestSendBitcoin | RequestGetAddress | RequestGetBoardingAddress | RequestGetBalance | RequestGetVtxos | RequestGetBoardingUtxos | RequestGetTransactionHistory | RequestGetStatus | RequestClear | RequestReloadWallet | RequestSignTransaction | RequestCreateContract | RequestGetContracts | RequestGetContractsWithVtxos | RequestAnnotateVtxos | RequestUpdateContract | RequestDeleteContract | RequestGetSpendablePaths | RequestGetAllSpendingPaths | RequestIsContractManagerWatching | RequestRefreshVtxos | RequestSend | RequestGetAssetDetails | RequestIssue | RequestReissue | RequestBurn | RequestDelegate | RequestGetDelegateInfo | RequestRecoverVtxos | RequestGetRecoverableBalance | RequestGetExpiringVtxos | RequestRenewVtxos | RequestGetExpiredBoardingUtxos | RequestSweepExpiredBoardingUtxos;
-export type WalletUpdaterResponse = ResponseEnvelope & (ResponseInitWallet | ResponseSettle | ResponseSettleEvent | ResponseSendBitcoin | ResponseGetAddress | ResponseGetBoardingAddress | ResponseGetBalance | ResponseGetVtxos | ResponseGetBoardingUtxos | ResponseGetTransactionHistory | ResponseGetStatus | ResponseClear | ResponseReloadWallet | ResponseUtxoUpdate | ResponseVtxoUpdate | ResponseSignTransaction | ResponseCreateContract | ResponseGetContracts | ResponseGetContractsWithVtxos | ResponseAnnotateVtxos | ResponseUpdateContract | ResponseDeleteContract | ResponseGetSpendablePaths | ResponseGetAllSpendingPaths | ResponseIsContractManagerWatching | ResponseRefreshVtxos | ResponseContractEvent | ResponseSend | ResponseGetAssetDetails | ResponseIssue | ResponseReissue | ResponseBurn | ResponseDelegate | ResponseGetDelegateInfo | ResponseRecoverVtxos | ResponseRecoverVtxosEvent | ResponseGetRecoverableBalance | ResponseGetExpiringVtxos | ResponseRenewVtxos | ResponseRenewVtxosEvent | ResponseGetExpiredBoardingUtxos | ResponseSweepExpiredBoardingUtxos);
+export type WalletUpdaterRequest = RequestInitWallet | RequestSettle | RequestSendBitcoin | RequestGetAddress | RequestGetBoardingAddress | RequestGetBalance | RequestGetVtxos | RequestGetBoardingUtxos | RequestGetTransactionHistory | RequestGetStatus | RequestClear | RequestReloadWallet | RequestSignTransaction | RequestCreateContract | RequestGetContracts | RequestGetContractsWithVtxos | RequestAnnotateVtxos | RequestUpdateContract | RequestDeleteContract | RequestGetSpendablePaths | RequestGetAllSpendingPaths | RequestIsContractManagerWatching | RequestRefreshVtxos | RequestRefreshOutpoints | RequestSend | RequestGetAssetDetails | RequestIssue | RequestReissue | RequestBurn | RequestDelegate | RequestGetDelegateInfo | RequestRecoverVtxos | RequestGetRecoverableBalance | RequestGetExpiringVtxos | RequestRenewVtxos | RequestGetExpiredBoardingUtxos | RequestSweepExpiredBoardingUtxos;
+export type WalletUpdaterResponse = ResponseEnvelope & (ResponseInitWallet | ResponseSettle | ResponseSettleEvent | ResponseSendBitcoin | ResponseGetAddress | ResponseGetBoardingAddress | ResponseGetBalance | ResponseGetVtxos | ResponseGetBoardingUtxos | ResponseGetTransactionHistory | ResponseGetStatus | ResponseClear | ResponseReloadWallet | ResponseUtxoUpdate | ResponseVtxoUpdate | ResponseSignTransaction | ResponseCreateContract | ResponseGetContracts | ResponseGetContractsWithVtxos | ResponseAnnotateVtxos | ResponseUpdateContract | ResponseDeleteContract | ResponseGetSpendablePaths | ResponseGetAllSpendingPaths | ResponseIsContractManagerWatching | ResponseRefreshVtxos | ResponseRefreshOutpoints | ResponseContractEvent | ResponseSend | ResponseGetAssetDetails | ResponseIssue | ResponseReissue | ResponseBurn | ResponseDelegate | ResponseGetDelegateInfo | ResponseRecoverVtxos | ResponseRecoverVtxosEvent | ResponseGetRecoverableBalance | ResponseGetExpiringVtxos | ResponseRenewVtxos | ResponseRenewVtxosEvent | ResponseGetExpiredBoardingUtxos | ResponseSweepExpiredBoardingUtxos);
 export declare class WalletMessageHandler implements MessageHandler<WalletUpdaterRequest, WalletUpdaterResponse> {
     readonly messageTag: string;
     private wallet;

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

@@ -410,13 +410,40 @@ export declare class VtxoManager implements AsyncDisposable, IVtxoManager {
     /**
      * 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.
      */
     private maybeRefreshAfterVtxoSpent;
+    /**
+     * 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.
+     */
+    private extractSpentOutpoint;
+    /**
+     * 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.
+     */
+    private revalidateBeforeSettle;
     /** Computes the next poll delay, applying exponential backoff on failures. */
     private getNextPollDelay;
     /**

package/package.json

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