@arkade-os/sdk 0.4.10 → 0.4.12

package/dist/esm/contracts/contractManager.js

@@ -2,6 +2,8 @@ import { hex } from "@scure/base";
 import { ContractWatcher } from './contractWatcher.js';
 import { contractHandlers } from './handlers/index.js';
 import { extendVtxoFromContract } from '../wallet/utils.js';
+import { advanceSyncCursors, clearSyncCursors, computeSyncWindow, cursorCutoff, getAllSyncCursors, } from '../utils/syncCursors.js';
+const DEFAULT_PAGE_SIZE = 500;
 /**
  * Central manager for contract lifecycle and operations.
  *
@@ -71,10 +73,14 @@ export class ContractManager {
         }
         // Load persisted contracts
         const contracts = await this.config.contractRepository.getContracts();
-        // fetch all VTXOs (including spent/swept) for all contracts,
-        // so the repository has full history for transaction history and balance
-        // TODO: what if the user has 1k contracts?
-        await this.fetchContractVxosFromIndexer(contracts, true);
+        // Delta-sync: fetch only VTXOs that changed since the last cursor,
+        // falling back to a full bootstrap for scripts seen for the first time.
+        await this.deltaSyncContracts(contracts);
+        // Reconcile the pending frontier: fetch all not-yet-finalized VTXOs
+        // to catch any that the delta window may have missed.
+        if (contracts.length > 0) {
+            await this.reconcilePendingFrontier(contracts);
+        }
         // add all contracts to the watcher
         const now = Date.now();
         for (const contract of contracts) {
@@ -91,7 +97,9 @@ export class ContractManager {
         this.initialized = true;
         // Start watching automatically
         this.stopWatcherFn = await this.watcher.startWatching((event) => {
-            this.handleContractEvent(event);
+            this.handleContractEvent(event).catch((error) => {
+                console.error("Error handling contract event:", error);
+            });
         });
     }
     /**
@@ -138,7 +146,15 @@ export class ContractManager {
         // Persist
         await this.config.contractRepository.saveContract(contract);
         // fetch all VTXOs (including spent/swept) for this contract
+        const requestStartedAt = Date.now();
         await this.fetchContractVxosFromIndexer([contract], true);
+        // Advance the sync cursor so that the watcher's vtxo_received
+        // event (triggered by addContract below) doesn't re-bootstrap
+        // the same script via deltaSyncContracts.
+        const cutoff = cursorCutoff(requestStartedAt);
+        await advanceSyncCursors(this.config.walletRepository, {
+            [contract.script]: cutoff,
+        });
         // Add to watcher
         await this.watcher.addContract(contract);
         return contract;
@@ -162,9 +178,9 @@ export class ContractManager {
         const dbFilter = this.buildContractsDbFilter(filter ?? {});
         return await this.config.contractRepository.getContracts(dbFilter);
     }
-    async getContractsWithVtxos(filter) {
+    async getContractsWithVtxos(filter, pageSize) {
         const contracts = await this.getContracts(filter);
-        const vtxos = await this.getVtxosForContracts(contracts);
+        const vtxos = await this.getVtxosForContracts(contracts, pageSize);
         return contracts.map((contract) => ({
             contract,
             vtxos: vtxos.get(contract.script) ?? [],
@@ -304,12 +320,43 @@ export class ContractManager {
         };
     }
     /**
-     * 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.
      */
