@spirobel/monero-wallet-api 0.4.0 → 0.5.0

package/dist/multisig/DistributedKeyGenerator.js

@@ -0,0 +1,197 @@
+import { frost_dkg_wasm } from "../wasm-processing/wasmFile";
+import { WasmProcessor } from "../wasm-processing/wasmProcessor";
+/**
+ * get the DKG public key from a 64-byte DKG secret key
+ * @param dkgSecretKey - 64 byte Uint8Array dkg secret key
+ * @returns - dkg public key as hex string
+ */
+export async function getDkgPublicKey(dkgSecretKey) {
+    const dkg = await DistributedKeyGenerator.create();
+    const pubResult = dkg.getPublicKey(dkgSecretKey);
+    if ("message" in pubResult) {
+        throw new Error(`getPublicKey failed: ${pubResult.message}`);
+    }
+    return pubResult.dkg_public_key;
+}
+/**
+ * derive a Monero address (mainnet, stagenet, testnet) from a DKG group key.
+ * spend_public_key is the group_key hex from dkg_verify output.
+ * view_secret_key is the 32-byte view secret key hex. (see performEscrowViewPairECDH on how to get one)
+ *
+ * @returns object with view_key, mainnet_primary, stagenet_primary, testnet_primary
+ */
+export async function getDkgMoneroAddress(spend_public_key, view_secret_key) {
+    const dkg = await DistributedKeyGenerator.create();
+    const result = dkg.getMoneroAddress({ spend_public_key, view_secret_key });
+    if ("message" in result) {
+        throw new Error(`getDkgMoneroAddress failed: ${result.message}`);
+    }
+    return result;
+}
+export class DistributedKeyGenerator extends WasmProcessor {
+    /**
+     * create distributed key generator wasm instance,
+     * without initializing generators
+     * (in case you just want to get the public dkg key from a secret dkg key)
+     *
+     * @returns  - Promise<DistributedKeyGenerator>
+     */
+    static async create() {
+        const dkg = new DistributedKeyGenerator();
+        await dkg.initWasmModule(frost_dkg_wasm);
+        return dkg;
+    }
+    /**
+     * 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 DistributedKeyGenerator();
+        await dkg.initWasmModule(frost_dkg_wasm);
+        dkg.setupGenerators(t, n);
+        return dkg;
+    }
+    /**
+     * setupGenerators
+     * configure the max threshold and max participants for the DKG generators.
+     * if never called, defaults to 16, 16 used automatically on first DKG operation.
+     */
+    setupGenerators(t, n) {
+        //@ts-ignore
+        this.tinywasi.instance.exports.setup_generators(t, n);
+    }
+    /**
+     * derive the DKG public key from a 64-byte DKG secret key.
+     *
+     * @param dkgSecretKeyBytes 64-byte DKG secret key (from seed function)
+     * @returns the DKG public key as a hex string, or an error object
+     */
+    getPublicKey(dkgSecretKeyBytes) {
+        // set up write callback: rust will call input(64) to read the secret key bytes
+        this.writeToWasmMemory = (ptr, len) => {
+            this.writeArray(ptr, len, dkgSecretKeyBytes);
+        };
+        // set up read callback: rust will call output_string() to return the result JSON
+        let result;
+        this.readFromWasmMemory = (ptr, len) => {
+            result = JSON.parse(this.readString(ptr, len));
+        };
+        //@ts-ignore
+        this.tinywasi.instance.exports.dkg_get_public_key();
+        if (!result) {
+            return { message: "No response from dkg_get_public_key" };
+        }
+        return result;
+    }
+    /**
+     * 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 jsonStr = JSON.stringify(params);
+        // set up write callback: rust will call input_string(json_len) to read the JSON
+        this.writeToWasmMemory = (ptr, len) => {
+            this.writeString(ptr, len, jsonStr);
+        };
+        // set up read callback: rust will call output_string() to return the result JSON
+        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.dkg_participate(jsonStr.length);
+        if (!result) {
+            return { message: "No response from dkg_participate" };
+        }
+        return result;
+    }
+    /**
+     * 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 jsonStr = JSON.stringify(params);
+        // set up write callback: rust will call input_string(json_len) to read the JSON
+        this.writeToWasmMemory = (ptr, len) => {
+            this.writeString(ptr, len, jsonStr);
+        };
+        // set up read callback: rust will call output_string() to return the result JSON
+        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.dkg_verify(jsonStr.length);
+        if (!result) {
+            return { message: "No response from dkg_verify" };
+        }
+        return result;
+    }
+    /**
+     * derive a Monero address from a DKG group key.
+     *
+     * Input JSON keys expected by the rust wasm:
+     *   spend_public_key (hex32) - the group_key hex from dkg_verify output
+     *   view_secret_key (hex32) - 32-byte view secret key (see performEscrowViewPairECDH on how to get one)
+     *
+     * @param params - spendPublicKey and viewSecretKey as hex strings
+     * @returns object with view_key, mainnet_primary, stagenet_primary, testnet_primary
+     */
+    getMoneroAddress(params) {
+        const jsonStr = JSON.stringify(params);
+        // set up write callback: rust calls input_string(json_len)
+        this.writeToWasmMemory = (ptr, len) => {
+            this.writeString(ptr, len, jsonStr);
+        };
+        // set up read callback: rust calls output_string()
+        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.dkg_get_monero_address(jsonStr.length);
+        if (!result) {
+            return { message: "No response from dkg_get_monero_address" };
+        }
+        return result;
+    }
+    /**
+     * participate in a DKG round (throws on error).
+     */
+    participate(params) {
+        const result = 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).
+     */
+    verify(params) {
+        const result = 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;
+    }
+}

