@arkade-os/sdk 0.4.17 → 0.4.18

package/dist/esm/wallet/wallet.js

@@ -12,7 +12,7 @@ import { validateConnectorsTxGraph, validateVtxoTxGraph, } from '../tree/validat
 import { validateBatchRecipients } from './validation.js';
 import { isBatchSignable } from '../identity/index.js';
 import { isExpired, isRecoverable, isSpendable, isSubdust, TxType, } from './index.js';
-import { createAssetPacket, selectedCoinsToAssetInputs, selectCoinsWithAsset, } from './asset.js';
+import { createAssetPacket, selectCoinsWithAsset, selectedCoinsToAssetInputs, } from './asset.js';
 import { VtxoScript } from '../script/base.js';
 import { CSVMultisigTapscript } from '../script/tapscript.js';
 import { buildOffchainTx, combineTapscriptSigs, hasBoardingTxExpired, isValidArkAddress, } from '../utils/arkTransaction.js';
@@ -20,7 +20,7 @@ import { DEFAULT_RENEWAL_CONFIG, DEFAULT_SETTLEMENT_CONFIG, VtxoManager, } from
 import { ArkNote } from '../arknote/index.js';
 import { Intent } from '../intent/index.js';
 import { RestIndexerProvider } from '../providers/indexer.js';
-import { extendCoin, extendVirtualCoin, validateRecipients } from './utils.js';
+import { extendCoin, validateRecipients } from './utils.js';
 import { ArkError } from '../providers/errors.js';
 import { Batch } from './batch.js';
 import { Estimator } from '../arkfee/index.js';
@@ -33,7 +33,7 @@ import { IndexedDBContractRepository, IndexedDBWalletRepository, } from '../repo
 import { ContractManager } from '../contracts/contractManager.js';
 import { contractHandlers } from '../contracts/handlers/index.js';
 import { timelockToSequence } from '../contracts/handlers/helpers.js';
-import { advanceSyncCursors, clearSyncCursors, computeSyncWindow, cursorCutoff, getAllSyncCursors, updateWalletState, } from '../utils/syncCursors.js';
+import { clearSyncCursor, updateWalletState } from '../utils/syncCursors.js';
 // Hardcoded unilateral exit delay for mainnet (~7 days in seconds).
 // Pinned here so that address derivation stays stable for existing mainnet
 // wallets even after the server lowers the delay it advertises.
