@spirobel/monero-wallet-api 0.4.1 → 0.5.1

package/dist/multisig/MultiSigTxSigner.js

@@ -0,0 +1,123 @@
+import { frost_dkg_wasm } from "../wasm-processing/wasmFile";
+import { WasmProcessor } from "../wasm-processing/wasmProcessor";
+export class MultiSigTxSigner extends WasmProcessor {
+    static async create() {
+        const signer = new MultiSigTxSigner();
+        await signer.initWasmModule(frost_dkg_wasm);
+        return signer;
+    }
+    /**
+     * preprocess
+     *
+     * @param params threshold_key hex, unsigned_tx hex
+     * @returns preprocess hex
+     */
+    preprocess(params) {
+        const result = this.preprocessNoThrow(params);
+        if ("message" in result) {
+            throw new Error(`preprocess failed: ${result.message}`);
+        }
+        return result;
+    }
+    /**
+     * preprocess -  does not throw, with return error type
+     *
+     * @param params threshold_key hex, unsigned_tx hex
+     * @returns preprocess hex
+     */
+    preprocessNoThrow(params) {
+        const jsonStr = JSON.stringify(params);
+        this.writeToWasmMemory = (ptr, len) => {
+            this.writeString(ptr, len, jsonStr);
+        };
+        let result;
+        this.readFromWasmMemory = (ptr, len) => {
+            result = JSON.parse(this.readString(ptr, len));
+        };
+        this.readErrorFromWasmMemory = (ptr, len) => {
+            result = JSON.parse(this.readString(ptr, len));
+        };
+        //@ts-ignore
+        this.tinywasi.instance.exports.monero_preprocess(jsonStr.length);
+        if (!result) {
+            return { message: "No response from monero_preprocess" };
+        }
+        return result;
+    }
+    /**
+     * sign
+     *
+     * @param params preprocesses map from all signers
+     * @returns share hex
+     */
+    sign(params) {
+        const result = this.signNoThrow(params);
+        if ("message" in result) {
+            throw new Error(`sign failed: ${result.message}`);
+        }
+        return result;
+    }
+    /**
+     * sign -  does not throw, with return error type
+     *
+     * @param params preprocesses map from all signers
+     * @returns share hex
+     */
+    signNoThrow(params) {
+        const jsonStr = JSON.stringify(params);
+        this.writeToWasmMemory = (ptr, len) => {
+            this.writeString(ptr, len, jsonStr);
+        };
+        let result;
+        this.readFromWasmMemory = (ptr, len) => {
+            result = JSON.parse(this.readString(ptr, len));
+        };
+        this.readErrorFromWasmMemory = (ptr, len) => {
+            result = JSON.parse(this.readString(ptr, len));
+        };
+        //@ts-ignore
+        this.tinywasi.instance.exports.monero_sign(jsonStr.length);
+        if (!result) {
+            return { message: "No response from monero_sign" };
+        }
+        return result;
+    }
+    /**
+     * complete
+     *
+     * @param params shares map from all signers
+     * @returns signed_tx hex
+     */
+    complete(params) {
+        const result = this.completeNoThrow(params);
+        if ("message" in result) {
+            throw new Error(`complete failed: ${result.message}`);
+        }
+        return result;
+    }
+    /**
+     * complete -  does not throw, with return error type
+     *
+     * @param params shares map from all signers
+     * @returns signed_tx hex
+     */
+    completeNoThrow(params) {
+        const jsonStr = JSON.stringify(params);
+        this.writeToWasmMemory = (ptr, len) => {
+            this.writeString(ptr, len, jsonStr);
+        };
+        let result;
+        this.readFromWasmMemory = (ptr, len) => {
+            result = JSON.parse(this.readString(ptr, len));
+        };
+        this.readErrorFromWasmMemory = (ptr, len) => {
+            result = JSON.parse(this.readString(ptr, len));
+        };
+        //@ts-ignore
+        this.tinywasi.instance.exports.monero_complete(jsonStr.length);
+        if (!result) {
+            return { message: "No response from monero_complete" };
+        }
+        return result;
+    }
+}

package/dist/multisig/escrow.d.ts

