@arkade-os/sdk 0.4.17 → 0.4.19

package/dist/esm/contracts/contractManager.js

@@ -1,8 +1,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';
+import { extendVirtualCoinForContract } from '../wallet/utils.js';
+import { advanceSyncCursor, computeSyncWindow, cursorCutoff, getSyncCursor, } from '../utils/syncCursors.js';
 const DEFAULT_PAGE_SIZE = 500;
 /**
  * Central manager for contract lifecycle and operations.
@@ -11,7 +11,7 @@ const DEFAULT_PAGE_SIZE = 500;
  * - 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
@@ -81,29 +81,16 @@ export class ContractManager {
         if (this.initialized) {
             return;
         }
-        // Load persisted contracts
+        // Register persisted contracts with the watcher BEFORE the first
+        // sync. `addContract` seeds `lastKnownVtxos` from the repo without
+        // starting to poll, so it's cheap, and it populates
+        // `getWatchedContracts()` so the sync below can scope itself to the
+        // real watched set instead of every contract ever persisted.
         const contracts = await this.config.contractRepository.getContracts();
-        // Delta-sync: fetch only virtual outputs that changed since the last cursor,
-        // falling back to a full bootstrap for scripts seen for the first time.
-        await this.deltaSyncContracts(contracts, undefined, true);
-        // Reconcile the pending frontier: fetch all not-yet-finalized virtual outputs
-        // 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) {
-            // Check for expired contracts and mark as inactive
-            if (contract.state === "active" &&
-                contract.expiresAt &&
-                contract.expiresAt <= now) {
-                contract.state = "inactive";
-                await this.config.contractRepository.saveContract(contract);
-            }
-            // Add to watcher
             await this.watcher.addContract(contract);
         }
+        await this.reconcileWatched();
         this.initialized = true;
         // Start watching automatically
         this.stopWatcherFn = await this.watcher.startWatching((event) => {
@@ -112,6 +99,23 @@ export class ContractManager {
             });
         });
     }
+    /**
+     * 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.
+     */
+    async reconcileWatched() {
+        await this.syncContracts({});
+        const watched = this.watcher.getWatchedContracts();
+        if (watched.length > 0) {
+            await this.reconcilePendingFrontier(watched);
+        }
+    }
     /**
      * Create and register a new contract.
      *
@@ -156,15 +160,7 @@ export class ContractManager {
         // Persist
         await this.config.contractRepository.saveContract(contract);
         // fetch all virtual outputs (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,
-        });
+        await this.fetchContractVxosFromIndexer([contract]);
         // Add to watcher
         await this.watcher.addContract(contract);
         return contract;
@@ -190,12 +186,26 @@ export class ContractManager {
     }
     async getContractsWithVtxos(filter, pageSize) {
         const contracts = await this.getContracts(filter);
-        const vtxos = await this.getVtxosForContracts(contracts, pageSize);
+        await this.syncContracts({ contracts, pageSize });
+        const vtxos = await this.getVtxosForContracts(contracts);
         return contracts.map((contract) => ({
             contract,
-            vtxos: vtxos.get(contract.script) ?? [],
+            vtxos: vtxos.filter((vtxo) => vtxo.contractScript === contract.script),
         }));
     }
+    async annotateVtxos(vtxos) {
+        if (vtxos.length === 0)
+            return [];
+        const scripts = Array.from(new Set(vtxos.map((v) => v.script)));
+        const byScript = new Map();
+        const contracts = await this.config.contractRepository.getContracts({
+            script: scripts,
+        });
+        for (const contract of contracts) {
+            byScript.set(contract.script, contract);
+        }
+        return vtxos.map((vtxo) => extendVirtualCoinForContract(vtxo, byScript));
+    }
     buildContractsDbFilter(filter) {
         return {
             script: filter.script,
@@ -336,41 +346,18 @@ export class ContractManager {
     /**
      * 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.
      */
     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(),
-            }
+        const contracts = opts?.scripts
+            ? await this.getContracts({ script: opts.scripts })
             : 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);
