@spirobel/monero-wallet-api 0.5.1 → 0.5.2

package/dist/scanning-syncing/scansettings/scanSettings.js

@@ -0,0 +1,338 @@
+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";
+// default value for subaddress highest minor index eg up to which minor index,
+// to add subaddresses to the scanner
+// (we never touch major index, having two values is just too confusing)
+export const SUB_ADDRESS_INDEX_DEFAULT_VALUE = 1;
+/**
+ * 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 scan_settings_path - 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, scan_settings_path = SCAN_SETTINGS_STORE_NAME_DEFAULT) {
+    return await atomicWrite(scan_settings_path, JSON.stringify(scan_settings, null, 2));
+}
+export async function writeScanSettingsFileDefaultLocation(params) {
+    let settings = await openScanSettingsFile(params.scan_settings_path);
+    if (!settings) {
+        // Create empty ScanSettings object with default values
+        settings = {
+            node_url: LOCAL_NODE_DEFAULT_URL,
+            wallets: [],
+            start_height: null,
+        };
+    }
+    await params.writeCallback(settings);
+    // write to settings file
+    await writeScanSettings(settings, params.scan_settings_path);
+}
+export async function writeStartHeightToScanSettings(start_height, scan_settings_path = SCAN_SETTINGS_STORE_NAME_DEFAULT) {
+    const scanSettings = (await openScanSettingsFile(scan_settings_path)) || {
+        node_url: LOCAL_NODE_DEFAULT_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, scan_settings_path = SCAN_SETTINGS_STORE_NAME_DEFAULT) {
+    const getInfo = await get_info(node_url);
+    const scanSettings = (await openScanSettingsFile(scan_settings_path)) || {
+        node_url: LOCAL_NODE_DEFAULT_URL,
+        wallets: [],
+        start_height: null,
+    };
+    scanSettings.start_height = getInfo.height - 1;
+    await atomicWrite(scan_settings_path, JSON.stringify(scanSettings, null, 2));
+    return getInfo.height;
+}
+export async function cullTooLargeScanHeight(node_url, scan_settings_path = SCAN_SETTINGS_STORE_NAME_DEFAULT) {
+    const getInfo = await get_info(node_url);
+    const scanSettings = (await openScanSettingsFile(scan_settings_path)) || {
+        node_url: LOCAL_NODE_DEFAULT_URL,
+        wallets: [],
+        start_height: null,
+    };
+    if (scanSettings.start_height === null ||
+        scanSettings.start_height > getInfo.height - 1) {
+        scanSettings.start_height = getInfo.height - 1;
+        await atomicWrite(scan_settings_path, JSON.stringify(scanSettings, null, 2));
+    }
+    return scanSettings.start_height;
+}
+export async function writeNodeUrlToScanSettings(node_url, scan_settings_path = SCAN_SETTINGS_STORE_NAME_DEFAULT) {
+    const scanSettings = (await openScanSettingsFile(scan_settings_path)) || {
+        node_url: LOCAL_NODE_DEFAULT_URL,
+        wallets: [],
+        start_height: null,
+    };
+    scanSettings.node_url = node_url;
+    return await atomicWrite(scan_settings_path, JSON.stringify(scanSettings, null, 2));
+}
+export async function readNodeUrlFromScanSettings(scan_settings_path = SCAN_SETTINGS_STORE_NAME_DEFAULT) {
+    const scanSettings = await openScanSettingsFile(scan_settings_path);
+    return scanSettings?.node_url;
+}
+/**
+ * Writes the merchant confirmation threshold to scan settings.
+ *
+ * This setting only has effect when the wallet is run as part of a checkout system,
+ * that accepts payments.
+ * It determines after how many confirmations a transaction is accepted
+ * for a payment. The actual enforcement of this policy is left to the
+ * custom payment-system code that consumes this library.
+ *
+ * @param merchant_confirmations - Number of confirmations required before
+ *   accepting a payment, or `null` to leave it unset.
+ * @param scan_settings_path - Optional path for the settings file.
+ *   Defaults to `SCAN_SETTINGS_STORE_NAME_DEFAULT`.
+ * @returns A promise that resolves when the file is successfully written.
+ */
+export async function writeMerchantConfirmationsToScanSettings(merchant_confirmations, scan_settings_path = SCAN_SETTINGS_STORE_NAME_DEFAULT) {
+    const scanSettings = (await openScanSettingsFile(scan_settings_path)) || {
+        node_url: LOCAL_NODE_DEFAULT_URL,
+        wallets: [],
+        start_height: null,
+    };
+    scanSettings.merchant_confirmations = merchant_confirmations;
+    return await atomicWrite(scan_settings_path, JSON.stringify(scanSettings, null, 2));
+}
+/**
+ * Reads the merchant confirmation threshold from scan settings.
+ *
+ * This setting only has effect when the wallet is run as part of a checkout system,
+ * that accepts payments.
+ *
+ * It determines after how many confirmations a transaction is accepted
+ * for a payment. The actual enforcement of this policy is left to the
+ * custom payment-system code that consumes this library.
+ *
+ * @param scan_settings_path - Optional path for the settings file.
+ *   Defaults to `SCAN_SETTINGS_STORE_NAME_DEFAULT`.
+ * @returns The configured number of confirmations, null, or `undefined`
+ *   if the setting has not been persisted yet.
+ */
+export async function readMerchantConfirmationsFromScanSettings(scan_settings_path = SCAN_SETTINGS_STORE_NAME_DEFAULT) {
+    const scanSettings = await openScanSettingsFile(scan_settings_path);
+    return scanSettings?.merchant_confirmations;
+}
+/**
+ * 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 scan_settings_path - 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 || SUB_ADDRESS_INDEX_DEFAULT_VALUE,
+                    halted: params.halted,
+                    wallet_route: params.wallet_route,
+                    wallet_name: params.wallet_name,
+                    wallet_slot: params.wallet_slot,
+                },
+            ],
+            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
+            : 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 || SUB_ADDRESS_INDEX_DEFAULT_VALUE,
+            halted: params.halted,
+            wallet_route: params.wallet_route,
+            wallet_name: params.wallet_name,
+            wallet_slot: params.wallet_slot,
+        });
+    }
+    else {
+        // wallet already exists
+        const wallet = scanSettings.wallets[already_has_settings];
+        if (wallet) {
+            wallet.subaddress_index =
+                params.subaddress_index ||
+                    wallet.subaddress_index ||
+                    SUB_ADDRESS_INDEX_DEFAULT_VALUE;
+            wallet.halted = params.halted || wallet.halted;
+            wallet.wallet_route = params.wallet_route || wallet.wallet_route;
+            wallet.wallet_name = params.wallet_name || wallet.wallet_name;
+            wallet.wallet_slot = params.wallet_slot || wallet.wallet_slot;
+        }
+    }
+    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 function getNonHaltedWallets(scan_settings) {
+    if (!scan_settings)
+        return [];
+    const nonHaltedWallets = scan_settings.wallets.filter((wallet) => !wallet?.halted);
+    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;
+    }
+}
+/**
+ * Either 1. the consumer explicitly sets a pathprefix, we extract it from the scan_settings_path
+ * or we pick the default which is nothing
+ * @param scan_settings_path optional scan settings path
+ * @param pathPrefix optional path prefix
+ * @returns definite path prefix
+ */
+export function getPathPrefix(scan_settings_path = SCAN_SETTINGS_STORE_NAME_DEFAULT, pathPrefix) {
+    const parts = scan_settings_path.split("/");
+    const basename = parts.pop();
+    const dir = parts.join("/");
+    const prefix = dir ? `${dir}/` : "";
+    return pathPrefix ?? prefix;
+}