@@ -0,0 +1,58 @@
+export declare function makeEscrowContext(context_index: number): {
+    ok: boolean;
+    error: string;
+    context?: undefined;
+    context_index?: undefined;
+} | {
+    ok: boolean;
+    context: string;
+    context_index: number;
+    error?: undefined;
+};
+export declare function parseEscrowContext(input: string): {
+    ok: boolean;
+    error: string;
+    context?: undefined;
+    context_index?: undefined;
+} | {
+    ok: boolean;
+    context: string;
+    context_index: string;
+    error?: undefined;
+};
+/**
+ * To give users the ability to conveniently partake in escrow transactions,
+ * the necessary secrets need to be organized well.
+ *
+ * The seedphrase package in this repository provides methods to derive
+ * secrets from a "walletroute" and a bip39 seedphrase.
+ *
+ * The "walletroute" is a string that is human readable and gives
+ * information on the context the wallet is created for.
+ *
+ * getWalletSecret() in the seedphrase package returns:
+ * 64 bytes of key data - uses KDF ( bip39.mnemonicToSeedSync of noble bip39)
+ *
+ * We use this method to derive the escrow-viewpair-comms secret from the
+ * "comms" key type of a walletroute. (consult the seedphrase package readme for more information)
+ *
+ * @param bip39_secret : 64 bytes key data
+ * @returns 32 bytes secret
+ */
+export declare function deriveEscrowViewpairCommsSecret(bip39_secret: Uint8Array): Uint8Array<ArrayBufferLike> & Uint8Array<ArrayBuffer>;
+export declare function escrowViewPairECDHgetPublicKey(vp_comms_secret: Uint8Array): Uint8Array<ArrayBufferLike> & Uint8Array<ArrayBuffer>;
+/**
+ * In the typical escrow setup, from the perspective of the customer,
+ * the customer_sk is used together with the merchant pk to make the
+ * escrow wallet viewpair.
+ *
+ * From the perspective of the merchant,
+ *  the merchant_sk is used together with the customer pk to make the
+ * escrow wallet viewpair.
+ *
+ * In the dispute flow case, the disputer shares the shared secret,
+ * that resulted from this ECDH exchange with the arbitrator.
+ * @param alice_sk - your viewpair secret
+ * @param bob_pk - the other multisig (escrow) party's viewpair public key
+ */
+export declare function performEscrowViewPairECDH(alice_sk: Uint8Array, bob_pk: Uint8Array): Promise<string>;

package/dist/multisig/escrow.js

@@ -0,0 +1,104 @@
+import { ed25519, x25519 } from "@noble/curves/ed25519.js";
+import { numberToBytesLE } from "@noble/curves/utils.js";
+import { blake3 } from "@noble/hashes/blake3.js";
+import { vk_from_entropy } from "../api";
+export function makeEscrowContext(context_index) {
+    if (Number.isNaN(parseInt(String(context_index)))) {
+        return { ok: false, error: `invalid context_index: "${context_index}"` };
+    }
+    if (parseInt(String(context_index)) < 0) {
+        return {
+            ok: false,
+            error: `invalid context_index: "${context_index} < 0"`,
+        };
+    }
+    if (parseInt(String(context_index)) > 10000) {
+        return {
+            ok: false,
+            error: `invalid context_index: "${context_index} > 10000"`,
+        };
+    }
+    const context = "escrow-" + String(context_index);
+    return { ok: true, context, context_index };
+}
+export function parseEscrowContext(input) {
+    const parts = input.split("-");
+    if (parts.length < 1 || !parts[0] || parts[0] !== "escrow") {
+        return {
+            ok: false,
+            error: "missing escrow string before - ${context_index}",
+        };
+    }
+    const context_index = parts[1];
+    if (Number.isNaN(parseInt(String(context_index)))) {
+        return { ok: false, error: `invalid context_index: "${context_index}"` };
+    }
+    if (parseInt(String(context_index)) < 0) {
+        return {
+            ok: false,
+            error: `invalid context_index: "${context_index} < 0"`,
+        };
+    }
+    if (parseInt(String(context_index)) > 10000) {
+        return {
+            ok: false,
+            error: `invalid context_index: "${context_index} > 10000"`,
+        };
+    }
+    const context = "escrow-" + String(context_index);
+    return { ok: true, context, context_index };
+}
+/**
+ * To give users the ability to conveniently partake in escrow transactions,
+ * the necessary secrets need to be organized well.
+ *
+ * The seedphrase package in this repository provides methods to derive
+ * secrets from a "walletroute" and a bip39 seedphrase.
+ *
+ * The "walletroute" is a string that is human readable and gives
+ * information on the context the wallet is created for.
+ *
+ * getWalletSecret() in the seedphrase package returns:
+ * 64 bytes of key data - uses KDF ( bip39.mnemonicToSeedSync of noble bip39)
+ *
+ * We use this method to derive the escrow-viewpair-comms secret from the
+ * "comms" key type of a walletroute. (consult the seedphrase package readme for more information)
+ *
+ * @param bip39_secret : 64 bytes key data
+ * @returns 32 bytes secret
+ */
+export function deriveEscrowViewpairCommsSecret(bip39_secret) {
+    if (bip39_secret.length !== 64) {
+        throw new Error("expected exactly 64 bytes for Multisig secret viewkey");
+    }
+    const txt = new TextEncoder();
+    return blake3(bip39_secret, { context: txt.encode("escrow-viewpair-comms") });
+}
+export function escrowViewPairECDHgetPublicKey(vp_comms_secret) {
+    return ed25519.getPublicKey(vp_comms_secret);
+}
+/**
+ * In the typical escrow setup, from the perspective of the customer,
+ * the customer_sk is used together with the merchant pk to make the
+ * escrow wallet viewpair.
+ *
+ * From the perspective of the merchant,
+ *  the merchant_sk is used together with the customer pk to make the
+ * escrow wallet viewpair.
+ *
+ * In the dispute flow case, the disputer shares the shared secret,
+ * that resulted from this ECDH exchange with the arbitrator.
+ * @param alice_sk - your viewpair secret
+ * @param bob_pk - the other multisig (escrow) party's viewpair public key
+ */
+export async function performEscrowViewPairECDH(alice_sk, bob_pk) {
+    const txt = new TextEncoder();
+    const aliceSecX = ed25519.utils.toMontgomerySecret(alice_sk);
+    const bobPubX = ed25519.utils.toMontgomery(bob_pk);
+    const sharedKey = x25519.getSharedSecret(aliceSecX, bobPubX);
+    const sharedSecret = blake3(sharedKey, {
+        context: txt.encode("escrow-viewpair-comms"),
+    });
+    const scalar = await vk_from_entropy(sharedSecret);
+    return scalar;
+}

