@spirobel/monero-wallet-api 0.1.2 → 0.3.0

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

@@ -0,0 +1,84 @@
+import { type KeyImage } from "./computeKeyImage";
+import type { ReorgInfo } from "./reorg";
+import type { BlockInfo, FeeEstimateResponse, GetBlockHeadersRange, GetBlockHeadersRangeParams, Output, SendRawTransactionResult, ViewPair } from "../../api";
+import type { Payment } from "../../send-functionality/inputSelection";
+export declare function initScanCache(viewpair: ViewPair, start_height: number, scan_settings_path?: string, pathPrefix?: string): Promise<CacheRange>;
+export declare function readCacheFile(cacheFilePath: string): Promise<ScanCache | undefined>;
+export declare function cacheFileDefaultLocation(primary_address: string, pathPrefix?: string): string;
+export declare function readCacheFileDefaultLocation(primary_address: string, pathPrefix?: string): Promise<ScanCache | undefined>;
+export type WriteCacheFileParams = {
+    primary_address: string;
+    pathPrefix?: string;
+    writeCallback: (cache: ScanCache) => void | Promise<void>;
+};
+export declare function writeCacheFileDefaultLocationThrows(params: WriteCacheFileParams): Promise<void>;
+export declare function writeCacheToFile(cache: ScanCache, pathPrefix?: string): Promise<number>;
+export declare function lastRange(ranges: CacheRange[]): CacheRange | undefined;
+export declare function mergeRanges(ranges: CacheRange[]): CacheRange[];
+export declare const findRange: (ranges: CacheRange[], value: number) => CacheRange | null;
+export type CacheRange = {
+    start: number;
+    end: number;
+    block_hashes: BlockInfo[];
+};
+export type GlobalOutputId = string;
+export type OutputsCache = Record<GlobalOutputId, Output>;
+export type OwnKeyImages = Record<KeyImage, GlobalOutputId>;
+export type Subaddress = {
+    minor: number;
+    address: string;
+    created_at_height: number;
+    created_at_timestamp: number;
+    not_yet_included?: boolean;
+    received_amount?: bigint;
+    pending_amount?: bigint;
+};
+export type ScanCache = {
+    outputs: OutputsCache;
+    own_key_images: OwnKeyImages;
+    scanned_ranges: CacheRange[];
+    primary_address: string;
+    tx_logs?: TxLog[];
+    pending_spent_utxos?: Record<GlobalOutputId, number>;
+    subaddresses?: Subaddress[];
+    reorg_info?: ReorgInfo;
+    daemon_height: number;
+};
+export type TxLog = {
+    inputs_index: string[];
+    payments: Payment[];
+    node_url: string;
+    height: number;
+    timestamp: number;
+    feeEstimate?: FeeEstimateResponse;
+    sendResult?: SendRawTransactionResult;
+    error?: string;
+};
+export type ChangeReason = "spent" | "added" | "ownspend" | "reorged" | "reorged_spent" | "burned";
+export type ChangedOutput = {
+    output: Output;
+    change_reason: ChangeReason;
+};
+export type CacheChangedCallbackParameters = {
+    newCache: ScanCache;
+    changed_outputs: ChangedOutput[];
+};
+export type CacheChangedCallbackSync<R = void> = (params: CacheChangedCallbackParameters) => R;
+export type CacheChangedCallbackAsync = CacheChangedCallbackSync<Promise<void>>;
+/**
+ * Callback invoked when the scan cache changes.
+ *
+ * @param params - The callback parameters.
+ * @param params.newCache - The updated scan cache.
+ * @param params.changed_outputs - Contains output and change_reason. {@link ChangedOutput}
+ *
+ */
+export type CacheChangedCallback = CacheChangedCallbackSync | CacheChangedCallbackAsync;
+export interface HasGetBlockHeadersRangeMethod {
+    getBlockHeadersRange: (params: GetBlockHeadersRangeParams) => Promise<GetBlockHeadersRange>;
+}
+export interface HasPrimaryAddress {
+    primary_address: string;
+}
+export declare function handleScanError(error: unknown): void;
+export declare function isConnectionError(error: unknown): true | undefined;

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

