@spirobel/monero-wallet-api 0.5.4 → 0.6.0

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

@@ -29,6 +29,7 @@ export type WorkToBeDone = {
  * @param scan_settings_path
  */
 export declare function findWorkToBeDone(scan_settings_path?: string, pathPrefix?: string): Promise<WorkToBeDone | false>;
+export declare function fastForwardFetch(wallet_configs: WalletConfigPlusCache[], start_height: number, batchEnd: number): CacheRange | null;
 export declare function workToBeDoneForBatch(cache: ScanCache, batch_meta_infos: BlockInfo[]): "skip" | {
     from: number;
 };
@@ -64,7 +65,6 @@ export type CoordinatorEvent = {
 } | {
     type: "scan_ready";
     address: string;
-    result: ScanLoopYield;
     newCache: ScanCache;
     changed_outputs: {
         output: any;
@@ -72,11 +72,13 @@ export type CoordinatorEvent = {
     }[];
 } | {
     type: "all_idle";
+} | {
+    type: "shutdown_done";
 } | {
     type: "error";
     error: Error;
 };
-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[];
@@ -96,10 +98,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>;

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

@@ -1,8 +1,8 @@
-import { setupBlocksBufferGenerator, ViewPair, handleConnectionStatusChanges, processScanResult, writeCacheToFile, sleep, findTipIndex, readWriteConnectionStatusFile, } from "../../api";
-import { markWorkItemAsDone, } from "./scanLoop";
+import { setupBlocksBufferGenerator, ViewPair, handleConnectionStatusChanges, processScanResult, writeCacheToFile, sleep, findTipIndex, readWriteConnectionStatusFile, applyWalletScanProgress, } from "../../api";
+import {} from "./scanLoop";
 import { makeWorkItem } from "./scanLoop";
 import { cullTooLargeScanHeight, getNonHaltedWallets, getPathPrefix, openScanSettingsFile, SCAN_SETTINGS_STORE_NAME_DEFAULT, walletSettingsPlusKeys, } from "../../api";
-import { findRange, initScanCacheFile, lastRange, makeCacheRangeForHeight, mergeRanges, } from "./scanCache";
+import { currentScanHeightFromRanges, findRange, initScanCacheFile, lastRange, makeCacheRangeForHeight, mergeRanges, } from "./scanCache";
 import { sendToCpuWorker } from "../worker-mains/cpubound-main";
 import { log } from "../../io/logging";
 /**
@@ -79,6 +79,19 @@ export async function findWorkToBeDone(scan_settings_path = SCAN_SETTINGS_STORE_
         scan_settings,
     };
 }
+// slowest wallet past this batch: return its range so fetch can restart at that tip.
+export function fastForwardFetch(wallet_configs, start_height, batchEnd) {
+    if (!wallet_configs.length)
+        return null;
+    const slowest = Math.min(...wallet_configs.map((w) => currentScanHeightFromRanges(w.cache.scanned_ranges, start_height)));
+    if (slowest <= batchEnd)
+        return null;
+    const owner = wallet_configs.find((w) => currentScanHeightFromRanges(w.cache.scanned_ranges, start_height) ===
+        slowest);
+    return owner
+        ? findRange(owner.cache.scanned_ranges, start_height)
+        : null;
+}
 export function workToBeDoneForBatch(cache, batch_meta_infos) {
     const begin_height = batch_meta_infos[0].block_height;
     const end_height = batch_meta_infos[batch_meta_infos.length - 1].block_height;
@@ -220,6 +233,9 @@ export async function processWorkItem(item, workBuffer, blocksBuffer, pathPrefix
         throw error;
     }
     await writeCacheToFile(cache, pathPrefix);
+    // raw cpu ScanResult is fully merged into cache now. drop it so workBuffer
+    // does not pin all_key_images / hash strings until left-edge free.
+    item.result = undefined;
     item.status = "process_result_done";
     log("processWorkItem", `process_result_done work_uuid=${item?.work_uuid}`);
     // remove from blocksbuffer if no more work items reference it
@@ -271,15 +287,22 @@ function computeETA(cache, totalBlocksScanned, scanStartTime) {
     const etaMs = remaining / blocksPerMs;
     return msToHHMM(etaMs);
 }
-export async function setupCoordinator(scanSettingsPath, pathPrefix) {
+export async function setupCoordinator(scanSettingsPath, pathPrefix, stopSync) {
     const work_to_be_done = await findWorkToBeDone(scanSettingsPath, pathPrefix);
     if (!work_to_be_done)
         return false;
+    // bring connection status file scan height in line with / cache file / in memory state 
+    await readWriteConnectionStatusFile((cs) => {
+        applyWalletScanProgress(cs, {
+            current_scan_height: currentScanHeightFromRanges(work_to_be_done.wallet_configs[0]?.cache.scanned_ranges ?? [], work_to_be_done.scan_settings.start_height || 0),
+        });
+    }, scanSettingsPath);
     const { generator: blocksGenerator, blocksBuffer } = await setupBlocksBufferGenerator({
         nodeUrl: work_to_be_done.scan_settings.node_url,
         startHeight: work_to_be_done.start_height,
         anchor_range: work_to_be_done.anchor_range,
         scanSettingsPath,
+        stopSync,
     });
     const workBuffer = [];
     //TODO: refactor to per wallet buffer
@@ -298,22 +321,53 @@ export async function setupCoordinator(scanSettingsPath, pathPrefix) {
         work_to_be_done,
     };
 }
+// flip inflight work back to fresh so a restart can reschedule it
+export function resetInProgressWorkItems(workBuffer) {
+    for (const item of workBuffer) {
+        if (item.status === "scanwork_in_progress") {
+            item.status = "fresh";
+            item.result = undefined;
+        }
+    }
+}
+// tell busy cpu ports to cancel and wait for their promises (with timeout)
+export async function cancelBusyCpuPorts(ports, timeoutMs = 3000) {
+    const busy = ports.filter((ps) => ps.promise);
+    for (const ps of busy) {
+        try {
+            sendToCpuWorker(ps.port, "cancel");
+        }
+        catch (err) {
+            log("cancelBusyCpuPorts", ["send cancel failed", String(err)]);
+        }
+    }
+    if (busy.length === 0)
+        return;
+    await Promise.race([
+        Promise.allSettled(busy.map((ps) => ps.promise)),
+        sleep(timeoutMs),
+    ]);
+    for (const ps of ports) {
+        ps.promise = null;
+    }
+}
 /**
  * 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 async function* coordinatorMainMultithreaded(scanSettingsPath, pathPrefix, cpuPorts) {
+export async function* coordinatorMainMultithreaded(scanSettingsPath, pathPrefix, cpuPorts, stopSync) {
     if (!cpuPorts || cpuPorts.length === 0) {
         throw new Error("[coordinatorMain Multithreaded] cpuPorts empty, there must be at least cpu worker");
     }
-    const ctx = await setupCoordinator(scanSettingsPath, pathPrefix);
+    const ctx = await setupCoordinator(scanSettingsPath, pathPrefix, stopSync);
     if (!ctx)
         throw new Error("[coordinatorMain Multithreaded] findWorkToBeDone returned false");
     const work_to_be_done = ctx.work_to_be_done;
-    const blocksBuffer = ctx.blocksBuffer;
+    let blocksBuffer = ctx.blocksBuffer;
     const workBuffer = ctx.workBuffer;
-    const blocksGenerator = ctx.blocksGenerator;
+    let blocksGenerator = ctx.blocksGenerator;
+    let fetchAt = work_to_be_done.start_height;
     let totalBlocksScanned = 0;
     let scanStartTime = Date.now();
     let blocksPromise = blocksGenerator.next();
@@ -327,6 +381,13 @@ export async function* coordinatorMainMultithreaded(scanSettingsPath, pathPrefix
     }
     let race_count = 0;
     while (true) {
+        if (stopSync?.aborted) {
+            log("coordinatorMainMultithreaded", ["shutdown signal, draining"]);
+            await cancelBusyCpuPorts(freePorts);
+            resetInProgressWorkItems(workBuffer);
+            yield { type: "shutdown_done" };
+            return;
+        }
         race_count++;
         log("coordinatorMainMultithreaded", ["race_count", race_count]);
         await scheduleWorkOnCpuPorts(freePorts, workBuffer);
@@ -344,6 +405,16 @@ export async function* coordinatorMainMultithreaded(scanSettingsPath, pathPrefix
         const winner = await Promise.race(races);
         log("coordinatorMainMultithreaded", "cpu ports status");
         if ("src" in winner && winner.src === "blocks") {
+            // fetch loop returned (done) on abort, treat as shutdown
+            if (winner.value.done) {
+                log("coordinatorMainMultithreaded", [
+                    "blocks generator done, draining",
+                ]);
+                await cancelBusyCpuPorts(freePorts);
+                resetInProgressWorkItems(workBuffer);
+                yield { type: "shutdown_done" };
+                return;
+            }
             const result = winner.value.value;
             const { isBlocksBufferChanged } = await handleBlocksYield(result, scanSettingsPath);
             if (isBlocksBufferChanged) {
@@ -376,30 +447,38 @@ export async function* coordinatorMainMultithreaded(scanSettingsPath, pathPrefix
                 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);
+            const jumped = fastForwardFetch(work_to_be_done.wallet_configs, work_to_be_done.scan_settings.start_height || 0, to_be_processed.batch.get_blocks_result_meta.block_infos[to_be_processed.to].block_height);
+            if (jumped && jumped.end > fetchAt) {
+                log("coordinatorMainMultithreaded", ["jump", fetchAt, "->", jumped.end]);
+                await blocksGenerator.return(undefined);
+                const next = await setupBlocksBufferGenerator({
+                    nodeUrl: work_to_be_done.scan_settings.node_url,
+                    startHeight: jumped.end,
+                    anchor_range: jumped,
+                    scanSettingsPath,
+                    stopSync,
+                });
+                blocksBuffer = next.blocksBuffer;
+                blocksGenerator = next.generator;
+                blocksPromise = blocksGenerator.next();
+                fetchAt = jumped.end;
+            }
+            // always persist wallet progress after process; eta only if we have a new one
+            // so missing eta does not wipe the previous value (no flicker)
+            const eta = computeETA(wallet.cache, totalBlocksScanned, scanStartTime);
+            await readWriteConnectionStatusFile((cs) => {
+                applyWalletScanProgress(cs, {
+                    current_scan_height: currentScanHeightFromRanges(wallet.cache.scanned_ranges, work_to_be_done.scan_settings.start_height || 0),
+                    scanned_ranges: wallet.cache.scanned_ranges,
+                    daemon_height: wallet.cache.daemon_height,
+                    eta,
+                });
+            }, scanSettingsPath);
             //  log("coordinatorMainMultithreaded", "processWorkItem result");
             yield {
                 type: "scan_ready",
                 address: wallet.primary_address,
-                result: {
-                    type: "Ready",
-                    work_uuid: to_be_processed.work_uuid,
-                    result: to_be_processed.result,
-                },
                 newCache: wallet.cache,
                 changed_outputs: res.changed_outputs,
             };
@@ -424,6 +503,17 @@ export async function scheduleWorkOnCpuPorts(ports, work_buffer) {
             const msg = event.data;
             // handle the result here:
             log("scheduleWorkOnCpuPorts", ["onmessage result", msg]);
+            // cancel ack may omit work_uuid when idle, but inflight cancel carries it
+            if (msg.type === "Canceled") {
+                if (item.status === "scanwork_in_progress") {
+                    item.status = "fresh";
+                    item.result = undefined;
+                }
+                port_status.promise = null;
+                // thin resolve: dont put full msg/result on the port promise on cancel
+                resolve_port({ type: "Canceled", work_uuid: item.work_uuid });
+                return;
+            }
             if (msg.work_uuid !== item.work_uuid) {
                 log("scheduleWorkOnCpuPorts", [
                     "wrong work_uuid in msg msg.work_uuid=",
@@ -441,10 +531,18 @@ export async function scheduleWorkOnCpuPorts(ports, work_buffer) {
                 log("scheduleWorkOnCpuPorts", "wrong status in msg");
                 throw new Error("[scheduleWorkOnCpuPorts] wrong status in msg");
             }
+            // fat ScanResult lives only on the work item until process clears it
             item.result = msg.result;
             item.status = "scanwork_done";
+            // cpu already has its own buffer copy; process only needs meta.
+            // drop work-item bytes now; blocksBuffer still owns the batch until left-edge free.
+            item.batch = {
+                ...item.batch,
+                data: new Uint8Array(0),
+            };
             port_status.promise = null;
-            resolve_port(msg);
+            // thin resolve: race/await must not retain all_key_images via promise value
+            resolve_port({ type: msg.type, work_uuid: msg.work_uuid });
         };
         port_status.port.onmessage = onmessage;
         item.status = "scanwork_in_progress";

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

@@ -12,9 +12,8 @@ export declare function makeWorkItem(walletConfig: WalletConfigPlusCache, batch:
 export type ScanLoopIteratorResult = IteratorYieldResult<ScanLoopYield>;
 export type ScanLoopInput = WorkItem | "cancel" | undefined;
 export type ScanLoopYield = {
-    type: "Ready" | "InProgress";
+    type: "Ready" | "InProgress" | "Canceled";
     work_uuid?: string;
     result?: ScanResult;
 };
 export declare function scanLoop(wallet: WalletConfig): AsyncGenerator<ScanLoopYield, void, ScanLoopInput>;
-export declare function markWorkItemAsDone(loop_event: ScanLoopYield, work_buffer: WorkItem[]): Promise<WorkItem | undefined>;

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

@@ -101,16 +101,3 @@ export async function* scanLoop(wallet) {
         // will be done by processScanResult in the consumer
     }
 }
-//theoretically markWorkItemAsDone could be done in the generator as WorkItem is passed in by reference
-// but: eventually this has to be done accross CPU worker boundaries
-// so we act on the yielded scan result
-export async function markWorkItemAsDone(loop_event, work_buffer) {
-    if (loop_event.type === "Ready" && loop_event.work_uuid) {
-        const work_item = work_buffer.find((w) => w.work_uuid === loop_event.work_uuid);
-        if (work_item) {
-            work_item.result = loop_event.result;
-            work_item.status = "scanwork_done";
-            return work_item;
-        }
-    }
-}

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

@@ -39,7 +39,7 @@ export async function processScanResult(params) {
                     reverted_spends: [],
                 };
             }
-            else {
+            else if (!cache.reorg_info.split_heights.some((s) => s.block_hash === split_height.block_hash)) {
                 cache.reorg_info.split_heights.push(split_height);
             }
             // First, collect reverted spends from all outputs (before any removals)
@@ -56,11 +56,14 @@ export async function processScanResult(params) {
             for (const [id, old_output_state] of removed_outputs) {
                 // 1. find key_image of output to be removed (as it was reorged)
                 const [key_image] = Object.entries(cache.own_key_images).find(([own_key_image, globalid]) => globalid === id) || [""]; // if this is viewonly the key_image will be empty
-                cache.reorg_info.removed_outputs.push({
-                    old_output_state,
-                    key_image,
-                    split_height,
-                });
+                if (!cache.reorg_info.removed_outputs.some((r) => r.old_output_state.index_on_blockchain ===
+                    old_output_state.index_on_blockchain)) {
+                    cache.reorg_info.removed_outputs.push({
+                        old_output_state,
+                        key_image,
+                        split_height,
+                    });
+                }
                 // 2. remove from outputs and own_key_images
                 delete cache.outputs[id];
                 delete cache.own_key_images[key_image];
@@ -72,11 +75,14 @@ export async function processScanResult(params) {
             for (const [id, old_output_state_pointer] of reverted_outputs) {
                 const [key_image] = Object.entries(cache.own_key_images).find(([own_key_image, globalid]) => globalid === id) || [""]; // if this is viewonly the key_image will be empty
                 const old_output_state = Object.assign({}, old_output_state_pointer);
-                cache.reorg_info.reverted_spends.push({
-                    old_output_state,
-                    key_image, // in this case key_image only used here, does not get removed
-                    split_height,
-                });
+                if (!cache.reorg_info.reverted_spends.some((r) => r.old_output_state.index_on_blockchain ===
+                    old_output_state.index_on_blockchain)) {
+                    cache.reorg_info.reverted_spends.push({
+                        old_output_state,
+                        key_image, // in this case key_image only used here, does not get removed
+                        split_height,
+                    });
+                }
                 // remove spend info from original cache (if output still exists
                 // it may have been deleted above in the removed_outputs loop)
                 if (cache.outputs[id]) {
@@ -226,7 +232,6 @@ export function outputStatus(output, cache, current_height) {
     if (unlock_height > current_height) {
         return { status: "pending", unlock_height };
     }
-    // TODO: check that that output is not txlog input indeces
     return { status: "spendable" };
 }
 export function spendable(output, cache, current_height) {

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

@@ -120,16 +120,19 @@ export function processFoundTransactions(cache, stats, current_height) {
         }
         // handle spent case
         if (output.spent_in_tx_hash) {
-            const spent_utxo_value = cache.pending_spent_utxos
-                ? cache.pending_spent_utxos[output.index_on_blockchain]
-                : null;
-            const txlog = cache.tx_logs && spent_utxo_value
-                ? cache.tx_logs[spent_utxo_value]
+            const spentIndex = cache.pending_spent_utxos
+                ? cache.pending_spent_utxos[String(output.index_on_blockchain)]
+                : undefined;
+            // index 0 is a real log. do not treat it as missing.
+            const txlog = cache.tx_logs && spentIndex !== undefined
+                ? cache.tx_logs[spentIndex]
                 : undefined;
             const spentTx = stats.found_transactions[output.spent_in_tx_hash];
             if (spentTx) {
                 spentTx.amount -= output.amount;
                 spentTx.inputs.push(output);
+                if (!spentTx.txlog && txlog)
+                    spentTx.txlog = txlog;
             }
             else {
                 stats.found_transactions[output.spent_in_tx_hash] = {