@arkade-os/sdk 0.4.10 → 0.4.11

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

@@ -286,7 +286,7 @@ export class WalletMessageHandler {
                 }
                 case "REFRESH_VTXOS": {
                     const manager = await this.readonlyWallet.getContractManager();
-                    await manager.refreshVtxos();
+                    await manager.refreshVtxos(message.payload);
                     return this.tagged({
                         id,
                         type: "REFRESH_VTXOS_SUCCESS",
@@ -531,11 +531,13 @@ export class WalletMessageHandler {
         // Initialize contract manager FIRST — this populates the repository
         // with full VTXO history for all contracts (one indexer call per contract)
         await this.ensureContractEventBroadcasting();
-        // Read VTXOs from repository (now populated by contract manager)
-        const vtxos = await this.getVtxosFromRepo();
+        // Refresh cached data (VTXOs, boarding UTXOs, tx history)
+        await this.refreshCachedData();
+        // Recover pending transactions (init-only, not on reload).
+        // Pending txs only exist if a send was interrupted mid-finalization.
         if (this.wallet) {
             try {
-                // recover pending transactions if possible
+                const vtxos = await this.getVtxosFromRepo();
                 const { pending, finalized } = await this.wallet.finalizePendingTxs(vtxos.filter((vtxo) => vtxo.virtualStatus.state !== "swept" &&
                     vtxo.virtualStatus.state !== "settled"));
                 console.info(`Recovered ${finalized.length}/${pending.length} pending transactions: ${finalized.join(", ")}`);
@@ -544,18 +546,10 @@ export class WalletMessageHandler {
                 console.error("Error recovering pending transactions:", error);
             }
         }
-        // Fetch boarding utxos and save using unified repository
-        const boardingAddress = await this.readonlyWallet.getBoardingAddress();
-        const coins = await this.readonlyWallet.onchainProvider.getCoins(boardingAddress);
-        await this.walletRepository.saveUtxos(boardingAddress, coins.map((utxo) => extendCoin(this.readonlyWallet, utxo)));
-        // Build transaction history from cached VTXOs (no indexer call)
-        const address = await this.readonlyWallet.getAddress();
-        const txs = await this.buildTransactionHistoryFromCache(vtxos);
-        if (txs)
-            await this.walletRepository.saveTransactions(address, txs);
         // unsubscribe previous subscription if any
         if (this.incomingFundsSubscription)
             this.incomingFundsSubscription();
+        const address = await this.readonlyWallet.getAddress();
         // subscribe for incoming funds and notify all clients when new funds arrive
         this.incomingFundsSubscription =
             await this.readonlyWallet.notifyIncomingFunds(async (funds) => {
@@ -608,15 +602,38 @@ export class WalletMessageHandler {
         }
     }
     /**
-     * Force a full VTXO refresh from the indexer, then re-run bootstrap.
-     * Used by RELOAD_WALLET to ensure fresh data.
+     * Refresh VTXOs, boarding UTXOs, and transaction history from cache.
+     * Shared by onWalletInitialized (full bootstrap) and reloadWallet
+     * (post-refresh), avoiding duplicate subscriptions and VtxoManager restarts.
+     */
+    async refreshCachedData() {
+        if (!this.readonlyWallet || !this.walletRepository) {
+            return;
+        }
+        // Read VTXOs from repository (now populated by contract manager)
+        const vtxos = await this.getVtxosFromRepo();
+        // Fetch boarding utxos and save using unified repository
+        const boardingAddress = await this.readonlyWallet.getBoardingAddress();
+        const coins = await this.readonlyWallet.onchainProvider.getCoins(boardingAddress);
+        await this.walletRepository.deleteUtxos(boardingAddress);
+        await this.walletRepository.saveUtxos(boardingAddress, coins.map((utxo) => extendCoin(this.readonlyWallet, utxo)));
+        // Build transaction history from cached VTXOs (no indexer call)
+        const address = await this.readonlyWallet.getAddress();
+        const txs = await this.buildTransactionHistoryFromCache(vtxos);
+        if (txs)
+            await this.walletRepository.saveTransactions(address, txs);
+    }
+    /**
+     * Force a full VTXO refresh from the indexer, then refresh cached data.
+     * Used by RELOAD_WALLET to ensure fresh data without re-subscribing
+     * to incoming funds or restarting the VtxoManager.
      */
     async reloadWallet() {
         if (!this.readonlyWallet)
             return;
         const manager = await this.readonlyWallet.getContractManager();
         await manager.refreshVtxos();
-        await this.onWalletInitialized();
+        await this.refreshCachedData();
     }
     async handleSettle(message) {
         const wallet = this.requireWallet();
@@ -791,24 +808,37 @@ export class WalletMessageHandler {
                 vtxoCreatedAt.set(vtxo.txid, ts);
             }
         }
-        // getTxCreatedAt resolves the creation timestamp of a transaction.
-        // buildTransactionHistory calls this for spent-offchain VTXOs with
-        // no change outputs to determine the time of the sending tx.
-        // Returns undefined on miss so buildTransactionHistory uses its
-        // own fallback (vtxo.createdAt + 1) rather than epoch 0.
-        // The vout:0 lookup in the indexer fallback mirrors the pre-existing
-        // convention in ReadonlyWallet.getTransactionHistory().
-        const getTxCreatedAt = async (txid) => {
-            const cached = vtxoCreatedAt.get(txid);
-            if (cached !== undefined)
-                return cached;
-            if (this.indexerProvider) {
-                const res = await this.indexerProvider.getVtxos({
-                    outpoints: [{ txid, vout: 0 }],
-                });
-                return res.vtxos[0]?.createdAt.getTime();
+        // Pre-fetch uncached timestamps in a single batched indexer call.
+        // buildTransactionHistory needs these for spent-offchain VTXOs with
+        // no change outputs (i.e. arkTxId is set but no VTXO has txid === arkTxId).
+        if (this.indexerProvider) {
+            const uncachedTxids = new Set();
+            for (const vtxo of vtxos) {
+                if (vtxo.isSpent &&
+                    vtxo.arkTxId &&
+                    !vtxoCreatedAt.has(vtxo.arkTxId) &&
+                    !vtxos.some((v) => v.txid === vtxo.arkTxId)) {
+                    uncachedTxids.add(vtxo.arkTxId);
+                }
             }
-            return undefined;
+            if (uncachedTxids.size > 0) {
+                const outpoints = [...uncachedTxids].map((txid) => ({
+                    txid,
+                    vout: 0,
+                }));
+                const BATCH_SIZE = 100;
+                for (let i = 0; i < outpoints.length; i += BATCH_SIZE) {
+                    const res = await this.indexerProvider.getVtxos({
+                        outpoints: outpoints.slice(i, i + BATCH_SIZE),
+                    });
+                    for (const v of res.vtxos) {
+                        vtxoCreatedAt.set(v.txid, v.createdAt.getTime());
+                    }
+                }
+            }
+        }
+        const getTxCreatedAt = async (txid) => {
+            return vtxoCreatedAt.get(txid);
         };
         return buildTransactionHistory(vtxos, boardingTxs, commitmentsToIgnore, getTxCreatedAt);
     }

package/dist/esm/wallet/serviceWorker/wallet.js

@@ -682,11 +682,12 @@ export class ServiceWorkerReadonlyWallet {
                     navigator.serviceWorker.removeEventListener("message", messageHandler);
                 };
             },
-            async refreshVtxos() {
+            async refreshVtxos(opts) {
                 const message = {
                     type: "REFRESH_VTXOS",
                     id: getRandomId(),
                     tag: messageTag,
+                    payload: opts,
                 };
                 await sendContractMessage(message);
             },

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

@@ -397,8 +397,8 @@ export class VtxoManager {
      * }
      * ```
      */
-    async getExpiredBoardingUtxos() {
-        const boardingUtxos = await this.wallet.getBoardingUtxos();
+    async getExpiredBoardingUtxos(prefetchedUtxos) {
+        const boardingUtxos = prefetchedUtxos ?? (await this.wallet.getBoardingUtxos());
         const boardingTimelock = this.getBoardingTimelock();
         // For block-based timelocks, fetch the chain tip height
         let chainTipHeight;
@@ -439,14 +439,14 @@ export class VtxoManager {
      * }
      * ```
      */
-    async sweepExpiredBoardingUtxos() {
+    async sweepExpiredBoardingUtxos(prefetchedUtxos) {
         const sweepEnabled = this.settlementConfig !== false &&
             (this.settlementConfig?.boardingUtxoSweep ??
                 DEFAULT_SETTLEMENT_CONFIG.boardingUtxoSweep);
         if (!sweepEnabled) {
             throw new Error("Boarding UTXO sweep is not enabled in settlementConfig");
         }
-        const allExpired = await this.getExpiredBoardingUtxos();
+        const allExpired = await this.getExpiredBoardingUtxos(prefetchedUtxos);
         // Filter out UTXOs already swept (tx broadcast but not yet confirmed)
         const expiredUtxos = allExpired.filter((u) => !this.sweptBoardingUtxos.has(`${u.txid}:${u.vout}`));
         if (expiredUtxos.length === 0) {
@@ -635,16 +635,25 @@ export class VtxoManager {
         // Guard: wallet must support boarding UTXO + sweep operations
         if (!isSweepCapable(this.wallet))
             return;
-        // Skip if a previous poll is still running
+        // Skip if disposed or a previous poll is still running
+        if (this.disposed)
+            return;
         if (this.pollInProgress)
             return;
         this.pollInProgress = true;
+        // Create a promise that dispose() can await
+        let resolve;
+        const promise = new Promise((r) => (resolve = r));
+        this.pollDone = { promise, resolve: resolve };
         let hadError = false;
         try {
+            // Fetch boarding UTXOs once for the entire poll cycle so that
+            // settle and sweep don't each hit the network independently.
+            const boardingUtxos = await this.wallet.getBoardingUtxos();
             // Settle new (unexpired) UTXOs first, then sweep expired ones.
             // Sequential to avoid racing for the same UTXOs.
             try {
-                await this.settleBoardingUtxos();
+                await this.settleBoardingUtxos(boardingUtxos);
             }
             catch (e) {
                 hadError = true;
@@ -655,7 +664,7 @@ export class VtxoManager {
                     DEFAULT_SETTLEMENT_CONFIG.boardingUtxoSweep);
             if (sweepEnabled) {
                 try {
-                    await this.sweepExpiredBoardingUtxos();
+                    await this.sweepExpiredBoardingUtxos(boardingUtxos);
                 }
                 catch (e) {
                     if (!(e instanceof Error) ||
@@ -666,6 +675,10 @@ export class VtxoManager {
                 }
             }
         }
+        catch (e) {
+            hadError = true;
+            console.error("Error fetching boarding UTXOs:", e);
+        }
         finally {
             if (hadError) {
                 this.consecutivePollFailures++;
@@ -674,6 +687,8 @@ export class VtxoManager {
                 this.consecutivePollFailures = 0;
             }
             this.pollInProgress = false;
+            this.pollDone.resolve();
+            this.pollDone = undefined;
             this.schedulePoll();
         }
     }
@@ -684,8 +699,7 @@ export class VtxoManager {
      * UTXOs are marked as known only after a successful settle, so failed
      * attempts will be retried on the next poll.
      */
-    async settleBoardingUtxos() {
-        const boardingUtxos = await this.wallet.getBoardingUtxos();
+    async settleBoardingUtxos(boardingUtxos) {
         // Exclude expired UTXOs — those should be swept, not settled.
         // If we can't determine expired status, bail out entirely to avoid
         // accidentally settling expired UTXOs (which would conflict with sweep).
@@ -732,6 +746,13 @@ export class VtxoManager {
                 clearTimeout(this.pollTimeoutId);
                 this.pollTimeoutId = undefined;
             }
+            // Wait for any in-flight poll to finish (with timeout to avoid hanging)
+            if (this.pollDone) {
+                let timer;
+                const timeout = new Promise((r) => (timer = setTimeout(r, 30000)));
+                await Promise.race([this.pollDone.promise, timeout]);
+                clearTimeout(timer);
+            }
             const subscription = await this.contractEventsSubscriptionReady;
             this.contractEventsSubscription = undefined;
             subscription?.();

package/dist/esm/wallet/wallet.js

@@ -32,6 +32,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';
 /**
  * Type guard function to check if an identity has a toReadonly method.
  */
@@ -269,61 +270,158 @@ export class ReadonlyWallet {
         };
     }
     async getVtxos(filter) {
-        const address = await this.getAddress();
-        const scriptMap = await this.getScriptMap();
+        const { isDelta, fetchedExtended, address } = await this.syncVtxos();
         const f = filter ?? { withRecoverable: true, withUnrolled: false };
-        const allExtended = [];
-        // Batch all scripts into a single indexer call
-        const allScripts = [...scriptMap.keys()];
-        const response = await this.indexerProvider.getVtxos({
-            scripts: allScripts,
-        });
-        for (const vtxo of response.vtxos) {
-            const vtxoScript = vtxo.script
-                ? scriptMap.get(vtxo.script)
-                : undefined;
-            if (!vtxoScript)
-                continue;
+        // For delta syncs, read the full merged set from cache so old
+        // VTXOs that weren't in the delta are still returned.
+        const vtxos = isDelta
+            ? await this.walletRepository.getVtxos(address)
+            : fetchedExtended;
+        return vtxos.filter((vtxo) => {
             if (isSpendable(vtxo)) {
                 if (!f.withRecoverable &&
                     (isRecoverable(vtxo) || isExpired(vtxo))) {
-                    continue;
+                    return false;
                 }
+                return true;
+            }
+            return !!(f.withUnrolled && vtxo.isUnrolled);
+        });
+    }
+    async getTransactionHistory() {
+        // Delta-sync VTXOs 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 { boardingTxs, commitmentsToIgnore } = await this.getBoardingTxs();
+        const getTxCreatedAt = (txid) => this.indexerProvider
+            .getVtxos({ outpoints: [{ txid, vout: 0 }] })
+            .then((res) => res.vtxos[0]?.createdAt.getTime());
+        return buildTransactionHistory(allVtxos, boardingTxs, commitmentsToIgnore, getTxCreatedAt);
+    }
+    /**
+     * Delta-sync wallet VTXOs: fetch only changed VTXOs since the last
+     * cursor, or do a full bootstrap when no cursor exists. Upserts
+     * the result into the cache and advances the sync cursors.
+     */
+    async syncVtxos() {
+        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 {
-                if (!f.withUnrolled || !vtxo.isUnrolled)
-                    continue;
+                deltaScripts.push(s);
+            }
+        }
+        const requestStartedAt = Date.now();
+        const allVtxos = [];
+        // 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);
             }
-            allExtended.push({
+        }
+        // Extend every fetched VTXO and upsert into the cache.
+        const fetchedExtended = [];
+        for (const vtxo of allVtxos) {
+            const vtxoScript = vtxo.script
+                ? scriptMap.get(vtxo.script)
+                : undefined;
+            if (!vtxoScript)
+                continue;
+            fetchedExtended.push({
                 ...vtxo,
                 forfeitTapLeafScript: vtxoScript.forfeit(),
                 intentTapLeafScript: vtxoScript.forfeit(),
                 tapTree: vtxoScript.encode(),
             });
         }
-        // Update cache with fresh data
-        await this.walletRepository.saveVtxos(address, allExtended);
-        return allExtended;
+        // Save VTXOs 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])));
+        // For delta syncs, reconcile pending (preconfirmed/spent) VTXOs
+        // whose state may have changed since the cursor so that
+        // getVtxos()/getTransactionHistory() don't serve stale state.
+        if (hasDelta) {
+            const { vtxos: pendingVtxos } = await this.indexerProvider.getVtxos({
+                scripts: deltaScripts,
+                pendingOnly: true,
+            });
+            const pendingExtended = [];
+            for (const vtxo of pendingVtxos) {
+                const vtxoScript = vtxo.script
+                    ? scriptMap.get(vtxo.script)
+                    : undefined;
+                if (!vtxoScript)
+                    continue;
+                pendingExtended.push({
+                    ...vtxo,
+                    forfeitTapLeafScript: vtxoScript.forfeit(),
+                    intentTapLeafScript: vtxoScript.forfeit(),
+                    tapTree: vtxoScript.encode(),
+                });
+            }
+            if (pendingExtended.length > 0) {
+                await this.walletRepository.saveVtxos(address, pendingExtended);
+            }
+        }
+        return {
+            isDelta: hasDelta || bootstrapScripts.length === 0,
+            fetchedExtended,
+            address,
+        };
     }
-    async getTransactionHistory() {
-        const scripts = await this.getWalletScripts();
-        const response = await this.indexerProvider.getVtxos({ scripts });
-        const { boardingTxs, commitmentsToIgnore } = await this.getBoardingTxs();
-        const getTxCreatedAt = (txid) => this.indexerProvider
-            .getVtxos({ outpoints: [{ txid, vout: 0 }] })
-            .then((res) => res.vtxos[0]?.createdAt.getTime());
-        return buildTransactionHistory(response.vtxos, boardingTxs, commitmentsToIgnore, getTxCreatedAt);
+    /**
+     * Clear all VTXO sync cursors, forcing a full re-bootstrap on next sync.
+     * Useful for recovery after indexer reprocessing or debugging.
+     */
+    async clearSyncCursors() {
+        await clearSyncCursors(this.walletRepository);
     }
     async getBoardingTxs() {
         const utxos = [];
         const commitmentsToIgnore = new Set();
         const boardingAddress = await this.getBoardingAddress();
         const txs = await this.onchainProvider.getTransactions(boardingAddress);
+        const outspendCache = new Map();
         for (const tx of txs) {
             for (let i = 0; i < tx.vout.length; i++) {
                 const vout = tx.vout[i];
                 if (vout.scriptpubkey_address === boardingAddress) {
-                    const spentStatuses = await this.onchainProvider.getTxOutspends(tx.txid);
+                    let spentStatuses = outspendCache.get(tx.txid);
+                    if (!spentStatuses) {
+                        spentStatuses =
+                            await this.onchainProvider.getTxOutspends(tx.txid);
+                        outspendCache.set(tx.txid, spentStatuses);
+                    }
                     const spentStatus = spentStatuses[i];
                     if (spentStatus?.spent) {
                         commitmentsToIgnore.add(spentStatus.txid);
@@ -1338,10 +1436,15 @@ export class Wallet extends ReadonlyWallet {
     }
     /**
      * Finalizes pending transactions by retrieving them from the server and finalizing each one.
+     * Skips the server check entirely when no send was interrupted (no pending tx flag set).
      * @param vtxos - Optional list of VTXOs to use instead of retrieving them from the server
      * @returns Array of transaction IDs that were finalized
      */
     async finalizePendingTxs(vtxos) {
+        const hasPending = await this.hasPendingTxFlag();
+        if (!hasPending) {
+            return { finalized: [], pending: [] };
+        }
         const MAX_INPUTS_PER_INTENT = 20;
         if (!vtxos || vtxos.length === 0) {
             // Batch all scripts into a single indexer call
@@ -1373,33 +1476,63 @@ export class Wallet extends ReadonlyWallet {
             }
             vtxos = allExtended;
         }
-        const finalized = [];
-        const pending = [];
+        const batches = [];
         for (let i = 0; i < vtxos.length; i += MAX_INPUTS_PER_INTENT) {
-            const batch = vtxos.slice(i, i + MAX_INPUTS_PER_INTENT);
+            batches.push(vtxos.slice(i, i + MAX_INPUTS_PER_INTENT));
+        }
+        // Track seen arkTxids so parallel batches don't finalize the same tx twice
+        const seen = new Set();
+        const results = await Promise.all(batches.map(async (batch) => {
+            const batchFinalized = [];
+            const batchPending = [];
             const intent = await this.makeGetPendingTxIntentSignature(batch);
             const pendingTxs = await this.arkProvider.getPendingTxs(intent);
-            // finalize each transaction by signing the checkpoints
             for (const pendingTx of pendingTxs) {
-                pending.push(pendingTx.arkTxid);
+                if (seen.has(pendingTx.arkTxid))
+                    continue;
+                seen.add(pendingTx.arkTxid);
+                batchPending.push(pendingTx.arkTxid);
                 try {
-                    // sign the checkpoints
                     const finalCheckpoints = await Promise.all(pendingTx.signedCheckpointTxs.map(async (c) => {
                         const tx = Transaction.fromPSBT(base64.decode(c));
                         const signedCheckpoint = await this.identity.sign(tx);
                         return base64.encode(signedCheckpoint.toPSBT());
                     }));
                     await this.arkProvider.finalizeTx(pendingTx.arkTxid, finalCheckpoints);
-                    finalized.push(pendingTx.arkTxid);
+                    batchFinalized.push(pendingTx.arkTxid);
                 }
                 catch (error) {
                     console.error(`Failed to finalize transaction ${pendingTx.arkTxid}:`, error);
-                    // continue with other transactions even if one fails
                 }
             }
+            return {
+                finalized: batchFinalized,
+                pending: batchPending,
+            };
+        }));
+        const finalized = [];
+        const pending = [];
+        for (const result of results) {
+            finalized.push(...result.finalized);
+            pending.push(...result.pending);
+        }
+        // Only clear the flag if every discovered pending tx was finalized;
+        // if any failed, keep it so recovery retries on next startup.
+        if (finalized.length === pending.length) {
+            await this.setPendingTxFlag(false);
         }
         return { finalized, pending };
     }
+    async hasPendingTxFlag() {
+        const state = await this.walletRepository.getWalletState();
+        return state?.settings?.hasPendingTx === true;
+    }
+    async setPendingTxFlag(value) {
+        await updateWalletState(this.walletRepository, (state) => ({
+            ...state,
+            settings: { ...state.settings, hasPendingTx: value },
+        }));
+    }
     /**
      * Send BTC and/or assets to one or more recipients.
      *
@@ -1568,6 +1701,9 @@ export class Wallet extends ReadonlyWallet {
             };
         }), outputs, this.serverUnrollScript);
         const signedVirtualTx = await this.identity.sign(offchainTx.arkTx);
+        // Mark pending before submitting — if we crash between submit and
+        // finalize, the next init will recover via finalizePendingTxs.
+        await this.setPendingTxFlag(true);
         const { arkTxid, signedCheckpointTxs } = await this.arkProvider.submitTx(base64.encode(signedVirtualTx.toPSBT()), offchainTx.checkpoints.map((c) => base64.encode(c.toPSBT())));
         const finalCheckpoints = await Promise.all(signedCheckpointTxs.map(async (c) => {
             const tx = Transaction.fromPSBT(base64.decode(c));
@@ -1575,6 +1711,12 @@ export class Wallet extends ReadonlyWallet {
             return base64.encode(signedCheckpoint.toPSBT());
         }));
         await this.arkProvider.finalizeTx(arkTxid, finalCheckpoints);
+        try {
+            await this.setPendingTxFlag(false);
+        }
+        catch (error) {
+            console.error("Failed to clear pending tx flag:", error);
+        }
         return { arkTxid, signedCheckpointTxs };
     }
     // mark vtxo spent and save change vtxo if any

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

@@ -43,6 +43,11 @@ import { ContractRepository } from "../repositories";
  * manager.dispose();
  * ```
  */
+export type RefreshVtxosOptions = {
+    scripts?: string[];
+    after?: number;
+    before?: number;
+};
 export interface IContractManager extends Disposable {
     /**
      * Create and register a new contract.
@@ -103,10 +108,12 @@ export interface IContractManager extends Disposable {
      */
     onContractEvent(callback: ContractEventCallback): () => void;
     /**
-     * Force a full VTXO refresh from the indexer for all contracts.
-     * Populates the wallet repository with complete VTXO history.
+     * Force a VTXO refresh from the indexer.
+     *
+     * Without options, refreshes all contracts from scratch.
+     * With options, narrows the refresh to specific scripts and/or a time window.
      */
-    refreshVtxos(): Promise<void>;
+    refreshVtxos(opts?: RefreshVtxosOptions): Promise<void>;
     /**
      * Whether the underlying watcher is currently active.
      */
@@ -240,7 +247,7 @@ export declare class ContractManager implements IContractManager {
      * ```
      */
     getContracts(filter?: GetContractsFilter): Promise<Contract[]>;
-    getContractsWithVtxos(filter?: GetContractsFilter): Promise<ContractWithVtxos[]>;
+    getContractsWithVtxos(filter?: GetContractsFilter, pageSize?: number): Promise<ContractWithVtxos[]>;
     private buildContractsDbFilter;
     /**
      * Update a contract.
@@ -298,10 +305,12 @@ export declare class ContractManager implements IContractManager {
      */
     onContractEvent(callback: ContractEventCallback): () => void;
     /**
-     * Force a full VTXO refresh from the indexer for all contracts.
-     * Populates the wallet repository with complete VTXO history.
+     * Force a VTXO refresh from the indexer.
+     *
+     * Without options, clears all sync cursors and re-fetches every contract.
+     * With options, narrows the refresh to specific scripts and/or a time window.
      */
-    refreshVtxos(): Promise<void>;
+    refreshVtxos(opts?: RefreshVtxosOptions): Promise<void>;
     /**
      * Check if currently watching.
      */
@@ -315,6 +324,18 @@ export declare class ContractManager implements IContractManager {
      */
     private handleContractEvent;
     private getVtxosForContracts;
+    /**
+     * Incrementally sync VTXOs 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.
+     */
+    private deltaSyncContracts;
+    /**
+     * Fetch all pending (not-yet-finalized) VTXOs and upsert them into the
+     * repository. This catches VTXOs whose state changed outside the delta
+     * window (e.g. a spend that hasn't settled yet).
+     */
+    private reconcilePendingFrontier;
     private fetchContractVxosFromIndexer;
     private fetchContractVtxosBulk;
     private fetchContractVtxosPaginated;

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

@@ -11,4 +11,4 @@ export type { ParsedArkContract } from "./arkcontract";
 export { ContractWatcher } from "./contractWatcher";
 export type { ContractWatcherConfig } from "./contractWatcher";
 export { ContractManager } from "./contractManager";
-export type { ContractManagerConfig, CreateContractParams, } from "./contractManager";
+export type { ContractManagerConfig, CreateContractParams, RefreshVtxosOptions, } from "./contractManager";