@arkade-os/sdk 0.4.9 → 0.4.11

package/dist/cjs/contracts/contractManager.js

@@ -5,6 +5,8 @@ const base_1 = require("@scure/base");
 const contractWatcher_1 = require("./contractWatcher");
 const handlers_1 = require("./handlers");
 const utils_1 = require("../wallet/utils");
+const syncCursors_1 = require("../utils/syncCursors");
+const DEFAULT_PAGE_SIZE = 500;
 /**
  * Central manager for contract lifecycle and operations.
  *
@@ -74,10 +76,14 @@ 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) {
@@ -94,7 +100,9 @@ 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);
+            });
         });
     }
     /**
@@ -165,9 +173,9 @@ 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) ?? [],
@@ -307,12 +315,43 @@ 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 (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);
+        }
     }
     /**
      * Check if currently watching.
@@ -338,14 +377,13 @@ 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;
@@ -357,14 +395,100 @@ 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);
     }
-    async fetchContractVxosFromIndexer(contracts, includeSpent) {
-        const fetched = await this.fetchContractVtxosBulk(contracts, includeSpent);
+    /**
+     * 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 (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 (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 = (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);
+        }
+        return result;
+    }
+    /**
+     * 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({
+                ...(0, utils_1.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);
@@ -375,14 +499,14 @@ 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
@@ -391,14 +515,24 @@ 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,
             });
@@ -417,19 +551,31 @@ 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,
             });
@@ -441,6 +587,8 @@ class ContractManager {
             }
             hasMore = page ? vtxos.length === pageSize : false;
             pageIndex++;
+            if (hasMore)
+                await new Promise((r) => setTimeout(r, 500));
         }
         return allVtxos;
     }

package/dist/cjs/index.js

@@ -36,9 +36,9 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.VtxoTaprootTree = exports.VtxoTreeExpiry = exports.CosignerPublicKey = exports.getArkPsbtFields = exports.setArkPsbtField = exports.ArkPsbtFieldKeyType = exports.ArkPsbtFieldKey = exports.TapTreeCoder = exports.CLTVMultisigTapscript = exports.ConditionMultisigTapscript = exports.ConditionCSVMultisigTapscript = exports.CSVMultisigTapscript = exports.MultisigTapscript = exports.decodeTapscript = exports.ServiceWorkerReadonlyWallet = exports.ServiceWorkerWallet = exports.ServiceWorkerTimeoutError = exports.MessageBusNotInitializedError = exports.DelegatorNotConfiguredError = exports.ReadonlyWalletError = exports.WalletNotInitializedError = exports.WalletMessageHandler = exports.MessageBus = exports.setupServiceWorker = exports.SettlementEventType = exports.ChainTxType = exports.IndexerTxType = exports.TxType = exports.VHTLC = exports.VtxoScript = exports.DelegateVtxo = exports.DefaultVtxo = exports.ArkAddress = exports.RestIndexerProvider = exports.RestArkProvider = exports.EsploraProvider = exports.ESPLORA_URL = exports.RestDelegatorProvider = exports.DelegatorManagerImpl = exports.VtxoManager = exports.Ramps = exports.OnchainWallet = exports.ReadonlyDescriptorIdentity = exports.MnemonicIdentity = exports.SeedIdentity = exports.ReadonlySingleKey = exports.SingleKey = exports.ReadonlyWallet = exports.Wallet = exports.asset = void 0;
-exports.contractFromArkContractWithAddress = exports.contractFromArkContract = exports.decodeArkContract = exports.encodeArkContract = exports.VHTLCContractHandler = exports.DelegateContractHandler = exports.DefaultContractHandler = exports.contractHandlers = exports.ContractWatcher = exports.ContractManager = exports.getSequence = exports.isExpired = exports.isSubdust = exports.isSpendable = exports.isRecoverable = exports.buildForfeitTx = exports.validateConnectorsTxGraph = exports.validateVtxoTxGraph = exports.Batch = exports.maybeArkError = exports.ArkError = exports.Transaction = exports.Unroll = exports.P2A = exports.TxTree = exports.BIP322 = exports.Intent = exports.ContractRepositoryImpl = exports.WalletRepositoryImpl = exports.rollbackMigration = exports.getMigrationStatus = exports.requiresMigration = exports.migrateWalletRepository = exports.MIGRATION_KEY = exports.InMemoryContractRepository = exports.InMemoryWalletRepository = exports.IndexedDBContractRepository = exports.IndexedDBWalletRepository = exports.openDatabase = exports.closeDatabase = exports.networks = exports.ArkNote = exports.isValidArkAddress = exports.isVtxoExpiringSoon = exports.combineTapscriptSigs = exports.hasBoardingTxExpired = exports.waitForIncomingFunds = exports.verifyTapscriptSignatures = exports.buildOffchainTx = exports.ConditionWitness = void 0;
-exports.isArkContract = void 0;
+exports.VtxoTreeExpiry = exports.CosignerPublicKey = exports.getArkPsbtFields = exports.setArkPsbtField = exports.ArkPsbtFieldKeyType = exports.ArkPsbtFieldKey = exports.TapTreeCoder = exports.CLTVMultisigTapscript = exports.ConditionMultisigTapscript = exports.ConditionCSVMultisigTapscript = exports.CSVMultisigTapscript = exports.MultisigTapscript = exports.decodeTapscript = exports.ServiceWorkerReadonlyWallet = exports.ServiceWorkerWallet = exports.ServiceWorkerTimeoutError = exports.MessageBusNotInitializedError = exports.MESSAGE_BUS_NOT_INITIALIZED = exports.DelegatorNotConfiguredError = exports.ReadonlyWalletError = exports.WalletNotInitializedError = exports.WalletMessageHandler = exports.MessageBus = exports.setupServiceWorker = exports.SettlementEventType = exports.ChainTxType = exports.IndexerTxType = exports.TxType = exports.VHTLC = exports.VtxoScript = exports.DelegateVtxo = exports.DefaultVtxo = exports.ArkAddress = exports.RestIndexerProvider = exports.RestArkProvider = exports.EsploraProvider = exports.ESPLORA_URL = exports.RestDelegatorProvider = exports.DelegatorManagerImpl = exports.VtxoManager = exports.Ramps = exports.OnchainWallet = exports.ReadonlyDescriptorIdentity = exports.MnemonicIdentity = exports.SeedIdentity = exports.ReadonlySingleKey = exports.SingleKey = exports.ReadonlyWallet = exports.Wallet = exports.asset = void 0;
+exports.contractFromArkContract = exports.decodeArkContract = exports.encodeArkContract = exports.VHTLCContractHandler = exports.DelegateContractHandler = exports.DefaultContractHandler = exports.contractHandlers = exports.ContractWatcher = exports.ContractManager = exports.getSequence = exports.isExpired = exports.isSubdust = exports.isSpendable = exports.isRecoverable = exports.buildForfeitTx = exports.validateConnectorsTxGraph = exports.validateVtxoTxGraph = exports.Batch = exports.maybeArkError = exports.ArkError = exports.Transaction = exports.Unroll = exports.P2A = exports.TxTree = exports.BIP322 = exports.Intent = exports.ContractRepositoryImpl = exports.WalletRepositoryImpl = exports.rollbackMigration = exports.getMigrationStatus = exports.requiresMigration = exports.migrateWalletRepository = exports.MIGRATION_KEY = exports.InMemoryContractRepository = exports.InMemoryWalletRepository = exports.IndexedDBContractRepository = exports.IndexedDBWalletRepository = exports.openDatabase = exports.closeDatabase = exports.networks = exports.ArkNote = exports.isValidArkAddress = exports.isVtxoExpiringSoon = exports.combineTapscriptSigs = exports.hasBoardingTxExpired = exports.waitForIncomingFunds = exports.verifyTapscriptSignatures = exports.buildOffchainTx = exports.ConditionWitness = exports.VtxoTaprootTree = void 0;
+exports.isArkContract = exports.contractFromArkContractWithAddress = void 0;
 const transaction_1 = require("./utils/transaction");
 Object.defineProperty(exports, "Transaction", { enumerable: true, get: function () { return transaction_1.Transaction; } });
 const singleKey_1 = require("./identity/singleKey");
@@ -180,5 +180,6 @@ Object.defineProperty(exports, "WalletNotInitializedError", { enumerable: true,
 Object.defineProperty(exports, "ReadonlyWalletError", { enumerable: true, get: function () { return wallet_message_handler_1.ReadonlyWalletError; } });
 Object.defineProperty(exports, "DelegatorNotConfiguredError", { enumerable: true, get: function () { return wallet_message_handler_1.DelegatorNotConfiguredError; } });
 const errors_2 = require("./worker/errors");
+Object.defineProperty(exports, "MESSAGE_BUS_NOT_INITIALIZED", { enumerable: true, get: function () { return errors_2.MESSAGE_BUS_NOT_INITIALIZED; } });
 Object.defineProperty(exports, "MessageBusNotInitializedError", { enumerable: true, get: function () { return errors_2.MessageBusNotInitializedError; } });
 Object.defineProperty(exports, "ServiceWorkerTimeoutError", { enumerable: true, get: function () { return errors_2.ServiceWorkerTimeoutError; } });

package/dist/cjs/providers/indexer.js

@@ -254,23 +254,40 @@ 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}`);
             });
@@ -282,6 +299,12 @@ 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/cjs/utils/arkTransaction.js

@@ -15,6 +15,7 @@ const anchor_1 = require("./anchor");
 const unknownFields_1 = require("./unknownFields");
 const transaction_1 = require("./transaction");
 const address_1 = require("../script/address");
+const extension_1 = require("../extension");
 /**
  * Builds an offchain transaction with checkpoint transactions.
  *
@@ -28,16 +29,26 @@ const address_1 = require("../script/address");
  * @returns Object containing the virtual transaction and checkpoint transactions
  */
 function buildOffchainTx(inputs, outputs, serverUnrollScript) {
-    let hasOpReturn = false;
+    // TODO: use arkd /info
+    const MAX_OP_RETURN = 2;
+    let countOpReturn = 0;
+    let hasExtensionOutput = false;
     for (const [index, output] of outputs.entries()) {
         if (!output.script)
             throw new Error(`missing output script ${index}`);
-        const isOpReturn = btc_signer_1.Script.decode(output.script)[0] === "RETURN";
-        if (!isOpReturn)
+        const isExtension = extension_1.Extension.isExtension(output.script);
+        const isOpReturn = isExtension || btc_signer_1.Script.decode(output.script)[0] === "RETURN";
+        if (isOpReturn) {
+            countOpReturn++;
+        }
+        if (!isExtension)
             continue;
-        if (hasOpReturn)
-            throw new Error("multiple OP_RETURN outputs");
-        hasOpReturn = true;
+        if (hasExtensionOutput)
+            throw new Error("multiple extension outputs");
+        hasExtensionOutput = true;
+    }
+    if (countOpReturn > MAX_OP_RETURN) {
+        throw new Error(`too many OP_RETURN outputs: ${countOpReturn} > ${MAX_OP_RETURN}`);
     }
     const checkpoints = inputs.map((input) => buildCheckpointTx(input, serverUnrollScript));
     const arkTx = buildVirtualTx(checkpoints.map((c) => c.input), outputs);

package/dist/cjs/utils/syncCursors.js

@@ -0,0 +1,136 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OVERLAP_MS = exports.SAFETY_LAG_MS = void 0;
+exports.updateWalletState = updateWalletState;
+exports.getSyncCursor = getSyncCursor;
+exports.getAllSyncCursors = getAllSyncCursors;
+exports.advanceSyncCursor = advanceSyncCursor;
+exports.advanceSyncCursors = advanceSyncCursors;
+exports.clearSyncCursors = clearSyncCursors;
+exports.computeSyncWindow = computeSyncWindow;
+exports.cursorCutoff = cursorCutoff;
+/** Lag behind real-time to avoid racing with indexer writes. */
+exports.SAFETY_LAG_MS = 30000;
+/** Overlap window so boundary VTXOs are never missed. */
+exports.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.
+ */
+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).
+ */
+async function getSyncCursor(repo, script) {
+    const state = await repo.getWalletState();
+    return state?.settings?.vtxoSyncCursors?.[script];
+}
+/**
+ * Read cursors for every previously-synced script.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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}).
+ */
+function computeSyncWindow(cursor) {
+    if (cursor === undefined)
+        return undefined;
+    const after = Math.max(0, cursor - exports.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.
+ */
+function cursorCutoff(requestStartedAt) {
+    return (requestStartedAt ?? Date.now()) - exports.SAFETY_LAG_MS;
+}

package/dist/cjs/wallet/delegator.js

@@ -25,10 +25,13 @@ class DelegatorManagerImpl {
             return { delegated: [], failed: [] };
         }
         const destinationScript = __1.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 }] };
@@ -55,7 +58,7 @@ 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 {
@@ -72,7 +75,7 @@ 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()) {
@@ -95,7 +98,7 @@ exports.DelegatorManagerImpl = 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");
     }
@@ -121,7 +124,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 __1.Estimator({
         ...fees.intentFee,
@@ -145,7 +148,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) {