@arkade-os/sdk 0.4.23 → 0.4.25

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

@@ -1,3 +1,4 @@
+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
@@ -40,8 +41,12 @@ export const contractPollProcessor = {
                 hasMore = page ? vtxos.length === pageSize : false;
                 pageIndex++;
             }
-            await walletRepository.saveVtxos(contract.address, allVtxos);
-            vtxosSaved += allVtxos.length;
+            // Skip wrong-script rows (legacy duplicates or indexer drift)
+            // 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 saveVtxosForContract(walletRepository, contract, filtered);
+            vtxosSaved += filtered.length;
             contractsProcessed++;
         }
         return {

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/handlers/helpers.d.ts

@@ -1,13 +1,4 @@
-import { RelativeTimelock } from "../../script/tapscript";
 import { Contract, PathContext } from "../types";
-/**
- * Convert RelativeTimelock to BIP68 sequence number.
- */
-export declare function timelockToSequence(timelock: RelativeTimelock): number;
-/**
- * Convert BIP68 sequence number back to RelativeTimelock.
- */
-export declare function sequenceToTimelock(sequence: number): RelativeTimelock;
 /**
  * Resolve wallet's role from explicit role or by matching descriptor/pubkey.
  */

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

@@ -0,0 +1,33 @@
+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
+ * legacy duplicate rows under the wrong bucket; these helpers gate reads and
+ * writes so a wrong-script row never wins.
+ *
+ * `script` is the authoritative ownership key. Equality is strict: a missing
+ * or empty `vtxo.script` never matches.
+ */
+export declare function vtxoOutpoint(vtxo: Pick<VirtualCoin, "txid" | "vout">): string;
+export declare function isVtxoForScript(vtxo: Pick<VirtualCoin, "script">, script: string): boolean;
+export declare function filterVtxosForScript<T extends Pick<VirtualCoin, "script">>(vtxos: T[], script: string): T[];
+/**
+ * Background/indexer sync flavour: drop wrong-script rows and log enough
+ * context to identify each rejection. Returns only matching rows so the
+ * caller can keep going.
+ */
+export declare function warnAndFilterVtxosForScript<T extends Pick<VirtualCoin, "txid" | "vout" | "script">>(vtxos: T[], script: string, context: string): T[];
+/**
+ * User-initiated transaction/signing flavour: throw before persisting or
+ * signing inconsistent ownership state. Silently skipping here would hide a
+ * 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/index.d.ts

@@ -51,7 +51,7 @@ export * as asset from "./extension/asset";
 import { ContractManager, ContractWatcher, contractHandlers, DefaultContractHandler, DelegateContractHandler, VHTLCContractHandler, encodeArkContract, decodeArkContract, contractFromArkContract, contractFromArkContractWithAddress, isArkContract } from "./contracts";
 import type { Contract, ContractVtxo, ContractState, ContractEvent, ContractEventCallback, ContractBalance, ContractWithVtxos, ContractHandler, PathSelection, PathContext, ContractManagerConfig, CreateContractParams, ContractWatcherConfig, ParsedArkContract, DefaultContractParams, DelegateContractParams, VHTLCContractParams } from "./contracts";
 import { IContractManager } from "./contracts/contractManager";
-import { timelockToSequence, sequenceToTimelock } from "./contracts/handlers/helpers";
+import { timelockToSequence, sequenceToTimelock } from "./utils/timelock";
 import { closeDatabase, openDatabase } from "./repositories/indexedDB/manager";
 import { WalletMessageHandler, WalletNotInitializedError, ReadonlyWalletError, DelegatorNotConfiguredError } from "./wallet/serviceWorker/wallet-message-handler";
 import { MESSAGE_BUS_NOT_INITIALIZED, MessageBusNotInitializedError, ServiceWorkerTimeoutError } from "./worker/errors";

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/script/tapscript.d.ts

@@ -90,6 +90,7 @@ export declare namespace CSVMultisigTapscript {
     function decode(script: Uint8Array): Type;
     /** Return true when the tapscript is a CSV multisig tapscript. */
     function is(tapscript: ArkTapscript<any, any>): tapscript is Type;
+    function isScriptValid(script: Uint8Array): true | Error;
 }
 /**
  * Combines a condition script with an exit closure. The resulting script requires
@@ -114,6 +115,7 @@ export declare namespace ConditionCSVMultisigTapscript {
     function decode(script: Uint8Array): Type;
     /** Return true when the tapscript is a condition + CSV multisig tapscript. */
     function is(tapscript: ArkTapscript<any, any>): tapscript is Type;
+    function isScriptValid(script: Uint8Array): true | Error;
 }
 /**
  * Combines a condition script with a forfeit closure. The resulting script requires
@@ -138,6 +140,7 @@ export declare namespace ConditionMultisigTapscript {
     function decode(script: Uint8Array): Type;
     /** Return true when the tapscript is a condition + multisig tapscript. */
     function is(tapscript: ArkTapscript<any, any>): tapscript is Type;
+    function isScriptValid(script: Uint8Array): true | Error;
 }
 /**
  * Implements an absolute timelock (CLTV) script combined with a forfeit closure.
@@ -162,4 +165,5 @@ export declare namespace CLTVMultisigTapscript {
     function decode(script: Uint8Array): Type;
     /** Return true when the tapscript is a CLTV multisig tapscript. */
     function is(tapscript: ArkTapscript<any, any>): tapscript is Type;
+    function isScriptValid(script: Uint8Array): true | Error;
 }

package/dist/types/utils/timelock.d.ts

@@ -0,0 +1,9 @@
+import type { RelativeTimelock } from "../script/tapscript";
+/**
+ * Convert RelativeTimelock to BIP68 sequence number.
+ */
+export declare function timelockToSequence(timelock: RelativeTimelock): number;
+/**
+ * Convert BIP68 sequence number back to RelativeTimelock.
+ */
+export declare function sequenceToTimelock(sequence: number): RelativeTimelock;

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/unroll.d.ts

@@ -15,6 +15,7 @@ export declare namespace Unroll {
      */
     type UnrollStep = {
         tx: Transaction;
+        pkg: [parent: string, child: string];
     };
     /**
      * Wait step where the transaction has to be confirmed onchain
@@ -102,3 +103,12 @@ export declare namespace Unroll {
      */
     function completeUnroll(wallet: Wallet, vtxoTxids: string[], outputAddress: string): Promise<string>;
 }
+/**
+ * Prepares the transaction that spends the CSV path to complete unrolling a VTXO.
+ * @param wallet the wallet owning the VTXO(s)
+ * @param vtxoTxIds the txids of the VTXO(s) to complete unroll
+ * @param outputAddress the address to send the unrolled funds to
+ * @throws if the VTXO(s) are not fully unrolled, if the txids are not found, if the tx is not confirmed, if no exit path is found or not available
+ * @returns the transaction spending the unrolled funds
+ */
+export declare function prepareUnrollTransaction(wallet: Wallet, vtxoTxIds: string[], outputAddress: string): Promise<Transaction>;

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.23",
+  "version": "0.4.25",
   "description": "TypeScript SDK for building Bitcoin wallets using the Arkade protocol",
   "type": "module",
   "main": "./dist/cjs/index.js",