@bitgo/wasm-utxo 1.28.0 → 1.29.0

package/dist/esm/js/testutils/AcidTest.js

@@ -0,0 +1,302 @@
+import { BitGoPsbt } from "../fixedScriptWallet/BitGoPsbt.js";
+import { ZcashBitGoPsbt } from "../fixedScriptWallet/ZcashBitGoPsbt.js";
+import { ECPair } from "../ecpair.js";
+import { assertChainCode, ChainCode, createOpReturnScript, inputScriptTypes, outputScript, outputScriptTypes, supportsScriptType, } from "../fixedScriptWallet/index.js";
+import { coinNames, isMainnet } from "../coinName.js";
+import { getDefaultWalletKeys, getWalletKeysForSeed, getKeyTriple } from "./keys.js";
+export const signStages = ["unsigned", "halfsigned", "fullsigned"];
+export const txFormats = ["psbt", "psbt-lite"];
+// Re-export for convenience
+export { inputScriptTypes, outputScriptTypes };
+/**
+ * Creates a valid PSBT with as many features as possible (kitchen sink).
+ *
+ * - Inputs:
+ *   - All wallet script types supported by the network
+ *   - A p2shP2pk input (for replay protection)
+ * - Outputs:
+ *   - All wallet script types supported by the network
+ *   - A p2sh output with derivation info of a different wallet
+ *   - A p2sh output with no derivation info (external output)
+ *   - An OP_RETURN output
+ *
+ * Signature stages:
+ * - unsigned: No signatures
+ * - halfsigned: One signature per input (user key)
+ * - fullsigned: Two signatures per input (user + bitgo)
+ *
+ * Transaction formats:
+ * - psbt: Full PSBT with non_witness_utxo
+ * - psbt-lite: Only witness_utxo (no non_witness_utxo)
+ */
+export class AcidTest {
+    network;
+    signStage;
+    txFormat;
+    rootWalletKeys;
+    otherWalletKeys;
+    inputs;
+    outputs;
+    // Store private keys for signing
+    userXprv;
+    backupXprv;
+    bitgoXprv;
+    constructor(network, signStage, txFormat, rootWalletKeys, otherWalletKeys, inputs, outputs, xprvTriple) {
+        this.network = network;
+        this.signStage = signStage;
+        this.txFormat = txFormat;
+        this.rootWalletKeys = rootWalletKeys;
+        this.otherWalletKeys = otherWalletKeys;
+        this.inputs = inputs;
+        this.outputs = outputs;
+        this.userXprv = xprvTriple[0];
+        this.backupXprv = xprvTriple[1];
+        this.bitgoXprv = xprvTriple[2];
+    }
+    /**
+     * Create an AcidTest with specific configuration
+     */
+    static withConfig(network, signStage, txFormat, suiteConfig = {}) {
+        const rootWalletKeys = getDefaultWalletKeys();
+        const otherWalletKeys = getWalletKeysForSeed("too many secrets");
+        // Filter inputs based on network support
+        const inputs = inputScriptTypes
+            .filter((scriptType) => {
+            // p2shP2pk is always supported (single-sig replay protection)
+            if (scriptType === "p2shP2pk")
+                return true;
+            // Map input script types to output script types for support check
+            if (scriptType === "p2trMusig2KeyPath" || scriptType === "p2trMusig2ScriptPath") {
+                return supportsScriptType(network, "p2trMusig2");
+            }
+            return supportsScriptType(network, scriptType);
+        })
+            .filter((scriptType) => (suiteConfig.includeP2trMusig2ScriptPath ?? false) ||
+            scriptType !== "p2trMusig2ScriptPath")
+            .map((scriptType, index) => ({
+            scriptType,
+            value: BigInt(10000 + index * 10000), // Deterministic amounts
+        }));
+        // Filter outputs based on network support
+        const outputs = outputScriptTypes
+            .filter((scriptType) => supportsScriptType(network, scriptType))
+            .map((scriptType, index) => ({
+            scriptType,
+            value: BigInt(900 + index * 100), // Deterministic amounts
+        }));
+        // Test other wallet output (with derivation info)
+        outputs.push({ scriptType: "p2sh", value: BigInt(800), walletKeys: otherWalletKeys });
+        // Test non-wallet output (no derivation info)
+        outputs.push({ scriptType: "p2sh", value: BigInt(700), walletKeys: null });
+        // Test OP_RETURN output
+        outputs.push({ opReturn: "setec astronomy", value: BigInt(0) });
+        // Get private keys for signing
+        const xprvTriple = getKeyTriple("default");
+        return new AcidTest(network, signStage, txFormat, rootWalletKeys, otherWalletKeys, inputs, outputs, xprvTriple);
+    }
+    /**
+     * Get a human-readable name for this test configuration
+     */
+    get name() {
+        return `${this.network} ${this.signStage} ${this.txFormat}`;
+    }
+    /**
+     * Get the BIP32 user key for replay protection (p2shP2pk)
+     */
+    getReplayProtectionKey() {
+        return this.rootWalletKeys.userKey();
+    }
+    /**
+     * Create the actual PSBT with all inputs and outputs
+     */
+    createPsbt() {
+        // Use ZcashBitGoPsbt for Zcash networks
+        const isZcash = this.network === "zec" || this.network === "tzec";
+        const psbt = isZcash
+            ? ZcashBitGoPsbt.createEmptyWithConsensusBranchId(this.network, this.rootWalletKeys, {
+                version: 2,
+                lockTime: 0,
+                consensusBranchId: 0xc2d6d0b4, // NU5
+            })
+            : BitGoPsbt.createEmpty(this.network, this.rootWalletKeys, {
+                version: 2,
+                lockTime: 0,
+            });
+        // Add inputs with deterministic outpoints
+        this.inputs.forEach((input, index) => {
+            // Resolve scriptId: either from explicit scriptId or from scriptType + index
+            const scriptId = input.scriptId ?? {
+                chain: ChainCode.value("p2sh", "external"),
+                index: input.index ?? index,
+            };
+            const walletKeys = input.walletKeys ?? this.rootWalletKeys;
+            // Get scriptType: either explicit or derive from scriptId chain
+            const scriptType = input.scriptType ?? ChainCode.scriptType(assertChainCode(scriptId.chain));
+            if (scriptType === "p2shP2pk") {
+                // Add replay protection input
+                const replayKey = this.getReplayProtectionKey();
+                // Convert BIP32 to ECPair using public key
+                const ecpair = ECPair.fromPublicKey(replayKey.publicKey);
+                psbt.addReplayProtectionInput({
+                    txid: "0".repeat(64),
+                    vout: index,
+                    value: input.value,
+                }, ecpair);
+            }
+            else {
+                // Determine signing path based on input type
+                let signPath;
+                if (scriptType === "p2trMusig2ScriptPath") {
+                    // Script path uses user + backup
+                    signPath = { signer: "user", cosigner: "backup" };
+                }
+                else {
+                    // Default: user + bitgo
+                    signPath = { signer: "user", cosigner: "bitgo" };
+                }
+                psbt.addWalletInput({
+                    txid: "0".repeat(64),
+                    vout: index,
+                    value: input.value,
+                }, walletKeys, {
+                    scriptId,
+                    signPath,
+                });
+            }
+        });
+        // Add outputs
+        this.outputs.forEach((output, index) => {
+            if (output.opReturn !== undefined) {
+                // OP_RETURN output
+                const data = new TextEncoder().encode(output.opReturn);
+                const script = createOpReturnScript(data);
+                psbt.addOutput(script, output.value);
+            }
+            else if (output.address !== undefined) {
+                // Address-based output
+                psbt.addOutput(output.address, output.value);
+            }
+            else if (output.script !== undefined) {
+                // Raw script output
+                psbt.addOutput(output.script, output.value);
+            }
+            else {
+                // Wallet output: resolve scriptId from scriptType or explicit scriptId
+                const scriptId = output.scriptId ?? {
+                    chain: output.scriptType ? ChainCode.value(output.scriptType, "external") : 0,
+                    index: output.index ?? index,
+                };
+                if (output.walletKeys === null) {
+                    // External output (no wallet keys, no bip32 derivation)
+                    // Use high index for external outputs if not specified
+                    const externalScriptId = output.scriptId ?? {
+                        chain: scriptId.chain,
+                        index: output.index ?? 1000 + index,
+                    };
+                    const script = outputScript(this.rootWalletKeys, externalScriptId.chain, externalScriptId.index, this.network);
+                    psbt.addOutput(script, output.value);
+                }
+                else {
+                    // Wallet output (with or without different wallet keys)
+                    const walletKeys = output.walletKeys ?? this.rootWalletKeys;
+                    psbt.addWalletOutput(walletKeys, {
+                        chain: scriptId.chain,
+                        index: scriptId.index,
+                        value: output.value,
+                    });
+                }
+            }
+        });
+        // Apply signing based on stage
+        if (this.signStage !== "unsigned") {
+            this.signPsbt(psbt);
+        }
+        return psbt;
+    }
+    /**
+     * Sign the PSBT according to the sign stage
+     */
+    signPsbt(psbt) {
+        // Use private keys stored in constructor
+        const userKey = this.userXprv;
+        const backupKey = this.backupXprv;
+        const bitgoKey = this.bitgoXprv;
+        // Generate MuSig2 nonces for user if needed
+        const hasMusig2Inputs = this.inputs.some((input) => input.scriptType === "p2trMusig2KeyPath" || input.scriptType === "p2trMusig2ScriptPath");
+        if (hasMusig2Inputs) {
+            const isZcash = this.network === "zec" || this.network === "tzec";
+            if (isZcash) {
+                throw new Error("Zcash does not support MuSig2/Taproot inputs");
+            }
+            // Generate nonces with user key
+            psbt.generateMusig2Nonces(userKey);
+            if (this.signStage === "fullsigned") {
+                // Create a second PSBT with cosigner nonces for combination
+                // For p2trMusig2ScriptPath use backup, for p2trMusig2KeyPath use bitgo
+                // Since we might have both types, we need to generate nonces separately
+                const bytes = psbt.serialize();
+                const hasKeyPath = this.inputs.some((input) => input.scriptType === "p2trMusig2KeyPath");
+                const hasScriptPath = this.inputs.some((input) => input.scriptType === "p2trMusig2ScriptPath");
+                if (hasKeyPath && !hasScriptPath) {
+                    // Only key path inputs - generate bitgo nonces for all
+                    const psbt2 = BitGoPsbt.fromBytes(bytes, this.network);
+                    psbt2.generateMusig2Nonces(bitgoKey);
+                    psbt.combineMusig2Nonces(psbt2);
+                }
+                else if (hasScriptPath && !hasKeyPath) {
+                    // Only script path inputs - generate backup nonces for all
+                    const psbt2 = BitGoPsbt.fromBytes(bytes, this.network);
+                    psbt2.generateMusig2Nonces(backupKey);
+                    psbt.combineMusig2Nonces(psbt2);
+                }
+                else {
+                    const psbt2 = BitGoPsbt.fromBytes(bytes, this.network);
+                    psbt2.generateMusig2Nonces(bitgoKey);
+                    psbt.combineMusig2Nonces(psbt2);
+                }
+            }
+        }
+        // Sign all wallet inputs with user key (bulk - more efficient)
+        psbt.sign(userKey);
+        // Sign replay protection inputs with raw private key
+        const hasReplayProtection = this.inputs.some((input) => input.scriptType === "p2shP2pk");
+        if (hasReplayProtection) {
+            if (!userKey.privateKey) {
+                throw new Error("User key must have private key for signing replay protection inputs");
+            }
+            psbt.sign(userKey.privateKey);
+        }
+        // For fullsigned, sign with cosigner
+        if (this.signStage === "fullsigned") {
+            const hasScriptPath = this.inputs.some((input) => input.scriptType === "p2trMusig2ScriptPath");
+            if (hasScriptPath) {
+                // Mixed case: script path uses backup, others use bitgo
+                // Need per-input signing (slow) to handle different cosigners
+                this.inputs.forEach((input, index) => {
+                    if (input.scriptType === "p2shP2pk") {
+                        // Replay protection is single-sig, already fully signed
+                        return;
+                    }
+                    if (input.scriptType === "p2trMusig2ScriptPath") {
+                        psbt.signInput(index, backupKey);
+                    }
+                    else {
+                        psbt.signInput(index, bitgoKey);
+                    }
+                });
+            }
+            else {
+                // No script path - can use bulk signing with bitgo (fast)
+                psbt.sign(bitgoKey);
+            }
+        }
+    }
+    /**
+     * Generate test suite for all networks, sign stages, and tx formats
+     */
+    static forAllNetworksSignStagesTxFormats(suiteConfig = {}) {
+        return coinNames
+            .filter((network) => isMainnet(network) && network !== "bsv") // Exclude bitcoinsv
+            .flatMap((network) => signStages.flatMap((signStage) => txFormats.map((txFormat) => AcidTest.withConfig(network, signStage, txFormat, suiteConfig))));
+    }
+}