-        }
+        await this.syncContracts({
+            contracts,
+            window: { after: opts?.after, before: opts?.before },
+        });
     }
     /**
      * Check if currently watching.
@@ -399,94 +386,54 @@ export class ContractManager {
             // Delta-sync only the changed virtual outputs for this contract.
             case "vtxo_received":
             case "vtxo_spent":
-                await this.deltaSyncContracts([event.contract]);
+                await this.syncContracts({ contracts: [event.contract] });
                 break;
-            case "connection_reset": {
-                // After a reconnect we don't know what we missed — full refetch.
-                const activeWatchedContracts = this.watcher.getActiveContracts();
-                await this.fetchContractVxosFromIndexer(activeWatchedContracts, true);
+            case "connection_reset":
+                // Same recovery path as boot: delta-sync the watched set
+                // and reconcile the pending frontier. `advanceSyncCursor`
+                // is monotonic so this never rewinds the cursor.
+                await this.reconcileWatched();
                 break;
-            }
-            case "contract_expired":
-                // just update DB
-                await this.config.contractRepository.saveContract(event.contract);
         }
         // Forward to all callbacks
         this.emitEvent(event);
     }
-    async getVtxosForContracts(contracts, pageSize) {
-        if (contracts.length === 0) {
-            return new Map();
-        }
-        // Deduplicate concurrent callers against an in-flight fetch so we don't
-        // issue redundant round-trips. Once the fetch settles we clear the
-        // reference so the next call triggers a fresh fetch.
-        // TODO: can be removed once we fix the persistence layer (address vs scripts)
-        if (this.syncVtxosCallInflight) {
-            return this.syncVtxosCallInflight;
-        }
-        this.syncVtxosCallInflight = this.fetchContractVxosFromIndexer(contracts, true, pageSize).finally(() => {
-            this.syncVtxosCallInflight = undefined;
-        });
-        return this.syncVtxosCallInflight;
+    async getVtxosForContracts(contracts) {
+        const res = await Promise.all(contracts.map(({ script, address }) => this.config.walletRepository.getVtxos(address).then((vtxos) => vtxos.map((vtxo) => ({
+            ...vtxo,
+            contractScript: script,
+        })))));
+        return res.flat();
     }
     /**
-     * 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.
      */
-    async deltaSyncContracts(contracts, pageSize, force) {
-        if (contracts.length === 0)
-            return new Map();
-        // If forced, we are treating all contracts as boostrapped and we clean the VTXO list
-        if (force === true) {
-            await Promise.all(contracts.map((contract) => this.config.walletRepository.deleteVtxos(contract.address)));
-        }
-        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 (force) {
-                bootstrap.push(c);
-                continue;
-            }
-            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);
+    async syncContracts(options) {
+        const cursor = await getSyncCursor(this.config.walletRepository);
+        const window = options.window ?? computeSyncWindow(cursor);
+        // Advance the global cursor only on full-scope, cursor-derived delta
+        // syncs. A caller-supplied window is targeted (e.g. `refreshVtxos`)
+        // and must not move the cursor — it may skip data outside its bounds.
+        // `<=` lets the bootstrap case (cursor=0, window.after=0) write the
+        // migration marker on first boot; otherwise the marker would never
+        // be written and every subsequent boot would treat the cursor as
+        // legacy and re-bootstrap.
+        const mustUpdateCursor = options.contracts === undefined &&
+            options.window === undefined &&
+            (window.after ?? 0) <= cursor;
+        const contracts = options.contracts ?? this.watcher.getWatchedContracts();
+        const requestStartedAt = Date.now();
+        const result = await this.fetchContractVxosFromIndexer(contracts, options.pageSize, window);
+        if (mustUpdateCursor) {
             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);
+            await advanceSyncCursor(this.config.walletRepository, cutoff);
         }
         return result;
     }
@@ -502,21 +449,20 @@ export class ContractManager {
             scripts,
             pendingOnly: true,
         });
-        // Group by contract and upsert.
+        // Share the annotation path with external callers so the two entry
+        // points can't drift.
+        const owned = vtxos.filter((v) => scriptToContract.has(v.script));
+        const annotated = await this.annotateVtxos(owned);
         const byContract = new Map();