package/dist/multisig/multisig.d.ts

@@ -0,0 +1,36 @@
+import type { DkgErrorResponse, DkgParticipateParams, DkgParticipateResult, DkgVerifyParams, DkgVerifyResult, DkgVerifyValidResult } from "./DistributedKeyGenerator";
+export declare class MultiSig {
+    private worker?;
+    /**
+     * set up a distributed key generator with t threshold and n total participants
+     * @param t  - total number of multisig participants
+     * @param n  - threshold to sign a transaction
+     * @returns  - Promise<DistributedKeyGenerator>
+     */
+    static createAndSetupGenerators(t: number, n: number): Promise<MultiSig>;
+    stopWorker(): void;
+    startWorker(t: number, n: number): Promise<void>;
+    /**
+     * participate in a DKG round (nothrow).
+     *
+     * @param params dkg_secret_key as 64-byte hex string, context, dkg_public_keys array (length is n implicitly), t (threshold)
+     * @returns The participation message as hex, or an error object
+     */
+    participateNoThrow(params: DkgParticipateParams): Promise<DkgParticipateResult | DkgErrorResponse>;
+    /**
+     * verify DKG participations and extract the group key (nothrow).
+     *
+     * @param params dkg_secret_key as 64-byte hex string, context, t (threshold), dkg_public_keys array (length is n implicitly),
+     *  participations [ paricipant index -> hex participation message ]
+     * @returns The group key and params, faulty participants, not-enough message, or error
+     */
+    verifyNoThrow(params: DkgVerifyParams): Promise<DkgVerifyResult | DkgErrorResponse>;
+    /**
+     * participate in a DKG round (throws on error).
+     */
+    participate(params: DkgParticipateParams): Promise<DkgParticipateResult>;
+    /**
+     * verify DKG participations and extract the group key (throws on error).
+     */
+    verify(params: DkgVerifyParams): Promise<DkgVerifyValidResult>;
+}

package/dist/multisig/multisig.js

