@spirobel/monero-wallet-api 0.5.1 → 0.5.3

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

@@ -1,12 +1,15 @@
-import { atomicWrite, NodeUrl, signTransaction, ViewPair, } from "../../api";
+import { NodeUrl, signTransaction, ViewPair, } from "../../api";
 import { prepareInput, sumPayments, } from "../../send-functionality/inputSelection";
 import { createWebworker } from "../backgroundWorker";
 import { spendable } from "./scanResult";
-import { getPathPrefix, openScanSettingsFile, readPrivateSpendKeyFromEnv, readWalletFromScanSettings, SCAN_SETTINGS_STORE_NAME_DEFAULT, SUB_ADDRESS_INDEX_DEFAULT_VALUE, walletSettingsPlusKeys, writeNodeUrlToScanSettings, writeStartHeightToScanSettings, writeWalletToScanSettings, } from "../scanSettings";
+import { getPathPrefix, readPrivateSpendKeyFromEnv, SCAN_SETTINGS_STORE_NAME_DEFAULT, SUB_ADDRESS_INDEX_DEFAULT_VALUE, walletSettingsPlusKeys, } from "../../api";
+import { ScanSettingsOpened } from "../../scansettings/scanSettingsOpened";
+import { ConnectionStatusOpened } from "../connectionStatusOpened";
 import { findRange, lastRange, readCacheFileDefaultLocation, writeCacheFileDefaultLocationThrows, } from "./scanCache";
 import { alignScanStatsWithCache, isSelfSpent, processTxlogInputs, processTxlogPayments, writeStatsFileDefaultLocation, } from "./scanStats";