package/dist/esm/js/testutils/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./keys.js";
+export * from "./AcidTest.js";

package/dist/esm/js/testutils/index.js

@@ -0,0 +1,2 @@
+export * from "./keys.js";
+export * from "./AcidTest.js";

package/dist/esm/js/testutils/keys.d.ts

@@ -0,0 +1,76 @@
+import { BIP32 } from "../bip32.js";
+import { RootWalletKeys } from "../fixedScriptWallet/RootWalletKeys.js";
+import type { Triple } from "../triple.js";
+/**
+ * Generate a deterministic BIP32 key from a seed string.
+ * Uses SHA256 hash of the seed to create the key, matching utxo-lib's implementation.
+ *
+ * @param seed - Seed string for deterministic key generation
+ * @returns BIP32 key derived from the seed
+ *
+ * @example
+ * ```typescript
+ * const key = getKey("user");
+ * const xpub = key.neutered().toBase58();
+ * ```
+ */
+export declare function getKey(seed: string): BIP32;
+/**
+ * Generate a triple of BIP32 keys for a 2-of-3 multisig wallet.
+ * Keys are generated deterministically from the seed string with suffixes .0, .1, .2
+ * for user, backup, and bitgo keys respectively.
+ *
+ * @param seed - Base seed string for key generation
+ * @returns Triple of BIP32 keys [user, backup, bitgo]
+ *
+ * @example
+ * ```typescript
+ * const keys = getKeyTriple("default");
+ * const [user, backup, bitgo] = keys;
+ * ```
+ */
+export declare function getKeyTriple(seed: string): Triple<BIP32>;
+/**
+ * Create RootWalletKeys from a seed string.
+ * Uses standard derivation prefixes ["m/0/0", "m/0/0", "m/0/0"].
+ *
+ * @param seed - Seed string for key generation
+ * @returns RootWalletKeys instance
+ *
+ * @example
+ * ```typescript
+ * const walletKeys = getWalletKeysForSeed("default");
+ * ```
+ */
+export declare function getWalletKeysForSeed(seed: string): RootWalletKeys;
+/**
+ * Get the default wallet keys for testing.
+ * Equivalent to getWalletKeysForSeed("default").
+ *
+ * @returns RootWalletKeys instance with default seed
+ *
+ * @example
+ * ```typescript
+ * const walletKeys = getDefaultWalletKeys();
+ * ```
+ */
+export declare function getDefaultWalletKeys(): RootWalletKeys;
+/**
+ * Get the key name (user, backup, or bitgo) for a given key in a triple.
+ *
+ * @param triple - Triple of BIP32 keys
+ * @param key - Key to find in the triple
+ * @returns "user", "backup", "bitgo", or undefined if not found
+ */
+export declare function getKeyName(triple: Triple<BIP32>, key: BIP32): "user" | "backup" | "bitgo" | undefined;
+/**
+ * Get the default cosigner for a given signer key.
+ * - If signer is user, returns bitgo
+ * - If signer is backup, returns bitgo
+ * - If signer is bitgo, returns user
+ *
+ * @param keyset - Triple of keys [user, backup, bitgo]
+ * @param signer - The signing key
+ * @returns The default cosigner key
+ */
+export declare function getDefaultCosigner<T>(keyset: Triple<T>, signer: T): T;

