@spirobel/monero-wallet-api 0.5.3 → 0.5.5

package/dist/scanning-syncing/scanresult/scanCacheOpened.js

@@ -1,4 +1,4 @@
-import { NodeUrl, signTransaction, ViewPair, } from "../../api";
+import { get_info, NodeUrl, signTransaction, ViewPair, } from "../../api";
 import { prepareInput, sumPayments, } from "../../send-functionality/inputSelection";
 import { createWebworker } from "../backgroundWorker";
 import { spendable } from "./scanResult";
@@ -37,11 +37,13 @@ export class ScanCacheOpened {
     /** sample sizes to try when decoyRetry is enabled, in order */
     decoyRetrySizes = [20, 50, 100, 200, 500];
     static async create(params) {
-        const theCatchToBeOpened = await readCacheFileDefaultLocation(params.primary_address, params.pathPrefix);
+        // same dir as workers / connection status: next to ScanSettings.json
+        const pathPrefix = getPathPrefix(params.scan_settings_path, params.pathPrefix);
+        const theCatchToBeOpened = await readCacheFileDefaultLocation(params.primary_address, pathPrefix);
         if (!params.primary_address)
             throw new Error(`primary_address is required, potentially half filled out wallet setting in: ${params.scan_settings_path || SCAN_SETTINGS_STORE_NAME_DEFAULT}`);
         // use ScanSettingsOpened instead of direct scanSettings calls
-        const scanSettings = await ScanSettingsOpened.create(params.scan_settings_path, params.pathPrefix);
+        const scanSettings = await ScanSettingsOpened.create(params.scan_settings_path, pathPrefix);
         const walletSettings = scanSettings.getWallet(params.primary_address);
         if (!walletSettings)
             throw new Error(`wallet not found in settings. did you call openwallet with the right params?
@@ -55,7 +57,7 @@ export class ScanCacheOpened {
         // read secret_view_key and secret_spend_key from env
         const walletSettingsWithKeys = await walletSettingsPlusKeys(walletWithSettings);
         // create viewpair + ScanCacheOpened instance
-        const scanCacheOpen = new ScanCacheOpened(scanSettings, await ViewPair.create(params.primary_address, walletSettingsWithKeys.secret_view_key, walletSettings.subaddress_index, scanSettings.node_url), walletSettings.wallet_route, walletSettings.wallet_name, walletSettings.wallet_slot, params.no_worker || false, params.masterCacheChanged || null, scanSettings.start_height, params.scan_settings_path, params.pathPrefix, params.workerError);
+        const scanCacheOpen = new ScanCacheOpened(scanSettings, await ViewPair.create(params.primary_address, walletSettingsWithKeys.secret_view_key, walletSettings.subaddress_index, scanSettings.node_url), walletSettings.wallet_route, walletSettings.wallet_name, walletSettings.wallet_slot, params.no_worker || false, params.masterCacheChanged || null, scanSettings.start_height, params.scan_settings_path, pathPrefix, params.workerError);
         if (theCatchToBeOpened)
             scanCacheOpen._cache = theCatchToBeOpened;
         if (!walletSettings.halted) {
@@ -66,7 +68,7 @@ export class ScanCacheOpened {
         scanCacheOpen._highest_subaddress_index =
             walletSettings.subaddress_index || SUB_ADDRESS_INDEX_DEFAULT_VALUE;
         if (!params.no_stats) {
-            scanCacheOpen._stats = await alignScanStatsWithCache(scanCacheOpen._cache, scanCacheOpen.view_pair, params.primary_address, getPathPrefix(params.scan_settings_path, params.pathPrefix), walletSettings.subaddress_index, lastRange(scanCacheOpen._cache.scanned_ranges)?.end);
+            scanCacheOpen._stats = await alignScanStatsWithCache(scanCacheOpen._cache, scanCacheOpen.view_pair, params.primary_address, pathPrefix, walletSettings.subaddress_index, lastRange(scanCacheOpen._cache.scanned_ranges)?.end);
         }
         else {
             scanCacheOpen._no_stats = params.no_stats; // true
@@ -83,8 +85,10 @@ export class ScanCacheOpened {
         return this._highest_subaddress_index;
     }
     get current_height() {
-        let current_range = findRange(this._cache.scanned_ranges, this._start_height || 0);
-        return current_range?.end || null;
+        // progress on the range that covers start_height (start can jump;
+        // lastRange would pick a different segment and be wrong)
+        const current_range = findRange(this._cache.scanned_ranges, this._start_height || 0);
+        return current_range == null ? null : current_range.end;
     }
     get current_top_range_height() {
         if (typeof this._stats === "undefined" || this._stats === null)
@@ -92,10 +96,7 @@ export class ScanCacheOpened {
         return this._stats.height;
     }
     async changeStartHeight(start_height) {
-        if (this.worker) {
-            this.worker.terminate();
-            delete this.worker;
-        }
+        await this.stopWorker();
         await this._scanSettings.setStartHeight(start_height);
         this._start_height = start_height;
         await this.unpause();
@@ -170,10 +171,7 @@ export class ScanCacheOpened {
         return this._scanSettings.logs_exclude;
     }
     async changeNodeUrlAndStartHeight(node_url, start_height) {
-        if (this.worker) {
-            this.worker.terminate();
-            delete this.worker;
-        }
+        await this.stopWorker();
         if (node_url !== undefined) {
             await this._scanSettings.setNodeUrl(node_url);
             this.node_url = node_url;
@@ -185,26 +183,21 @@ export class ScanCacheOpened {
         await this.unpause();
     }
     async changeNodeUrl(node_url) {
-        if (this.worker) {
-            this.worker.terminate();
-            delete this.worker;
-        }
+        await this.stopWorker();
         await this._scanSettings.setNodeUrl(node_url);
         this.node_url = node_url;
         await this.unpause();
     }
     async setMerchantConfirmations(merchant_confirmations) {
-        this.stopWorker();
         await this._scanSettings.setMerchantConfirmations(merchant_confirmations);
-        await this.unpause();
     }
     async setCpuWorkerCount(cpu_worker_count) {
-        this.stopWorker();
+        await this.stopWorker();
         await this._scanSettings.setCpuWorkerCount(cpu_worker_count);
         await this.unpause();
     }
     async setLogSettings(logs, logs_include, logs_exclude) {
-        this.stopWorker();
+        await this.stopWorker();
         await this._scanSettings.setLogSettings(logs, logs_include, logs_exclude);
         await this.unpause();
     }
@@ -212,10 +205,7 @@ export class ScanCacheOpened {
         await this._scanSettings.setWalletName(this.view_pair.primary_address, name);
     }
     async retry() {
-        if (this.worker) {
-            this.worker.terminate();
-            delete this.worker;
-        }
+        await this.stopWorker();
         //  scansettings  so external changes (e.g. from a sidebar frontend instance) are picked up
         await this._scanSettings.reload();
         const walletStillExists = this._scanSettings.walletExists(this.primary_address);
@@ -247,7 +237,7 @@ export class ScanCacheOpened {
         const feeFor10kb = feePerByte * 10000n;
         //2. check if fee is too high
         if (feeFor10kb > max_plausible_fee) {
-            throw new Error(`fee too high: 
+            throw new Error(`fee too high:
           ${feeFor10kb} (fee for 10kb tx size) > ${max_plausible_fee} (0.001 XMR)
           most likely your node is faulty. connect to another node.
            preferably run one yourself locally.`);
@@ -266,7 +256,7 @@ export class ScanCacheOpened {
             const feeFor10kb = feePerByte * 10000n;
             //2. check if fee is too high
             if (feeFor10kb > max_plausible_fee) {
-                throw new Error(`fee too high: 
+                throw new Error(`fee too high:
           ${feeFor10kb} (fee for 10kb tx size) > ${max_plausible_fee} (0.001 XMR)
           most likely your node is faulty. connect to another node.
            preferably run one yourself locally.`);
@@ -410,10 +400,7 @@ export class ScanCacheOpened {
             if (sendResult.status !== "OK")
                 throw new Error("send raw transaction rpc returned error");
             // before writing the scan cache, we stop the worker to avoid a race
-            if (this.worker) {
-                this.worker.terminate();
-                delete this.worker;
-            }
+            await this.stopWorker();
             // write txlog to cache + update pending_spent_utxos (affects stats + spendability)
             await writeCacheFileDefaultLocationThrows({
                 primary_address: this.primary_address,
@@ -457,10 +444,7 @@ export class ScanCacheOpened {
         }
         catch (e) {
             // before writing the scan cache, we stop the worker to avoid a race
-            if (this.worker) {
-                this.worker.terminate();
-                delete this.worker;
-            }
+            await this.stopWorker();
             // write txlog error to cache
             await writeCacheFileDefaultLocationThrows({
                 primary_address: this.primary_address,
@@ -570,43 +554,65 @@ export class ScanCacheOpened {
         };
     }
     async pause() {
-        if (this.worker)
-            this.worker.terminate();
+        await this.stopWorker();
         return await this._scanSettings.haltWallet(this.view_pair.primary_address);
     }
-    stopWorker() {
+    // debug: dump coordinator + cpu worker heaps while they are live
+    // in browser: use inspector directly, this is only useful for bun
+    async dumpWorkerHeaps(dir) {
+        if (!this.worker?.dumpHeaps)
+            return [];
+        return await this.worker.dumpHeaps(dir);
+    }
+    async stopWorker() {
         if (this.worker) {
-            this.worker.terminate();
+            const worker = this.worker;
+            // clear ref first so concurrent stop/retry cannot double shutdown
+            this.worker.cpuWorkers = [];
+            this.worker.fetchWorker = undefined;
             delete this.worker;
+            // drain coordinator first, then hard kill workers
+            try {
+                await worker.shutdown();
+            }
+            catch {
+                // still terminate below
+            }
+            try {
+                worker.terminate();
+            }
+            catch {
+            }
         }
     }
     async unpause() {
         // if worker does not exist yet, start it (if we are not slave / no_worker)
         if (!this.worker && !this.no_worker) {
-            this.worker = await createWebworker(async (params) => await this.feed(params), this.scan_settings_path, this.pathPrefix, (error) => {
-                const workerErrCB = this.workerError;
-                this.stopWorker();
-                readWriteConnectionStatusFile((cs) => {
-                    if (cs?.last_packet.status === "catastrophic_reorg")
-                        return;
-                    const connectionStatus = {
-                        ...cs,
-                        last_packet: {
-                            status: "connection_failed",
-                            bytes_read: 0,
-                            node_url: this.node_url,
-                            timestamp: new Date().toISOString(),
-                        },
-                    };
-                    return connectionStatus;
-                }, this.scan_settings_path).then(() => {
-                    if (workerErrCB)
-                        workerErrCB(error);
-                });
-            });
+            this.worker = await createWebworker(async (params) => await this.feed(params), this.scan_settings_path, this.pathPrefix, (params) => this._onWorkerError(params));
         }
         return await this._scanSettings.unhaltWallet(this.view_pair.primary_address);
     }
+    _onWorkerError = (error) => {
+        const workerErrCB = this.workerError;
+        this.stopWorker();
+        readWriteConnectionStatusFile((cs) => {
+            if (cs?.last_packet.status === "catastrophic_reorg")
+                return;
+            const connectionStatus = {
+                ...cs,
+                last_packet: {
+                    status: "connection_failed",
+                    bytes_read: 0,
+                    node_url: this.node_url,
+                    timestamp: new Date().toISOString(),
+                },
+            };
+            return connectionStatus;
+        }, this.scan_settings_path).then(() => {
+            if (workerErrCB)
+                workerErrCB(error);
+        });
+    };
     /**
      * selectInputs returns array of inputs, whose sum is larger than amount
      * adds approximate fee for 10kb transaction to amount if feePerByte is supplied
@@ -715,10 +721,17 @@ export class ManyScanCachesOpened {
             return null;
         return this.wallets[0]?.start_height;
     }
+    // overall scan tip = lagging non-halted wallet (this.wallets is already non-halted)
     get current_height() {
-        if (this.wallets.length === 0)
-            return null;
-        return this.wallets[0]?.current_height;
+        let min = null;
+        for (const w of this.wallets) {
+            const h = w.current_height;
+            if (h == null)
+                continue;
+            if (min == null || h < min)
+                min = h;
+        }
+        return min;
     }
     get node_url() {
         if (this.wallets.length === 0)
@@ -727,25 +740,32 @@ export class ManyScanCachesOpened {
     }
     async changeNodeUrlAndStartHeight(node_url, start_height) {
         if (this.wallets.length === 0)
-            throw new Error("no wallets");
+            return;
         const masterWallet = this.wallets[0];
         return await masterWallet.changeNodeUrlAndStartHeight(node_url, start_height);
     }
     async retry() {
         if (this.wallets.length === 0)
-            throw new Error("no wallets");
+            return;
         const masterWallet = this.wallets[0];
         return await masterWallet.retry();
     }
-    stopWorker() {
+    async stopWorker() {
         if (this.wallets.length === 0)
-            throw new Error("no wallets");
+            return;
         const masterWallet = this.wallets[0];
-        return masterWallet.stopWorker();
+        return await masterWallet.stopWorker();
+    }
+    // debug: dump live coordinator + cpu worker heaps via master wallet workers
+    // in browser: use inspector directly, this is only useful for bun
+    async dumpWorkerHeaps(dir) {
+        if (this.wallets.length === 0)
+            return [];
+        return await this.wallets[0].dumpWorkerHeaps(dir);
     }
     async changeNodeUrl(node_url) {
         if (this.wallets.length === 0)
-            throw new Error("no wallets");
+            return;
         const masterWallet = this.wallets[0];
         return await masterWallet.changeNodeUrl(node_url);
     }
@@ -760,19 +780,13 @@ export class ManyScanCachesOpened {
         return this.wallets[0]?.cpu_worker_count;
     }
     get logs() {
-        if (this.wallets.length === 0)
-            return undefined;
-        return this.wallets[0]?.logs;
+        return this._scanSettings.logs;
     }
     get logs_include() {
-        if (this.wallets.length === 0)
-            return undefined;
-        return this.wallets[0]?.logs_include;
+        return this._scanSettings.logs_include;
     }
     get logs_exclude() {
-        if (this.wallets.length === 0)
-            return undefined;
-        return this.wallets[0]?.logs_exclude;
+        return this._scanSettings.logs_exclude;
     }
     get connectionStatus() {
         return this.connectionStatusOpened.connectionStatus;
@@ -788,25 +802,26 @@ export class ManyScanCachesOpened {
     }
     async setMerchantConfirmations(merchant_confirmations) {
         if (this.wallets.length === 0)
-            throw new Error("no wallets");
+            return;
         return await this.wallets[0].setMerchantConfirmations(merchant_confirmations);
     }
     async setCpuWorkerCount(cpu_worker_count) {
         if (this.wallets.length === 0)
-            throw new Error("no wallets");
+            return;
         return await this.wallets[0].setCpuWorkerCount(cpu_worker_count);
     }
     async setLogSettings(logs, logs_include, logs_exclude) {
-        if (this.wallets.length === 0)
-            throw new Error("no wallets");
-        return await this.wallets[0].setLogSettings(logs, logs_include, logs_exclude);
+        return await this._scanSettings.setLogSettings(logs, logs_include, logs_exclude);
     }
     async setWalletName(primary_address, name) {
         await this._scanSettings.setWalletName(primary_address, name);
     }
+    async setWalletSlot(primary_address, slot) {
+        await this._scanSettings.setWalletSlot(primary_address, slot);
+    }
     async changeStartHeight(start_height) {
         if (this.wallets.length === 0)
-            throw new Error("no wallets");
+            return;
         const masterWallet = this.wallets[0];
         return await masterWallet.changeStartHeight(start_height);
     }
@@ -866,56 +881,122 @@ export class ManyScanCachesOpened {
     static async create(options) {
         const { scan_settings_path, pathPrefix, onConnectionStatusChange, connectionStatusIntervalMs, autoRetry, retryDelayMs, } = options;
         const scanSettingsOpened = await ScanSettingsOpened.create(scan_settings_path, pathPrefix);
-        if (!scanSettingsOpened.wallets || scanSettingsOpened.wallets.length === 0)
-            throw new Error(`no wallets in settings file. Did you supply the right path?
-     are there wallets in the default '${SCAN_SETTINGS_STORE_NAME_DEFAULT}' file?`);
+        // persist log options into ScanSettings.json before workers start
+        if (options.logs !== undefined ||
+            options.logs_include !== undefined ||
+            options.logs_exclude !== undefined) {
+            await scanSettingsOpened.setLogSettings(options.logs !== undefined ? options.logs : scanSettingsOpened.logs, options.logs_include !== undefined
+                ? options.logs_include
+                : scanSettingsOpened.logs_include, options.logs_exclude !== undefined
+                ? options.logs_exclude
+                : scanSettingsOpened.logs_exclude);
+        }
         // wrap workerError with auto-retry
         let retryTimer;
         let instance = null;
+        const retryFn = async () => {
+            // no wallets means idle, do not rebuild or restart workers
+            if (!instance || instance.wallets.length === 0) {
+                clearTimeout(retryTimer);
+                retryTimer = undefined;
+                return;
+            }
+            await instance.buildWallets();
+            // still empty after rebuild, stay idle
+            if (instance.wallets.length === 0) {
+                clearTimeout(retryTimer);
+                retryTimer = undefined;
+                return;
+            }
+            const node_url = instance.node_url;
+            if (!node_url)
+                throw new Error("No nodeurl set, can't retry connection");
+            const getinfo_result = await get_info(node_url)
+                .then((r) => {
+                r?.status === "OK";
+            })
+                .catch(() => false);
+            if (getinfo_result)
+                await instance?.retry();
+            clearTimeout(retryTimer);
+            retryTimer = undefined;
+        };
         const newOptions = { ...options };
+        let connectionFailedShown = false;
         if (autoRetry) {
             const originalError = options.workerError;
             newOptions.workerError = (err) => {
                 originalError?.(err);
-                if (!retryTimer) {
-                    retryTimer = setTimeout(() => {
-                        retryTimer = undefined;
-                        instance?.retry();
-                    }, retryDelayMs ?? 1000);
+                const msg = err instanceof Error ? err.message : String(err);
+                if (csOpened.connectionStatus?.last_packet?.status ===
+                    "catastrophic_reorg") {
+                    clearTimeout(retryTimer);
+                    instance?.stopWorker();
+                    throw new Error("catastrophic reorg, aborting ...");
+                }
+                if (msg.includes("connect") ||
+                    msg.includes("fetch") ||
+                    msg.includes("NetworkError")) {
+                    if (!connectionFailedShown) {
+                        connectionFailedShown = true;
+                        console.error("unable to connect to node ... retrying ...");
+                    }
+                }
+                // only schedule retry when we still have wallets to scan
+                if (!retryTimer && instance && instance.wallets.length > 0) {
+                    retryTimer = setTimeout(retryFn, retryDelayMs ?? 5000);
                 }
             };
         }
-        const wallets = await this._buildWallets(scanSettingsOpened, newOptions);
-        if (!wallets)
-            return undefined;
-        const csOpened = new ConnectionStatusOpened(scan_settings_path || SCAN_SETTINGS_STORE_NAME_DEFAULT, onConnectionStatusChange ?? null);
+        const wallets = (await this._buildWallets(scanSettingsOpened, newOptions)) ?? [];
+        const csOpened = new ConnectionStatusOpened(scan_settings_path || SCAN_SETTINGS_STORE_NAME_DEFAULT, autoRetry
+            ? (status) => {
+                if (status?.last_packet?.status === "OK" && connectionFailedShown) {
+                    connectionFailedShown = false;
+                    console.log("connection to node established");
+                }
+                if (onConnectionStatusChange)
+                    onConnectionStatusChange(status);
+            }
+            : (onConnectionStatusChange ?? null));
         csOpened.watch(connectionStatusIntervalMs);
         instance = new ManyScanCachesOpened(wallets, csOpened, scanSettingsOpened, newOptions);
         return instance;
     }
     async buildWallets() {
-        for (const w of this._wallets) {
-            w.stopWorker();
-        }
+        await this.stopWorker();
+        await this.reloadWalletsAfterStop();
+    }
+    // assumes stopWorker already ran (graceful shutdown + terminate)
+    async reloadWalletsAfterStop() {
         await this._scanSettings.reload();
+        // empty after reload: stay idle, do not open ScanCacheOpened or start workers
+        const remaining = this._scanSettings.wallets.filter((w) => !w?.halted);
+        if (remaining.length === 0) {
+            this._wallets = [];
+            return;
+        }
         const newWallets = await ManyScanCachesOpened._buildWallets(this._scanSettings, this._options);
-        if (!newWallets)
-            throw new Error("no non-halted wallets left after rebuild, use addViewWallet or addSpendWallet first");
-        this._wallets = newWallets;
+        this._wallets = newWallets ?? [];
     }
     async addViewWallet(primary_address, view_key, fields) {
+        await this.stopWorker();
         await this._scanSettings.addViewWallet(primary_address, view_key, fields);
-        await this.buildWallets();
+        await this.reloadWalletsAfterStop();
     }
     async addSpendWallet(wallet_secret, fields) {
+        await this.stopWorker();
         await this._scanSettings.addSpendWallet(wallet_secret, fields);
-        await this.buildWallets();
+        await this.reloadWalletsAfterStop();
     }
     async removeWallet(primary_address) {
+        await this.stopWorker();
         await this._scanSettings.removeWallet(primary_address);
-        await this.buildWallets();
+        await this.reloadWalletsAfterStop();
     }
     async feed(params) {
+        if (this.wallets.length === 0)
+            return;
         await this.wallets[0].feed(params);
     }
     _wallets = [];

package/dist/scanning-syncing/scanresult/scanCoordination.d.ts

@@ -45,26 +45,12 @@ export declare function makeWorkItemsForAllWallets(wallet_configs: WalletConfigP
  * blocks buffer if no remaining work items reference it.
  */
 export declare function reconcileWorkItemDone(blocksBuffer: GetBlocksBinBufferItem[], workItemBuffer: WorkItem[]): void;
-/**
- * one round of the select race. takes two primed promises (blocks, scan),
- * races them, returns winner info. the loser stays in flight.
- */
-export declare function raceStep(blocksPromise: Promise<IteratorResult<BlocksBufferLoopResult>>, scanPromise: Promise<IteratorResult<ScanLoopYield, void>>): Promise<{
-    src: "blocks" | "scan";
-    value: IteratorResult<BlocksBufferLoopResult> | IteratorResult<ScanLoopYield, void>;
-    done: boolean;
-}>;
 /**
  * handle a yield from the blocks buffer fetch loop.
  */
 export declare function handleBlocksYield(value: BlocksBufferLoopResult, scanSettingsPath?: string): Promise<{
     isBlocksBufferChanged: boolean;
 }>;
-/**
- * process a scan result for a completed work item.
- * updates the cache, writes to disk, marks work item done, reconciles.
- */
-export declare function processScanResultForWorkItem(value: ScanLoopYield, workBuffer: WorkItem[], blocksBuffer: GetBlocksBinBufferItem[], pathPrefix: string, secret_spend_key?: string): Promise<void>;
 /**
  * process a scan result for a completed work item.
  * updates the cache, writes to disk, marks work item done, reconciles blockbuffer with this.
@@ -78,7 +64,6 @@ export type CoordinatorEvent = {
 } | {
     type: "scan_ready";
     address: string;
-    result: ScanLoopYield;
     newCache: ScanCache;
     changed_outputs: {
         output: any;
@@ -86,19 +71,13 @@ export type CoordinatorEvent = {
     }[];
 } | {
     type: "all_idle";
+} | {
+    type: "shutdown_done";
 } | {
     type: "error";
     error: Error;
 };
-/**
- * coordinator main: async generator that drives the full scan cycle.
- * takes only scanSettingsPath, derives everything else internally.
- * yields events for some of the underlying generator events,
- * look at CoordinatorEvent, processing not decoupled from cpu bound scan work,
- * as this single threaded, there is no point
- */
-export declare function coordinatorMain(scanSettingsPath?: string, pathPrefix?: string): AsyncGenerator<CoordinatorEvent>;
-export declare function setupCoordinator(scanSettingsPath?: string, pathPrefix?: string): Promise<false | {
+export declare function setupCoordinator(scanSettingsPath?: string, pathPrefix?: string, stopSync?: AbortSignal): Promise<false | {
     blocksGenerator: AsyncGenerator<BlocksBufferLoopResult, any, any>;
     workBuffer: WorkItem[];
     blocksBuffer: GetBlocksBinBufferItem[];
@@ -118,10 +97,12 @@ export type BlocksBufferRacer = {
 };
 export type ScanLoopRacer = ScanLoopYield;
 export type Racers = BlocksBufferRacer | ScanLoopRacer;
+export declare function resetInProgressWorkItems(workBuffer: WorkItem[]): void;
+export declare function cancelBusyCpuPorts(ports: PortStatus[], timeoutMs?: number): Promise<void>;
 /**
  * coordinator main (multithreaded): dispatches scan work to CPU workers
  * via MessagePorts, processes results in order per wallet.
  * falls back to single-threaded coordinator if no cpuPorts provided.
  */
-export declare function coordinatorMainMultithreaded(scanSettingsPath?: string, pathPrefix?: string, cpuPorts?: MessagePort[]): AsyncGenerator<CoordinatorEvent>;
+export declare function coordinatorMainMultithreaded(scanSettingsPath?: string, pathPrefix?: string, cpuPorts?: MessagePort[], stopSync?: AbortSignal): AsyncGenerator<CoordinatorEvent>;
 export declare function scheduleWorkOnCpuPorts(ports: PortStatus[], work_buffer: WorkItem[]): Promise<void>;