package/dist/multisig/MultiSigTxSigner.d.ts

@@ -0,0 +1,68 @@
+import { WasmProcessor } from "../wasm-processing/wasmProcessor";
+export type MoneroPreprocessParams = {
+    threshold_key: string;
+    unsigned_tx: string;
+};
+export type MoneroPreprocessResult = {
+    preprocess: string;
+};
+export type MoneroSignParams = {
+    preprocesses: Record<string, string>;
+};
+export type MoneroSignResult = {
+    share: string;
+};
+export type MoneroCompleteParams = {
+    shares: Record<string, string>;
+};
+export type MoneroCompleteResult = {
+    signed_tx: string;
+};
+export type MoneroErrorResponse = {
+    message: string;
+};
+export declare class MultiSigTxSigner extends WasmProcessor {
+    static create(): Promise<MultiSigTxSigner>;
+    /**
+     * preprocess
+     *
+     * @param params threshold_key hex, unsigned_tx hex
+     * @returns preprocess hex
+     */
+    preprocess(params: MoneroPreprocessParams): MoneroPreprocessResult;
+    /**
+     * preprocess -  does not throw, with return error type
+     *
+     * @param params threshold_key hex, unsigned_tx hex
+     * @returns preprocess hex
+     */
+    preprocessNoThrow(params: MoneroPreprocessParams): MoneroPreprocessResult | MoneroErrorResponse;
+    /**
+     * sign
+     *
+     * @param params preprocesses map from all signers
+     * @returns share hex
+     */
+    sign(params: MoneroSignParams): MoneroSignResult;
+    /**
+     * sign -  does not throw, with return error type
+     *
+     * @param params preprocesses map from all signers
+     * @returns share hex
+     */
+    signNoThrow(params: MoneroSignParams): MoneroSignResult | MoneroErrorResponse;
+    /**
+     * complete
+     *
+     * @param params shares map from all signers
+     * @returns signed_tx hex
+     */
+    complete(params: MoneroCompleteParams): MoneroCompleteResult;
+    /**
+     * complete -  does not throw, with return error type
+     *
+     * @param params shares map from all signers
+     * @returns signed_tx hex
+     */
+    completeNoThrow(params: MoneroCompleteParams): MoneroCompleteResult | MoneroErrorResponse;
+}

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>;
+}