package/dist/esm/js/testutils/keys.js

@@ -0,0 +1,113 @@
+import * as crypto from "crypto";
+import { BIP32 } from "../bip32.js";
+import { RootWalletKeys } from "../fixedScriptWallet/RootWalletKeys.js";
+/**
+ * Generate a deterministic BIP32 key from a seed string.
+ * Uses SHA256 hash of the seed to create the key, matching utxo-lib's implementation.
+ *
+ * @param seed - Seed string for deterministic key generation
+ * @returns BIP32 key derived from the seed
+ *
+ * @example
+ * ```typescript
+ * const key = getKey("user");
+ * const xpub = key.neutered().toBase58();
+ * ```
+ */
+export function getKey(seed) {
+    return BIP32.fromSeed(crypto.createHash("sha256").update(seed).digest());
+}
+/**
+ * Generate a triple of BIP32 keys for a 2-of-3 multisig wallet.
+ * Keys are generated deterministically from the seed string with suffixes .0, .1, .2
+ * for user, backup, and bitgo keys respectively.
+ *
+ * @param seed - Base seed string for key generation
+ * @returns Triple of BIP32 keys [user, backup, bitgo]
+ *
+ * @example
+ * ```typescript
+ * const keys = getKeyTriple("default");
+ * const [user, backup, bitgo] = keys;
+ * ```
+ */
+export function getKeyTriple(seed) {
+    return [getKey(seed + ".0"), getKey(seed + ".1"), getKey(seed + ".2")];
+}
+/**
+ * Create RootWalletKeys from a seed string.
+ * Uses standard derivation prefixes ["m/0/0", "m/0/0", "m/0/0"].
+ *
+ * @param seed - Seed string for key generation
+ * @returns RootWalletKeys instance
+ *
+ * @example
+ * ```typescript
+ * const walletKeys = getWalletKeysForSeed("default");
+ * ```
+ */
+export function getWalletKeysForSeed(seed) {
+    const triple = getKeyTriple(seed);
+    return RootWalletKeys.from({
+        triple,
+        derivationPrefixes: ["m/0/0", "m/0/0", "m/0/0"],
+    });
+}
+/**
+ * Get the default wallet keys for testing.
+ * Equivalent to getWalletKeysForSeed("default").
+ *
+ * @returns RootWalletKeys instance with default seed
+ *
+ * @example
+ * ```typescript
+ * const walletKeys = getDefaultWalletKeys();
+ * ```
+ */
+export function getDefaultWalletKeys() {
+    return getWalletKeysForSeed("default");
+}
+/**
+ * Get the key name (user, backup, or bitgo) for a given key in a triple.
+ *
+ * @param triple - Triple of BIP32 keys
+ * @param key - Key to find in the triple
+ * @returns "user", "backup", "bitgo", or undefined if not found
+ */
+export function getKeyName(triple, key) {
+    const index = triple.findIndex((k) => {
+        const kb58 = k.toBase58();
+        const keyb58 = key.toBase58();
+        return kb58 === keyb58;
+    });
+    if (index === 0)
+        return "user";
+    if (index === 1)
+        return "backup";
+    if (index === 2)
+        return "bitgo";
+    return undefined;
+}
+/**
+ * Get the default cosigner for a given signer key.
+ * - If signer is user, returns bitgo
+ * - If signer is backup, returns bitgo
+ * - If signer is bitgo, returns user
+ *
+ * @param keyset - Triple of keys [user, backup, bitgo]
+ * @param signer - The signing key
+ * @returns The default cosigner key
+ */
+export function getDefaultCosigner(keyset, signer) {
+    const [user, backup, bitgo] = keyset;
+    if (signer === user) {
+        return bitgo;
+    }
+    if (signer === backup) {
+        return bitgo;
+    }
+    if (signer === bitgo) {
+        return user;
+    }
+    throw new Error("signer not in keyset");
+}