-    async refreshVtxos() {
-        const contracts = await this.config.contractRepository.getContracts();
-        await this.fetchContractVxosFromIndexer(contracts, true);
+    async refreshVtxos(opts) {
+        let contracts = await this.config.contractRepository.getContracts();
+        if (opts?.scripts && opts.scripts.length > 0) {
+            const scriptSet = new Set(opts.scripts);
+            contracts = contracts.filter((c) => scriptSet.has(c.script));
+        }
+        const syncWindow = opts?.after !== undefined || opts?.before !== undefined
+            ? {
+                after: opts.after ?? 0,
+                before: opts.before ?? Date.now(),
+            }
+            : undefined;
+        if (!syncWindow) {
+            // Full refresh — clear cursors so the next delta sync re-bootstraps.
+            if (opts?.scripts && opts.scripts.length > 0) {
+                await clearSyncCursors(this.config.walletRepository, opts.scripts);
+            }
+            else {
+                await clearSyncCursors(this.config.walletRepository);
+            }
+        }
+        const requestStartedAt = Date.now();
+        const fetched = await this.fetchContractVxosFromIndexer(contracts, true, undefined, syncWindow);
+        // Persist cursors so subsequent incremental syncs don't re-bootstrap.
+        const cutoff = cursorCutoff(requestStartedAt);
+        const cursorUpdates = {};
+        for (const script of fetched.keys()) {
+            cursorUpdates[script] = cutoff;
+        }
+        if (Object.keys(cursorUpdates).length > 0) {
+            await advanceSyncCursors(this.config.walletRepository, cursorUpdates);
+        }
     }
     /**
      * Check if currently watching.
@@ -335,14 +382,13 @@ export class ContractManager {
      */
     async handleContractEvent(event) {
         switch (event.type) {
-            // Every time there is a VTXO event for a contract, refresh all its VTXOs
+            // Delta-sync only the changed VTXOs for this contract.
             case "vtxo_received":
             case "vtxo_spent":
-                await this.fetchContractVxosFromIndexer([event.contract], true);
+                await this.deltaSyncContracts([event.contract]);
                 break;
             case "connection_reset": {
-                // Refetch all VTXOs (including spent/swept) for all active
-                // contracts so the repo stays consistent with bootstrap state
+                // After a reconnect we don't know what we missed — full refetch.
                 const activeWatchedContracts = this.watcher.getActiveContracts();
                 await this.fetchContractVxosFromIndexer(activeWatchedContracts, true);
                 break;
@@ -354,14 +400,100 @@ export class ContractManager {
         // Forward to all callbacks
         this.emitEvent(event);
     }
-    async getVtxosForContracts(contracts) {
+    async getVtxosForContracts(contracts, pageSize) {
         if (contracts.length === 0) {
             return new Map();
         }
-        return await this.fetchContractVxosFromIndexer(contracts, false);
+        return await this.fetchContractVxosFromIndexer(contracts, false, pageSize);
+    }
+    /**
+     * 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.
+     */
+    async deltaSyncContracts(contracts, pageSize) {
+        if (contracts.length === 0)
+            return new Map();
+        const cursors = await getAllSyncCursors(this.config.walletRepository);
+        // Partition into bootstrap (no cursor) and delta (has cursor) groups.
+        const bootstrap = [];
+        const delta = [];
+        for (const c of contracts) {
+            if (cursors[c.script] !== undefined) {
+                delta.push(c);
+            }
+            else {
+                bootstrap.push(c);
+            }
+        }
+        const result = new Map();
+        const cursorUpdates = {};
+        // Full bootstrap for new scripts.
+        if (bootstrap.length > 0) {
+            const requestStartedAt = Date.now();
+            const fetched = await this.fetchContractVxosFromIndexer(bootstrap, true);
+            const cutoff = cursorCutoff(requestStartedAt);
+            for (const [script, vtxos] of fetched) {
+                result.set(script, vtxos);
+                cursorUpdates[script] = cutoff;
+            }
+        }
+        // Delta sync for scripts with an existing cursor.
+        if (delta.length > 0) {
+            // Use the oldest cursor so the shared window covers every script.
+            const minCursor = Math.min(...delta.map((c) => cursors[c.script]));
+            const window = computeSyncWindow(minCursor);
+            if (window) {
+                const requestStartedAt = Date.now();
+                const fetched = await this.fetchContractVxosFromIndexer(delta, true, pageSize, window);
+                const cutoff = cursorCutoff(requestStartedAt);
+                for (const [script, vtxos] of fetched) {
+                    result.set(script, vtxos);
+                    cursorUpdates[script] = cutoff;
+                }
+            }
+        }
+        if (Object.keys(cursorUpdates).length > 0) {
+            await advanceSyncCursors(this.config.walletRepository, cursorUpdates);
+        }
+        return result;
     }
-    async fetchContractVxosFromIndexer(contracts, includeSpent) {
-        const fetched = await this.fetchContractVtxosBulk(contracts, includeSpent);
+    /**
+     * 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).
+     */
+    async reconcilePendingFrontier(contracts) {
+        const scripts = contracts.map((c) => c.script);
+        const scriptToContract = new Map(contracts.map((c) => [c.script, c]));
+        const { vtxos } = await this.config.indexerProvider.getVtxos({
+            scripts,
+            pendingOnly: true,
+        });
+        // Group by contract and upsert.
+        const byContract = new Map();
+        for (const vtxo of vtxos) {
+            if (!vtxo.script)
+                continue;
+            const contract = scriptToContract.get(vtxo.script);
+            if (!contract)
+                continue;
+            let arr = byContract.get(contract.address);
+            if (!arr) {
+                arr = [];
+                byContract.set(contract.address, arr);
+            }
+            arr.push({
+                ...extendVtxoFromContract(vtxo, contract),
+                contractScript: contract.script,
+            });
+        }
+        for (const [addr, contractVtxos] of byContract) {
+            await this.config.walletRepository.saveVtxos(addr, contractVtxos);
+        }
+    }
+    async fetchContractVxosFromIndexer(contracts, includeSpent, pageSize, syncWindow) {
+        const fetched = await this.fetchContractVtxosBulk(contracts, includeSpent, pageSize, syncWindow);
         const result = new Map();
         for (const [contractScript, vtxos] of fetched) {
             result.set(contractScript, vtxos);
@@ -372,14 +504,14 @@ export class ContractManager {
         }
         return result;
     }
-    async fetchContractVtxosBulk(contracts, includeSpent) {
+    async fetchContractVtxosBulk(contracts, includeSpent, pageSize = DEFAULT_PAGE_SIZE, syncWindow) {
         if (contracts.length === 0) {
             return new Map();
         }
         // For a single contract, use the paginated path directly.
         if (contracts.length === 1) {
             const contract = contracts[0];
-            const vtxos = await this.fetchContractVtxosPaginated(contract, includeSpent);
+            const vtxos = await this.fetchContractVtxosPaginated(contract, includeSpent, pageSize, syncWindow);
             return new Map([[contract.script, vtxos]]);
         }
         // For multiple contracts, batch all scripts into a single indexer call
@@ -388,14 +520,24 @@ export class ContractManager {
         const scriptToContract = new Map(contracts.map((c) => [c.script, c]));
         const result = new Map(contracts.map((c) => [c.script, []]));
         const scripts = contracts.map((c) => c.script);
-        const pageSize = 100;
         const opts = includeSpent ? {} : { spendableOnly: true };
+        const windowOpts = syncWindow
+            ? {
+                ...(syncWindow.after !== undefined && {
+                    after: syncWindow.after,
+                }),
+                ...(syncWindow.before !== undefined && {
+                    before: syncWindow.before,
+                }),
+            }
+            : {};
         let pageIndex = 0;
         let hasMore = true;
         while (hasMore) {
             const { vtxos, page } = await this.config.indexerProvider.getVtxos({
                 scripts,
                 ...opts,
+                ...windowOpts,
                 pageIndex,
                 pageSize,
             });
@@ -414,19 +556,31 @@ export class ContractManager {
             }
             hasMore = page ? vtxos.length === pageSize : false;
             pageIndex++;
+            if (hasMore)
+                await new Promise((r) => setTimeout(r, 500));
         }
         return result;
     }
-    async fetchContractVtxosPaginated(contract, includeSpent) {
-        const pageSize = 100;
+    async fetchContractVtxosPaginated(contract, includeSpent, pageSize = DEFAULT_PAGE_SIZE, syncWindow) {
         const allVtxos = [];
         let pageIndex = 0;
         let hasMore = true;
         const opts = includeSpent ? {} : { spendableOnly: true };
+        const windowOpts = syncWindow
+            ? {
+                ...(syncWindow.after !== undefined && {
+                    after: syncWindow.after,
+                }),
+                ...(syncWindow.before !== undefined && {
+                    before: syncWindow.before,
+                }),
+            }
+            : {};
         while (hasMore) {
             const { vtxos, page } = await this.config.indexerProvider.getVtxos({
                 scripts: [contract.script],
                 ...opts,
+                ...windowOpts,
                 pageIndex,
                 pageSize,
             });
@@ -438,6 +592,8 @@ export class ContractManager {
             }
             hasMore = page ? vtxos.length === pageSize : false;
             pageIndex++;
+            if (hasMore)
+                await new Promise((r) => setTimeout(r, 500));
         }
         return allVtxos;
     }

package/dist/esm/providers/indexer.js

@@ -251,23 +251,40 @@ export class RestIndexerProvider {
         return data;
     }
     async getVtxos(opts) {
+        const hasScripts = (opts?.scripts?.length ?? 0) > 0;
+        const hasOutpoints = (opts?.outpoints?.length ?? 0) > 0;
         // scripts and outpoints are mutually exclusive
-        if (opts?.scripts && opts?.outpoints) {
+        if (hasScripts && hasOutpoints) {
             throw new Error("scripts and outpoints are mutually exclusive options");
         }
-        if (!opts?.scripts && !opts?.outpoints) {
+        if (!hasScripts && !hasOutpoints) {
             throw new Error("Either scripts or outpoints must be provided");
         }
+        const filterCount = [
+            opts?.spendableOnly,
+            opts?.spentOnly,
+            opts?.recoverableOnly,
+        ].filter(Boolean).length;
+        if (filterCount > 1) {
+            throw new Error("spendableOnly, spentOnly, and recoverableOnly are mutually exclusive options");
+        }
+        if (opts?.after !== undefined &&
+            opts?.before !== undefined &&
+            opts.after !== 0 &&
+            opts.before !== 0 &&
+            opts.before <= opts.after) {
+            throw new Error("before must be greater than after");
+        }
         let url = `${this.serverUrl}/v1/indexer/vtxos`;
         const params = new URLSearchParams();
         // Handle scripts with multi collection format
-        if (opts?.scripts && opts.scripts.length > 0) {
+        if (hasScripts) {
             opts.scripts.forEach((script) => {
                 params.append("scripts", script);
             });
         }
         // Handle outpoints with multi collection format
-        if (opts?.outpoints && opts.outpoints.length > 0) {
+        if (hasOutpoints) {
             opts.outpoints.forEach((outpoint) => {
                 params.append("outpoints", `${outpoint.txid}:${outpoint.vout}`);
             });
@@ -279,6 +296,12 @@ export class RestIndexerProvider {
                 params.append("spentOnly", opts.spentOnly.toString());
             if (opts.recoverableOnly !== undefined)
                 params.append("recoverableOnly", opts.recoverableOnly.toString());
+            if (opts.pendingOnly !== undefined)
+                params.append("pendingOnly", opts.pendingOnly.toString());
+            if (opts.after !== undefined)
+                params.append("after", opts.after.toString());
+            if (opts.before !== undefined)
+                params.append("before", opts.before.toString());
             if (opts.pageIndex !== undefined)
                 params.append("page.index", opts.pageIndex.toString());
             if (opts.pageSize !== undefined)

package/dist/esm/utils/syncCursors.js

@@ -0,0 +1,125 @@
+/** Lag behind real-time to avoid racing with indexer writes. */
+export const SAFETY_LAG_MS = 30000;
+/** Overlap window so boundary VTXOs are never missed. */
+export const OVERLAP_MS = 60000;
+/**
+ * Per-repository mutex that serializes wallet-state mutations so that
+ * concurrent read-modify-write cycles (e.g. advanceSyncCursors racing
+ * with clearSyncCursors or setPendingTxFlag) never silently overwrite
+ * each other's changes.
+ */
+const walletStateLocks = new WeakMap();
+/**
+ * Atomically read, mutate, and persist wallet state.
+ * All callers that modify wallet state should go through this helper
+ * to avoid lost-update races between interleaved async operations.
+ */
+export async function updateWalletState(repo, updater) {
+    const prev = walletStateLocks.get(repo) ?? Promise.resolve();
+    const op = prev.then(async () => {
+        const state = (await repo.getWalletState()) ?? {};
+        await repo.saveWalletState(updater(state));
+    });
+    // Store a version that never rejects so the chain doesn't break.
+    walletStateLocks.set(repo, op.catch(() => { }));
+    return op;
+}
+/**
+ * Read the high-water mark for a single script.
+ * Returns `undefined` when the script has never been synced (bootstrap case).
+ */
+export async function getSyncCursor(repo, script) {
+    const state = await repo.getWalletState();
+    return state?.settings?.vtxoSyncCursors?.[script];
+}
+/**
+ * Read cursors for every previously-synced script.
+ */
+export async function getAllSyncCursors(repo) {
+    const state = await repo.getWalletState();
+    return state?.settings?.vtxoSyncCursors ?? {};
+}
+/**
+ * Advance the cursor for one script after a successful delta sync.
+ * `cursor` should be the `before` cutoff used in the request.
+ */
+export async function advanceSyncCursor(repo, script, cursor) {
+    await updateWalletState(repo, (state) => {
+        const existing = state.settings?.vtxoSyncCursors ?? {};
+        return {
+            ...state,
+            settings: {
+                ...state.settings,
+                vtxoSyncCursors: { ...existing, [script]: cursor },
+            },
+        };
+    });
+}
+/**
+ * Advance cursors for multiple scripts in a single write.
+ */
+export async function advanceSyncCursors(repo, updates) {
+    await updateWalletState(repo, (state) => {
+        const existing = state.settings?.vtxoSyncCursors ?? {};
+        return {
+            ...state,
+            settings: {
+                ...state.settings,
+                vtxoSyncCursors: { ...existing, ...updates },
+            },
+        };
+    });
+}
+/**
+ * Remove sync cursors, forcing a full re-bootstrap on next sync.
+ * When `scripts` is provided, only those cursors are cleared.
+ */
+export async function clearSyncCursors(repo, scripts) {
+    await updateWalletState(repo, (state) => {
+        if (!scripts) {
+            const { vtxoSyncCursors: _, ...restSettings } = state.settings ?? {};
+            return {
+                ...state,
+                settings: restSettings,
+            };
+        }
+        const existing = state.settings?.vtxoSyncCursors ?? {};
+        const filtered = { ...existing };
+        for (const s of scripts)
+            delete filtered[s];
+        return {
+            ...state,
+            settings: {
+                ...state.settings,
+                vtxoSyncCursors: filtered,
+            },
+        };
+    });
+}
+/**
+ * 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 VTXOs are never excluded. The safety lag is applied only
+ * when advancing the cursor (see {@link cursorCutoff}).
+ */
+export function computeSyncWindow(cursor) {
+    if (cursor === undefined)
+        return undefined;
+    const after = Math.max(0, cursor - OVERLAP_MS);
+    return { after };
+}
+/**
+ * The safe high-water mark for cursor advancement.
+ * Lags behind real-time by {@link SAFETY_LAG_MS} so that VTXOs still
+ * being indexed are re-queried on the next sync.
+ *
+ * When `requestStartedAt` is provided the cutoff is frozen to the
+ * request start rather than wall-clock at commit time, preventing
+ * long-running paginated fetches from advancing the cursor past the
+ * data they actually observed.
+ */
+export function cursorCutoff(requestStartedAt) {
+    return (requestStartedAt ?? Date.now()) - SAFETY_LAG_MS;
+}

package/dist/esm/wallet/delegator.js

@@ -21,10 +21,13 @@ export class DelegatorManagerImpl {
             return { delegated: [], failed: [] };
         }
         const destinationScript = ArkAddress.decode(destination).pkScript;
+        // fetch server and delegator info once, shared across all groups
+        const arkInfo = await this.arkInfoProvider.getInfo();
+        const delegateInfo = await this.delegatorProvider.getDelegateInfo();
         // if explicit delegateAt is provided, delegate all vtxos at once without sorting
         if (delegateAt) {
             try {
-                await delegate(this.identity, this.delegatorProvider, this.arkInfoProvider, vtxos, destinationScript, delegateAt);
+                await delegate(this.identity, this.delegatorProvider, arkInfo, delegateInfo, vtxos, destinationScript, delegateAt);
             }
             catch (error) {
                 return { delegated: [], failed: [{ outpoints: vtxos, error }] };
@@ -51,7 +54,7 @@ export class DelegatorManagerImpl {
         // if no groups, it means we only need to delegate the recoverable vtxos
         if (groupByExpiry.size === 0) {
             try {
-                await delegate(this.identity, this.delegatorProvider, this.arkInfoProvider, recoverableVtxos, destinationScript, delegateAt);
+                await delegate(this.identity, this.delegatorProvider, arkInfo, delegateInfo, recoverableVtxos, destinationScript, delegateAt);
             }
             catch (error) {
                 return {
@@ -68,7 +71,7 @@ export class DelegatorManagerImpl {
             ...recoverableVtxos,
         ]);
         const groupsList = Array.from(groupByExpiry.entries());
-        const result = await Promise.allSettled(groupsList.map(async ([, vtxosGroup]) => delegate(this.identity, this.delegatorProvider, this.arkInfoProvider, vtxosGroup, destinationScript)));
+        const result = await Promise.allSettled(groupsList.map(async ([, vtxosGroup]) => delegate(this.identity, this.delegatorProvider, arkInfo, delegateInfo, vtxosGroup, destinationScript)));
         const delegated = [];
         const failed = [];
         for (const [index, resultItem] of result.entries()) {
@@ -90,7 +93,7 @@ export class DelegatorManagerImpl {
  *                     should occur. If not provided, defaults to 12 hours before the earliest
  *                     expiry time of the provided vtxos.
  */
-async function delegate(identity, delegatorProvider, arkInfoProvider, vtxos, destinationScript, delegateAt) {
+async function delegate(identity, delegatorProvider, arkInfo, delegateInfo, vtxos, destinationScript, delegateAt) {
     if (vtxos.length === 0) {
         throw new Error("unable to delegate: no vtxos provided");
     }
@@ -116,7 +119,7 @@ async function delegate(identity, delegatorProvider, arkInfoProvider, vtxos, des
             }
         }
     }
-    const { fees, dust, forfeitAddress, network } = await arkInfoProvider.getInfo();
+    const { fees, dust, forfeitAddress, network } = arkInfo;
     const delegateAtSeconds = delegateAt.getTime() / 1000;
     const estimator = new Estimator({
         ...fees.intentFee,
@@ -140,7 +143,7 @@ async function delegate(identity, delegatorProvider, arkInfoProvider, vtxos, des
         }
         amount += BigInt(coin.value) - BigInt(inputFee.value);
     }
-    const { delegatorAddress, pubkey, fee } = await delegatorProvider.getDelegateInfo();
+    const { delegatorAddress, pubkey, fee } = delegateInfo;
     const outputs = [];
     const delegatorFee = BigInt(Number(fee));
     if (delegatorFee > 0n) {