@spirobel/monero-wallet-api 0.5.4 → 0.5.5

package/dist/io/sleep.d.ts

@@ -1 +1 @@
-export declare const sleep: (ms: number) => Promise<unknown>;
+export declare const sleep: (ms: number, signal?: AbortSignal) => Promise<void>;

package/dist/io/sleep.js

@@ -1 +1,16 @@
-export const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+export const sleep = (ms, signal) => new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+        reject(signal.reason ?? new DOMException("aborted", "AbortError"));
+        return;
+    }
+    const onAbort = () => {
+        clearTimeout(timer);
+        signal?.removeEventListener("abort", onAbort);
+        reject(signal?.reason ?? new DOMException("aborted", "AbortError"));
+    };
+    const timer = setTimeout(() => {
+        signal?.removeEventListener("abort", onAbort);
+        resolve();
+    }, ms);
+    signal?.addEventListener("abort", onAbort, { once: true });
+});

package/dist/scanning-syncing/backgroundWorker.d.ts

@@ -3,7 +3,9 @@ export declare const CPU_POOL_SIZE = 4;
 export type WorkerSet = {
     fetchWorker: Worker;
     cpuWorkers: Worker[];
+    shutdown: (timeoutMs?: number) => Promise<void>;
     terminate: () => void;
+    dumpHeaps: (dir?: string) => Promise<string[]>;
 };
 export declare function createWebworker(handle_result?: (result: CacheChangedCallbackParameters) => void, scan_settings_path?: string, pathPrefix?: string, handle_error?: (error: unknown) => void): Promise<WorkerSet | undefined>;
 export declare function makeWebworkerScript(): string;

package/dist/scanning-syncing/backgroundWorker.js

@@ -46,6 +46,36 @@ export async function createWebworker(handle_result, scan_settings_path, pathPre
             "coordinator worker started, node_url=" + node_url,
             ", cpuPorts=" + cpuPorts.length,
         ]);