package/dist/esm/js/wasm/wasm_utxo.d.ts

@@ -677,6 +677,16 @@ export class FixedScriptWalletNamespace {
    * - Dogecoin only supports legacy scripts (p2sh)
    */
   static supports_script_type(coin: string, script_type: string): boolean;
+  /**
+   * Create an OP_RETURN output script with optional data
+   *
+   * # Arguments
+   * * `data` - Optional data bytes to include in the OP_RETURN script
+   *
+   * # Returns
+   * The OP_RETURN script as bytes
+   */
+  static create_op_return_script(data?: Uint8Array | null): Uint8Array;
   static address_with_network_str(keys: WasmRootWalletKeys, chain: number, index: number, network: string, address_format?: string | null): string;
   static output_script_with_network_str(keys: WasmRootWalletKeys, chain: number, index: number, network: string): Uint8Array;
   static address(keys: WasmRootWalletKeys, chain: number, index: number, network: any, address_format?: string | null): string;

package/dist/esm/js/wasm/wasm_utxo_bg.js

@@ -1902,6 +1902,37 @@ export class FixedScriptWalletNamespace {
             wasm.__wbindgen_add_to_stack_pointer(16);
         }
     }
+    /**
+     * Create an OP_RETURN output script with optional data
+     *
+     * # Arguments
+     * * `data` - Optional data bytes to include in the OP_RETURN script
+     *
+     * # Returns
+     * The OP_RETURN script as bytes
+     * @param {Uint8Array | null} [data]
+     * @returns {Uint8Array}
+     */
+    static create_op_return_script(data) {
+        try {
+            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+            var ptr0 = isLikeNone(data) ? 0 : passArray8ToWasm0(data, wasm.__wbindgen_export);
+            var len0 = WASM_VECTOR_LEN;
+            wasm.fixedscriptwalletnamespace_create_op_return_script(retptr, ptr0, len0);
+            var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+            var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+            var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
+            var r3 = getDataViewMemory0().getInt32(retptr + 4 * 3, true);
+            if (r3) {
+                throw takeObject(r2);
+            }
+            var v2 = getArrayU8FromWasm0(r0, r1).slice();
+            wasm.__wbindgen_export4(r0, r1 * 1, 1);
+            return v2;
+        } finally {
+            wasm.__wbindgen_add_to_stack_pointer(16);
+        }
+    }
     /**
      * @param {WasmRootWalletKeys} keys
      * @param {number} chain

package/dist/esm/js/wasm/wasm_utxo_bg.wasm.d.ts

@@ -100,6 +100,7 @@ export const bitgopsbt_version_group_id: (a: number) => number;
 export const fixedscriptwalletnamespace_address: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => void;
 export const fixedscriptwalletnamespace_address_with_network_str: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number) => void;
 export const fixedscriptwalletnamespace_chain_code_table: () => number;
+export const fixedscriptwalletnamespace_create_op_return_script: (a: number, b: number, c: number) => void;
 export const fixedscriptwalletnamespace_output_script: (a: number, b: number, c: number, d: number, e: number) => void;
 export const fixedscriptwalletnamespace_output_script_with_network_str: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
 export const fixedscriptwalletnamespace_supports_script_type: (a: number, b: number, c: number, d: number, e: number) => void;
@@ -154,8 +155,8 @@ export const wasmrootwalletkeys_new: (a: number, b: number, c: number, d: number
 export const wasmrootwalletkeys_user_key: (a: number) => number;
 export const wasmrootwalletkeys_with_derivation_prefixes: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number) => void;
 export const wasmbip32_from_bip32_properties: (a: number, b: number) => void;
-export const bitgopsbt_sign_all_with_xpriv: (a: number, b: number, c: number) => void;
 export const bitgopsbt_sign_replay_protection_inputs: (a: number, b: number, c: number) => void;
+export const bitgopsbt_sign_all_with_xpriv: (a: number, b: number, c: number) => void;
 export const bitgopsbt_sign_wallet_input: (a: number, b: number, c: number, d: number) => void;
 export const __wbg_wasmdashtransaction_free: (a: number, b: number) => void;
 export const __wbg_wasmreplayprotection_free: (a: number, b: number) => void;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@bitgo/wasm-utxo",
   "description": "WebAssembly wrapper for rust-bitcoin (beta)",
-  "version": "1.28.0",
+  "version": "1.29.0",
   "type": "module",
   "repository": {
     "type": "git",