@arkade-os/sdk 0.4.17 → 0.4.19

package/README.md

@@ -878,9 +878,22 @@ const wallet = await Wallet.create({
 For React Native apps using Realm, pass your Realm instance directly:
 
 ```typescript
-import { RealmWalletRepository, RealmContractRepository, ArkRealmSchemas } from '@arkade-os/sdk/repositories/realm'
-
-const realm = await Realm.open({ schema: [...ArkRealmSchemas, ...yourSchemas] })
+import {
+  RealmWalletRepository,
+  RealmContractRepository,
+  ArkRealmSchemas,
+  ARK_REALM_SCHEMA_VERSION,
+  runArkRealmMigrations,
+} from '@arkade-os/sdk/repositories/realm'
+
+const realm = await Realm.open({
+  schema: [...ArkRealmSchemas, ...yourSchemas],
+  schemaVersion: Math.max(ARK_REALM_SCHEMA_VERSION, yourSchemaVersion),
+  onMigration: (oldRealm, newRealm) => {
+    runArkRealmMigrations(oldRealm, newRealm)
+    // your own migrations
+  },
+})
 const wallet = await Wallet.create({
   identity,
   arkServerUrl: 'https://arkade.computer',
@@ -1074,9 +1087,6 @@ const unsubscribe = await manager.onContractEvent((event) => {
     case 'vtxo_spent':
       console.log(`Spent virtual outputs from ${event.contractScript}`)
       break
-    case 'contract_expired':
-      console.log(`Contract ${event.contractScript} expired`)
-      break
   }
 })
 

package/dist/cjs/contracts/arkcontract.js

@@ -110,7 +110,6 @@ function contractFromArkContract(encoded, options = {}) {
         params,
         state: options.state || "active",
         createdAt: Date.now(),
-        expiresAt: options.expiresAt,
         metadata: options.metadata,
     };
 }
@@ -136,7 +135,6 @@ function contractFromArkContractWithAddress(encoded, serverPubKey, addressPrefix
         address: vtxoScript.address(addressPrefix, serverPubKey).encode(),
         state: options.state || "active",
         createdAt: Date.now(),
-        expiresAt: options.expiresAt,
         metadata: options.metadata,
     };
 }

package/dist/cjs/contracts/contractManager.js

@@ -14,7 +14,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
@@ -84,29 +84,16 @@ 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) => {
@@ -115,6 +102,23 @@ 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.
      *
@@ -159,15 +163,7 @@ 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 = (0, syncCursors_1.cursorCutoff)(requestStartedAt);
-        await (0, syncCursors_1.advanceSyncCursors)(this.config.walletRepository, {
-            [contract.script]: cutoff,
-        });
+        await this.fetchContractVxosFromIndexer([contract]);
         // Add to watcher
         await this.watcher.addContract(contract);
         return contract;
@@ -193,12 +189,26 @@ 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) => (0, utils_1.extendVirtualCoinForContract)(vtxo, byScript));
+    }
     buildContractsDbFilter(filter) {
         return {
             script: filter.script,
@@ -339,41 +349,18 @@ 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 (0, syncCursors_1.clearSyncCursors)(this.config.walletRepository, opts.scripts);
-            }
-            else {
-                await (0, syncCursors_1.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 = (0, syncCursors_1.cursorCutoff)(requestStartedAt);
-        const cursorUpdates = {};
-        for (const script of fetched.keys()) {
-            cursorUpdates[script] = cutoff;
-        }
-        if (Object.keys(cursorUpdates).length > 0) {
-            await (0, syncCursors_1.advanceSyncCursors)(this.config.walletRepository, cursorUpdates);
-        }
+        await this.syncContracts({
+            contracts,
+            window: { after: opts?.after, before: opts?.before },
+        });
     }
     /**
      * Check if currently watching.
@@ -402,94 +389,54 @@ 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 (0, syncCursors_1.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 (0, syncCursors_1.getSyncCursor)(this.config.walletRepository);
+        const window = options.window ?? (0, syncCursors_1.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 = (0, syncCursors_1.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 = (0, syncCursors_1.computeSyncWindow)(minCursor);
-            if (window) {
-                const requestStartedAt = Date.now();
-                const fetched = await this.fetchContractVxosFromIndexer(delta, true, pageSize, window);
-                const cutoff = (0, syncCursors_1.cursorCutoff)(requestStartedAt);
-                for (const [script, vtxos] of fetched) {
-                    result.set(script, vtxos);
-                    cursorUpdates[script] = cutoff;
-                }
-            }
-        }
-        if (Object.keys(cursorUpdates).length > 0) {
-            await (0, syncCursors_1.advanceSyncCursors)(this.config.walletRepository, cursorUpdates);
+            await (0, syncCursors_1.advanceSyncCursor)(this.config.walletRepository, cutoff);
         }
         return result;
     }
@@ -505,21 +452,20 @@ 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({
-                ...(0, utils_1.extendVtxoFromContract)(vtxo, contract),
+                ...vtxo,
                 contractScript: contract.script,
             });
         }
@@ -527,8 +473,8 @@ 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);
@@ -539,23 +485,17 @@ 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 && {
@@ -571,22 +511,20 @@ 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({
-                    ...(0, utils_1.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;
@@ -596,42 +534,6 @@ 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({
-                    ...(0, utils_1.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.
      *
@@ -660,13 +562,7 @@ class ContractManager {
      * ```
      */
     [Symbol.dispose]() {
-        // Stop watching
-        this.stopWatcherFn?.();
-        this.stopWatcherFn = undefined;
-        // Clear callbacks
-        this.eventCallbacks.clear();
-        // Mark as uninitialized
-        this.initialized = false;
+        this.dispose();
     }
 }
 exports.ContractManager = ContractManager;