+        let shutdownResolve;
+        let shuttingDown = false;
+        const hardTerminate = () => {
+            for (const p of cpuPorts) {
+                try {
+                    p.close();
+                }
+                catch {
+                    // port may already be closed
+                }
+            }
+            coordinationWorker.onmessage = null;
+            coordinationWorker.onerror = null;
+            for (const w of cpuWorkers) {
+                w.onerror = null;
+                w.onmessage = null;
+                try {
+                    w.terminate();
+                }
+                catch {
+                    // already dead
+                }
+            }
+            try {
+                coordinationWorker.terminate();
+            }
+            catch {
+                // already dead
+            }
+        };
         coordinationWorker.onmessage = (event) => {
             if (event.data.type === "ERROR") {
                 if (handle_error)
@@ -55,22 +85,74 @@ export async function createWebworker(handle_result, scan_settings_path, pathPre
                 if (handle_result)
                     handle_result(event.data.payload);
             }
+            else if (event.data.type === "SHUTDOWN_DONE") {
+                log("createWebworker", ["SHUTDOWN_DONE received"]);
+                shutdownResolve?.();
+                shutdownResolve = undefined;
+            }
         };
+        // wait for one HEAP_SNAPSHOT_DONE / ERROR from a worker
+        const waitHeap = (w, path, timeoutMs = 15000) => new Promise((resolve, reject) => {
+            const t = setTimeout(() => {
+                w.removeEventListener("message", onMsg);
+                reject(new Error("heap snapshot timeout: " + path));
+            }, timeoutMs);
+            const onMsg = (event) => {
+                if (event.data?.type === "HEAP_SNAPSHOT_DONE") {
+                    clearTimeout(t);
+                    w.removeEventListener("message", onMsg);
+                    resolve(event.data.path || path);
+                }
+                else if (event.data?.type === "HEAP_SNAPSHOT_ERROR") {
+                    clearTimeout(t);
+                    w.removeEventListener("message", onMsg);
+                    reject(new Error(String(event.data.error || "heap snapshot failed")));
+                }
+            };
+            w.addEventListener("message", onMsg);
+            try {
+                w.postMessage({ type: "heap_snapshot", path });
+            }
+            catch (err) {
+                clearTimeout(t);
+                w.removeEventListener("message", onMsg);
+                reject(err);
+            }
+        });
         return {
             fetchWorker: coordinationWorker,
             cpuWorkers,
-            terminate: () => {
-                for (const p of cpuPorts) {
-                    p.close();
+            // graceful only: abort fetch, cancel cpus, wait. does not terminate.
+            shutdown: async (timeoutMs = 5000) => {
+                if (shuttingDown)
+                    return;
+                shuttingDown = true;
+                log("createWebworker", ["shutdown start, timeoutMs=", timeoutMs]);
+                const done = new Promise((resolve) => {
+                    shutdownResolve = resolve;
+                });
+                try {
+                    coordinationWorker.postMessage({ type: "shutdown" });
                 }
-                coordinationWorker.onmessage = null;
-                coordinationWorker.onerror = null;
-                for (const w of cpuWorkers) {
-                    w.onerror = null;
-                    w.onmessage = null;
-                    w.terminate();
+                catch (err) {
+                    log("createWebworker", ["post shutdown failed", String(err)]);
+                    return;
                 }
-                coordinationWorker.terminate();
+                await Promise.race([done, sleep(timeoutMs)]);
+            },
+            terminate: () => {
+                hardTerminate();
+            },
+            dumpHeaps: async (dir = ".") => {
+                const stamp = Date.now();
+                const paths = [];
+                const coordPath = `${dir}/coordinator-${stamp}.heapsnapshot`;
+                paths.push(await waitHeap(coordinationWorker, coordPath));
+                for (let i = 0; i < cpuWorkers.length; i++) {
+                    const p = `${dir}/cpubound-${i}-${stamp}.heapsnapshot`;
+                    paths.push(await waitHeap(cpuWorkers[i], p));
+                }
+                return paths;
             },
         };
     }

package/dist/scanning-syncing/blocksbuffer/blocksBufferFetchLoop.js

@@ -27,6 +27,10 @@ max_blocks_buffer_size = MAX_BLOCKS_BUFFER_SIZE, anchor_range, stopSync) {
     };
     yield connection_status.last_packet;
     while (true) {
+        if (stopSync?.aborted) {
+            log("blocksBufferFetchLoop", ["aborted, exiting fetch loop"]);
+            return;
+        }
         // avoid overwriting last_packet in case of catastrophic reorg
         // this generator will block on this. coordinator should rethrow the CatastrophicReorgError
         if (connection_status.last_packet.status === "catastrophic_reorg") {
@@ -39,9 +43,17 @@ max_blocks_buffer_size = MAX_BLOCKS_BUFFER_SIZE, anchor_range, stopSync) {
                 bytes_read: 0,
                 node_url: node_url,
                 timestamp: new Date().toISOString(),
+                daemon_height: connection_status.sync.daemon_height ||
+                    connection_status.last_packet.daemon_height,
             };
             yield connection_status.last_packet;
-            await sleep(5000);
+            try {
+                await sleep(1000, stopSync);
+            }
+            catch {
+                log("blocksBufferFetchLoop", ["aborted during buffer-full sleep"]);
+                return;
+            }
             continue;
         }
         log("blocksBufferFetchLoop", [
@@ -56,11 +68,18 @@ max_blocks_buffer_size = MAX_BLOCKS_BUFFER_SIZE, anchor_range, stopSync) {
             get_blocks_bin = await doRPCrequest(nodeUrl, current_range, stopSync);
         }
         catch (error) {
+            // abort is intentional shutdown, not a connection failure
+            if (stopSync?.aborted || isAbortError(error)) {
+                log("blocksBufferFetchLoop", ["aborted during rpc request"]);
+                return;
+            }
             connection_status.last_packet = {
                 status: "connection_failed",
                 bytes_read: 0,
                 node_url,
                 timestamp: new Date().toISOString(),
+                daemon_height: connection_status.sync.daemon_height ||
+                    connection_status.last_packet.daemon_height,
             };
             yield connection_status.last_packet;
             throw error;
@@ -78,7 +97,13 @@ max_blocks_buffer_size = MAX_BLOCKS_BUFFER_SIZE, anchor_range, stopSync) {
         yield connection_status.last_packet;
         // no new blocks: at tip, sleep and retry
         if (!result_meta.block_infos.length) {
-            await sleep(1000);
+            try {
+                await sleep(1000, stopSync);
+            }
+            catch {
+                log("blocksBufferFetchLoop", ["aborted during tip sleep"]);
+                return;
+            }
             continue;
         }
         const bufferItem = makeBlocksBufferItem(result_meta, get_blocks_bin);
@@ -379,3 +404,9 @@ export async function reduceStartHeightToTip(start_height, node_url) {
 export class CatastrophicReorgError extends Error {
     name = "CatastrophicReorgError";
 }
+function isAbortError(error) {
+    if (!error || typeof error !== "object")
+        return false;
+    const name = error.name;
+    return name === "AbortError" || name === "DOMException";
+}

package/dist/scanning-syncing/connectionStatus.d.ts

@@ -19,6 +19,12 @@ export type ConnectionStatus = {
     last_packet: ConnectionSatusLastPacket;
     sync: ConnectionStatusSync;
 };
+export declare function applyWalletScanProgress(cs: ConnectionStatus, progress: {
+    current_scan_height: number;
+    scanned_ranges?: CacheRange[];
+    daemon_height?: number;
+    eta?: string;
+}): void;
 export declare const DEFAULT_CONNECTION_STATUS_PREFIX = "ConnectionStatus-";
 export declare function msToHHMM(ms: number): string;
 export declare function emptyConnectionStatus(overrides?: Partial<ConnectionStatus>): ConnectionStatus;

package/dist/scanning-syncing/connectionStatus.js

@@ -1,5 +1,20 @@
 import { atomicWrite, } from "../api";
 import { SCAN_SETTINGS_STORE_NAME_DEFAULT } from "../api";
+// wallet progress write: always set scan fields; only replace eta when a new one is provided
+// so a missing eta does not wipe / flicker the previous value.
+export function applyWalletScanProgress(cs, progress) {
+    cs.sync.current_scan_height = progress.current_scan_height;
+    if (progress.scanned_ranges) {
+        cs.sync.scanned_ranges = progress.scanned_ranges;
+    }
+    if (typeof progress.daemon_height === "number") {
+        cs.sync.daemon_height = progress.daemon_height;
+    }
+    if (progress.eta !== undefined) {
+        cs.sync.eta = progress.eta;
+    }
+    cs.sync.timestamp = new Date().toISOString();
+}
 export const DEFAULT_CONNECTION_STATUS_PREFIX = "ConnectionStatus-";
 export function msToHHMM(ms) {
     const totalSeconds = Math.floor(ms / 1000);

package/dist/scanning-syncing/connectionStatusOpened.d.ts

@@ -4,6 +4,7 @@ export declare class ConnectionStatusOpened {
     private _timer;
     private _cached;
     private _prevConnected;
+    private _prevSyncKey;
     private _path;
     constructor(scan_settings_path: string, _onChange?: ((status: ConnectionStatus | null) => void) | null | undefined);
     watch(intervalMs?: number): Promise<void>;
@@ -11,5 +12,6 @@ export declare class ConnectionStatusOpened {
     get connectionStatus(): ConnectionStatus | null;
     get isConnected(): boolean;
     get daemonHeight(): number | undefined;
+    private _syncKey;
     private _poll;
 }

package/dist/scanning-syncing/connectionStatusOpened.js

@@ -4,6 +4,8 @@ export class ConnectionStatusOpened {
     _timer;
     _cached = null;
     _prevConnected = false;
+    // notify when sync progress fields change, not only connect flip
+    _prevSyncKey = "";
     _path;
     constructor(scan_settings_path, _onChange) {
         this._onChange = _onChange;
@@ -37,14 +39,29 @@ export class ConnectionStatusOpened {
         return age >= 0 && age <= 10_000;
     }
     get daemonHeight() {
-        return this._cached?.last_packet?.daemon_height;
+        return this._cached?.sync?.daemon_height;
+    }
+    _syncKey(cs) {
+        const s = cs?.sync;
+        if (!s)
+            return "";
+        return [
+            s.daemon_height ?? "",
+            s.current_scan_height ?? "",
+            s.eta ?? "",
+            s.timestamp ?? "",
+        ].join("|");
     }
     async _poll() {
         this._cached =
             (await readConnectionStatusFile(this._path).catch(() => null)) || null;
         const now = this.isConnected;
-        if (now !== this._prevConnected) {
-            this._prevConnected = now;
+        const syncKey = this._syncKey(this._cached);
+        const connectedChanged = now !== this._prevConnected;
+        const syncChanged = syncKey !== this._prevSyncKey;
+        this._prevConnected = now;
+        this._prevSyncKey = syncKey;
+        if (connectedChanged || syncChanged) {
             this._onChange?.(this._cached);
         }
     }

package/dist/scanning-syncing/openWallet.d.ts

@@ -7,9 +7,12 @@ import { ManyScanCachesOpened, ScanCacheOpened, type ManyScanCachesOpenedCreateO
  * @param options.no_worker to feed the ManyScanCachesOpened manually with .feed(params) from CacheChangedCallbackParams
  * @param options.no_stats to disable creation of stats file with aggregated information e.g. amount per wallet / subaddress
  * @param options.notifyMasterChanged pass the output of this to another (no_worker) instance to feed
+ * @param options.logs "console" | "file" | "console-and-file" | "off"
+ * @param options.logs_include function names to include (e.g. handleCpuboundScan, blocksBufferFetchLoop)
+ * @param options.logs_exclude function names to exclude
  * @returns Promise<ManyScanCachesOpened>
  */
-export declare function openWallets(options?: ManyScanCachesOpenedCreateOptions): Promise<ManyScanCachesOpened | undefined>;
+export declare function openWallets(options?: ManyScanCachesOpenedCreateOptions): Promise<ManyScanCachesOpened>;
 /**
  * Opens a **single wallet** for scanning.
  * **Touches ScanSettings.json**,

package/dist/scanning-syncing/openWallet.js

@@ -8,6 +8,9 @@ import { openScanSettingsFile, writeWalletToScanSettings } from "../api";
  * @param options.no_worker to feed the ManyScanCachesOpened manually with .feed(params) from CacheChangedCallbackParams
  * @param options.no_stats to disable creation of stats file with aggregated information e.g. amount per wallet / subaddress
  * @param options.notifyMasterChanged pass the output of this to another (no_worker) instance to feed
+ * @param options.logs "console" | "file" | "console-and-file" | "off"
+ * @param options.logs_include function names to include (e.g. handleCpuboundScan, blocksBufferFetchLoop)
+ * @param options.logs_exclude function names to exclude
  * @returns Promise<ManyScanCachesOpened>
  */
 export async function openWallets(options) {

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

@@ -129,7 +129,8 @@ export declare class ScanCacheOpened {
         remove: () => null;
     };
     pause(): Promise<void>;
-    stopWorker(): void;
+    dumpWorkerHeaps(dir?: string): Promise<string[]>;
+    stopWorker(): Promise<void>;
     unpause(): Promise<void>;
     private _onWorkerError;
     /**
@@ -178,6 +179,9 @@ export type ManyScanCachesOpenedCreateOptions = {
     retryDelayMs?: number;
     connectionStatusIntervalMs?: number;
     onConnectionStatusChange?: ((status: ConnectionStatus | null) => void) | null;
+    logs?: LogSetting;
+    logs_include?: PossibleLogs[];
+    logs_exclude?: PossibleLogs[];
 };
 export declare class ManyScanCachesOpened {
     readonly connectionStatusOpened: ConnectionStatusOpened;
@@ -187,8 +191,9 @@ export declare class ManyScanCachesOpened {
     get current_height(): number | null;
     get node_url(): string;
     changeNodeUrlAndStartHeight(node_url?: string, start_height?: number | null): Promise<void>;
-    retry(): Promise<boolean>;
-    stopWorker(): void;
+    retry(): Promise<boolean | undefined>;
+    stopWorker(): Promise<void>;
+    dumpWorkerHeaps(dir?: string): Promise<string[]>;
     changeNodeUrl(node_url: string): Promise<void>;
     get merchant_confirmations(): number | null | undefined;
     get cpu_worker_count(): number | undefined;
@@ -206,8 +211,9 @@ export declare class ManyScanCachesOpened {
     setWalletSlot(primary_address: string, slot?: number): Promise<void>;
     changeStartHeight(start_height: number | null): Promise<void>;
     private static _buildWallets;
-    static create(options: ManyScanCachesOpenedCreateOptions): Promise<ManyScanCachesOpened | undefined>;
+    static create(options: ManyScanCachesOpenedCreateOptions): Promise<ManyScanCachesOpened>;
     buildWallets(): Promise<void>;
+    private reloadWalletsAfterStop;
     addViewWallet(primary_address: string, view_key: string, fields?: {
         wallet_name?: string;
         wallet_slot?: number;