@arkade-os/sdk 0.4.17 → 0.4.19

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

@@ -74,7 +74,6 @@ export declare function decodeArkContract(encoded: string): ParsedArkContract;
 export declare function contractFromArkContract(encoded: string, options?: {
     label?: string;
     state?: "active" | "inactive";
-    expiresAt?: number;
     metadata?: Record<string, unknown>;
 }): Omit<Contract, "script" | "address"> & {
     script?: string;
@@ -92,7 +91,6 @@ export declare function contractFromArkContract(encoded: string, options?: {
 export declare function contractFromArkContractWithAddress(encoded: string, serverPubKey: Uint8Array, addressPrefix: string, options?: {
     label?: string;
     state?: "active" | "inactive";
-    expiresAt?: number;
     metadata?: Record<string, unknown>;
 }): Contract;
 /**

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 { VirtualCoin } from "../wallet";
+import { ExtendedVirtualCoin, VirtualCoin } from "../wallet";
 import { ContractRepository } from "../repositories";
 export type RefreshVtxosOptions = {
     scripts?: string[];
@@ -36,6 +36,19 @@ export interface IContractManager extends Disposable {
      * If no filter is provided, returns all contracts with their virtual outputs.
      */
     getContractsWithVtxos(filter?: GetContractsFilter): Promise<ContractWithVtxos[]>;
+    /**
+     * Stamp raw virtual outputs with the correct per-contract tapscripts
+     * (forfeit, intent, tap tree).
+     *
+     * Resolves each vtxo's `script` to its owning contract via the contract
+     * repository and attaches the matching tapscripts. Throws when any vtxo
+     * references a script with no registered contract — callers are expected
+     * to register the contract before asking for annotation. This is the
+     * single shared path that replaces scattered `extendVirtualCoin*` calls
+     * in wallet/handler code, and keeps the wallet from silently stamping the
+     * default tapscript onto a non-default vtxo.
+     */
+    annotateVtxos(vtxos: VirtualCoin[]): Promise<ExtendedVirtualCoin[]>;
     /**
      * Update mutable contract fields.
      *
@@ -135,7 +148,7 @@ export type CreateContractParams = Omit<Contract, "createdAt" | "state"> & {
  * - Create and persist contracts
  * - Query stored contracts (optionally with their virtual outputs)
  * - Provide spendable path selection for a contract
- * - Emit contract-related events (virtual output received/spent/expired, connection reset)
+ * - Emit contract-related events (virtual output received/spent, connection reset)
  *
  * Notes:
  * - Implementations typically start watching automatically during initialization
@@ -181,7 +194,6 @@ export declare class ContractManager implements IContractManager {
     private initialized;
     private eventCallbacks;
     private stopWatcherFn?;
-    private syncVtxosCallInflight?;
     private constructor();
     /**
      * Static factory method for creating a new ContractManager.
@@ -194,6 +206,17 @@ export declare class ContractManager implements IContractManager {
      */
     static create(config: ContractManagerConfig): Promise<ContractManager>;
     private initialize;
+    /**
+     * Delta-sync the full watched set and reconcile the pending frontier.
+     *
+     * Shared recovery path used on initial boot and after a subscription
+     * reconnect. `syncContracts({})` scopes to the current watched set
+     * (see {@link ContractWatcher.getWatchedContracts}), uses the
+     * cursor-derived delta window, and advances the cursor on success.
+     * `reconcilePendingFrontier` catches not-yet-finalized virtual
+     * outputs that could sit outside any delta window.
+     */
+    private reconcileWatched;
     /**
      * Create and register a new contract.
      *
@@ -218,6 +241,7 @@ export declare class ContractManager implements IContractManager {
      */
     getContracts(filter?: GetContractsFilter): Promise<Contract[]>;
     getContractsWithVtxos(filter?: GetContractsFilter, pageSize?: number): Promise<ContractWithVtxos[]>;
+    annotateVtxos(vtxos: VirtualCoin[]): Promise<ExtendedVirtualCoin[]>;
     private buildContractsDbFilter;
     /**
      * Update a contract.
@@ -281,8 +305,9 @@ export declare class ContractManager implements IContractManager {
     /**
      * Force refresh virtual outputs from the indexer.
      *
-     * Without options, clears all sync cursors and re-fetches every contract.
+     * Without options, re-fetches every contract and advances the global cursor.
      * With options, narrows the refresh to specific scripts and/or a time window.
+     * Subset refreshes (scripts filter) intentionally do not advance the cursor.
      */
     refreshVtxos(opts?: RefreshVtxosOptions): Promise<void>;
     /**
@@ -299,11 +324,16 @@ export declare class ContractManager implements IContractManager {
     private handleContractEvent;
     private getVtxosForContracts;
     /**
-     * Incrementally sync virtual outputs for the given contracts.
-     * Uses per-script cursors to fetch only what changed since the last sync.
-     * Scripts without a cursor are bootstrapped with a full fetch.
+     * Sync virtual outputs for the given contracts against the indexer.
+     *
+     * When `options.contracts` is omitted the sync covers the full
+     * watched set (active contracts plus any inactive contracts still
+     * holding cached VTXOs) and the global cursor is advanced on
+     * success. Passing an explicit subset leaves the cursor alone so a
+     * narrow poll can't hide data that other contracts still need to
+     * pick up.
      */
-    private deltaSyncContracts;
+    private syncContracts;
     /**
      * Fetch all pending (unfinalized) virtual outputs and upsert them into the
      * repository. This catches virtual outputs whose state changed outside the delta
@@ -312,7 +342,6 @@ export declare class ContractManager implements IContractManager {
     private reconcilePendingFrontier;
     private fetchContractVxosFromIndexer;
     private fetchContractVtxosBulk;
-    private fetchContractVtxosPaginated;
     /**
      * Dispose of the ContractManager and release all resources.
      *

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

@@ -108,6 +108,14 @@ export declare class ContractWatcher {
      * (which may cause them to be watched even if inactive).
      */
     addContract(contract: Contract): Promise<void>;
+    /**
+     * Pre-populate `lastKnownVtxos` from the wallet repository.
+     *
+     * Runs on add (and can be re-run after reconnect) so polling always
+     * compares the indexer's view against what is already persisted,
+     * emitting only genuine deltas.
+     */
+    private seedLastKnownVtxos;
     /**
      * Update an existing contract.
      */
@@ -121,20 +129,17 @@ export declare class ContractWatcher {
      */
     getAllContracts(): Contract[];
     /**
-     * Get all active in-memory contracts.
-     */
-    getActiveContracts(): Contract[];
-    /**
-     * Get scripts that should be watched.
+     * Contracts the watcher is actually tracking:
+     * - all active contracts, plus
+     * - inactive contracts that still hold known virtual outputs
+     *   (the subscription keeps watching them so `vtxo_spent` events for
+     *   those unspent outputs are still observed).
      *
-     * Returns scripts for:
-     * - All active contracts
-     * - All contracts with known virtual outputs (regardless of state)
-     *
-     * This ensures we continue monitoring contracts even after they're
-     * deactivated, as long as they have unspent virtual outputs.
+     * This is the single source of truth for "contracts whose VTXO state
+     * we still care about" — callers and the subscription itself fan out
+     * over the same set so nothing is reconciled that isn't also watched.
      */
-    private getScriptsToWatch;
+    getWatchedContracts(): Contract[];
     /**
      * Get virtual outputs for contracts, grouped by contract script.
      * @see WalletRepository for `repo`
@@ -161,10 +166,6 @@ export declare class ContractWatcher {
      * Useful for manual refresh or after app resume.
      */
     forcePoll(): Promise<void>;
-    /**
-     * Check for expired contracts, update their state, and emit events.
-     */
-    private checkExpiredContracts;
     /**
      * Connect to the subscription.
      */
@@ -177,9 +178,6 @@ export declare class ContractWatcher {
      * Start the failsafe polling interval.
      */
     private startFailsafePolling;
-    /**
-     * Poll all active contracts for current state.
-     */
     private pollAllContracts;
     /**
      * Poll specific contracts and emit events for changes.
@@ -201,8 +199,11 @@ export declare class ContractWatcher {
      */
     private handleSubscriptionUpdate;
     /**
-     * Process virtual outputs from subscription and route to correct contracts.
-     * Uses the scripts from the subscription response to determine contract ownership.
+     * Process virtual outputs from subscription and route each VTXO to the
+     * single contract that actually locks it via `vtxo.script`. If the script
+     * doesn't match any watched contract, skip the VTXO rather than fan it
+     * out to every matching contract — fan-out produced phantom state in
+     * non-owning contracts that then never reconciled.
      */
     private processSubscriptionVtxos;
     /**

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

@@ -58,8 +58,6 @@ export interface Contract {
     state: ContractState;
     /** Unix timestamp in milliseconds when this contract was created. */
     createdAt: number;
-    /** Unix timestamp in milliseconds when this contract expires. */
-    expiresAt?: number;
     /**
      * Optional metadata for external integrations.
      */
@@ -194,11 +192,6 @@ export type ContractEvent = {
     vtxos: ContractVtxo[];
     contract: Contract;
     timestamp: number;
-} | {
-    type: "contract_expired";
-    contractScript: string;
-    contract: Contract;
-    timestamp: number;
 } | {
     type: "connection_reset";
     timestamp: number;

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

@@ -7,11 +7,14 @@ export declare function getGlobalObject(): {
  *
  * @param dbName The name of the database to open.
  * @param dbVersion The database version to open.
- * @param initDatabase A function that migrates the database schema, called on `onupgradeneeded` only.
+ * @param initDatabase A function that migrates the database schema, called
+ *   on `onupgradeneeded` only. Receives the database, the previous version
+ *   (0 for fresh installs), and the upgrade transaction — the transaction is
+ *   required for data migrations (cursor/update on existing stores).
  *
  * @returns A promise that resolves to the database instance.
  */
-export declare function openDatabase(dbName: string, dbVersion: number, initDatabase: (db: IDBDatabase) => void): Promise<IDBDatabase>;
+export declare function openDatabase(dbName: string, dbVersion: number, initDatabase: (db: IDBDatabase, oldVersion: number, transaction: IDBTransaction | null) => void): Promise<IDBDatabase>;
 /**
  * Decrements the reference count and closes the database when no references remain.
  *

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

@@ -4,5 +4,6 @@ export declare const STORE_TRANSACTIONS = "transactions";
 export declare const STORE_WALLET_STATE = "walletState";
 export declare const STORE_CONTRACTS = "contracts";
 export declare const LEGACY_STORE_CONTRACT_COLLECTIONS = "contractsCollections";
-export declare const DB_VERSION = 2;
-export declare function initDatabase(db: IDBDatabase): void;
+export declare const DB_VERSION = 3;
+export declare function initDatabase(db: IDBDatabase, oldVersion: number, transaction: IDBTransaction | null): void;
+export declare function backfillVtxoScripts(transaction: IDBTransaction): void;

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

@@ -1,4 +1,4 @@
 export { RealmWalletRepository } from "./walletRepository";
 export { RealmContractRepository } from "./contractRepository";
-export { ArkRealmSchemas } from "./schemas";
+export { ArkRealmSchemas, ARK_REALM_SCHEMA_VERSION, runArkRealmMigrations, } from "./schemas";
 export type { RealmLike, RealmResults } from "./types";

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

@@ -35,6 +35,10 @@ export declare const ArkVtxoSchema: {
         readonly isUnrolled: "bool";
         readonly isSpent: "bool?";
         readonly assetsJson: "string?";
+        readonly script: {
+            readonly type: "string";
+            readonly indexed: true;
+        };
     };
 };
 export declare const ArkUtxoSchema: {
@@ -138,6 +142,10 @@ export declare const ArkRealmSchemas: ({
         readonly isUnrolled: "bool";
         readonly isSpent: "bool?";
         readonly assetsJson: "string?";
+        readonly script: {
+            readonly type: "string";
+            readonly indexed: true;
+        };
     };
 } | {
     readonly name: "ArkUtxo";
@@ -206,3 +214,36 @@ export declare const ArkRealmSchemas: ({
         readonly metadataJson: "string?";
     };
 })[];
+/**
+ * Current Realm schema version for the Arkade wallet.
+ *
+ * Consumers opening Realm must pass a `schemaVersion` at least this high so
+ * legacy databases get migrated; merge it with your own app's version:
+ *
+ * ```ts
+ * await Realm.open({
+ *     schema: [...ArkRealmSchemas, ...yourSchemas],
+ *     schemaVersion: Math.max(ARK_REALM_SCHEMA_VERSION, yourSchemaVersion),
+ *     onMigration: (oldRealm, newRealm) => {
+ *         runArkRealmMigrations(oldRealm, newRealm);
+ *         // your own migrations
+ *     },
+ * });
+ * ```
+ *
+ * History:
+ *   - v1: initial ArkVtxo/ArkUtxo/... schemas, `script` nullable.
+ *   - v2: ArkVtxo.script becomes required; NULL values are backfilled from
+ *     the owning Ark address during migration.
+ */
+export declare const ARK_REALM_SCHEMA_VERSION = 2;
+/**
+ * Run every Arkade schema migration applicable to the open Realm.
+ *
+ * Designed to be composed with the consumer's own migrations inside a single
+ * `onMigration` callback. Each migration step does a per-row check so it
+ * remains idempotent and independent of the app's global `schemaVersion` —
+ * a consumer whose app is already at version 10 can still trigger the
+ * Arkade v1→v2 script backfill when the row has never been populated.
+ */
+export declare function runArkRealmMigrations(oldRealm: any, newRealm: any): void;

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

@@ -0,0 +1,9 @@
+/**
+ * Compute the hex-encoded `scriptPubKey` locking a VTXO from its owning Ark
+ * address. Used by repository-layer migrations to backfill `script` on legacy
+ * rows that pre-date the column (the indexer now guarantees the field, so new
+ * rows never go through this path). The `script` field is required by the
+ * domain type, so backfill must produce the same value the indexer would
+ * have returned — which is the hex of the address's `pkScript`.
+ */
+export declare function scriptFromArkAddress(address: string): string;

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

@@ -20,7 +20,7 @@ export declare const serializeVtxo: (v: ExtendedVirtualCoin) => {
     isUnrolled: boolean;
     isSpent?: boolean;
     assets?: import("../wallet").Asset[];
-    script?: string;
+    script: string;
     value: number;
     status: import("../wallet").Status;
     txid: string;

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

@@ -23,6 +23,28 @@ export declare class SQLiteWalletRepository implements WalletRepository {
     constructor(db: SQLExecutor, options?: SQLiteWalletRepositoryOptions);
     private ensureInit;
     private init;
+    /**
+     * Bring the `vtxos` table to the current schema (v1 = `script` NOT NULL).
+     *
+     * Three cases:
+     *   - Fresh install: create the v1 schema directly.
+     *   - Legacy install without a `script` column: add it, backfill from
+     *     `address`, then rebuild the table with NOT NULL (SQLite cannot add
+     *     the NOT NULL constraint in place).
+     *   - Legacy install with a nullable `script` column: backfill the NULLs
+     *     and rebuild.
+     *
+     * The backfill derives `script` from the Ark address, matching what the
+     * indexer would have returned — new rows from the indexer always carry a
+     * populated `script`, so the migration is idempotent.
+     *
+     * The rebuild path is wrapped in a transaction: without it, a crash
+     * between the `DROP TABLE vtxos` and the `RENAME tmp → vtxos` commits
+     * would leave the next startup seeing no `vtxos` table and create a
+     * fresh empty one, silently orphaning every row in the temp table.
+     */
+    private migrateVtxosTable;
+    private vtxosCreateSql;
     [Symbol.asyncDispose](): Promise<void>;
     clear(): Promise<void>;
     getVtxos(address: string): Promise<ExtendedVirtualCoin[]>;

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

@@ -1,9 +1,17 @@
 import { ArkTransaction, ExtendedCoin, ExtendedVirtualCoin } from "../wallet";
 export interface WalletState {
-    /** Timestamp of the last successful wallet sync, in milliseconds. */
-    lastSyncTime?: number;
     /** Arbitrary stored wallet settings. */
     settings?: Record<string, any>;
+    /**
+     * High-water mark for VTXO indexer syncs, in milliseconds.
+     *
+     * Reused the legacy `lastSyncTime` column name to avoid an
+     * `ALTER TABLE` migration; the value is interpreted as the new
+     * "max indexer `updatedAt`" cursor only after `settings.vtxoCursorMigrated`
+     * is set, so pre-existing values written by the buggy pre-PR sync
+     * are ignored and force a one-shot re-bootstrap on upgrade.
+     */
+    lastSyncTime?: number;
 }
 /** Stored commitment transaction metadata. */
 export type CommitmentTxRecord = {

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

@@ -2,8 +2,7 @@ import { WalletRepository, WalletState } from "../repositories/walletRepository"
 /** Lag behind real-time to avoid racing with indexer writes. */
 export declare const SAFETY_LAG_MS = 30000;
 /** Overlap window so boundary virtual outputs are never missed. */
-export declare const OVERLAP_MS = 60000;
-type SyncCursors = Record<string, number>;
+export declare const OVERLAP_MS: number;
 /**
  * Atomically read, mutate, and persist wallet state.
  * All callers that modify wallet state should go through this helper
@@ -11,39 +10,43 @@ type SyncCursors = Record<string, number>;
  */
 export declare function updateWalletState(repo: WalletRepository, updater: (state: WalletState) => WalletState): Promise<void>;
 /**
- * Read the high-water mark for a single script.
- * Returns `undefined` when the script has never been synced (bootstrap case).
- */
-export declare function getSyncCursor(repo: WalletRepository, script: string): Promise<number | undefined>;
-/**
- * Read cursors for every previously-synced script.
- */
-export declare function getAllSyncCursors(repo: WalletRepository): Promise<SyncCursors>;
-/**
- * Advance the cursor for one script after a successful delta sync.
- * `cursor` should be the `before` cutoff used in the request.
+ * Read the global high-water mark for VTXO indexer syncs.
+ *
+ * Returns `0` when:
+ *  - the wallet has never been synced (bootstrap case), or
+ *  - the stored `lastSyncTime` was written by pre-PR code and is not
+ *    safe to reuse under the new semantics (see {@link CURSOR_MIGRATED_KEY}).
  */
-export declare function advanceSyncCursor(repo: WalletRepository, script: string, cursor: number): Promise<void>;
+export declare function getSyncCursor(repo: WalletRepository): Promise<number>;
 /**
- * Advance cursors for multiple scripts in a single write.
+ * Advance the global cursor after a successful full-scope delta sync.
+ *
+ * Clamped with `Math.max` against the current value so concurrent syncs
+ * that finish out of order can't rewind the cursor: `lastUpdatedAt` is
+ * captured before each sync enters the `updateWalletState` mutex, and
+ * the later-started sync would otherwise overwrite the earlier-captured
+ * one with a smaller value. The legacy value is discarded on the first
+ * advance if the migration marker is absent so pre-PR data doesn't
+ * survive the upgrade.
  */
-export declare function advanceSyncCursors(repo: WalletRepository, updates: Record<string, number>): Promise<void>;
+export declare function advanceSyncCursor(repo: WalletRepository, lastUpdatedAt: number): Promise<void>;
 /**
- * Remove sync cursors, forcing a full re-bootstrap on next sync.
- * When `scripts` is provided, only those cursors are cleared.
+ * Remove the sync cursor, forcing a full re-bootstrap on next sync.
+ *
+ * Also clears the migration marker so any stored `lastSyncTime` is
+ * treated as untrusted on the next read.
  */
-export declare function clearSyncCursors(repo: WalletRepository, scripts?: string[]): Promise<void>;
+export declare function clearSyncCursor(repo: WalletRepository): Promise<void>;
 /**
  * Compute the `after` lower-bound for a delta sync query.
- * Returns `undefined` when the script has no cursor (bootstrap needed).
  *
  * No upper bound (`before`) is applied to the query so that freshly
  * created virtual outputs are never excluded. The safety lag is applied only
  * when advancing the cursor (see @see cursorCutoff).
  */
-export declare function computeSyncWindow(cursor: number | undefined): {
+export declare function computeSyncWindow(cursor: number): {
     after: number;
-} | undefined;
+};
 /**
  * The safe high-water mark for cursor advancement.
  * Lags behind real-time by @see SAFETY_LAG_MS so that virtual outputs still
@@ -55,4 +58,3 @@ export declare function computeSyncWindow(cursor: number | undefined): {
  * data they actually observed.
  */
 export declare function cursorCutoff(requestStartedAt?: number): number;
-export {};

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

@@ -480,7 +480,7 @@ export interface VirtualCoin extends Coin {
     /** Assets carried by this virtual output, if any. */
     assets?: Asset[];
     /** The scriptPubKey (hex) locking this virtual output, as returned by the indexer. */
-    script?: string;
+    script: string;
 }
 /** Wallet transaction direction. */
 export declare enum TxType {

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

@@ -1,7 +1,7 @@
 import { SettlementEvent } from "../../providers/ark";
 import type { Contract, ContractEvent, ContractWithVtxos, GetContractsFilter, PathSelection } from "../../contracts";
 import type { CreateContractParams, GetAllSpendingPathsOptions, GetSpendablePathsOptions } from "../../contracts/contractManager";
-import { ArkTransaction, AssetDetails, BurnParams, ExtendedCoin, ExtendedVirtualCoin, GetVtxosFilter, IssuanceParams, IssuanceResult, IWallet, Recipient, ReissuanceParams, SendBitcoinParams, SettleParams, WalletBalance } from "../index";
+import { ArkTransaction, AssetDetails, BurnParams, ExtendedCoin, ExtendedVirtualCoin, GetVtxosFilter, IssuanceParams, IssuanceResult, IWallet, Recipient, ReissuanceParams, SendBitcoinParams, SettleParams, VirtualCoin, WalletBalance } from "../index";
 import { DelegateInfo } from "../../providers/delegator";
 import { MessageHandler, RequestEnvelope, ResponseEnvelope } from "../../worker/messageBus";
 import { Transaction } from "../../utils/transaction";
@@ -182,6 +182,18 @@ export type ResponseGetContractsWithVtxos = ResponseEnvelope & {
         contracts: ContractWithVtxos[];
     };
 };
+export type RequestAnnotateVtxos = RequestEnvelope & {
+    type: "ANNOTATE_VTXOS";
+    payload: {
+        vtxos: VirtualCoin[];
+    };
+};
+export type ResponseAnnotateVtxos = ResponseEnvelope & {
+    type: "ANNOTATED_VTXOS";
+    payload: {
+        vtxos: ExtendedVirtualCoin[];
+    };
+};
 export type RequestUpdateContract = RequestEnvelope & {
     type: "UPDATE_CONTRACT";
     payload: {
@@ -443,8 +455,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 | 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 | 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 | 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 declare class WalletMessageHandler implements MessageHandler<WalletUpdaterRequest, WalletUpdaterResponse> {
     readonly messageTag: string;
     private wallet;

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

@@ -4,13 +4,29 @@ import type { Contract } from "../contracts/types";
 import { ReadonlyWallet } from "./wallet";
 import { Bytes } from "@scure/btc-signer/utils";
 export declare const DUST_AMOUNT = 546;
-export declare function extendVirtualCoin(wallet: {
-    offchainTapscript: ReadonlyWallet["offchainTapscript"];
-}, vtxo: VirtualCoin): ExtendedVirtualCoin;
 export declare function extendCoin(wallet: {
     boardingTapscript: ReadonlyWallet["boardingTapscript"];
 }, utxo: Coin): ExtendedCoin;
-export declare function extendVtxoFromContract(vtxo: VirtualCoin, contract: Contract): ExtendedVirtualCoin;
+/**
+ * Extend a VirtualCoin with the tap scripts of whichever contract locks it.
+ *
+ * The second argument accepts either form, so each callsite passes what it
+ * already has:
+ * - a single `Contract` (when the caller already knows the owning contract,
+ *   e.g. the contract manager iterating its own `scriptToContract` map), or
+ * - a `ReadonlyMap<script, Contract>` (when the caller resolves by
+ *   `vtxo.script`, populated by the indexer).
+ *
+ * Throws when no contract can be resolved — there is intentionally no
+ * default-tapscript fallback. When the wallet owns multiple contracts
+ * (default + delegate, several active vHTLCs, etc.) a default-tapscript path
+ * silently stamps every VTXO with the same forfeit/intent data, overwriting
+ * the correct data for any VTXO locked to a non-default contract. Callers
+ * must feed a Contract or a populated script→Contract map; otherwise the
+ * caller (typically `ContractManager.annotateVtxos`) should fetch the owning
+ * contract first.
+ */
+export declare function extendVirtualCoinForContract(vtxo: VirtualCoin, contractOrMap?: Contract | ReadonlyMap<string, Contract>): ExtendedVirtualCoin;
 export declare function getRandomId(): string;
 export declare function isValidArkAddress(address: string): boolean;
 type ValidatedRecipient = Required<Recipient> & {

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

@@ -220,6 +220,13 @@ export declare class VtxoManager implements AsyncDisposable, IVtxoManager {
     private renewalInProgress;
     private lastRenewalTimestamp;
     private static readonly RENEWAL_COOLDOWN_MS;
+    private lastPeriodicSettleTimestamp;
+    private consecutivePeriodicSettleFailures;
+    private static readonly PERIODIC_SETTLE_COOLDOWN_MS;
+    private static readonly PERIODIC_SETTLE_MAX_BACKOFF_MS;
+    private lastVtxoSpentRefreshTimestamp;
+    private vtxoSpentRefreshPromise?;
+    private static readonly VTXO_SPENT_REFRESH_COOLDOWN_MS;
     constructor(wallet: IWallet, 
     /** @deprecated Use settlementConfig instead */
     renewalConfig?: RenewalConfig | undefined, settlementConfig?: SettlementConfig | false);
@@ -398,6 +405,16 @@ export declare class VtxoManager implements AsyncDisposable, IVtxoManager {
     /** Returns the wallet's identity for transaction signing. */
     private getIdentity;
     private initializeSubscription;
+    /**
+     * VTXO_ALREADY_SPENT means the server's authoritative view of VTXO state
+     * is ahead of ours — cross-instance race, pre-lock snapshot drift, or an
+     * SSE gap left stale data in the local cache. Silent-swallowing guarantees
+     * the same error on the next cycle because nothing reconciles the cache,
+     * so instead we trigger a full refreshVtxos() to advance the global sync
+     * cursor. Throttled to prevent a buggy indexer from causing a refresh
+     * storm.
+     */
+    private maybeRefreshAfterVtxoSpent;
     /** Computes the next poll delay, applying exponential backoff on failures. */
     private getNextPollDelay;
     /**
@@ -412,13 +429,19 @@ export declare class VtxoManager implements AsyncDisposable, IVtxoManager {
     private schedulePoll;
     private pollBoardingUtxos;
     /**
-     * Auto-settle new (unexpired) boarding inputs into Arkade.
-     * Skips UTXOs that are already expired (those are handled by sweep).
-     * Only settles UTXOs not already in-flight (tracked in knownBoardingUtxos).
-     * UTXOs are marked as known only after a successful settle, so failed
-     * attempts will be retried on the next poll.
+     * Auto-settle new (unexpired) boarding inputs AND near-expiry VTXOs into
+     * Arkade in a single intent. Skips boarding UTXOs that are already expired
+     * (those are handled by sweep) and those already in-flight (tracked in
+     * knownBoardingUtxos). If the event-driven renewal path is currently
+     * running, VTXOs are omitted from this cycle to avoid double-spending.
+     *
+     * Failure bookkeeping: after every settle *attempt*, lastPeriodicSettleTimestamp
+     * is armed and consecutive failures are counted so the next attempt is
+     * blocked by an exponentially growing cooldown (capped). This stops a
+     * persistently failing input from producing identical RegisterIntent +
+     * DeleteIntent retries on every 60s poll.
      */
-    private settleBoardingUtxos;
+    private runPeriodicSettle;
     dispose(): Promise<void>;
     [Symbol.asyncDispose](): Promise<void>;
 }