-        for (const vtxo of vtxos) {
-            if (!vtxo.script)
-                continue;
+        for (const vtxo of annotated) {
             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),
+                ...vtxo,
                 contractScript: contract.script,
             });
         }
@@ -524,8 +470,8 @@ export class ContractManager {
             await this.config.walletRepository.saveVtxos(addr, contractVtxos);
         }
     }
-    async fetchContractVxosFromIndexer(contracts, includeSpent, pageSize, syncWindow) {
-        const fetched = await this.fetchContractVtxosBulk(contracts, includeSpent, pageSize, syncWindow);
+    async fetchContractVxosFromIndexer(contracts, pageSize, syncWindow) {
+        const fetched = await this.fetchContractVtxosBulk(contracts, pageSize, syncWindow);
         const result = new Map();
         for (const [contractScript, vtxos] of fetched) {
             result.set(contractScript, vtxos);
@@ -536,23 +482,17 @@ export class ContractManager {
         }
         return result;
     }
-    async fetchContractVtxosBulk(contracts, includeSpent, pageSize = DEFAULT_PAGE_SIZE, syncWindow) {
+    async fetchContractVtxosBulk(contracts, 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, pageSize, syncWindow);
-            return new Map([[contract.script, vtxos]]);
-        }
-        // For multiple contracts, batch all scripts into a single indexer call
-        // per page to minimise round-trips.  Results are keyed by script so we
-        // can distribute them back to the correct contract afterwards.
+        // Batch all scripts into a single indexer call per page to minimise
+        // round-trips. Results are keyed by script so we can distribute them
+        // back to the correct contract afterwards. Always fetches the full
+        // history (spent/swept included) so the repo is the source of truth.
         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 opts = includeSpent ? {} : { spendableOnly: true };
         const windowOpts = syncWindow
             ? {
                 ...(syncWindow.after !== undefined && {
@@ -568,22 +508,20 @@ export class ContractManager {
         while (hasMore) {
             const { vtxos, page } = await this.config.indexerProvider.getVtxos({
                 scripts,
-                ...opts,
                 ...windowOpts,
                 pageIndex,
                 pageSize,
             });
-            for (const vtxo of vtxos) {
-                // Match the virtual output back to its contract via the script field
-                // populated by the indexer.
-                if (!vtxo.script)
-                    continue;
-                const contract = scriptToContract.get(vtxo.script);
-                if (!contract)
-                    continue;
-                result.get(contract.script).push({
-                    ...extendVtxoFromContract(vtxo, contract),
-                    contractScript: contract.script,
+            // Match virtual outputs back to their contract via the script field
+            // populated by the indexer, then share the annotation path with
+            // external callers via annotateVtxos so the two entry points can't
+            // drift.
+            const owned = vtxos.filter((v) => scriptToContract.has(v.script));
+            const annotated = await this.annotateVtxos(owned);
+            for (const vtxo of annotated) {
+                result.get(vtxo.script).push({
+                    ...vtxo,
+                    contractScript: vtxo.script,
                 });
             }
             hasMore = page ? vtxos.length === pageSize : false;
@@ -593,42 +531,6 @@ export class ContractManager {
         }
         return result;
     }
-    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,
-            });
-            for (const vtxo of vtxos) {
-                allVtxos.push({
-                    ...extendVtxoFromContract(vtxo, contract),
-                    contractScript: contract.script,
-                });
-            }
-            hasMore = page ? vtxos.length === pageSize : false;
-            pageIndex++;
-            if (hasMore)
-                await new Promise((r) => setTimeout(r, 500));
-        }
-        return allVtxos;
-    }
     /**
      * Dispose of the ContractManager and release all resources.
      *
@@ -657,12 +559,6 @@ export class ContractManager {
      * ```
      */
     [Symbol.dispose]() {
-        // Stop watching
-        this.stopWatcherFn?.();
-        this.stopWatcherFn = undefined;
-        // Clear callbacks
-        this.eventCallbacks.clear();
-        // Mark as uninitialized
-        this.initialized = false;
+        this.dispose();
     }
 }