@@ -299,8 +299,10 @@ export class ReadonlyWallet {
     async getVtxos(filter) {
         const f = filter ?? { withRecoverable: true, withUnrolled: false };
         const contractManager = await this.getContractManager();
-        const contractsWithVtxos = await contractManager.getContractsWithVtxos();
-        return contractsWithVtxos.flatMap(({ vtxos }) => vtxos.filter((vtxo) => {
+        const vtxos = await contractManager.getContractsWithVtxos();
+        return vtxos
+            .flatMap((_) => _.vtxos)
+            .filter((vtxo) => {
             if (isSpendable(vtxo)) {
                 if (!f.withRecoverable &&
                     (isRecoverable(vtxo) || isExpired(vtxo))) {
@@ -309,17 +311,15 @@ export class ReadonlyWallet {
                 return true;
             }
             return !!(f.withUnrolled && vtxo.isUnrolled);
-        }));
+        });
     }
     /**
      * Return wallet transaction history derived from Arkade state and boarding transactions.
      */
     async getTransactionHistory() {
-        // Delta-sync virtual outputs into cache, then build history from the cache.
-        const { isDelta, fetchedExtended, address } = await this.syncVtxos();
-        const allVtxos = isDelta
-            ? await this.walletRepository.getVtxos(address)
-            : fetchedExtended;
+        const contractManager = await this.getContractManager();
+        const response = await contractManager.getContractsWithVtxos();
+        const allVtxos = response.flatMap((_) => _.vtxos);
         const { boardingTxs, commitmentsToIgnore } = await this.getBoardingTxs();
         const getTxCreatedAt = (txid) => this.indexerProvider
             .getVtxos({ outpoints: [{ txid, vout: 0 }] })
@@ -327,166 +327,11 @@ export class ReadonlyWallet {
         return buildTransactionHistory(allVtxos, boardingTxs, commitmentsToIgnore, getTxCreatedAt);
     }
     /**
-     * Delta-sync wallet virtual outputs: fetch only changed virtual outputs since the last
-     * cursor, or do a full bootstrap when no cursor exists. Upserts
-     * the result into the cache and advances the sync cursors.
-     *
-     * Concurrent calls are deduplicated: if a sync is already in flight,
-     * subsequent callers receive the same promise instead of triggering
-     * a second network round-trip.
-     */
-    syncVtxos() {
-        if (this._syncVtxosInflight)
-            return this._syncVtxosInflight;
-        const p = this.doSyncVtxos().finally(() => {
-            this._syncVtxosInflight = undefined;
-        });
-        this._syncVtxosInflight = p;
-        return p;
-    }
-    async doSyncVtxos() {
-        const address = await this.getAddress();
-        // Batch cursor read with script map to avoid extra async hops
-        // before the fetch (background operations may run between hops).
-        const [scriptMap, cursors] = await Promise.all([
-            this.getScriptMap(),
-            getAllSyncCursors(this.walletRepository),
-        ]);
-        const allScripts = [...scriptMap.keys()];
-        // Partition scripts into bootstrap (no cursor) and delta (has cursor).
-        const bootstrapScripts = [];
-        const deltaScripts = [];
-        for (const s of allScripts) {
-            if (cursors[s] === undefined) {
-                bootstrapScripts.push(s);
-            }
-            else {
-                deltaScripts.push(s);
-            }
-        }
-        const requestStartedAt = Date.now();
-        const allVtxos = [];
-        const extendWithScript = (vtxo) => {
-            const vtxoScript = vtxo.script
-                ? scriptMap.get(vtxo.script)
-                : undefined;
-            if (!vtxoScript)
-                return undefined;
-            return {
-                ...vtxo,
-                forfeitTapLeafScript: vtxoScript.forfeit(),
-                intentTapLeafScript: vtxoScript.forfeit(),
-                tapTree: vtxoScript.encode(),
-            };
-        };
-        // Full fetch for scripts with no cursor.
-        if (bootstrapScripts.length > 0) {
-            const response = await this.indexerProvider.getVtxos({
-                scripts: bootstrapScripts,
-            });
-            allVtxos.push(...response.vtxos);
-        }
-        // Delta fetch for scripts with an existing cursor.
-        let hasDelta = false;
-        if (deltaScripts.length > 0) {
-            const minCursor = Math.min(...deltaScripts.map((s) => cursors[s]));
-            const window = computeSyncWindow(minCursor);
-            if (window) {
-                hasDelta = true;
-                const response = await this.indexerProvider.getVtxos({
-                    scripts: deltaScripts,
-                    after: window.after,
-                });
-                allVtxos.push(...response.vtxos);
-            }
-        }
-        // Extend every fetched virtual output and upsert into the cache.
-        const fetchedExtended = [];
-        for (const vtxo of allVtxos) {
-            const extended = extendWithScript(vtxo);
-            if (extended)
-                fetchedExtended.push(extended);
-        }
-        // Save virtual outputs first, then advance cursors only on success.
-        const cutoff = cursorCutoff(requestStartedAt);
-        await this.walletRepository.saveVtxos(address, fetchedExtended);
-        await advanceSyncCursors(this.walletRepository, Object.fromEntries(allScripts.map((s) => [s, cutoff])));
-        // Delta-sync reconciliation: full re-fetch for delta scripts.
-        //
-        // The delta fetch (above) only returns virtual outputs changed after the
-        // cursor, so it can miss preconfirmed virtual outputs that were consumed
-        // by a round between syncs.  Rather than layering targeted
-        // queries (pendingOnly, spendableOnly) with pagination guards
-        // and set algebra, we perform a single unfiltered re-fetch for
-        // delta scripts.  This is slightly more data over the wire but
-        // gives us complete, authoritative state in one call and keeps
-        // the reconciliation logic simple.
-        //
-        // Any cached non-spent virtual output that is absent from the full
-        // result set is marked spent; any virtual output whose state changed
-        // (e.g. preconfirmed → settled) is updated in place.
-        if (hasDelta) {
-            const { vtxos: fullVtxos, page: fullPage } = await this.indexerProvider.getVtxos({
-                scripts: deltaScripts,
-            });
-            // Reconciliation is best-effort: if the response is
-            // paginated we don't have a complete picture, so we skip
-            // rather than act on partial data.  Wallets with enough
-            // virtual outputs to exceed a single page rely solely on the
-            // cursor-based delta mechanism for state updates.
-            const fullSetComplete = !fullPage || fullPage.total <= 1;
-            if (fullSetComplete) {
-                const fullOutpoints = new Map(fullVtxos.map((v) => [`${v.txid}:${v.vout}`, v]));
-                const deltaScriptSet = new Set(deltaScripts);
-                const cachedVtxos = await this.walletRepository.getVtxos(address);
-                const reconciledExtended = [];
-                for (const cached of cachedVtxos) {
-                    if (!cached.script ||
-                        !deltaScriptSet.has(cached.script) ||
-                        cached.isSpent) {
-                        continue;
-                    }
-                    const outpoint = `${cached.txid}:${cached.vout}`;
-                    const fresh = fullOutpoints.get(outpoint);
-                    if (!fresh) {
-                        // Server no longer knows about this virtual output —
-                        // it was spent between syncs.
-                        reconciledExtended.push({
-                            ...cached,
-                            isSpent: true,
-                        });
-                        continue;
-                    }
-                    const extended = extendWithScript(fresh);
-                    if (extended &&
-                        extended.virtualStatus.state !==
-                            cached.virtualStatus.state) {
-                        // State transitioned (e.g. preconfirmed →
-                        // settled) — update the cached entry.
-                        reconciledExtended.push(extended);
-                    }
-                }
-                if (reconciledExtended.length > 0) {
-                    console.warn(`[ark-sdk] delta sync: reconciled ${reconciledExtended.length} stale VTXO(s) via full re-fetch`);
-                    await this.walletRepository.saveVtxos(address, reconciledExtended);
-                }
-            }
-            else {
-                console.warn("[ark-sdk] delta sync: skipping reconciliation — full re-fetch was paginated");
-            }
-        }
-        return {
-            isDelta: hasDelta || bootstrapScripts.length === 0,
-            fetchedExtended,
-            address,
-        };
-    }
-    /**
-     * Clear all virtual output sync cursors, forcing a full re-bootstrap on next sync.
+     * Clear the global VTXO sync cursor, forcing a full re-bootstrap on next sync.
      * Useful for recovery after indexer reprocessing or debugging.
      */
-    async clearSyncCursors() {
-        await clearSyncCursors(this.walletRepository);
+    async clearSyncCursor() {
+        await clearSyncCursor(this.walletRepository);
     }
     /**
      * Build a transaction history view for the wallet's boarding address.
@@ -529,6 +374,7 @@ export class ReadonlyWallet {
                         createdAt: tx.status.confirmed
                             ? new Date(tx.status.block_time * 1000)
                             : new Date(0),
+                        script: hex.encode(this.boardingTapscript.pkScript),
                     });
                 }
             }
@@ -618,22 +464,41 @@ export class ReadonlyWallet {
                 await this.indexerProvider?.unsubscribeForScripts(subscriptionId);
             };
             // Handle subscription updates asynchronously without blocking.
-            // Note: subscription covers all wallet scripts (default + delegate),
-            // but we can't determine which script each virtual output belongs to from the
-            // subscription event. Virtual outputs are extended with the current offchainTapscript;
-            // this is for notification/display only — not for spending.
-            // For correct extension metadata, use getVtxos() which queries per-script.
+            // Subscription covers all wallet scripts (default + delegate) plus
+            // any additional registered contracts. Virtual outputs carry a
+            // `script` field from the indexer which the contract manager
+            // resolves to the owning contract so the extension uses the
+            // correct forfeit/intent tapscripts.
             (async () => {
                 try {
+                    const cm = await this.getContractManager();
                     for await (const update of subscription) {
-                        if (update.newVtxos?.length > 0 ||
-                            update.spentVtxos?.length > 0) {
+                        if (update.newVtxos?.length === 0 &&
+                            update.spentVtxos?.length === 0) {
+                            continue;
+                        }
+                        // Isolate per-update annotation failures (e.g. a VTXO
+                        // arriving for a contract we haven't registered yet).
+                        // Without this a single bad update would kill the
+                        // for-await loop and silently drop every subsequent
+                        // subscription event for the session.
+                        try {
+                            // Default to `[]` so a one-sided update (e.g.
+                            // only `newVtxos`) doesn't pass `undefined` into
+                            // annotateVtxos and throw on `.length`.
+                            const [newVtxos, spentVtxos] = await Promise.all([
+                                cm.annotateVtxos(update.newVtxos ?? []),
+                                cm.annotateVtxos(update.spentVtxos ?? []),
+                            ]);
                             eventCallback({
                                 type: "vtxo",
-                                newVtxos: update.newVtxos.map((vtxo) => extendVirtualCoin(this, vtxo)),
-                                spentVtxos: update.spentVtxos.map((vtxo) => extendVirtualCoin(this, vtxo)),
+                                newVtxos,
+                                spentVtxos,
                             });
                         }
+                        catch (error) {
+                            console.warn("Dropping subscription update after annotation failed; next sync will reconcile:", error);
+                        }
                     }
                 }
                 catch (error) {
@@ -903,11 +768,10 @@ export class Wallet extends ReadonlyWallet {
             }
         });
     }
-    constructor(identity, network, networkName, onchainProvider, arkProvider, indexerProvider, arkServerPublicKey, offchainTapscript, boardingTapscript, serverUnrollScript, forfeitOutputScript, forfeitPubkey, dustAmount, walletRepository, contractRepository, 
+    constructor(identity, network, onchainProvider, arkProvider, indexerProvider, arkServerPublicKey, offchainTapscript, boardingTapscript, serverUnrollScript, forfeitOutputScript, forfeitPubkey, dustAmount, walletRepository, contractRepository, 
     /** @deprecated Use settlementConfig */
     renewalConfig, delegatorProvider, watcherConfig, settlementConfig) {
         super(identity, network, onchainProvider, indexerProvider, arkServerPublicKey, offchainTapscript, boardingTapscript, dustAmount, walletRepository, contractRepository, delegatorProvider, watcherConfig);
-        this.networkName = networkName;
         this.arkProvider = arkProvider;
         this.serverUnrollScript = serverUnrollScript;
         this.forfeitOutputScript = forfeitOutputScript;
@@ -1027,7 +891,7 @@ export class Wallet extends ReadonlyWallet {
         const forfeitPubkey = hex.decode(setup.info.forfeitPubkey).slice(1);
         const forfeitAddress = Address(setup.network).decode(setup.info.forfeitAddress);
         const forfeitOutputScript = OutScript.encode(forfeitAddress);
-        const wallet = new Wallet(config.identity, setup.network, setup.networkName, setup.onchainProvider, setup.arkProvider, setup.indexerProvider, setup.serverPubKey, setup.offchainTapscript, setup.boardingTapscript, serverUnrollScript, forfeitOutputScript, forfeitPubkey, setup.dustAmount, setup.walletRepository, setup.contractRepository, config.renewalConfig, config.delegatorProvider, config.watcherConfig, config.settlementConfig);
+        const wallet = new Wallet(config.identity, setup.network, setup.onchainProvider, setup.arkProvider, setup.indexerProvider, setup.serverPubKey, setup.offchainTapscript, setup.boardingTapscript, serverUnrollScript, forfeitOutputScript, forfeitPubkey, setup.dustAmount, setup.walletRepository, setup.contractRepository, config.renewalConfig, config.delegatorProvider, config.watcherConfig, config.settlementConfig);
         await wallet.getVtxoManager();
         return wallet;
     }
@@ -1290,7 +1154,7 @@ export class Wallet extends ReadonlyWallet {
         const abortController = new AbortController();
         try {
             const stream = this.arkProvider.getEventStream(abortController.signal, topics);
-            const intentId = await this.safeRegisterIntent(intent);
+            const intentId = await this.safeRegisterIntent(intent, params.inputs);
             const handler = this.createBatchHandler(intentId, params.inputs, recipients, session);
             const commitmentTxid = await Batch.join(stream, handler, {
                 abortController,
@@ -1303,8 +1167,16 @@ export class Wallet extends ReadonlyWallet {
             return commitmentTxid;
         }
         catch (error) {
-            // delete the intent to not be stuck in the queue
-            await this.arkProvider.deleteIntent(deleteIntent).catch(() => { });
+            // delete the intent to not be stuck in the queue. If deletion fails
+            // the intent stays on the server and the next settle will hit
+            // "duplicated input" in safeRegisterIntent — surface the failure
+            // rather than silently swallowing it.
+            const inputIds = params.inputs
+                .map((i) => `${i.txid}:${i.vout}`)
+                .join(",");
+            await this.arkProvider.deleteIntent(deleteIntent).catch((e) => {
+                console.warn(`Failed to delete intent after settle failure for inputs [${inputIds}]; intent may linger on server and cause 'duplicated input' on next settle`, e);
+            });
             throw error;
         }
         finally {
@@ -1494,7 +1366,7 @@ export class Wallet extends ReadonlyWallet {
             },
         };
     }
-    async safeRegisterIntent(intent) {
+    async safeRegisterIntent(intent, inputs) {
         try {
             return await this.arkProvider.registerIntent(intent);
         }
@@ -1503,11 +1375,13 @@ export class Wallet extends ReadonlyWallet {
             if (error instanceof ArkError &&
                 error.code === 0 &&
                 error.message.includes("duplicated input")) {
-                // delete all intents spending one of the wallet coins
-                const allSpendableCoins = await this.getVtxos({
-                    withRecoverable: true,
-                });
-                const deleteIntent = await this.makeDeleteIntentSignature(allSpendableCoins);
+                // Clear any queued intent spending these exact inputs. The
+                // previous implementation signed a proof over getVtxos() only,
+                // which misses boarding UTXOs — the most common trigger for
+                // "duplicated input" on the auto-settle path. Signing the
+                // caller's own inputs keeps the proof surgical and correct
+                // regardless of whether the stuck input is a VTXO or boarding.
+                const deleteIntent = await this.makeDeleteIntentSignature(inputs);
                 await this.arkProvider.deleteIntent(deleteIntent);
                 // try again
                 return this.arkProvider.registerIntent(intent);
@@ -1575,9 +1449,7 @@ export class Wallet extends ReadonlyWallet {
                 scripts: allScripts,
             });
             for (const vtxo of fetchedVtxos) {
-                const vtxoScript = vtxo.script
-                    ? scriptMap.get(vtxo.script)
-                    : undefined;
+                const vtxoScript = scriptMap.get(vtxo.script);
                 if (!vtxoScript)
                     continue;
                 if (vtxo.virtualStatus.state === "swept" ||
@@ -1880,8 +1752,9 @@ export class Wallet extends ReadonlyWallet {
                 console.warn(`updateDbAfterOffchainTx: inputs length (${inputs.length}) differs from signedCheckpointTxs length (${signedCheckpointTxs.length})`);
             }
             const safeLength = Math.min(inputs.length, signedCheckpointTxs.length);
-            for (const [inputIndex, input] of inputs.entries()) {
-                const vtxo = extendVirtualCoin(this, input);
+            const cm = await this.getContractManager();
+            const annotatedInputs = await cm.annotateVtxos(inputs);
+            for (const [inputIndex, vtxo] of annotatedInputs.entries()) {
                 if (inputIndex < safeLength &&
                     signedCheckpointTxs[inputIndex]) {
                     const checkpoint = Transaction.fromPSBT(base64.decode(signedCheckpointTxs[inputIndex]));
@@ -1941,6 +1814,7 @@ export class Wallet extends ReadonlyWallet {
                         confirmed: false,
                     },
                     assets: changeAssets,
+                    script: hex.encode(this.offchainTapscript.pkScript),
                 };
             }
             await this.walletRepository.saveVtxos(addr, changeVtxo ? [...spentVtxos, changeVtxo] : spentVtxos);
@@ -1971,10 +1845,14 @@ export class Wallet extends ReadonlyWallet {
             const inputArkTxIds = new Set();
             const boardingUtxoToRemove = new Set();
             const isVtxo = (input) => "virtualStatus" in input;
+            const vtxoInputs = inputs.filter(isVtxo);
+            const cm = await this.getContractManager();
+            const annotatedVtxos = await cm.annotateVtxos(vtxoInputs);
+            const annotatedByKey = new Map(annotatedVtxos.map((v) => [`${v.txid}:${v.vout}`, v]));
             for (const input of inputs) {
                 if (isVtxo(input)) {
                     // virtual output = mark it settled
-                    const vtxo = extendVirtualCoin(this, input);
+                    const vtxo = annotatedByKey.get(`${input.txid}:${input.vout}`);
                     if (vtxo.arkTxId) {
                         inputArkTxIds.add(vtxo.arkTxId);
                     }
@@ -2060,7 +1938,7 @@ export function selectVirtualCoins(coins, targetAmount) {
  */
 export async function waitForIncomingFunds(wallet) {
     let stopFunc;
-    const promise = new Promise((resolve) => {
+    return new Promise((resolve) => {
         wallet
             .notifyIncomingFunds((coins) => {
             resolve(coins);
@@ -2071,5 +1949,4 @@ export async function waitForIncomingFunds(wallet) {
             stopFunc = stop;
         });
     });
-    return promise;
 }

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

@@ -5,27 +5,24 @@ export const CONTRACT_POLL_TASK_TYPE = "contract-poll";
  *
  * Replicates the polling subset of @see ContractManager.initialize:
  * 1. Load all contracts from the contract repository.
- * 2. Mark expired active contracts as inactive.
- * 3. Paginated fetch of spendable VTXOs from the indexer.
- * 4. Extend each VTXO with tapscript data.
- * 5. Save to the wallet repository.
+ * 2. Paginated fetch of every VTXO (including spent) from the indexer.
+ * 3. Extend each VTXO with tapscript data.
+ * 4. Save to the wallet repository.
+ *
+ * NOTE: the indexer query deliberately omits `spendableOnly`. Every
+ * repository implements `saveVtxos` as an upsert with no batch delete,
+ * so filtering to spendable-only would leave VTXOs that became spent
+ * between polls marked as spendable forever. Fetching the full set lets
+ * the upsert overwrite stale records with their latest state.
  */
 export const contractPollProcessor = {
     taskType: CONTRACT_POLL_TASK_TYPE,
     async execute(item, deps) {
         const { contractRepository, walletRepository, indexerProvider, extendVtxo, } = deps;
         const contracts = await contractRepository.getContracts();
-        const now = Date.now();
         let contractsProcessed = 0;
         let vtxosSaved = 0;
         for (const contract of contracts) {
-            // Mark expired active contracts as inactive
-            if (contract.state === "active" &&
-                contract.expiresAt &&
-                contract.expiresAt <= now) {
-                contract.state = "inactive";
-                await contractRepository.saveContract(contract);
-            }
             // Paginated fetch of spendable virtual outputs
             const pageSize = 100;
             let pageIndex = 0;
@@ -34,7 +31,6 @@ export const contractPollProcessor = {
             while (hasMore) {
                 const { vtxos, page } = await indexerProvider.getVtxos({
                     scripts: [contract.script],
-                    spendableOnly: true,
                     pageIndex,
                     pageSize,
                 });

package/dist/esm/worker/expo/taskRunner.js

@@ -1,4 +1,4 @@
-import { getRandomId, extendVirtualCoin, extendVtxoFromContract, } from '../../wallet/utils.js';
+import { getRandomId, extendVirtualCoinForContract } from '../../wallet/utils.js';
 /**
  * Run all pending tasks from the queue through matching processors.
  *
@@ -62,17 +62,8 @@ export async function runTasks(queue, processors, deps) {
  * can build deps without depending on Expo.
  */
 export function createTaskDependencies(options) {
-    const { walletRepository, contractRepository, indexerProvider, arkProvider, offchainTapscript, } = options;
     return {
-        walletRepository,
-        contractRepository,
-        indexerProvider,
-        arkProvider,
-        extendVtxo: (vtxo, contract) => {
-            if (contract) {
-                return extendVtxoFromContract(vtxo, contract);
-            }
-            return extendVirtualCoin({ offchainTapscript }, vtxo);
-        },
+        ...options,
+        extendVtxo: (vtxo, contract) => extendVirtualCoinForContract(vtxo, contract),
     };
 }

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.
      *