@@ -0,0 +1,140 @@
+import { log } from "../io/logging";
+import { startWebworkerReady } from "../scanning-syncing/backgroundWorker";
+export class MultiSig {
+    worker = undefined;
+    /**
+     * set up a distributed key generator with t threshold and n total participants
+     * @param t  - total number of multisig participants
+     * @param n  - threshold to sign a transaction
+     * @returns  - Promise<DistributedKeyGenerator>
+     */
+    static async createAndSetupGenerators(t, n) {
+        const dkg = new MultiSig();
+        await dkg.startWorker(t, n);
+        return dkg;
+    }
+    stopWorker() {
+        if (this.worker) {
+            this.worker.terminate();
+            delete this.worker;
+        }
+    }
+    async startWorker(t, n) {
+        if (!this.worker) {
+            this.worker = await startWebworkerReady();
+            const that = this;
+            const result_promise = new Promise((resolve) => {
+                if (!that.worker) {
+                    resolve();
+                    return;
+                }
+                that.worker.onmessage = (e) => {
+                    const msg = e.data;
+                    if (msg.type === "multisig-ready") {
+                        resolve();
+                    }
+                    else {
+                        handleUnknownMessage(msg, "startWorker");
+                    }
+                };
+                that.worker.postMessage({
+                    type: "setup",
+                    t,
+                    n,
+                    role: "multisig",
+                });
+            });
+            return await result_promise;
+        }
+        else {
+            this.stopWorker();
+            this.startWorker(t, n);
+        }
+    }
+    /**
+     * participate in a DKG round (nothrow).
+     *
+     * @param params dkg_secret_key as 64-byte hex string, context, dkg_public_keys array (length is n implicitly), t (threshold)
+     * @returns The participation message as hex, or an error object
+     */
+    participateNoThrow(params) {
+        const msg = { type: "multisig-call", functionName: "participate", params };
+        const that = this;
+        const result_promise = new Promise((resolve) => {
+            if (!that.worker) {
+                handleNoWorkerButMethodCalled("participate");
+                return;
+            }
+            that.worker.onmessage = (e) => {
+                const msg = e.data;
+                if (msg.type === "multisig-call-result") {
+                    resolve(msg.result);
+                }
+                else {
+                    handleUnknownMessage(msg, "participate");
+                }
+            };
+            that.worker.postMessage(msg);
+        });
+        return result_promise;
+    }
+    /**
+     * verify DKG participations and extract the group key (nothrow).
+     *
+     * @param params dkg_secret_key as 64-byte hex string, context, t (threshold), dkg_public_keys array (length is n implicitly),
+     *  participations [ paricipant index -> hex participation message ]
+     * @returns The group key and params, faulty participants, not-enough message, or error
+     */
+    verifyNoThrow(params) {
+        const msg = { type: "multisig-call", functionName: "verify", params };
+        const that = this;
+        const result_promise = new Promise((resolve) => {
+            if (!that.worker) {
+                handleNoWorkerButMethodCalled("participate");
+                return;
+            }
+            that.worker.onmessage = (e) => {
+                const msg = e.data;
+                if (msg.type === "multisig-call-result") {
+                    resolve(msg.result);
+                }
+                else {
+                    handleUnknownMessage(msg, "participate");
+                }
+            };
+            that.worker.postMessage(msg);
+        });
+        return result_promise;
+    }
+    /**
+     * participate in a DKG round (throws on error).
+     */
+    async participate(params) {
+        const result = await this.participateNoThrow(params);
+        if ("message" in result) {
+            throw new Error(`participate failed: ${result.message}`);
+        }
+        return result;
+    }
+    /**
+     * verify DKG participations and extract the group key (throws on error).
+     */
+    async verify(params) {
+        const result = await this.verifyNoThrow(params);
+        if ("message" in result) {
+            throw new Error(`verify failed: ${result.message}`);
+        }
+        if ("faulty_participants" in result) {
+            throw new Error(`verify failed: ${result.faulty_participants}`);
+        }
+        return result;
+    }
+}
+function handleUnknownMessage(msg, functionName) {
+    log("multisig", [`${functionName}(): unknown message type:  ${msg.type}`]);
+    throw new Error(`[multisig] ${functionName}(): unknown message type:  ${msg.type}`);
+}
+function handleNoWorkerButMethodCalled(functionName) {
+    log("multisig", [`${functionName}(): no worker`]);
+    throw new Error(`[multisig] ${functionName}(): no worker`);
+}

package/dist/node-interaction/nodeUrl.js