@@ -0,0 +1,134 @@
+import {} from "./computeKeyImage";
+import { atomicWrite } from "../../io/atomicWrite";
+export async function initScanCache(viewpair, start_height, scan_settings_path, pathPrefix) {
+    const initialCache = await readCacheFileDefaultLocation(viewpair.primary_address, pathPrefix);
+    let cache = {
+        daemon_height: 0,
+        outputs: {},
+        own_key_images: {},
+        scanned_ranges: [],
+        primary_address: viewpair.primary_address,
+    };
+    if (initialCache)
+        cache = initialCache;
+    let current_height = start_height;
+    // merge existing ranges & find end of current range
+    cache.scanned_ranges = mergeRanges(cache.scanned_ranges);
+    let current_range = findRange(cache.scanned_ranges, current_height);
+    let start_block_hash = current_range?.block_hashes[0];
+    if (!start_block_hash) {
+        const blockHeaderResponse = (await viewpair.getBlockHeadersRange({
+            start_height,
+            end_height: start_height,
+        })).headers[0];
+        start_block_hash = {
+            block_hash: blockHeaderResponse.hash,
+            block_height: blockHeaderResponse.height,
+            block_timestamp: blockHeaderResponse.timestamp,
+        };
+        const newRange = {
+            start: start_block_hash.block_height,
+            end: start_block_hash.block_height,
+            block_hashes: [start_block_hash, start_block_hash, start_block_hash],
+        };
+        current_range = newRange;
+        cache.scanned_ranges.push(newRange);
+    }
+    if (!start_block_hash)
+        throw new Error("could not find start block hash");
+    if (current_range == null || !current_range?.block_hashes.length)
+        throw new Error("current_range was malformed. block_hashes is empty");
+    await viewpair.addSubaddressesToScanCache(cache, scan_settings_path);
+    // write to cache
+    await writeCacheToFile(cache, pathPrefix);
+    return current_range;
+}
+export async function readCacheFile(cacheFilePath) {
+    const jsonString = await Bun.file(cacheFilePath)
+        .text()
+        .catch(() => undefined);
+    return jsonString
+        ? JSON.parse(jsonString, (key, value) => {
+            if (key === "amount")
+                return BigInt(value);
+            return value;
+        })
+        : undefined;
+}
+export function cacheFileDefaultLocation(primary_address, pathPrefix) {
+    return `${pathPrefix ?? ""}${primary_address}_cache.json`;
+}
+export async function readCacheFileDefaultLocation(primary_address, pathPrefix) {
+    return await readCacheFile(cacheFileDefaultLocation(primary_address, pathPrefix));
+}
+export async function writeCacheFileDefaultLocationThrows(params) {
+    const cache = await readCacheFileDefaultLocation(params.primary_address, params.pathPrefix);
+    if (!cache)
+        throw new Error(`cache not found for primary address: ${params.primary_address}, and path prefix: ${params.pathPrefix}`);
+    await params.writeCallback(cache);
+    // write to cache
+    await writeCacheToFile(cache, params.pathPrefix);
+}
+export async function writeCacheToFile(cache, pathPrefix) {
+    // write to cache
+    return await atomicWrite(cacheFileDefaultLocation(cache.primary_address, pathPrefix), JSON.stringify(cache, (key, value) => (typeof value === "bigint" ? value.toString() : value), 2));
+}
+export function lastRange(ranges) {
+    if (!ranges.length)
+        return undefined;
+    return ranges.reduce((maxRange, current) => (current.end > maxRange.end ? current : maxRange), ranges[0]);
+}
+export function mergeRanges(ranges) {
+    if (ranges.length <= 1)
+        return ranges.map((r) => ({ ...r }));
+    const sorted = [...ranges].sort((a, b) => a.start - b.start);
+    const merged = [sorted[0]];
+    for (let i = 1; i < sorted.length; i++) {
+        const curr = sorted[i];
+        const last = merged[merged.length - 1];
+        // If last range overlaps or touches current range
+        if (curr.start <= last.end) {
+            // Extend last range to cover both (take max end value)
+            last.end = Math.max(last.end, curr.end);
+            last.block_hashes = curr.block_hashes;
+        }
+        else {
+            // No overlap: add current range as new merged interval
+            merged.push(curr);
+        }
+    }
+    return merged;
+}
+// find the cache range that contains the given height, if not found return null
+export const findRange = (ranges, value) => ranges.find((r) => value >= r.start && value <= r.end) ?? null;
+export function handleScanError(error) {
+    // treat errno 0 code "ConnectionRefused" as non fatal outcome, and rethrow,
+    // so that UI can be informed after catching it higher up
+    if (isConnectionError(error)) {
+        console.log("Scan stopped. node might be offline. Connection Refused");
+        throw error;
+    }
+    // Treat AbortError as a normal, non-fatal outcome
+    if (error &&
+        typeof error === "object" &&
+        (("name" in error && error.name === "AbortError") ||
+            ("code" in error && error.code === 20))) {
+        console.log("Scan was aborted.");
+        return;
+    }
+    else {
+        console.log(error, "\n, scanWithCache in scanning-syncing/scanWithCache.ts`");
+        throw error;
+    }
+}
+export function isConnectionError(error) {
+    if (error &&
+        typeof error === "object" &&
+        (("code" in error && error.code === "ConnectionRefused") ||
+            ("errno" in error && error.errno === 0))) {
+        return true;
+    }
+    else {
+        false;
+    }
+}

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

