@spirobel/monero-wallet-api 0.2.0 → 0.3.1

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

@@ -0,0 +1,28 @@
+import { ManyScanCachesOpened, ScanCacheOpened, type ManyScanCachesOpenedCreateOptions } from "./scanresult/scanCacheOpened";
+/**
+ * Opens all **non halted wallets listed in ScanSettings.json** for scanning.
+ *
+ * @param options.scan_settings_path if you want to use a different settings file other than the default "ScanSettings.json"
+ * @param options.pathPrefix if you want to keep wallet scan caches, getblocksbinbuffer in a different directory
+ * @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
+ * @returns Promise<ManyScanCachesOpened>
+ */
+export declare function openWallets(options?: ManyScanCachesOpenedCreateOptions): Promise<ManyScanCachesOpened | undefined>;
+/**
+ * Opens a **single wallet** for scanning.
+ * **Touches ScanSettings.json**,
+ *  halts all other wallets and scans only this wallet (use `openWallets()` for scanning all non halted wallets in the settings file).
+ *
+ * Scan runs in a worker thread to not block the main thread.
+ *
+ * @param primary_address Wallet address
+ * @param scan_settings_path if you want to use a different settings file other than the default "ScanSettings.json"
+ * @param pathPrefix if you want to keep wallet scan caches, getblocksbinbuffer in a different directory
+ * @param 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
+ * @returns Promise<ScanCacheOpened>
+ */
+export declare function openWallet(primary_address: string, scan_settings_path?: string, pathPrefix?: string, no_worker?: boolean, no_stats?: boolean): Promise<ScanCacheOpened>;
+export declare function haltAllWalletsExcept(primary_address: string, scan_settings_path?: string): Promise<void>;

package/dist/scanning-syncing/openWallet.js

@@ -0,0 +1,57 @@
+import { ManyScanCachesOpened, ScanCacheOpened, } from "./scanresult/scanCacheOpened";
+import { openScanSettingsFile, writeWalletToScanSettings, } from "./scanSettings";
+/**
+ * Opens all **non halted wallets listed in ScanSettings.json** for scanning.
+ *
+ * @param options.scan_settings_path if you want to use a different settings file other than the default "ScanSettings.json"
+ * @param options.pathPrefix if you want to keep wallet scan caches, getblocksbinbuffer in a different directory
+ * @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
+ * @returns Promise<ManyScanCachesOpened>
+ */
+export async function openWallets(options) {
+    return await ManyScanCachesOpened.create(options ?? {});
+}
+/**
+ * Opens a **single wallet** for scanning.
+ * **Touches ScanSettings.json**,
+ *  halts all other wallets and scans only this wallet (use `openWallets()` for scanning all non halted wallets in the settings file).
+ *
+ * Scan runs in a worker thread to not block the main thread.
+ *
+ * @param primary_address Wallet address
+ * @param scan_settings_path if you want to use a different settings file other than the default "ScanSettings.json"
+ * @param pathPrefix if you want to keep wallet scan caches, getblocksbinbuffer in a different directory
+ * @param 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
+ * @returns Promise<ScanCacheOpened>
+ */
+export async function openWallet(primary_address, scan_settings_path, pathPrefix, no_worker, no_stats) {
+    await haltAllWalletsExcept(primary_address, scan_settings_path);
+    return await ScanCacheOpened.create({
+        primary_address,
+        scan_settings_path,
+        pathPrefix,
+        no_worker,
+        no_stats,
+    });
+}
+export async function haltAllWalletsExcept(primary_address, scan_settings_path) {
+    const scan_settings = await openScanSettingsFile(scan_settings_path);
+    if (!scan_settings?.wallets)
+        return;
+    const nonHaltedWallets = scan_settings.wallets.filter((wallet) => !wallet?.halted);
+    for (const wallet of nonHaltedWallets) {
+        await writeWalletToScanSettings({
+            primary_address: wallet.primary_address, // halt all wallets
+            halted: true,
+            scan_settings_path,
+        });
+    }
+    await writeWalletToScanSettings({
+        primary_address, // unhalt this wallet
+        halted: false,
+        scan_settings_path,
+    });
+}

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