-import { updateSyncETA, readWriteConnectionStatusFile, } from "../connectionStatus";
+import { readWriteConnectionStatusFile, } from "../connectionStatus";
 export class ScanCacheOpened {
+    _scanSettings;
     view_pair;
     wallet_route;
     wallet_name;
@@ -35,17 +38,24 @@ export class ScanCacheOpened {
     decoyRetrySizes = [20, 50, 100, 200, 500];
     static async create(params) {
         const theCatchToBeOpened = await readCacheFileDefaultLocation(params.primary_address, params.pathPrefix);
-        const walletSettings = await readWalletFromScanSettings(params.primary_address, params.scan_settings_path);
+        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 walletSettings = scanSettings.getWallet(params.primary_address);
         if (!walletSettings)
             throw new Error(`wallet not found in settings. did you call openwallet with the right params?
       Either wrong file name supplied to params.scan_settings_path: ${params.scan_settings_path}
       Or wrong primary_address supplied params.primary_address: ${params.primary_address}`);
-        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}`);
+        const walletWithSettings = {
+            ...walletSettings,
+            node_url: scanSettings.node_url,
+            start_height: scanSettings.start_height,
+        };
         // read secret_view_key and secret_spend_key from env
-        const walletSettingsWithKeys = await walletSettingsPlusKeys(walletSettings);
+        const walletSettingsWithKeys = await walletSettingsPlusKeys(walletWithSettings);
         // create viewpair + ScanCacheOpened instance
-        const scanCacheOpen = new ScanCacheOpened(await ViewPair.create(params.primary_address, walletSettingsWithKeys.secret_view_key, walletSettings.subaddress_index, walletSettings.node_url), walletSettings.wallet_route, walletSettings.wallet_name, walletSettings.wallet_slot, params.no_worker || false, params.masterCacheChanged || null, walletSettings.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, params.pathPrefix, params.workerError);
         if (theCatchToBeOpened)
             scanCacheOpen._cache = theCatchToBeOpened;
         if (!walletSettings.halted) {
@@ -86,7 +96,7 @@ export class ScanCacheOpened {
             this.worker.terminate();
             delete this.worker;
         }
-        await writeStartHeightToScanSettings(start_height, this.scan_settings_path);
+        await this._scanSettings.setStartHeight(start_height);
         this._start_height = start_height;
         await this.unpause();
     }
@@ -144,17 +154,32 @@ export class ScanCacheOpened {
     set node_url(nu) {
         this.view_pair.node_url = nu;
     }
+    get merchant_confirmations() {
+        return this._scanSettings.merchant_confirmations;
+    }
+    get cpu_worker_count() {
+        return this._scanSettings.cpu_worker_count;
+    }
+    get logs() {
+        return this._scanSettings.logs;
+    }
+    get logs_include() {
+        return this._scanSettings.logs_include;
+    }
+    get logs_exclude() {
+        return this._scanSettings.logs_exclude;
+    }
     async changeNodeUrlAndStartHeight(node_url, start_height) {
         if (this.worker) {
             this.worker.terminate();
             delete this.worker;
         }
         if (node_url !== undefined) {
-            await writeNodeUrlToScanSettings(node_url, this.scan_settings_path);
+            await this._scanSettings.setNodeUrl(node_url);
             this.node_url = node_url;
         }
         if (start_height !== undefined) {
-            await writeStartHeightToScanSettings(start_height, this.scan_settings_path);
+            await this._scanSettings.setStartHeight(start_height);
             this._start_height = start_height;
         }
         await this.unpause();
@@ -164,17 +189,37 @@ export class ScanCacheOpened {
             this.worker.terminate();
             delete this.worker;
         }
-        await writeNodeUrlToScanSettings(node_url, this.scan_settings_path);
+        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._scanSettings.setCpuWorkerCount(cpu_worker_count);
+        await this.unpause();
+    }
+    async setLogSettings(logs, logs_include, logs_exclude) {
+        this.stopWorker();
+        await this._scanSettings.setLogSettings(logs, logs_include, logs_exclude);
+        await this.unpause();
+    }
+    async setWalletName(name) {
+        await this._scanSettings.setWalletName(this.view_pair.primary_address, name);
+    }
     async retry() {
         if (this.worker) {
             this.worker.terminate();
             delete this.worker;
         }
-        const scan_settings = await readWalletFromScanSettings(this.primary_address, this.scan_settings_path).catch(() => false);
-        if (scan_settings) {
+        //  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);
+        if (walletStillExists) {
             // if there is no scan settings file,
             // the retry loop is stopped.
             // the wallet reset happens through deleting all the scan setting + cache files
@@ -182,7 +227,7 @@ export class ScanCacheOpened {
             //TODO ? write connection status retry
             await this.unpause();
         }
-        return scan_settings ? true : false;
+        return walletStillExists;
     }
     async sendTransaction(signedTx) {
         const node = await NodeUrl.create(this.node_url);
@@ -480,7 +525,9 @@ export class ScanCacheOpened {
      * @returns Adressstring
      */
     async makeSubaddress() {
-        const walletSettings = await readWalletFromScanSettings(this.view_pair.primary_address, this.scan_settings_path);
+        // reload scansettings so external changes (e.g. from a sidebar frontend instance) are picked up
+        await this._scanSettings.reload();
+        const walletSettings = this._scanSettings.getWallet(this.view_pair.primary_address);
         if (!walletSettings)
             throw new Error(`wallet not found in settings. did you call openwallet with the right params?
       Either wrong file name supplied to params.scan_settings_path: ${this.scan_settings_path}
@@ -489,11 +536,7 @@ export class ScanCacheOpened {
         const minor = last_subaddress_index + 1;
         const subaddress = this.view_pair.makeSubaddress(minor);
         this._highest_subaddress_index = minor;
-        await writeWalletToScanSettings({
-            primary_address: this.view_pair.primary_address,
-            subaddress_index: minor,
-            scan_settings_path: this.scan_settings_path,
-        });
+        await this._scanSettings.setSubaddressIndex(this.view_pair.primary_address, minor);
         const created_at_height = lastRange(this._cache.scanned_ranges)?.end || 0;
         const created_at_timestamp = new Date().getTime();
         const new_subaddress = {
@@ -529,11 +572,7 @@ export class ScanCacheOpened {
     async pause() {
         if (this.worker)
             this.worker.terminate();
-        return await writeWalletToScanSettings({
-            primary_address: this.view_pair.primary_address,
-            halted: true,
-            scan_settings_path: this.scan_settings_path,
-        });
+        return await this._scanSettings.haltWallet(this.view_pair.primary_address);
     }
     stopWorker() {
         if (this.worker) {
@@ -566,11 +605,7 @@ export class ScanCacheOpened {
                 });
             });
         }
-        return await writeWalletToScanSettings({
-            primary_address: this.view_pair.primary_address,
-            halted: false,
-            scan_settings_path: this.scan_settings_path,
-        });
+        return await this._scanSettings.unhaltWallet(this.view_pair.primary_address);
     }
     /**
      * selectInputs returns array of inputs, whose sum is larger than amount
@@ -635,11 +670,6 @@ export class ScanCacheOpened {
         this._cache = params.newCache;
         if (!this._no_stats)
             this._stats = await alignScanStatsWithCache(this._cache, this.view_pair, this.primary_address, getPathPrefix(this.scan_settings_path, this.pathPrefix), this.subaddress_index, lastRange(this._cache.scanned_ranges)?.end);
-        if (!this.no_worker) {
-            const etaResult = await updateSyncETA(this._cache.daemon_height, this.current_height || 0, this.last_eta_height, this.last_eta_timestamp, this.scan_settings_path);
-            this.last_eta_height = etaResult.last_height;
-            this.last_eta_timestamp = etaResult.last_timestamp;
-        }
         for (const listener of this.notifyListeners) {
             if (listener)
                 listener(params);
@@ -660,7 +690,8 @@ export class ScanCacheOpened {
     worker = undefined;
     last_eta_height = null;
     last_eta_timestamp = null;
-    constructor(view_pair, wallet_route, wallet_name, wallet_slot, no_worker, masterCacheChanged, _start_height, scan_settings_path, pathPrefix, workerError) {
+    constructor(_scanSettings, view_pair, wallet_route, wallet_name, wallet_slot, no_worker, masterCacheChanged, _start_height, scan_settings_path, pathPrefix, workerError) {
+        this._scanSettings = _scanSettings;
         this.view_pair = view_pair;
         this.wallet_route = wallet_route;
         this.wallet_name = wallet_name;
@@ -676,7 +707,9 @@ export class ScanCacheOpened {
     notifyListeners = [];
 }
 export class ManyScanCachesOpened {
-    wallets;
+    connectionStatusOpened;
+    _scanSettings;
+    _options;
     get start_height() {
         if (this.wallets.length === 0)
             return null;
@@ -716,18 +749,70 @@ export class ManyScanCachesOpened {
         const masterWallet = this.wallets[0];
         return await masterWallet.changeNodeUrl(node_url);
     }
+    get merchant_confirmations() {
+        if (this.wallets.length === 0)
+            return undefined;
+        return this.wallets[0]?.merchant_confirmations;
+    }
+    get cpu_worker_count() {
+        if (this.wallets.length === 0)
+            return undefined;
+        return this.wallets[0]?.cpu_worker_count;
+    }
+    get logs() {
+        if (this.wallets.length === 0)
+            return undefined;
+        return this.wallets[0]?.logs;
+    }
+    get logs_include() {
+        if (this.wallets.length === 0)
+            return undefined;
+        return this.wallets[0]?.logs_include;
+    }
+    get logs_exclude() {
+        if (this.wallets.length === 0)
+            return undefined;
+        return this.wallets[0]?.logs_exclude;
+    }
+    get connectionStatus() {
+        return this.connectionStatusOpened.connectionStatus;
+    }
+    get daemonHeight() {
+        return this.connectionStatusOpened.daemonHeight;
+    }
+    watchConnectionStatus(intervalMs) {
+        this.connectionStatusOpened.watch(intervalMs);
+    }
+    unwatchConnectionStatus() {
+        this.connectionStatusOpened.unwatch();
+    }
+    async setMerchantConfirmations(merchant_confirmations) {
+        if (this.wallets.length === 0)
+            throw new Error("no wallets");
+        return await this.wallets[0].setMerchantConfirmations(merchant_confirmations);
+    }
+    async setCpuWorkerCount(cpu_worker_count) {
+        if (this.wallets.length === 0)
+            throw new Error("no wallets");
+        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);
+    }
+    async setWalletName(primary_address, name) {
+        await this._scanSettings.setWalletName(primary_address, name);
+    }
     async changeStartHeight(start_height) {
         if (this.wallets.length === 0)
             throw new Error("no wallets");
         const masterWallet = this.wallets[0];
         return await masterWallet.changeStartHeight(start_height);
     }
-    static async create({ scan_settings_path, pathPrefix, no_worker, notifyMasterChanged, no_stats, workerError, }) {
-        const scan_settings = await openScanSettingsFile(scan_settings_path);
-        if (!scan_settings?.wallets)
-            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?`);
-        const nonHaltedWallets = scan_settings.wallets.filter((wallet) => !wallet?.halted);
+    static async _buildWallets(scanSettingsOpened, options) {
+        const { scan_settings_path, pathPrefix, no_worker, no_stats, workerError, notifyMasterChanged, } = options;
+        const nonHaltedWallets = scanSettingsOpened.wallets.filter((wallet) => !wallet?.halted);
         if (!nonHaltedWallets.length)
             return undefined;
         const openedWallets = [];
@@ -776,15 +861,71 @@ export class ManyScanCachesOpened {
             });
             openedWallets.push(onlyWallet);
         }
-        return new ManyScanCachesOpened(openedWallets);
+        return openedWallets;
+    }
+    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?`);
+        // wrap workerError with auto-retry
+        let retryTimer;
+        let instance = null;
+        const newOptions = { ...options };
+        if (autoRetry) {
+            const originalError = options.workerError;
+            newOptions.workerError = (err) => {
+                originalError?.(err);
+                if (!retryTimer) {
+                    retryTimer = setTimeout(() => {
+                        retryTimer = undefined;
+                        instance?.retry();
+                    }, retryDelayMs ?? 1000);
+                }
+            };
+        }
+        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);
+        csOpened.watch(connectionStatusIntervalMs);
+        instance = new ManyScanCachesOpened(wallets, csOpened, scanSettingsOpened, newOptions);
+        return instance;
+    }
+    async buildWallets() {
+        for (const w of this._wallets) {
+            w.stopWorker();
+        }
+        await this._scanSettings.reload();
+        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;
+    }
+    async addViewWallet(primary_address, view_key, fields) {
+        await this._scanSettings.addViewWallet(primary_address, view_key, fields);
+        await this.buildWallets();
+    }
+    async addSpendWallet(wallet_secret, fields) {
+        await this._scanSettings.addSpendWallet(wallet_secret, fields);
+        await this.buildWallets();
+    }
+    async removeWallet(primary_address) {
+        await this._scanSettings.removeWallet(primary_address);
+        await this.buildWallets();
     }
-    /**
-     * feed the master wallet and therefore all wallets
-     */
     async feed(params) {
         await this.wallets[0].feed(params);
     }
-    constructor(wallets) {
-        this.wallets = wallets;
+    _wallets = [];
+    get wallets() {
+        return this._wallets;
+    }
+    constructor(wallets, connectionStatusOpened, _scanSettings, _options) {
+        this.connectionStatusOpened = connectionStatusOpened;
+        this._scanSettings = _scanSettings;
+        this._options = _options;
+        this._wallets = wallets;
     }
 }

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

@@ -1,7 +1,7 @@
 import { type GetBlocksBinBufferItem, type BlocksBufferLoopResult, type BlocksBufferIteratorResult, type ProcessScanResult, type BlockInfo } from "../../api";
 import { type ScanLoopYield } from "./scanLoop";
 import { type WorkItem } from "./scanLoop";
-import { type ScanSettings } from "../scanSettings";
+import { type ScanSettings } from "../../api";
 import { type CacheRange, type ScanCache } from "./scanCache";
 export type WalletConfig = {
     primary_address: string;

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

@@ -1,7 +1,7 @@
-import { setupBlocksBufferGenerator, ViewPair, handleConnectionStatusChanges, processScanResult, writeCacheToFile, sleep, findTipIndex, } from "../../api";
+import { setupBlocksBufferGenerator, ViewPair, handleConnectionStatusChanges, processScanResult, writeCacheToFile, sleep, findTipIndex, readWriteConnectionStatusFile, connectionStatusFilePath, } from "../../api";
 import { markWorkItemAsDone, } from "./scanLoop";
 import { makeWorkItem, scanLoop } from "./scanLoop";
-import { cullTooLargeScanHeight, getNonHaltedWallets, getPathPrefix, openScanSettingsFile, SCAN_SETTINGS_STORE_NAME_DEFAULT, walletSettingsPlusKeys, } from "../scanSettings";
+import { cullTooLargeScanHeight, getNonHaltedWallets, getPathPrefix, openScanSettingsFile, SCAN_SETTINGS_STORE_NAME_DEFAULT, walletSettingsPlusKeys, } from "../../api";
 import { findRange, initScanCacheFile, lastRange, makeCacheRangeForHeight, mergeRanges, } from "./scanCache";
 import { sendToCpuWorker } from "../worker-mains/cpubound-main";
 import { log } from "../../io/logging";
@@ -299,6 +299,30 @@ function logBufStatus(blocksBuffer, workBuffer, ports, label) {
         `[buf] ${label} blocks=[${bb.join(",")}] work=[${wb.join(",")}]`,
     ]);
 }
+function msToHHMM(ms) {
+    if (!Number.isFinite(ms) || ms < 0)
+        return "00:00";
+    const totalSeconds = Math.floor(ms / 1000);
+    const minutes = Math.floor(totalSeconds / 60);
+    const hours = Math.floor(minutes / 60);
+    const remainingMinutes = minutes % 60;
+    return `${String(hours).padStart(2, "0")}:${String(remainingMinutes).padStart(2, "0")}`;
+}
+function computeETA(cache, totalBlocksScanned, scanStartTime) {
+    const scanProgress = lastRange(cache.scanned_ranges)?.end || 0;
+    const elapsed = Date.now() - scanStartTime;
+    const daemonHeight = cache.daemon_height;
+    if (totalBlocksScanned <= 0 || elapsed <= 0 || daemonHeight <= 0)
+        return undefined;
+    const remaining = daemonHeight - scanProgress;
+    if (remaining <= 0)
+        return "00:00";
+    const blocksPerMs = totalBlocksScanned / elapsed;
+    if (blocksPerMs <= 0)
+        return undefined;
+    const etaMs = remaining / blocksPerMs;
+    return msToHHMM(etaMs);
+}
 /**
  * coordinator main: async generator that drives the full scan cycle.
  * takes only scanSettingsPath, derives everything else internally.
@@ -314,6 +338,8 @@ export async function* coordinatorMain(scanSettingsPath, pathPrefix) {
     const blocksBuffer = ctx.blocksBuffer;
     const workBuffer = ctx.workBuffer;
     const blocksGenerator = ctx.blocksGenerator;
+    let totalBlocksScanned = 0;
+    let scanStartTime = Date.now();
     let blocksPromise = blocksGenerator.next();
     const scanGens = new Map();
     const scanPromises = new Map();
@@ -379,7 +405,25 @@ export async function* coordinatorMain(scanSettingsPath, pathPrefix) {
                 const wc = work_to_be_done.wallet_configs.find((x) => x.primary_address === addr);
                 if (!wc)
                     throw new Error("[coordinatorMain] wallet config not found on process result");
+                // count blocks scanned in this work item for ETA
+                const doneItem = workBuffer.find((x) => x.work_uuid === value.work_uuid);
+                const blockCount = doneItem ? doneItem.to - doneItem.from + 1 : 0;
                 await processScanResultForWorkItem(value, workBuffer, blocksBuffer, getPathPrefix(scanSettingsPath, pathPrefix), wc?.secret_spend_key);
+                totalBlocksScanned += blockCount;
+                const eta = computeETA(wc.cache, totalBlocksScanned, scanStartTime);
+                // write connection status sync (includes eta)
+                if (eta) {
+                    await readWriteConnectionStatusFile((cs) => {
+                        cs.sync = {
+                            ...cs.sync,
+                            scanned_ranges: wc.cache.scanned_ranges,
+                            daemon_height: wc.cache.daemon_height,
+                            current_scan_height: lastRange(wc.cache.scanned_ranges)?.end || 0,
+                            eta,
+                            timestamp: new Date().toISOString(),
+                        };
+                    }, scanSettingsPath);
+                }
                 const nextItem = workBuffer.find((x) => x.status !== "process_result_done" &&
                     x.walletConfig.primary_address === addr);
                 if (nextItem) {
@@ -452,6 +496,8 @@ export async function* coordinatorMainMultithreaded(scanSettingsPath, pathPrefix
     const blocksBuffer = ctx.blocksBuffer;
     const workBuffer = ctx.workBuffer;
     const blocksGenerator = ctx.blocksGenerator;
+    let totalBlocksScanned = 0;
+    let scanStartTime = Date.now();
     let blocksPromise = blocksGenerator.next();
     const freePorts = [];
     for (const port of cpuPorts) {
@@ -510,6 +556,22 @@ export async function* coordinatorMainMultithreaded(scanSettingsPath, pathPrefix
             const to_be_processed = processable[0];
             if (!to_be_processed)
                 continue;
+            const blockCount = to_be_processed.to - to_be_processed.from + 1;
+            totalBlocksScanned += blockCount;
+            const eta = computeETA(wallet.cache, totalBlocksScanned, scanStartTime);
+            // write connection status sync (includes eta)
+            if (eta) {
+                await readWriteConnectionStatusFile((cs) => {
+                    cs.sync = {
+                        ...cs.sync,
+                        scanned_ranges: wallet.cache.scanned_ranges,
+                        daemon_height: wallet.cache.daemon_height,
+                        current_scan_height: lastRange(wallet.cache.scanned_ranges)?.end || 0,
+                        eta,
+                        timestamp: new Date().toISOString(),
+                    };
+                }, scanSettingsPath);
+            }
             const res = await processWorkItem(to_be_processed, workBuffer, blocksBuffer, getPathPrefix(scanSettingsPath, pathPrefix), wallet.secret_spend_key);
             //  log("coordinatorMainMultithreaded", "processWorkItem result");
             yield {

package/dist/scanning-syncing/scansettings/scanSettings.d.ts

@@ -0,0 +1,165 @@
+import type { LogSetting, PossibleLogs } from "../../io/logging";
+export declare const SCAN_SETTINGS_STORE_NAME_DEFAULT = "ScanSettings.json";
+export declare const SUB_ADDRESS_INDEX_DEFAULT_VALUE = 1;
+export type ScanSetting = {
+    primary_address: string;
+    subaddress_index?: number;
+    halted?: boolean;
+    wallet_route?: string;
+    wallet_name?: string;
+    wallet_slot?: number;
+};
+export type WriteScanSettingParams = {
+    primary_address: string;
+    start_height?: number | null;
+    subaddress_index?: number;
+    halted?: boolean;
+    scan_settings_path?: string;
+    node_url?: string;
+    wallet_route?: string;
+    wallet_name?: string;
+    wallet_slot?: number;
+    logs?: LogSetting;
+    logs_include?: PossibleLogs[];
+    logs_exclude?: PossibleLogs[];
+};
+export type ScanSettingOpened = {
+    primary_address: string;
+    start_height: number | null;
+    node_url: string;
+    subaddress_index?: number;
+    secret_view_key?: string;
+    halted?: boolean;
+    secret_spend_key?: string;
+    wallet_route?: string;
+    wallet_name?: string;
+    wallet_slot?: number;
+};
+export type ScanSettings = {
+    wallets: ScanSetting[];
+    node_url: string;
+    start_height: number | null;
+    merchant_confirmations?: number | null;
+    cpu_worker_count?: number;
+    logs?: LogSetting;
+    logs_include?: PossibleLogs[];
+    logs_exclude?: PossibleLogs[];
+};
+export type ScanSettingsOpened = {
+    wallets: (ScanSettingOpened | undefined)[];
+    node_url: string;
+    start_height: number | null;
+    merchant_confirmations?: number | null;
+    cpu_worker_count?: number;
+    logs?: LogSetting;
+    logs_include?: PossibleLogs[];
+    logs_exclude?: PossibleLogs[];
+};
+/**
+ * Writes scan settings to the default or specified storage file in json.
+ *
+ * @example
+ * ```
+ * const settings: ScanSettings = {
+ *   wallets: [{
+ *     primary_address: "5dsf...",
+ *     start_height: 1741707,
+ *   }],
+ *   node_urls: ["https://monerooo.roooo"]
+ * };
+ * await writeScanSettings(settings);
+ * ```
+ *
+ * @param scan_settings - The complete {@link ScanSettings} configuration to persist.
+ * @param scan_settings_path - Optional path for the settings file. Defaults to `SCAN_SETTINGS_STORE_NAME_DEFAULT`.
+ * @returns A promise that resolves when the file is successfully written.
+ * @throws Will throw if file writing fails (e.g., permissions, disk space).
+ */
+export declare function writeScanSettings(scan_settings: ScanSettings, scan_settings_path?: string): Promise<number>;
+export type WriteScanSettingsFileParams = {
+    scan_settings_path?: string;
+    writeCallback: (settings: ScanSettings) => void | Promise<void>;
+};
+export declare function writeScanSettingsFileDefaultLocation(params: WriteScanSettingsFileParams): Promise<void>;
+export declare function writeStartHeightToScanSettings(start_height: number | null, scan_settings_path?: string): Promise<number>;
+export declare function writeDaemonHeightAsStartHeightToScanSettings(node_url: string, scan_settings_path?: string): Promise<number>;
+export declare function cullTooLargeScanHeight(node_url: string, scan_settings_path?: string): Promise<number>;
+export declare function writeNodeUrlToScanSettings(node_url: string, scan_settings_path?: string): Promise<number>;
+export declare function readNodeUrlFromScanSettings(scan_settings_path?: string): Promise<string | undefined>;
+/**
+ * Writes the merchant confirmation threshold to scan settings.
+ *
+ * This setting only has effect when the wallet is run as part of a checkout system,
+ * that accepts payments.
+ * It determines after how many confirmations a transaction is accepted
+ * for a payment. The actual enforcement of this policy is left to the
+ * custom payment-system code that consumes this library.
+ *
+ * @param merchant_confirmations - Number of confirmations required before
+ *   accepting a payment, or `null` to leave it unset.
+ * @param scan_settings_path - Optional path for the settings file.
+ *   Defaults to `SCAN_SETTINGS_STORE_NAME_DEFAULT`.
+ * @returns A promise that resolves when the file is successfully written.
+ */
+export declare function writeMerchantConfirmationsToScanSettings(merchant_confirmations: number | null, scan_settings_path?: string): Promise<number>;
+/**
+ * Reads the merchant confirmation threshold from scan settings.
+ *
+ * This setting only has effect when the wallet is run as part of a checkout system,
+ * that accepts payments.
+ *
+ * It determines after how many confirmations a transaction is accepted
+ * for a payment. The actual enforcement of this policy is left to the
+ * custom payment-system code that consumes this library.
+ *
+ * @param scan_settings_path - Optional path for the settings file.
+ *   Defaults to `SCAN_SETTINGS_STORE_NAME_DEFAULT`.
+ * @returns The configured number of confirmations, null, or `undefined`
+ *   if the setting has not been persisted yet.
+ */
+export declare function readMerchantConfirmationsFromScanSettings(scan_settings_path?: string): Promise<number | null | undefined>;
+/**
+ * Reads scan settings from the default or specified storage file.
+ * secret_view_key and spend_private_key are read from environment variables
+ *
+ * @example
+ * ```
+ * const settings = await readScanSettings();
+ * if (settings) {
+ *   console.log(settings.wallets?.primary_address);
+ * }
+ * ```
+ *
+ * @param scan_settings_path - Path to the settings file. Defaults to `SCAN_SETTINGS_STORE_NAME_DEFAULT`.
+ * @returns The parsed {@link ScanSettings} object if file exists and is valid JSON, otherwise `undefined`.
+ */
+export declare function readScanSettings(scan_settings_path?: string): Promise<ScanSettingsOpened | undefined>;
+export declare function readPrivateSpendKeyFromEnv(primary_address: string): string | undefined;
+export declare function readPrivateViewKeyFromEnv(primary_address: string): string | undefined;
+export declare function readWalletFromScanSettings(primary_address: string, scan_settings_path?: string): Promise<ScanSettingOpened | undefined>;
+export declare function readWalletsFromScanSettings(scan_settings_path?: string): Promise<ScanSettingOpened[]>;
+export declare function walletSettingsPlusKeys(wallet_settings: ScanSettingOpened, secret_view_key?: string, secret_spend_key?: string): Promise<{
+    secret_view_key: string;
+    secret_spend_key: string | undefined;
+    primary_address: string;
+    start_height: number | null;
+    node_url: string;
+    subaddress_index?: number;
+    halted?: boolean;
+    wallet_route?: string;
+    wallet_name?: string;
+    wallet_slot?: number;
+}>;
+export declare function writeWalletToScanSettings(params: WriteScanSettingParams): Promise<number>;
+export declare function openScanSettingsFile(scan_settings_path?: string): Promise<ScanSettings | undefined>;
+export declare function openNonHaltedWallets(scan_settings_path?: string): Promise<ScanSettingOpened[]>;
+export declare function getNonHaltedWallets(scan_settings?: ScanSettings): ScanSetting[];
+export declare function doesScanSettingsFileExist(scan_settings_path?: string): Promise<boolean>;
+/**
+ * Either 1. the consumer explicitly sets a pathprefix, we extract it from the scan_settings_path
+ * or we pick the default which is nothing
+ * @param scan_settings_path optional scan settings path
+ * @param pathPrefix optional path prefix
+ * @returns definite path prefix
+ */
+export declare function getPathPrefix(scan_settings_path?: string, pathPrefix?: string): string;