@spirobel/monero-wallet-api 0.3.18 → 0.4.1

package/dist/api.d.ts

@@ -1,5 +1,4 @@
 import "./io/indexedDB";
-export type { ScanResult, ScanResultCallback, } from "./scanning-syncing/scanresult/scanResult";
 export type { CacheChangedCallback, CacheChangedCallbackParameters, } from "./scanning-syncing/scanresult/scanCache";
 export { NodeUrl } from "./node-interaction/nodeUrl";
 export { ViewPair } from "./viewpair/ViewPair";
@@ -12,14 +11,18 @@ export * from "./io/sleep";
 export { writeScanSettings, readScanSettings, } from "./scanning-syncing/scanSettings";
 export { signTransaction, parseAddress, type ParsedAddress, type ParseAddressError, } from "./send-functionality/transactionBuilding";
 export { computeKeyImage } from "./scanning-syncing/scanresult/computeKeyImage";
-export { scanWallets, startWebworker, createWebworker, makeWebworkerScript, } from "./scanning-syncing/backgroundWorker";
+export { startWebworker, createWebworker, makeWebworkerScript, } from "./scanning-syncing/backgroundWorker";
 export { spendable } from "./scanning-syncing/scanresult/scanResult";
 export { openWallets, openWallet } from "./scanning-syncing/openWallet";
+export * from "./scanning-syncing/blocksbuffer/blocksBufferFetchLoop";
+export * from "./scanning-syncing/blocksbuffer/blocksbufferCoordination";
 export * from "./scanning-syncing/connectionStatus";
 export * from "./scanning-syncing/scanSettings";
 export * from "./scanning-syncing/scanresult/scanResult";
 export * from "./scanning-syncing/scanresult/scanStats";
 export * from "./scanning-syncing/scanresult/scanCache";
+export * from "./scanning-syncing/scanresult/scanCoordination";
+export * from "./scanning-syncing/scanresult/scanLoop";
 export * from "./keypairs-seeds/writeKeypairs";
 export * from "./keypairs-seeds/keypairs";
 export * from "./send-functionality/conversion";

package/dist/api.js

@@ -10,14 +10,18 @@ export * from "./io/sleep";
 export { writeScanSettings, readScanSettings, } from "./scanning-syncing/scanSettings";
 export { signTransaction, parseAddress, } from "./send-functionality/transactionBuilding";
 export { computeKeyImage } from "./scanning-syncing/scanresult/computeKeyImage";
-export { scanWallets, startWebworker, createWebworker, makeWebworkerScript, } from "./scanning-syncing/backgroundWorker";
+export { startWebworker, createWebworker, makeWebworkerScript, } from "./scanning-syncing/backgroundWorker";
 export { spendable } from "./scanning-syncing/scanresult/scanResult";
 export { openWallets, openWallet } from "./scanning-syncing/openWallet";
+export * from "./scanning-syncing/blocksbuffer/blocksBufferFetchLoop";
+export * from "./scanning-syncing/blocksbuffer/blocksbufferCoordination";
 export * from "./scanning-syncing/connectionStatus";
 export * from "./scanning-syncing/scanSettings";
 export * from "./scanning-syncing/scanresult/scanResult";
 export * from "./scanning-syncing/scanresult/scanStats";
 export * from "./scanning-syncing/scanresult/scanCache";
+export * from "./scanning-syncing/scanresult/scanCoordination";
+export * from "./scanning-syncing/scanresult/scanLoop";
 export * from "./keypairs-seeds/writeKeypairs";
 export * from "./keypairs-seeds/keypairs";
 export * from "./send-functionality/conversion";

package/dist/io/atomicWrite.js

@@ -1,9 +1,11 @@
+import { log } from "./logging";
 export async function atomicWrite(targetPath, data) {
+    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);
     const { rename } = await import("node:fs/promises");