@@ -0,0 +1,96 @@
+export declare const SCAN_SETTINGS_STORE_NAME_DEFAULT = "ScanSettings.json";
+export type ScanSetting = {
+    primary_address: string;
+    subaddress_index?: number;
+    halted?: boolean;
+    wallet_route?: string;
+};
+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;
+};
+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;
+};
+export type ScanSettings = {
+    wallets: ScanSetting[];
+    node_url: string;
+    start_height: number | null;
+};
+export type ScanSettingsOpened = {
+    wallets: (ScanSettingOpened | undefined)[];
+    node_url: string;
+    start_height: number | null;
+};
+/**
+ * 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 settingsStorePath - 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, settingsStorePath?: string): Promise<number>;
+export declare function writeStartHeightToScanSettings(start_height: number | null, settingsStorePath?: string): Promise<number>;
+export declare function writeDaemonHeightAsStartHeightToScanSettings(node_url: string, settingsStorePath?: string): Promise<number>;
+export declare function cullTooLargeScanHeight(node_url: string, settingsStorePath?: string): Promise<number>;
+export declare function writeNodeUrlToScanSettings(node_url: string, settingsStorePath?: string): Promise<number>;
+export declare function readNodeUrlFromScanSettings(settingsStorePath?: string): Promise<string | 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 settingsStorePath - 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;
+}>;
+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 doesScanSettingsFileExist(scan_settings_path?: string): Promise<boolean>;

package/dist/scanning-syncing/scanSettings.js

@@ -0,0 +1,240 @@
+import { get_info } from "../api";
+import { atomicWrite } from "../io/atomicWrite";
+import { refreshEnvIndexedDB } from "../io/indexedDB";
+import { LOCAL_NODE_DEFAULT_URL } from "../node-interaction/nodeUrl";
+export const SCAN_SETTINGS_STORE_NAME_DEFAULT = "ScanSettings.json";
+/**
+ * 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 settingsStorePath - 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 async function writeScanSettings(scan_settings, settingsStorePath = SCAN_SETTINGS_STORE_NAME_DEFAULT) {
+    return await atomicWrite(settingsStorePath, JSON.stringify(scan_settings, null, 2));
+}
+export async function writeStartHeightToScanSettings(start_height, settingsStorePath = SCAN_SETTINGS_STORE_NAME_DEFAULT) {
+    const scanSettings = (await openScanSettingsFile(settingsStorePath)) || {
+        node_url: "",
+        wallets: [],
+        start_height: null,
+    };
+    scanSettings.start_height = start_height;
+    return await atomicWrite(SCAN_SETTINGS_STORE_NAME_DEFAULT, JSON.stringify(scanSettings, null, 2));
+}
+export async function writeDaemonHeightAsStartHeightToScanSettings(node_url, settingsStorePath = SCAN_SETTINGS_STORE_NAME_DEFAULT) {
+    const getInfo = await get_info(node_url);
+    const scanSettings = (await openScanSettingsFile(settingsStorePath)) || {
+        node_url: "",
+        wallets: [],
+        start_height: null,
+    };
+    scanSettings.start_height = getInfo.height - 1;
+    await atomicWrite(settingsStorePath, JSON.stringify(scanSettings, null, 2));
+    return getInfo.height;
+}
+export async function cullTooLargeScanHeight(node_url, settingsStorePath = SCAN_SETTINGS_STORE_NAME_DEFAULT) {
+    const getInfo = await get_info(node_url);
+    const scanSettings = (await openScanSettingsFile(settingsStorePath)) || {
+        node_url: "",
+        wallets: [],
+        start_height: null,
+    };
+    if (scanSettings.start_height === null ||
+        scanSettings.start_height > getInfo.height - 1) {
+        scanSettings.start_height = getInfo.height - 1;
+        await atomicWrite(settingsStorePath, JSON.stringify(scanSettings, null, 2));
+    }
+    return scanSettings.start_height;
+}
+export async function writeNodeUrlToScanSettings(node_url, settingsStorePath = SCAN_SETTINGS_STORE_NAME_DEFAULT) {
+    const scanSettings = (await openScanSettingsFile(settingsStorePath)) || {
+        node_url: "",
+        wallets: [],
+        start_height: null,
+    };
+    scanSettings.node_url = node_url;
+    return await atomicWrite(settingsStorePath, JSON.stringify(scanSettings, null, 2));
+}
+export async function readNodeUrlFromScanSettings(settingsStorePath = SCAN_SETTINGS_STORE_NAME_DEFAULT) {
+    const scanSettings = await openScanSettingsFile(settingsStorePath);
+    return scanSettings?.node_url;
+}
+/**
+ * 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 settingsStorePath - 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 async function readScanSettings(scan_settings_path = SCAN_SETTINGS_STORE_NAME_DEFAULT) {
+    const scanSettings = await openScanSettingsFile(scan_settings_path);
+    if (!scanSettings)
+        return undefined;
+    const openScanSettings = Object.assign({}, scanSettings);
+    for (const [i, wallet] of scanSettings.wallets.entries()) {
+        if (!wallet.primary_address)
+            throw new Error("The entry ${i} in the wallet settings list in ${scan_settings_path} has no primary address");
+        const walletWithKeys = await walletSettingsPlusKeys({
+            ...wallet,
+            node_url: scanSettings.node_url,
+            start_height: scanSettings.start_height,
+        });
+        openScanSettings.wallets[i].secret_view_key =
+            walletWithKeys.secret_view_key;
+        openScanSettings.wallets[i].secret_spend_key =
+            walletWithKeys.secret_spend_key;
+    }
+    return openScanSettings;
+}
+export function readPrivateSpendKeyFromEnv(primary_address) {
+    return Bun.env["sk" + primary_address];
+}
+export function readPrivateViewKeyFromEnv(primary_address) {
+    return Bun.env["vk" + primary_address];
+}
+export async function readWalletFromScanSettings(primary_address, scan_settings_path = SCAN_SETTINGS_STORE_NAME_DEFAULT) {
+    const scanSettings = await openScanSettingsFile(scan_settings_path);
+    if (!scanSettings)
+        return undefined;
+    const walletSettings = scanSettings.wallets.find((wallet) => wallet?.primary_address === 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: ${scan_settings_path}
+      Or wrong primary_address supplied params.primary_address: ${primary_address}`);
+    return {
+        ...walletSettings,
+        node_url: scanSettings.node_url,
+        start_height: scanSettings.start_height,
+    };
+}
+export async function readWalletsFromScanSettings(scan_settings_path = SCAN_SETTINGS_STORE_NAME_DEFAULT) {
+    const scanSettings = await openScanSettingsFile(scan_settings_path);
+    const scanSettingsOpened = [];
+    for (const wallet of scanSettings?.wallets || []) {
+        scanSettingsOpened.push({
+            ...wallet,
+            node_url: scanSettings?.node_url || LOCAL_NODE_DEFAULT_URL,
+            start_height: scanSettings?.start_height || null,
+        });
+    }
+    return scanSettingsOpened;
+}
+export async function walletSettingsPlusKeys(wallet_settings, secret_view_key, secret_spend_key) {
+    // read secret_view_key and secret_spend_key from env
+    if (!secret_view_key)
+        secret_view_key = Bun.env[`vk${wallet_settings.primary_address}`];
+    if (!secret_view_key) {
+        await refreshEnvIndexedDB();
+        secret_view_key = Bun.env[`vk${wallet_settings.primary_address}`];
+    }
+    if (!secret_view_key)
+        throw ("no secret_view_key provided and not found in env for address: " +
+            wallet_settings.primary_address);
+    if (!secret_spend_key)
+        secret_spend_key = Bun.env[`sk${wallet_settings.primary_address}`];
+    return {
+        ...wallet_settings,
+        secret_view_key,
+        secret_spend_key,
+    };
+}
+export async function writeWalletToScanSettings(params) {
+    if (!params.scan_settings_path)
+        params.scan_settings_path = SCAN_SETTINGS_STORE_NAME_DEFAULT;
+    if (!params.primary_address)
+        throw new Error("no primary address provided to writeWalletToScanSettings()");
+    const scanSettings = await openScanSettingsFile(params.scan_settings_path);
+    if (!scanSettings) {
+        if (!params.node_url)
+            params.node_url = LOCAL_NODE_DEFAULT_URL;
+        // case: no scan settings exist yet
+        return await writeScanSettings({
+            wallets: [
+                {
+                    primary_address: params.primary_address,
+                    subaddress_index: params.subaddress_index || 1,
+                    halted: params.halted,
+                    wallet_route: params.wallet_route,
+                },
+            ],
+            node_url: params.node_url,
+            start_height: params.start_height || null,
+        }, params.scan_settings_path);
+    }
+    scanSettings.node_url = params.node_url || scanSettings.node_url;
+    scanSettings.start_height =
+        params.start_height === undefined
+            ? scanSettings.start_height
+            : params.start_height;
+    const already_has_settings = scanSettings.wallets.findIndex((wallet) => wallet?.primary_address === params.primary_address);
+    if (already_has_settings === -1) {
+        // wallet does not exist yet in settings
+        scanSettings.wallets.push({
+            primary_address: params.primary_address,
+            subaddress_index: params.subaddress_index || 1,
+            halted: params.halted,
+            wallet_route: params.wallet_route,
+        });
+    }
+    else {
+        // wallet already exists
+        const wallet = scanSettings.wallets[already_has_settings];
+        if (wallet) {
+            wallet.subaddress_index =
+                params.subaddress_index || wallet.subaddress_index || 1;
+            wallet.halted = params.halted || wallet.halted;
+            wallet.wallet_route = params.wallet_route || wallet.wallet_route;
+        }
+    }
+    return await atomicWrite(params.scan_settings_path, JSON.stringify(scanSettings, null, 2));
+}
+export async function openScanSettingsFile(scan_settings_path = SCAN_SETTINGS_STORE_NAME_DEFAULT) {
+    const jsonString = await Bun.file(scan_settings_path)
+        .text()
+        .catch(() => undefined);
+    return jsonString ? JSON.parse(jsonString) : undefined;
+}
+export async function openNonHaltedWallets(scan_settings_path = SCAN_SETTINGS_STORE_NAME_DEFAULT) {
+    const scan_settings = await readWalletsFromScanSettings(scan_settings_path);
+    if (!scan_settings)
+        throw new Error("no scan settings file found at path: " + scan_settings_path);
+    if (!scan_settings)
+        throw new Error("no wallets in scan settings");
+    const nonHaltedWallets = scan_settings.filter((wallet) => !wallet?.halted);
+    if (!nonHaltedWallets.length)
+        throw new Error("no non halted wallets in scan settings");
+    return nonHaltedWallets;
+}
+export async function doesScanSettingsFileExist(scan_settings_path = SCAN_SETTINGS_STORE_NAME_DEFAULT) {
+    const scan_settings_file_content = await Bun.file(scan_settings_path)
+        .text()
+        .catch(() => "");
+    if (scan_settings_file_content.length) {
+        return true;
+    }
+    else {
+        return false;
+    }
+}

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

@@ -0,0 +1,3 @@
+import type { Output } from "../../api";
+export type KeyImage = string;
+export declare function computeKeyImage(output: Output, sender_spend_key: string): Promise<KeyImage | undefined>;

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

@@ -0,0 +1,21 @@
+import { WasmProcessor } from "../../wasm-processing/wasmProcessor";
+export async function computeKeyImage(output, sender_spend_key) {
+    const wasmProcessor = await WasmProcessor.init();
+    wasmProcessor.writeToWasmMemory = (ptr, len) => {
+        wasmProcessor.writeString(ptr, len, output.serialized);
+        wasmProcessor.writeToWasmMemory = (ptr, len) => {
+            wasmProcessor.writeString(ptr, len, sender_spend_key);
+        };
+    };
+    let result = undefined;
+    wasmProcessor.readFromWasmMemory = (ptr, len) => {
+        result = JSON.parse(wasmProcessor.readString(ptr, len));
+    };
+    //@ts-ignore
+    wasmProcessor.tinywasi.instance.exports.compute_key_image(output.serialized.length, sender_spend_key.length);
+    if (!result) {
+        throw new Error("Failed to compute key image for output with global id: " +
+            output.index_on_blockchain);
+    }
+    return result["key_image"];
+}

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

@@ -0,0 +1,28 @@
+import type { BlockInfo, GetBlocksBinRequest, ViewPair } from "../../api";
+import type { ScanSetting } from "../scanSettings";
+import { type CacheRange } from "./scanCache";
+export declare function writeGetblocksBinBuffer(getBlocksBinResponseContent: Uint8Array, block_infos: BlockInfo[], pathPrefix?: string): Promise<number | undefined>;
+export type GetBlocksBinBufferItem = {
+    start: number;
+    end: number;
+    filename: string;
+    date: string;
+    last_block_hash: string;
+};
+export declare function readGetblocksBinBuffer(current_height: number, pathPrefix?: string): Promise<GetBlocksBinBufferItem[]>;
+export type BlocksGenerator = AsyncGenerator<Uint8Array>;
+export type SlaveViewPair = {
+    viewpair: ViewPair;
+    current_range: CacheRange;
+    secret_spend_key?: string;
+};
+declare module "bun" {
+    interface BunFile {
+        delete(): Promise<void>;
+    }
+}
+export declare function trimGetBlocksBinBuffer(nonHaltedWallets: ScanSetting[], pathPrefix?: string): Promise<void>;
+export declare function readGetblocksBinBufferItems(pathPrefix?: string): Promise<GetBlocksBinBufferItem[]>;
+export interface HasGetBlocksBinExecuteRequestMethod {
+    getBlocksBinExecuteRequest: (params: GetBlocksBinRequest, stopSync?: AbortSignal) => Promise<Uint8Array>;
+}

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

@@ -0,0 +1,52 @@
+import { atomicWrite } from "../../io/atomicWrite";
+import { readDir } from "../../io/readDir";
+import { readCacheFileDefaultLocation } from "./scanCache";
+export async function writeGetblocksBinBuffer(getBlocksBinResponseContent, block_infos, pathPrefix) {
+    if (!block_infos.length)
+        return;
+    const start = block_infos[0].block_height;
+    const end = block_infos.at(-1)?.block_height;
+    const block_hash = block_infos.at(-1)?.block_hash;
+    const bufferItems = await readGetblocksBinBufferItems(pathPrefix);
+    if (bufferItems.find((bi) => bi.last_block_hash === block_hash))
+        return;
+    // if we have the same end blockhash already, dont write
+    return await atomicWrite(`${pathPrefix ?? ""}getblocksbinbuffer/${Date.now()}-${start}-${end}-${block_hash}-getblocks.bin`, getBlocksBinResponseContent);
+}
+export async function readGetblocksBinBuffer(current_height, pathPrefix) {
+    const bufferItems = await readGetblocksBinBufferItems(pathPrefix);
+    const start_buffer = bufferItems.find((r) => current_height >= r.start && current_height <= r.end) ?? null;
+    if (start_buffer)
+        return [
+            start_buffer,
+            ...bufferItems.filter((r) => r.date > start_buffer?.date),
+        ];
+    return [];
+}
+export async function trimGetBlocksBinBuffer(nonHaltedWallets, pathPrefix) {
+    const snail = Math.min(...(await Promise.all(nonHaltedWallets
+        .slice(1)
+        .map(async (wallet) => (await readCacheFileDefaultLocation(wallet.primary_address, pathPrefix))?.scanned_ranges[0]?.end))).filter((x) => x !== undefined));
+    // if all wallets have  higher start than end of blocksbufferitem, delete
+    const bufferItems = await readGetblocksBinBufferItems(pathPrefix);
+    for (const bufferItem of bufferItems) {
+        if (bufferItem.end <= snail) {
+            await Bun.file(`${pathPrefix ?? ""}getblocksbinbuffer/${bufferItem.filename}`).delete();
+        }
+    }
+}
+export async function readGetblocksBinBufferItems(pathPrefix) {
+    const bufferItems = await readDir(`${pathPrefix ?? ""}getblocksbinbuffer/`).catch(() => []);
+    const ranges = [];
+    for (const filename of bufferItems) {
+        const [date, start, end, last_block_hash] = filename.split("-");
+        ranges.push({
+            start: parseInt(start),
+            end: parseInt(end),
+            filename,
+            date,
+            last_block_hash,
+        });
+    }
+    return ranges;
+}

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

@@ -0,0 +1,14 @@
+import type { BlockInfo, Output } from "../../api";
+import type { KeyImage } from "./computeKeyImage";
+import { type ScanResult } from "./scanResult";
+import type { CacheRange, ChangedOutput, ScanCache } from "./scanCache";
+export type ReorgInfo = {
+    split_height: BlockInfo;
+    removed_outputs: ReorgedOutput[];
+    reverted_spends: ReorgedOutput[];
+};
+export type ReorgedOutput = {
+    old_output_state: Output;
+    key_image: KeyImage;
+};
+export declare function handleReorg(current_range: CacheRange, result: ScanResult, cache: ScanCache, oldRange: CacheRange): [CacheRange, ChangedOutput[]];

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

@@ -0,0 +1,78 @@
+import { makeNewRange } from "./scanResult";
+export function handleReorg(current_range, result, cache, oldRange) {
+    let changed_outputs = [];
+    // we need to check where anchor candidate is and if not found, try the same for anchor
+    // if else throw on catastrophic reorg
+    for (const block_hash of oldRange.block_hashes) {
+        const split_height_index = result.block_infos.findIndex((b) => b.block_hash === block_hash.block_hash);
+        const split_height = result.block_infos[split_height_index];
+        // still a chance to find the split height, (could be candidate_anchor or anchor)
+        if (!split_height)
+            continue;
+        // we found the split height & do the reorg
+        const reorg_info = {
+            split_height,
+            removed_outputs: [],
+            reverted_spends: [],
+        };
+        const removed_outputs = Object.entries(cache.outputs).filter(([id, output]) => output.block_height >= split_height.block_height);
+        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
+            reorg_info.removed_outputs.push({ old_output_state, key_image });
+            // 2. remove from outputs and own_key_images
+            delete cache.outputs[id];
+            delete cache.own_key_images[key_image];
+            changed_outputs.push({
+                output: old_output_state,
+                change_reason: "reorged",
+            });
+        }
+        //for reverted spents, just do the same again with spent_height
+        const reverted_outputs = Object.entries(cache.outputs).filter(([id, output]) => output.spent_block_height !== undefined &&
+            output.spent_block_height >= split_height.block_height);
+        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);
+            reorg_info.reverted_spends.push({
+                old_output_state,
+                key_image, // in this case key_image only used here, does not get removed
+            });
+            // remove spend info from original cache
+            delete cache.outputs[id].spent_relative_index;
+            delete cache.outputs[id].spent_in_tx_hash;
+            delete cache.outputs[id].spent_block_height;
+            delete cache.outputs[id].spent_block_timestamp;
+            changed_outputs.push({
+                output: old_output_state,
+                change_reason: "reorged_spent",
+            });
+        }
+        // find current range in scanned ranges and change its end value + latest_block_hash
+        oldRange.end = split_height.block_height;
+        oldRange.block_hashes[0] = split_height;
+        cache.reorg_info = reorg_info;
+        // fix current_range
+        let anchor = result.block_infos.slice(-100)[0]; // if we got lots of new blocks
+        const old_anchor = oldRange.block_hashes.at(-1);
+        if (!anchor &&
+            old_anchor &&
+            split_height.block_height > old_anchor.block_height //if we did not get many new blocks + split height was candidate anchor
+        ) {
+            anchor = old_anchor; // we keep the anchor the same
+        }
+        if (!anchor)
+            anchor = split_height;
+        let last_block_hash_of_result = result.block_infos.at(-1);
+        const end = last_block_hash_of_result.block_height;
+        const start = current_range.start > end ? end : current_range.start;
+        const newRange = {
+            start,
+            end,
+            block_hashes: [last_block_hash_of_result, anchor, anchor],
+        };
+        return [makeNewRange(newRange, cache), changed_outputs];
+    }
+    // we tried all the block hashes and could not find the split height
+    throw new Error("Could not find reorg split height. Most likely connected to faulty node / catastrophic reorg.");
+}