@@ -0,0 +1,149 @@
+import { ViewPair, type FeeEstimateResponse, type Output, type SendRawTransactionResult } from "../../api";
+import { type Payment } from "../../send-functionality/inputSelection";
+import { type CacheChangedCallback, type CacheChangedCallbackParameters, type ScanCache, type Subaddress, type TxLog } from "./scanCache";
+import { type FoundTransaction, type PrePendingTx } from "./scanStats";
+export type SlaveScanCache = boolean;
+export type ScanCacheOpenedCreateParams = {
+    primary_address: string;
+    scan_settings_path?: string;
+    pathPrefix?: string;
+    no_worker?: boolean;
+    no_stats?: boolean;
+    masterCacheChanged?: CacheChangedCallback;
+    workerError?: (error: unknown) => void;
+};
+export type CreateTransactionParams = {
+    payments: Payment[];
+    inputs?: Output[];
+    no_fee_circuit_breaker?: boolean;
+};
+export declare class ScanCacheOpened {
+    readonly view_pair: ViewPair;
+    readonly wallet_route: string | undefined;
+    readonly no_worker: boolean;
+    readonly masterCacheChanged: CacheChangedCallback | null;
+    private _start_height;
+    private scan_settings_path?;
+    private pathPrefix?;
+    private workerError?;
+    static create(params: ScanCacheOpenedCreateParams): Promise<ScanCacheOpened>;
+    get start_height(): number | null;
+    get current_height(): number | null;
+    get current_top_range_height(): number | null;
+    changeStartHeight(start_height: number | null): Promise<void>;
+    get cache(): ScanCache;
+    get prepending_txs(): PrePendingTx[];
+    get transactions(): FoundTransaction[];
+    get primary_address(): string;
+    get node_url(): string;
+    private set node_url(value);
+    changeNodeUrlAndStartHeight(node_url?: string, start_height?: number | null): Promise<void>;
+    changeNodeUrl(node_url: string): Promise<void>;
+    retry(): Promise<boolean>;
+    sendTransaction(signedTx: string): Promise<SendRawTransactionResult>;
+    signTransaction(unsignedTx: string): Promise<string>;
+    calculateFeeAndSelectInputs(params: CreateTransactionParams): Promise<{
+        selectedInputs: Output[];
+        feeEstimate: {
+            status: string;
+            fee: number;
+            quantization_mask: number;
+            fees?: number[] | undefined;
+        };
+    }>;
+    makeTransactionFromSelectedInputs(payments: Payment[], selectedInputs: Output[], feeEstimate: FeeEstimateResponse): Promise<string>;
+    /**
+     * this function returns the unsigned transaction, throws {@link SendError}
+     */
+    makeTransaction(params: CreateTransactionParams): Promise<string>;
+    get daemon_height(): number;
+    get amount(): bigint;
+    get pending_amount(): bigint;
+    get subaddresses(): Subaddress[];
+    get tx_logs(): TxLog[];
+    makeSignSendTransaction(params: CreateTransactionParams): Promise<SendRawTransactionResult>;
+    /**
+     * makeStandardTransaction
+     */
+    makeStandardTransaction(destination_address: string, amount: string): Promise<string>;
+    /**
+     * makeIntegratedAddress
+     */
+    makeIntegratedAddress(paymentId: number): string;
+    /**
+     * This method makes a Subaddress for the Address of the Viewpair it was opened with.
+     * The network (mainnet, stagenet, testnet) is the same as the one of the Viewpairaddress.
+     * will increment minor by 1 on major 0 in "ScanSettings.json" subaddresses definition
+     *
+     * if there is an active scan going on, call this here on ScanCacheOpened, so the new subaddress will be scanned
+     * (and not on a viewpair / scancacheopened instance that is not conducting the scan, aka where no_worker is true)
+     *
+     * @returns Adressstring
+     */
+    makeSubaddress(): Promise<Subaddress>;
+    /**
+     * notify
+     *
+     * ChangeReason = "added" | "ownspend" | "reorged" | "burned";
+     */
+    notify(callback: CacheChangedCallback): {
+        remove: () => null;
+    };
+    pause(): Promise<number>;
+    stopWorker(): void;
+    unpause(): Promise<number>;
+    /**
+     * selectInputs returns array of inputs, whose sum is larger than amount
+     * adds approximate fee for 10kb transaction to amount if feePerByte is supplied
+     */
+    selectInputs(amount: bigint, feePerByte?: bigint): Output[];
+    /**
+     * selectOneInput larger than amount, (smallest one matching this amount)
+     */
+    selectOneInput(amount: bigint): Output | undefined;
+    /**
+     * selectMultipleInputs larger than amount, sorted from largest to smallest until total reaches amount
+     */
+    selectMultipleInputs(amount: bigint): Output[];
+    /**
+     * get spendableInputs
+     */
+    spendableInputs(): Output[];
+    /**
+     * feed the ScanCacheOpened with new ScanCache as syncing happens
+     * if primary_address does not match, do not feed
+     * if masterCacheChanged is set, it will be called here
+     * for all primary addresses
+     */
+    feed(params: CacheChangedCallbackParameters): Promise<void>;
+    private _cache;
+    private worker?;
+    private constructor();
+    private _stats;
+    private notifyListeners;
+}
+export type ManyScanCachesOpenedCreateOptions = {
+    scan_settings_path?: string;
+    pathPrefix?: string;
+    no_worker?: boolean;
+    notifyMasterChanged?: CacheChangedCallback;
+    no_stats?: boolean;
+    workerError?: (error: unknown) => void;
+};
+export declare class ManyScanCachesOpened {
+    readonly wallets: ScanCacheOpened[];
+    get start_height(): number | null;
+    get current_height(): number | null;
+    get node_url(): string;
+    changeNodeUrlAndStartHeight(node_url?: string, start_height?: number | null): Promise<void>;
+    retry(): Promise<boolean>;
+    stopWorker(): void;
+    changeNodeUrl(node_url: string): Promise<void>;
+    changeStartHeight(start_height: number | null): Promise<void>;
+    static create({ scan_settings_path, pathPrefix, no_worker, notifyMasterChanged, no_stats, workerError, }: ManyScanCachesOpenedCreateOptions): Promise<ManyScanCachesOpened | undefined>;
+    /**
+     * feed the master wallet and therefore all wallets
+     */
+    feed(params: CacheChangedCallbackParameters): Promise<void>;
+    private constructor();
+}