-    const tempPath = targetPath + ".tmp";
+    const tempPath = targetPath + ".tmp." + Date.now() + "." + Math.random();
     const bytesWritten = await Bun.write(tempPath, data);
     try {
         await rename(tempPath, targetPath);

package/dist/io/indexedDB.js

@@ -45,8 +45,11 @@ class IndexedDBFile {
         return new BunFileSink();
     }
     exists() {
-        throw new Error("not implemented");
-        return Promise.resolve(false);
+        if (!this.path)
+            return Promise.resolve(false);
+        return getFileFromIndexedDB(this.path)
+            .then((r) => r !== undefined)
+            .catch(() => false);
     }
     delete() {
         return deleteFileFromIndexedDB(this.path);
@@ -158,6 +161,8 @@ else {
     browserGlobal.areWeInTheBrowser = false;
 }
 export async function refreshEnvIndexedDB() {
+    if (!areWeInTheBrowser)
+        return;
     browserGlobal.Bun.env = await readEnvIndexedDB();
 }
 // we need this to change the env at runtime from inside the Browser extension,

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/keypairs-seeds/keypairs.d.ts

@@ -18,6 +18,20 @@
  * duffed the implementation."
  */
 export type SpendKey = string;
+export type Keypair = {
+    spend_key: SpendKey;
+    view_key: ViewPairJson;
+};
+/**
+ *  use this function to generate a keypair for testing
+ * @returns spendkey and viewkey (contains primary address, for mainnet, testnet,stagenet)
+ */
+export declare function makeTestKeyPair(): Promise<Keypair>;
+/**
+ *  use this function to generate a spend key for testing
+ *  use the spend key to generate a view key with the makeViewKey function
+ * @returns SpendKey
+ */
 export declare function makeSpendKey(): Promise<SpendKey>;
 export declare function makeSpendKeyFromSeed(wallet_secret: string): Promise<SpendKey>;
 export type ViewPairJson = {
@@ -26,4 +40,11 @@ export type ViewPairJson = {
     stagenet_primary: string;
     testnet_primary: string;
 };
+/**
+ * spend private key is hashed with keccak to make the view private key
+ * this is according to the convention in the monero code base,
+ * read the comment at the top of the file for more details & link to source
+ * @param spend_private_key the spendkey the viewkey will be derived from
+ * @returns the viewkey that was derive from the spendkey
+ */
 export declare function makeViewKey(spend_private_key: string): Promise<ViewPairJson>;

package/dist/keypairs-seeds/keypairs.js

@@ -61,6 +61,20 @@
 // 4849   crypto::ElectrumWords::bytes_to_words(recovery_val, electrum_words, mnemonic_language);
 // https://github.com/monero-project/monero/blob/48ad374b0d6d6e045128729534dc2508e6999afe/src/simplewallet/simplewallet.cpp#L4849
 import { WasmProcessor } from "../wasm-processing/wasmProcessor";
+/**
+ *  use this function to generate a keypair for testing
+ * @returns spendkey and viewkey (contains primary address, for mainnet, testnet,stagenet)
+ */
+export async function makeTestKeyPair() {
+    const spend_key = await makeSpendKey();
+    const view_key = await makeViewKey(spend_key);
+    return { spend_key, view_key };
+}
+/**
+ *  use this function to generate a spend key for testing
+ *  use the spend key to generate a view key with the makeViewKey function
+ * @returns SpendKey
+ */
 export async function makeSpendKey() {
     const wasmProcessor = await WasmProcessor.init();
     let result = undefined;
@@ -94,6 +108,13 @@ export async function makeSpendKeyFromSeed(wallet_secret) {
     }
     return result;
 }
+/**
+ * spend private key is hashed with keccak to make the view private key
+ * this is according to the convention in the monero code base,
+ * read the comment at the top of the file for more details & link to source
+ * @param spend_private_key the spendkey the viewkey will be derived from
+ * @returns the viewkey that was derive from the spendkey
+ */
 export async function makeViewKey(spend_private_key) {
     if (spend_private_key.length !== 64) {
         throw new Error(`Invalid spendkey length: ${spend_private_key.length}.

package/dist/node-interaction/binaryEndpoints.d.ts

@@ -56,7 +56,6 @@ export type GetBlocksResultMeta = {
     new_height: number;
     daemon_height: number;
     status: Status;
-    primary_address: "parsing-monerod-response-without-wallet" | "error-address-not-set" | string;
     block_infos: BlockInfo[];
 };
 export type BlockInfo = {
@@ -102,7 +101,6 @@ export declare function getBlocksBinMakeRequest<T extends WasmProcessor>(process
 export declare function getBlocksBinExecuteRequest<T extends WasmProcessor & HasNodeUrl>(processor: T, params: GetBlocksBinRequest, stopSync?: AbortSignal): Promise<Uint8Array<ArrayBufferLike>>;
 export declare function getBlocksBinScanResponse<T extends WasmProcessor>(processor: T, getBlocksBinResponseBuffer: Uint8Array, metaCallBack?: GetBlocksBinMetaCallback): Promise<ScanResult | ErrorResponse | undefined>;
 export declare function getBlocksBinScan<T extends WasmProcessor & HasNodeUrl>(processor: T, params: GetBlocksBinRequest, metaCallBack?: GetBlocksBinMetaCallback, stopSync?: AbortSignal): Promise<ScanResult | ErrorResponse | undefined>;
-export declare function getBlocksBinJson<T extends WasmProcessor & HasNodeUrl>(processor: T, params: GetBlocksBinRequest): Promise<GetBlocksBinResponse | ErrorResponse>;
 /**
  * throws error on failure to create request
  * @param processor wasmprocessor
@@ -113,5 +111,36 @@ export declare function getOutsBinMakeRequest<T extends WasmProcessor>(processor
 export type GetOutsResponseBuffer = Uint8Array;
 export declare function getOutsBinExecuteRequest<T extends WasmProcessor & HasNodeUrl>(processor: T, params: GetOutsBinRequest): Promise<GetOutsResponseBuffer>;
 export declare function getOutsBinJson<T extends WasmProcessor & HasNodeUrl>(processor: T, params: GetOutsBinRequest): Promise<GetOutsBinResponse>;
+/**
+ * Loads a getBlocks.bin response into the WASM module for later single-block scanning
+ * via repeated calls to scan_block. Unlike getBlocksBinScanResponse, this does not
+ * scan any outputs,it only returns the block metadata (heights, timestamps, hashes).
+ * Each call overwrites the previously stored response, so it can be called repeatedly
+ * without leaking memory.
+ * @param processor the WASM processor used to interface with the Rust module, eg ViewPair in viewpair.ts
+ * @param getBlocksBinResponseBuffer the raw binary response from the get_blocks.bin endpoint
+ * @returns metadata about the loaded blocks (new_height, daemon_height, status, block_infos)
+ */
+export declare function loadGetBlocksBinResponse<T extends WasmProcessor>(processor: T, getBlocksBinResponseBuffer: Uint8Array): Promise<GetBlocksResultMeta>;
+/**
+ * Scans a single block from the previously loaded getBlocks.bin response.
+ * Call loadGetBlocksBinResponse first to load a response into WASM memory.
+ * @param processor the WASM processor
+ * @param blockIndex index of the block within the loaded response (0-based)
+ * @returns scan result with outputs and key images for that one block
+ *
+ * ErrorResponse type:
+ * the error messages come from the rust side in rust/src/:
+ * - "Block index {} out of bounds (total blocks: {})"
+ *   in lib.rs get_blocks_bin_scan_one_block, guards blockIndex against response.blocks.len
+ * - "No getBlocks.bin response loaded. Call loadGetBlocksBinResponse first."
+ *   in lib.rs get_blocks_bin_scan_one_block, when GLOBAL_GET_BLOCKS_BIN_RESPONSE is None
+ * - "Error scanning miner transaction: {}"
+ *   in block_parsing/mod.rs scan_block, scanner.scan_transaction failed when parsing miner tx of block
+ * - "Error scanning block: {}"
+ *   in block_parsing/mod.rs scan_block, scanner.scan(scan_block) failed
+ * all errors are returned as { error: string } (ErrorResponse type)
+ */
+export declare function getBlocksBinScanOneBlock<T extends WasmProcessor>(processor: T, blockIndex: number): Promise<ScanResult | ErrorResponse>;
 export declare function binaryFetchRequest(url: string, body: Uint8Array, stopSync?: AbortSignal): Promise<Uint8Array>;
 export {};

package/dist/node-interaction/binaryEndpoints.js

@@ -68,7 +68,6 @@ export async function getBlocksBinScanResponse(processor, getBlocksBinResponseBu
             });
             if (!("error" in result)) {
                 result.new_height = resultMeta.new_height;
-                result.primary_address = resultMeta.primary_address;
                 result.block_infos = resultMeta.block_infos;
                 result.daemon_height = resultMeta.daemon_height;
             }
@@ -82,27 +81,6 @@ export async function getBlocksBinScan(processor, params, metaCallBack, stopSync
     const getBlocksBinResponseBuffer = await getBlocksBinExecuteRequest(processor, params, stopSync);
     return getBlocksBinScanResponse(processor, getBlocksBinResponseBuffer, metaCallBack);
 }
-export async function getBlocksBinJson(processor, params) {
-    const getBlocksRequestArray = getBlocksBinMakeRequest(processor, params);
-    const getBlocksBinResponseBuffer = await binaryFetchRequest(processor.node_url + "/getblocks.bin", getBlocksRequestArray);
-    processor.writeToWasmMemory = (ptr, len) => {
-        processor.writeArray(ptr, len, getBlocksBinResponseBuffer);
-    };
-    let resultMeta;
-    let result;
-    processor.readFromWasmMemory = (ptr, len) => {
-        resultMeta = JSON.parse(processor.readString(ptr, len));
-        processor.readFromWasmMemory = (ptr, len) => {
-            result = JSON.parse(processor.readString(ptr, len));
-            if (!("error" in result)) {
-                result.new_height = resultMeta.new_height;
-            }
-        };
-    };
-    //@ts-ignore
-    processor.tinywasi.instance.exports.convert_get_blocks_bin_response_to_json(getBlocksBinResponseBuffer.length);
-    return result; //result written in convert_get_blocks_bin_response_to_json
-}
 /**
  * throws error on failure to create request
  * @param processor wasmprocessor
@@ -148,6 +126,60 @@ export async function getOutsBinJson(processor, params) {
     }
     return result;
 }
+/**
+ * Loads a getBlocks.bin response into the WASM module for later single-block scanning
+ * via repeated calls to scan_block. Unlike getBlocksBinScanResponse, this does not
+ * scan any outputs,it only returns the block metadata (heights, timestamps, hashes).
+ * Each call overwrites the previously stored response, so it can be called repeatedly
+ * without leaking memory.
+ * @param processor the WASM processor used to interface with the Rust module, eg ViewPair in viewpair.ts
+ * @param getBlocksBinResponseBuffer the raw binary response from the get_blocks.bin endpoint
+ * @returns metadata about the loaded blocks (new_height, daemon_height, status, block_infos)
+ */
+export async function loadGetBlocksBinResponse(processor, getBlocksBinResponseBuffer) {
+    processor.writeToWasmMemory = (ptr, len) => {
+        processor.writeArray(ptr, len, getBlocksBinResponseBuffer);
+    };
+    let resultMeta;
+    processor.readFromWasmMemory = (ptr, len) => {
+        resultMeta = JSON.parse(processor.readString(ptr, len));
+    };
+    //@ts-ignore
+    processor.tinywasi.instance.exports.load_get_blocks_bin_response(getBlocksBinResponseBuffer.length);
+    return resultMeta;
+}
+/**
+ * Scans a single block from the previously loaded getBlocks.bin response.
+ * Call loadGetBlocksBinResponse first to load a response into WASM memory.
+ * @param processor the WASM processor
+ * @param blockIndex index of the block within the loaded response (0-based)
+ * @returns scan result with outputs and key images for that one block
+ *
+ * ErrorResponse type:
+ * the error messages come from the rust side in rust/src/:
+ * - "Block index {} out of bounds (total blocks: {})"
+ *   in lib.rs get_blocks_bin_scan_one_block, guards blockIndex against response.blocks.len
+ * - "No getBlocks.bin response loaded. Call loadGetBlocksBinResponse first."
+ *   in lib.rs get_blocks_bin_scan_one_block, when GLOBAL_GET_BLOCKS_BIN_RESPONSE is None
+ * - "Error scanning miner transaction: {}"
+ *   in block_parsing/mod.rs scan_block, scanner.scan_transaction failed when parsing miner tx of block
+ * - "Error scanning block: {}"
+ *   in block_parsing/mod.rs scan_block, scanner.scan(scan_block) failed
+ * all errors are returned as { error: string } (ErrorResponse type)
+ */
+export async function getBlocksBinScanOneBlock(processor, blockIndex) {
+    let result;
+    processor.readFromWasmMemory = (ptr, len) => {
+        result = JSON.parse(processor.readString(ptr, len), (key, value) => {
+            if (key === "amount")
+                return BigInt(value);
+            return value;
+        });
+    };
+    //@ts-ignore
+    processor.tinywasi.instance.exports.get_blocks_bin_scan_one_block(blockIndex);
+    return result;
+}
 export async function binaryFetchRequest(url, body, stopSync) {
     const response = await fetch(url, {
         body: body,
@@ -156,28 +188,14 @@ export async function binaryFetchRequest(url, body, stopSync) {
     });
     if (!response.ok)
         throw new Error(`HTTP ${response.status}`);
-    const reader = response.body.getReader();
-    const chunks = [];
-    let totalBytes = 0;
     const MAX_SIZE = 125829120; // 120MB
-    try {
-        while (true) {
-            const { done, value } = await reader.read();
-            if (done)
-                break;
-            totalBytes += value.length;
-            if (totalBytes > MAX_SIZE)
-                throw new Error(`Response exceeds 120MB (${totalBytes} bytes)`);
-            chunks.push(value);
-        }
-    }
-    catch (readError) {
-        console.error("Reader error:", readError, "Partial bytes:", totalBytes);
-        // Eat the error - continue to return partial data
+    const contentLength = parseInt(response.headers.get("content-length") || "0", 10);
+    if (contentLength > MAX_SIZE) {
+        throw new Error(`Response exceeds 120MB (${contentLength} bytes)`);
     }
-    finally {
-        reader.releaseLock();
+    const buffer = await response.arrayBuffer();
+    if (buffer.byteLength > MAX_SIZE) {
+        throw new Error(`Response exceeds 120MB (${buffer.byteLength} bytes)`);
     }
-    // Always return what we got (even if partial)
-    return Uint8Array.from(chunks.reduce((acc, chunk) => [...acc, ...chunk], []));
+    return new Uint8Array(buffer);
 }