@@ -2,6 +2,7 @@ import { getBlocksBinExecuteRequest, loadGetBlocksBinResponse, getOutsBinJson, g
 import { get_block_headers_range, get_fee_estimate, get_info, get_output_distribution, send_raw_transaction, } from "./jsonEndpoints";
 import { makeInput, sampleDecoys, } from "../send-functionality/transactionBuilding";
 import { WasmProcessor } from "../wasm-processing/wasmProcessor";
+import { monero_wallet_api_wasm } from "../wasm-processing/wasmFile";
 /**
  * This class is useful to interact with Moneros DaemonRpc binary requests in a convenient way.
  * (similar to how you would interact with a REST api that gives you json back.)
@@ -27,7 +28,7 @@ export class NodeUrl extends WasmProcessor {
     }
     static async create(node_url) {
         const nodeUrl = new NodeUrl(node_url || LOCAL_NODE_DEFAULT_URL);
-        await nodeUrl.initWasmModule();
+        await nodeUrl.initWasmModule(monero_wallet_api_wasm);
         return nodeUrl;
     }
     /**

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

@@ -8,3 +8,4 @@ export type WorkerSet = {
 export declare function createWebworker(handle_result?: (result: CacheChangedCallbackParameters) => void, scan_settings_path?: string, pathPrefix?: string, handle_error?: (error: unknown) => void): Promise<WorkerSet | undefined>;
 export declare function makeWebworkerScript(): string;
 export declare function startWebworker(handle_result?: (result: unknown) => void, handle_error?: (error: unknown) => void): Worker;
+export declare function startWebworkerReady(): Promise<Worker>;

package/dist/scanning-syncing/backgroundWorker.js

@@ -101,7 +101,7 @@ export function startWebworker(handle_result, handle_error) {
 // WORKER_READY (meaning self.onmessage = handleMessage has executed).
 // after that, postMessage is safe, no race between worker startup
 // and message delivery.
-function startWebworkerReady() {
+export function startWebworkerReady() {
     const worker = startWebworker();
     return new Promise((resolve) => {
         const onReady = (e) => {

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

@@ -1,5 +1,6 @@
 import type { LogSetting, PossibleLogs } from "../io/logging";
 export declare const SCAN_SETTINGS_STORE_NAME_DEFAULT = "ScanSettings.json";
+export declare const SUB_ADDRESS_INDEX_DEFAULT_VALUE = 1;
 export type ScanSetting = {
     primary_address: string;
     subaddress_index?: number;
@@ -70,21 +71,21 @@ export type ScanSettingsOpened = {
  * ```
  *
  * @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`.
+ * @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 declare function writeScanSettings(scan_settings: ScanSettings, settingsStorePath?: string): Promise<number>;
+export declare function writeScanSettings(scan_settings: ScanSettings, scan_settings_path?: string): Promise<number>;
 export type WriteScanSettingsFileParams = {
-    settingsStorePath?: string;
+    scan_settings_path?: string;
     writeCallback: (settings: ScanSettings) => void | Promise<void>;
 };
 export declare function writeScanSettingsFileDefaultLocation(params: WriteScanSettingsFileParams): Promise<void>;
-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>;
+export declare function writeStartHeightToScanSettings(start_height: number | null, scan_settings_path?: string): Promise<number>;
+export declare function writeDaemonHeightAsStartHeightToScanSettings(node_url: string, scan_settings_path?: string): Promise<number>;
+export declare function cullTooLargeScanHeight(node_url: string, scan_settings_path?: string): Promise<number>;
+export declare function writeNodeUrlToScanSettings(node_url: string, scan_settings_path?: string): Promise<number>;
+export declare function readNodeUrlFromScanSettings(scan_settings_path?: string): Promise<string | undefined>;
 /**
  * Writes the merchant confirmation threshold to scan settings.
  *
@@ -96,11 +97,11 @@ export declare function readNodeUrlFromScanSettings(settingsStorePath?: string):
  *
  * @param merchant_confirmations - Number of confirmations required before
  *   accepting a payment, or `null` to leave it unset.
- * @param settingsStorePath - Optional path for the settings file.
+ * @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 declare function writeMerchantConfirmationsToScanSettings(merchant_confirmations: number | null, settingsStorePath?: string): Promise<number>;
+export declare function writeMerchantConfirmationsToScanSettings(merchant_confirmations: number | null, scan_settings_path?: string): Promise<number>;
 /**
  * Reads the merchant confirmation threshold from scan settings.
  *
@@ -111,12 +112,12 @@ export declare function writeMerchantConfirmationsToScanSettings(merchant_confir
  * for a payment. The actual enforcement of this policy is left to the
  * custom payment-system code that consumes this library.
  *
- * @param settingsStorePath - Optional path for the settings file.
+ * @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 declare function readMerchantConfirmationsFromScanSettings(settingsStorePath?: string): Promise<number | null | undefined>;
+export declare function readMerchantConfirmationsFromScanSettings(scan_settings_path?: string): Promise<number | null | undefined>;
 /**
  * Reads scan settings from the default or specified storage file.
  * secret_view_key and spend_private_key are read from environment variables
@@ -129,7 +130,7 @@ export declare function readMerchantConfirmationsFromScanSettings(settingsStoreP
  * }
  * ```
  *
- * @param settingsStorePath - Path to the settings file. Defaults to `SCAN_SETTINGS_STORE_NAME_DEFAULT`.
+ * @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 declare function readScanSettings(scan_settings_path?: string): Promise<ScanSettingsOpened | undefined>;