@spirobel/monero-wallet-api 0.4.0 → 0.4.1

package/dist/io/atomicWrite.js

@@ -1,5 +1,6 @@
+import { log } from "./logging";
 export async function atomicWrite(targetPath, data) {
-    //console.log("[atomicWrite] writing to", targetPath);
+    log("atomicWrite", ["writing to", targetPath]);
     // in the browser we don't have rename + indexedDB writes are atomic in any case
     if (areWeInTheBrowser)
         return await Bun.write(targetPath, data);

package/dist/io/logging.d.ts

@@ -0,0 +1,40 @@
+/**
+ * logging function names registry.
+ *
+ * useful filter combinations for `scanSettings.json`:
+ *
+ *   "logs": "console",
+ *   "logs_include": ["handleCpuboundScan", "logBufStatus"]
+ *     -> cpu worker progress + buffer/work status.
+ *
+ *   "logs_include": ["coordinatorMainMultithreaded", "scheduleWorkOnCpuPorts", "workToBeDoneForBatch"]
+ *     -> coordinator events: race count, work dispatch, batch decisions.
+ *
+ *   "logs_include": ["blocksBufferFetchLoop", "makeWorkItemsFromBlocksBuffer", "logBufStatus"]
+ *     -> block fetching, reconciliation, buffer state.
+ *
+ *   "logs_include": ["processScanResult", "processWorkItem", "processScanResultForWorkItem"]
+ *     -> result processing, cache updates, reorg detection.
+ *
+ *   "logs_include": ["handleConnectionStatusChanges", "handleScanError"]
+ *     -> connection events and scan errors.
+ *
+ *   "logs": "off"   disables all logging.
+ *   "logs": "file"  writes to `<coordinator|cpubound|mainthread>-<id>-<timestamp>.log`.
+ *   "logs": "console-and-file"  writes to file and console.
+ */
+export declare const LOGGING_FUNCTIONS: readonly ["findWorkToBeDone", "workToBeDoneForBatch", "makeWorkItemsFromBlocksBuffer", "reconcileWorkItemDone", "processScanResultForWorkItem", "processWorkItem", "logBufStatus", "coordinatorMain", "coordinatorMainMultithreaded", "scheduleWorkOnCpuPorts", "processScanResult", "handleScanError", "createWebworker", "startWebworker", "blocksBufferFetchLoop", "reduceStartHeightToTip", "handleConnectionStatusChanges", "handleCpuboundScan", "coordinatorMainWorker", "CPU_PORT_HANDLER", "atomicWrite"];
+export type PossibleLogs = (typeof LOGGING_FUNCTIONS)[number];
+export type LogSetting = "console" | "file" | "console-and-file" | "off";
+export type FileLogMessage = {
+    timestamp: string;
+    message: any;
+};
+export declare function setupLoggingPath(scan_settings_path: string, path_prefix: string, role: "coordinator" | "cpubound" | "mainthread", cpu_worker_id?: number): Promise<{
+    logs: LogSetting | undefined;
+    logs_include: ("findWorkToBeDone" | "workToBeDoneForBatch" | "makeWorkItemsFromBlocksBuffer" | "reconcileWorkItemDone" | "processScanResultForWorkItem" | "processWorkItem" | "logBufStatus" | "coordinatorMain" | "coordinatorMainMultithreaded" | "scheduleWorkOnCpuPorts" | "processScanResult" | "handleScanError" | "createWebworker" | "startWebworker" | "blocksBufferFetchLoop" | "reduceStartHeightToTip" | "handleConnectionStatusChanges" | "handleCpuboundScan" | "coordinatorMainWorker" | "CPU_PORT_HANDLER" | "atomicWrite")[] | undefined;
+    logs_exclude: ("findWorkToBeDone" | "workToBeDoneForBatch" | "makeWorkItemsFromBlocksBuffer" | "reconcileWorkItemDone" | "processScanResultForWorkItem" | "processWorkItem" | "logBufStatus" | "coordinatorMain" | "coordinatorMainMultithreaded" | "scheduleWorkOnCpuPorts" | "processScanResult" | "handleScanError" | "createWebworker" | "startWebworker" | "blocksBufferFetchLoop" | "reduceStartHeightToTip" | "handleConnectionStatusChanges" | "handleCpuboundScan" | "coordinatorMainWorker" | "CPU_PORT_HANDLER" | "atomicWrite")[] | undefined;
+    file_logbuffer: FileLogMessage[];
+    global_logging_path: string;
+}>;
+export declare function log(fnname: string, message: any): void;

package/dist/io/logging.js

@@ -0,0 +1,172 @@
+import { getPathPrefix, openScanSettingsFile } from "../api";
+import { atomicWrite } from "./atomicWrite";
+/**
+ * logging function names registry.
+ *
+ * useful filter combinations for `scanSettings.json`:
+ *
+ *   "logs": "console",
+ *   "logs_include": ["handleCpuboundScan", "logBufStatus"]
+ *     -> cpu worker progress + buffer/work status.
+ *
+ *   "logs_include": ["coordinatorMainMultithreaded", "scheduleWorkOnCpuPorts", "workToBeDoneForBatch"]
+ *     -> coordinator events: race count, work dispatch, batch decisions.
+ *
+ *   "logs_include": ["blocksBufferFetchLoop", "makeWorkItemsFromBlocksBuffer", "logBufStatus"]
+ *     -> block fetching, reconciliation, buffer state.
+ *
+ *   "logs_include": ["processScanResult", "processWorkItem", "processScanResultForWorkItem"]
+ *     -> result processing, cache updates, reorg detection.
+ *
+ *   "logs_include": ["handleConnectionStatusChanges", "handleScanError"]
+ *     -> connection events and scan errors.
+ *
+ *   "logs": "off"   disables all logging.
+ *   "logs": "file"  writes to `<coordinator|cpubound|mainthread>-<id>-<timestamp>.log`.
+ *   "logs": "console-and-file"  writes to file and console.
+ */
+export const LOGGING_FUNCTIONS = [
+    // scanCoordination.ts
+    "findWorkToBeDone",
+    "workToBeDoneForBatch",
+    "makeWorkItemsFromBlocksBuffer",
+    "reconcileWorkItemDone",
+    "processScanResultForWorkItem",
+    "processWorkItem",
+    "logBufStatus",
+    "coordinatorMain",
+    "coordinatorMainMultithreaded",
+    "scheduleWorkOnCpuPorts",
+    // scanResult.ts
+    "processScanResult",
+    // scanCache.ts
+    "handleScanError",
+    // backgroundWorker.ts
+    "createWebworker",
+    "startWebworker",
+    // blocksBufferFetchLoop.ts
+    "blocksBufferFetchLoop",
+    "reduceStartHeightToTip",
+    // blocksbufferCoordination.ts
+    "handleConnectionStatusChanges",
+    // cpubound-main.ts
+    "handleCpuboundScan",
+    // coordinator-main.ts
+    "coordinatorMainWorker",
+    // worker.ts
+    "CPU_PORT_HANDLER",
+    // io/atomicWrite.ts
+    "atomicWrite",
+];
+export async function setupLoggingPath(scan_settings_path, path_prefix, role, cpu_worker_id) {
+    const scanSettings = await openScanSettingsFile(scan_settings_path);
+    const logs = scanSettings?.logs;
+    const logs_include = scanSettings?.logs_include;
+    const logs_exclude = scanSettings?.logs_exclude;
+    const file_logbuffer = [];
+    const logging_path_prefix = getPathPrefix(scan_settings_path, path_prefix);
+    const timestamp = new Date().toISOString().slice(0, 19).replace("T", " ");
+    const global_logging_path = `${logging_path_prefix}${role}-${cpu_worker_id ?? ""}-${timestamp}.log`;
+    const global_log_setup = {
+        logs,
+        logs_include,
+        logs_exclude,
+        file_logbuffer,
+        global_logging_path,
+    };
+    globalThis.__global_log_setup = global_log_setup;
+    startLogFlusher(global_log_setup);
+    return global_log_setup;
+}
+function safeStringify(value) {
+    try {
+        return JSON.stringify(value, (_key, v) => {
+            if (typeof v === "bigint")
+                return v.toString();
+            if (typeof v === "function")
+                return `fn ${v.name || "anon"}`;
+            if (v !== null && typeof v === "object") {
+                // promise or thenable
+                if (typeof v.then === "function") {
+                    try {
+                        return typeof Bun !== "undefined" && Bun.inspect
+                            ? Bun.inspect(v)
+                            : "Promise";
+                    }
+                    catch {
+                        return "Promise";
+                    }
+                }
+                // message port
+                const ctor = v.constructor;
+                if (ctor?.name === "MessagePort")
+                    return "MessagePort";
+            }
+            return v;
+        });
+    }
+    catch {
+        return String(value);
+    }
+}
+const flusherRef = new WeakMap();
+function startLogFlusher(setup) {
+    if (setup.logs !== "file" && setup.logs !== "console-and-file")
+        return;
+    if (flusherRef.has(setup))
+        return; // already running
+    let writtenIndex = 0;
+    const id = setInterval(async () => {
+        const buffer = setup.file_logbuffer;
+        if (buffer.length <= writtenIndex)
+            return; // nothing new
+        const newEntries = buffer.slice(writtenIndex);
+        writtenIndex = buffer.length;
+        if (newEntries.length === 0)
+            return;
+        const lines = newEntries
+            .map((e) => `[${e.timestamp}] ${safeStringify(e.message)}`)
+            .join("\n");
+        try {
+            const existing = await Bun.file(setup.global_logging_path)
+                .text()
+                .catch(() => "");
+            const newContent = existing ? existing + "\n" + lines : lines;
+            await atomicWrite(setup.global_logging_path, newContent);
+        }
+        catch (err) {
+            console.error("[logFlusher] write failed:", err);
+        }
+    }, 2000);
+    flusherRef.set(setup, id);
+}
+export function log(fnname, message) {
+    const setup = globalThis.__global_log_setup;
+    if (!setup)
+        return;
+    const { logs, logs_include, logs_exclude, file_logbuffer } = setup;
+    if (logs === "off")
+        return;
+    // Apply include/exclude filters
+    if (logs_include && logs_include.length > 0 && !logs_include.includes(fnname))
+        return;
+    if (logs_exclude && logs_exclude.includes(fnname))
+        return;
+    // skip messages that are about writing to the log file itself
+    // (prevents atomicWrite calls inside the flusher from feeding back)
+    const logPath = setup.global_logging_path;
+    if (logPath) {
+        const msg = message;
+        if ((typeof msg === "string" && msg.includes(logPath)) ||
+            (Array.isArray(msg) &&
+                msg.some((m) => typeof m === "string" && m.includes(logPath))))
+            return;
+    }
+    const timestamp = new Date().toISOString().slice(0, 19).replace("T", " ");
+    if (logs === "console" || logs === "console-and-file") {
+        console.log(`[${fnname}]`, ...(Array.isArray(message) ? message : [message]));
+    }
+    if (logs === "file" || logs === "console-and-file") {
+        file_logbuffer.push({ timestamp, message });
+    }
+}

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

@@ -1,4 +1,5 @@
 import { type CacheChangedCallbackParameters } from "./scanresult/scanCache";
+export declare const CPU_POOL_SIZE = 4;
 export type WorkerSet = {
     fetchWorker: Worker;
     cpuWorkers: Worker[];

package/dist/scanning-syncing/backgroundWorker.js

@@ -1,11 +1,14 @@
 import { LOCAL_NODE_DEFAULT_URL } from "../node-interaction/nodeUrl";
 import {} from "./scanresult/scanCache";
-import { openScanSettingsFile } from "./scanSettings";
+import { openScanSettingsFile, SCAN_SETTINGS_STORE_NAME_DEFAULT, } from "./scanSettings";
+import { log, setupLoggingPath } from "../io/logging";
 import { workerMainCode } from "./worker-entrypoints/worker";
-const CPU_POOL_SIZE = 4;
+export const CPU_POOL_SIZE = 4;
 export async function createWebworker(handle_result, scan_settings_path, pathPrefix, handle_error) {
     try {
-        const scanSettings = await openScanSettingsFile(scan_settings_path);
+        const resolvedPath = scan_settings_path || SCAN_SETTINGS_STORE_NAME_DEFAULT;
+        const scanSettings = await openScanSettingsFile(resolvedPath);
+        await setupLoggingPath(resolvedPath, pathPrefix ?? "", "mainthread");
         const node_url = scanSettings?.node_url || LOCAL_NODE_DEFAULT_URL;
         const cpu_worker_count = typeof scanSettings?.cpu_worker_count !== "undefined"
             ? scanSettings?.cpu_worker_count
@@ -16,7 +19,13 @@ export async function createWebworker(handle_result, scan_settings_path, pathPre
         for (let i = 0; i < cpu_worker_count; i++) {
             const channel = new MessageChannel();
             const cpuWorker = await startWebworkerReady();
-            cpuWorker.postMessage({ type: "setup", role: "cpubound", cpu_worker_id: i }, [channel.port1]);
+            cpuWorker.postMessage({
+                type: "setup",
+                role: "cpubound",
+                cpu_worker_id: i,
+                scan_settings_path: resolvedPath,
+                pathPrefix,
+            }, [channel.port1]);
             cpuWorker.onerror = (e) => {
                 if (handle_error)
                     handle_error("cpu worker " + i + " error: " + (e.message ?? String(e)));
@@ -27,13 +36,16 @@ export async function createWebworker(handle_result, scan_settings_path, pathPre
         const coordinationWorker = await startWebworkerReady();
         coordinationWorker.postMessage({
             type: "setup",
-            scan_settings_path,
+            scan_settings_path: resolvedPath,
             pathPrefix,
             role: "coordinator",
             node_url,
             start_height: 0,
         }, cpuPorts); // transfer CPU port2s to coordination worker
-        console.log("[createWebworker] coordinator worker started, node_url=" + node_url, ", cpuPorts=" + cpuPorts.length);
+        log("createWebworker", [
+            "coordinator worker started, node_url=" + node_url,
+            ", cpuPorts=" + cpuPorts.length,
+        ]);
         coordinationWorker.onmessage = (event) => {
             if (event.data.type === "ERROR") {
                 if (handle_error)
@@ -79,7 +91,7 @@ export function startWebworker(handle_result, handle_error) {
                     handle_error(event.data.payload ?? event.data.error);
                 break;
             case "DEBUG":
-                console.log("worker debug:", event.data.payload);
+                log("startWebworker", ["worker debug:", event.data.payload]);
                 break;
         }
     };

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

@@ -1,5 +1,6 @@
 import { findRange, get_block_headers_range, get_info, mergeRanges, NodeUrl, sleep, } from "../../api";
 import {} from "../connectionStatus";
+import { log } from "../../io/logging";
 export const MAX_BLOCKS_BUFFER_SIZE = 10;
 // runs forever, fetching blocks from the node.
 // handles scan level reorg detection and catastrophic reorg
@@ -8,7 +9,7 @@ connection_status, // we make a local copy of this and pass last_packet and sync
 max_blocks_buffer_size = MAX_BLOCKS_BUFFER_SIZE, anchor_range, stopSync) {
     connection_status = structuredClone(connection_status);
     const nodeUrl = await NodeUrl.create(node_url);
-    console.log("[blocksBufferFetchLoop] NodeUrl created, fetching info...");
+    log("blocksBufferFetchLoop", ["NodeUrl:", nodeUrl.node_url, "start:", start_height]);
     start_height = await reduceStartHeightToTip(start_height, nodeUrl.node_url);
     // initialise ranges on first call
     let { current_range, scanned_ranges } = await initScannedRanges(nodeUrl.node_url, start_height, anchor_range ? [anchor_range] : []);
@@ -38,12 +39,10 @@ max_blocks_buffer_size = MAX_BLOCKS_BUFFER_SIZE, anchor_range, stopSync) {
             await sleep(5000);
             continue;
         }
-        console.log("[blocksBufferFetchLoop] fetching from current_range...");
+        log("blocksBufferFetchLoop", ["fetching", nodeUrl.node_url, current_range.start, "->", current_range.end]);
         const get_blocks_bin = await doRPCrequest(nodeUrl, current_range, stopSync);
         const result_meta = await nodeUrl.loadGetBlocksBinResponse(get_blocks_bin);
-        console.log("[blocksBufferFetchLoop] response: " +
-            result_meta.block_infos.length +
-            " blocks");
+        log("blocksBufferFetchLoop", "response: " + result_meta.block_infos.length + " blocks");
         connection_status.last_packet = {
             status: "OK",
             bytes_read: get_blocks_bin.length,
@@ -343,8 +342,11 @@ export async function reduceStartHeightToTip(start_height, node_url) {
     if (start_height > getInfo.height - 1) {
         const oldStartHeight = start_height;
         start_height = getInfo.height - 1;
-        console.log("[reduceStartHeightToTip] start height was larger than daemon height, setting start_height=" +
-            start_height, " oldStartHeight=" + oldStartHeight);
+        log("reduceStartHeightToTip", [
+            "start height was larger than daemon height, setting start_height=" +
+                start_height,
+            " oldStartHeight=" + oldStartHeight,
+        ]);
     }
     return start_height;
 }

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

@@ -1,4 +1,5 @@
 import { blocksBufferFetchLoop, readWriteConnectionStatusFile, CatastrophicReorgError, readOrInitConnectionStatus, } from "../../api";
+import { log } from "../../io/logging";
 export async function setupBlocksBufferGenerator(params) {
     const blocksBuffer = [];
     const connection_status = await readOrInitConnectionStatus(params.scanSettingsPath);
@@ -13,7 +14,7 @@ export async function handleConnectionStatusChanges(event, scanSettingsPath) {
             cs2.last_packet = event;
         }, scanSettingsPath);
         if (event.status === "catastrophic_reorg") {
-            console.log("[blocksbufferCoordinator] catastrophic reorg, stopping");
+            log("handleConnectionStatusChanges", "catastrophic reorg, stopping");
             throw new CatastrophicReorgError("[blocksbufferCoordinator] catastrophic reorg, stopping");
         }
     }

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

@@ -1,3 +1,4 @@
+import type { LogSetting, PossibleLogs } from "../io/logging";
 export declare const SCAN_SETTINGS_STORE_NAME_DEFAULT = "ScanSettings.json";
 export type ScanSetting = {
     primary_address: string;
@@ -17,6 +18,9 @@ export type WriteScanSettingParams = {
     wallet_route?: string;
     wallet_name?: string;
     wallet_slot?: number;
+    logs?: LogSetting;
+    logs_include?: PossibleLogs[];
+    logs_exclude?: PossibleLogs[];
 };
 export type ScanSettingOpened = {
     primary_address: string;
@@ -36,6 +40,9 @@ export type ScanSettings = {
     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)[];
@@ -43,6 +50,9 @@ export type ScanSettingsOpened = {
     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.

package/dist/scanning-syncing/scanSettings.js

@@ -239,10 +239,19 @@ export async function writeWalletToScanSettings(params) {
                 },
             ],
             node_url: params.node_url,
+            logs: params.logs,
+            logs_include: params.logs_include,
+            logs_exclude: params.logs_exclude,
             start_height: params.start_height || null,
         }, params.scan_settings_path);
     }
     scanSettings.node_url = params.node_url || scanSettings.node_url;
+    if (params.logs)
+        scanSettings.logs = params.logs;
+    if (params.logs_include)
+        scanSettings.logs_include = params.logs_include;
+    if (params.logs_exclude)
+        scanSettings.logs_exclude = params.logs_exclude;
     scanSettings.start_height =
         params.start_height === undefined
             ? scanSettings.start_height

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

@@ -1,6 +1,7 @@
 import {} from "./computeKeyImage";
 import { get_block_headers_range, } from "../../api";
 import { atomicWrite } from "../../io/atomicWrite";
+import { log } from "../../io/logging";
 export async function initScanCache(viewpair, start_height, scan_settings_path, pathPrefix) {
     const initialCache = await readCacheFileDefaultLocation(viewpair.primary_address, pathPrefix);
     let cache = {
@@ -161,7 +162,7 @@ export function handleScanError(error) {
     // treat errno 0 code "ConnectionRefused" as non fatal outcome, and rethrow,
     // so that UI can be informed after catching it higher up
     if (isConnectionError(error)) {
-        console.log("Scan stopped. node might be offline. Connection Refused");
+        log("handleScanError", "Scan stopped. node might be offline. Connection Refused");
         throw error;
     }
     // Treat AbortError as a normal, non-fatal outcome
@@ -169,11 +170,14 @@ export function handleScanError(error) {
         typeof error === "object" &&
         (("name" in error && error.name === "AbortError") ||
             ("code" in error && error.code === 20))) {
-        console.log("Scan was aborted.");
+        log("handleScanError", "Scan was aborted.");
         return;
     }
     else {
-        console.log(error, "\n, scanWithCache in scanning-syncing/scanWithCache.ts`");
+        log("handleScanError", [
+            error,
+            "\n, scanWithCache in scanning-syncing/scanWithCache.ts`",
+        ]);
         throw error;
     }
 }