@bitgo/wasm-utxo 1.27.0 → 1.28.0

package/dist/cjs/js/bip32.d.ts

@@ -138,3 +138,10 @@ export declare class BIP32 implements BIP32Interface {
      */
     get wasm(): WasmBIP32;
 }
+/**
+ * Type guard to check if a value is a BIP32Arg
+ *
+ * @param key - The value to check
+ * @returns true if the value is a BIP32Arg (string, BIP32, WasmBIP32, or BIP32Interface)
+ */
+export declare function isBIP32Arg(key: unknown): key is BIP32Arg;

package/dist/cjs/js/bip32.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BIP32 = void 0;
+exports.isBIP32Arg = isBIP32Arg;
 const wasm_utxo_js_1 = require("./wasm/wasm_utxo.js");
 /**
  * BIP32 wrapper class for extended key operations
@@ -175,3 +176,18 @@ class BIP32 {
     }
 }
 exports.BIP32 = BIP32;
+/**
+ * Type guard to check if a value is a BIP32Arg
+ *
+ * @param key - The value to check
+ * @returns true if the value is a BIP32Arg (string, BIP32, WasmBIP32, or BIP32Interface)
+ */
+function isBIP32Arg(key) {
+    return (typeof key === "string" ||
+        key instanceof BIP32 ||
+        key instanceof wasm_utxo_js_1.WasmBIP32 ||
+        (typeof key === "object" &&
+            key !== null &&
+            "derive" in key &&
+            typeof key.derive === "function"));
+}

package/dist/cjs/js/fixedScriptWallet/BitGoPsbt.d.ts

@@ -371,16 +371,63 @@ export declare class BitGoPsbt {
      */
     verifySignature(inputIndex: number, key: BIP32Arg | ECPairArg): boolean;
     /**
-     * Sign a single input with a private key
+     * Sign all matching inputs with a private key.
+     *
+     * This method signs all inputs that match the provided key in a single efficient pass.
+     * It accepts either:
+     * - An xpriv (BIP32Arg: base58 string, BIP32 instance, or WasmBIP32) for wallet inputs
+     * - A raw privkey (ECPairArg: Buffer, ECPair instance, or WasmECPair) for replay protection inputs
+     *
+     * **Note:** MuSig2 inputs are skipped by this method when using xpriv because they require
+     * FirstRound state. After calling this method, sign MuSig2 inputs individually using
+     * `signInput()` after calling `generateMusig2Nonces()`.
+     *
+     * @param key - Either an xpriv (BIP32Arg) or a raw privkey (ECPairArg)
+     * @returns Array of input indices that were signed
+     * @throws Error if signing fails
+     *
+     * @example
+     * ```typescript
+     * // Sign all wallet inputs with user's xpriv
+     * const signedIndices = psbt.sign(userXpriv);
+     * console.log(`Signed inputs: ${signedIndices.join(", ")}`);
+     *
+     * // Sign all replay protection inputs with raw privkey
+     * const rpSignedIndices = psbt.sign(replayProtectionPrivkey);
+     * ```
+     */
+    sign(key: BIP32Arg | ECPairArg): number[];
+    /**
+     * Sign a single input with a private key.
+     *
+     * @deprecated Use `sign(key)` to sign all matching inputs (more efficient), or use
+     * `signInput(inputIndex, key)` for explicit single-input signing.
+     *
+     * **Note:** This method is NOT more efficient than `sign(key)` for non-MuSig2 inputs.
+     * The underlying miniscript library signs all inputs regardless. This overload exists
+     * for backward compatibility only.
+     *
+     * @param inputIndex - The index of the input to sign (0-based)
+     * @param key - Either an xpriv (BIP32Arg) or a raw privkey (ECPairArg)
+     * @throws Error if signing fails, or if generateMusig2Nonces() was not called first for MuSig2 inputs
+     */
+    sign(inputIndex: number, key: BIP32Arg | ECPairArg): void;
+    /**
+     * Sign a single input with a private key.
      *
      * This method signs a specific input using the provided key. It accepts either:
-     * - An xpriv (BIP32Arg: base58 string, BIP32 instance, or WasmBIP32) for wallet inputs - derives the key and signs
-     * - A raw privkey (ECPairArg: Buffer, ECPair instance, or WasmECPair) for replay protection inputs - signs directly
+     * - An xpriv (BIP32Arg: base58 string, BIP32 instance, or WasmBIP32) for wallet inputs
+     * - A raw privkey (ECPairArg: Buffer, ECPair instance, or WasmECPair) for replay protection inputs
      *
-     * This method automatically detects and handles different input types:
-     * - For regular inputs: uses standard PSBT signing
-     * - For MuSig2 inputs: uses the FirstRound state stored by generateMusig2Nonces()
-     * - For replay protection inputs: signs with legacy P2SH sighash
+     * **Important:** This method is NOT faster than `sign(key)` for non-MuSig2 inputs.
+     * The underlying miniscript library signs all inputs regardless. This method uses a
+     * save/restore pattern to ensure only the target input receives the signature.
+     *
+     * Use this method only when you need precise control over which inputs are signed,
+     * for example:
+     * - Signing MuSig2 inputs (after calling generateMusig2Nonces())
+     * - Mixed transactions where different inputs need different keys
+     * - Testing or debugging signing behavior
      *
      * @param inputIndex - The index of the input to sign (0-based)
      * @param key - Either an xpriv (BIP32Arg) or a raw privkey (ECPairArg)
@@ -388,28 +435,15 @@ export declare class BitGoPsbt {
      *
      * @example
      * ```typescript
-     * // Parse transaction to identify input types
-     * const parsed = psbt.parseTransactionWithWalletKeys(walletKeys, replayProtection);
-     *
-     * // Sign regular wallet inputs with xpriv
-     * for (let i = 0; i < parsed.inputs.length; i++) {
-     *   const input = parsed.inputs[i];
-     *   if (input.scriptId !== null && input.scriptType !== "p2shP2pk") {
-     *     psbt.sign(i, userXpriv);
-     *   }
-     * }
+     * // Sign a specific MuSig2 input after nonce generation
+     * psbt.generateMusig2Nonces(userXpriv);
+     * psbt.signInput(musig2InputIndex, userXpriv);
      *
-     * // Sign replay protection inputs with raw privkey
-     * const userPrivkey = bip32.fromBase58(userXpriv).privateKey!;
-     * for (let i = 0; i < parsed.inputs.length; i++) {
-     *   const input = parsed.inputs[i];
-     *   if (input.scriptType === "p2shP2pk") {
-     *     psbt.sign(i, userPrivkey);
-     *   }
-     * }
+     * // Sign a specific replay protection input
+     * psbt.signInput(rpInputIndex, replayProtectionPrivkey);
      * ```
      */
-    sign(inputIndex: number, key: BIP32Arg | ECPairArg): void;
+    signInput(inputIndex: number, key: BIP32Arg | ECPairArg): void;
     /**
      * @deprecated - use verifySignature with the replay protection key instead
      *

package/dist/cjs/js/fixedScriptWallet/BitGoPsbt.js

@@ -306,17 +306,49 @@ class BitGoPsbt {
         const wasmECPair = ecpair_js_1.ECPair.from(key).wasm;
         return this._wasm.verify_signature_with_pub(inputIndex, wasmECPair);
     }
+    sign(inputIndexOrKey, key) {
+        // Detect which overload was called
+        if (typeof inputIndexOrKey === "number") {
+            // Called as sign(inputIndex, key) - deprecated single-input signing
+            if (key === undefined) {
+                throw new Error("Key is required when signing a single input");
+            }
+            this.signInput(inputIndexOrKey, key);
+            return;
+        }
+        // Called as sign(key) - sign all matching inputs
+        const keyArg = inputIndexOrKey;
+        if ((0, bip32_js_1.isBIP32Arg)(keyArg)) {
+            // It's a BIP32Arg - sign all wallet inputs (ECDSA + MuSig2)
+            const wasmKey = bip32_js_1.BIP32.from(keyArg);
+            // Sign all non-MuSig2 wallet inputs
+            const walletSigned = this._wasm.sign_all_wallet_inputs(wasmKey.wasm);
+            // Sign all MuSig2 keypath inputs (more efficient - reuses SighashCache)
+            const musig2Signed = this._wasm.sign_all_musig2_inputs(wasmKey.wasm);
+            return [...walletSigned, ...musig2Signed];
+        }
+        else {
+            // It's an ECPairArg - sign all replay protection inputs
+            const wasmKey = ecpair_js_1.ECPair.from(keyArg);
+            return this._wasm.sign_replay_protection_inputs(wasmKey.wasm);
+        }
+    }
     /**
-     * Sign a single input with a private key
+     * Sign a single input with a private key.
      *
      * This method signs a specific input using the provided key. It accepts either:
-     * - An xpriv (BIP32Arg: base58 string, BIP32 instance, or WasmBIP32) for wallet inputs - derives the key and signs
-     * - A raw privkey (ECPairArg: Buffer, ECPair instance, or WasmECPair) for replay protection inputs - signs directly
+     * - An xpriv (BIP32Arg: base58 string, BIP32 instance, or WasmBIP32) for wallet inputs
+     * - A raw privkey (ECPairArg: Buffer, ECPair instance, or WasmECPair) for replay protection inputs
+     *
+     * **Important:** This method is NOT faster than `sign(key)` for non-MuSig2 inputs.
+     * The underlying miniscript library signs all inputs regardless. This method uses a
+     * save/restore pattern to ensure only the target input receives the signature.
      *
-     * This method automatically detects and handles different input types:
-     * - For regular inputs: uses standard PSBT signing
-     * - For MuSig2 inputs: uses the FirstRound state stored by generateMusig2Nonces()
-     * - For replay protection inputs: signs with legacy P2SH sighash
+     * Use this method only when you need precise control over which inputs are signed,
+     * for example:
+     * - Signing MuSig2 inputs (after calling generateMusig2Nonces())
+     * - Mixed transactions where different inputs need different keys
+     * - Testing or debugging signing behavior
      *
      * @param inputIndex - The index of the input to sign (0-based)
      * @param key - Either an xpriv (BIP32Arg) or a raw privkey (ECPairArg)
@@ -324,42 +356,30 @@ class BitGoPsbt {
      *
      * @example
      * ```typescript
-     * // Parse transaction to identify input types
-     * const parsed = psbt.parseTransactionWithWalletKeys(walletKeys, replayProtection);
-     *
-     * // Sign regular wallet inputs with xpriv
-     * for (let i = 0; i < parsed.inputs.length; i++) {
-     *   const input = parsed.inputs[i];
-     *   if (input.scriptId !== null && input.scriptType !== "p2shP2pk") {
-     *     psbt.sign(i, userXpriv);
-     *   }
-     * }
+     * // Sign a specific MuSig2 input after nonce generation
+     * psbt.generateMusig2Nonces(userXpriv);
+     * psbt.signInput(musig2InputIndex, userXpriv);
      *
-     * // Sign replay protection inputs with raw privkey
-     * const userPrivkey = bip32.fromBase58(userXpriv).privateKey!;
-     * for (let i = 0; i < parsed.inputs.length; i++) {
-     *   const input = parsed.inputs[i];
-     *   if (input.scriptType === "p2shP2pk") {
-     *     psbt.sign(i, userPrivkey);
-     *   }
-     * }
+     * // Sign a specific replay protection input
+     * psbt.signInput(rpInputIndex, replayProtectionPrivkey);
      * ```
      */
-    sign(inputIndex, key) {
-        // Detect key type
-        // If string or has 'derive' method → BIP32Arg
-        // Otherwise → ECPairArg
-        if (typeof key === "string" ||
-            (typeof key === "object" &&
-                key !== null &&
-                "derive" in key &&
-                typeof key.derive === "function")) {
+    signInput(inputIndex, key) {
+        if ((0, bip32_js_1.isBIP32Arg)(key)) {
             // It's a BIP32Arg
             const wasmKey = bip32_js_1.BIP32.from(key);
-            this._wasm.sign_with_xpriv(inputIndex, wasmKey.wasm);
+            // Route to the appropriate method based on input type
+            if (this._wasm.is_musig2_input(inputIndex)) {
+                // MuSig2 keypath: true single-input signing (efficient)
+                this._wasm.sign_musig2_input(inputIndex, wasmKey.wasm);
+            }
+            else {
+                // ECDSA/Schnorr script path: save/restore pattern (not faster than bulk)
+                this._wasm.sign_wallet_input(inputIndex, wasmKey.wasm);
+            }
         }
         else {
-            // It's an ECPairArg
+            // It's an ECPairArg - for replay protection inputs
             const wasmKey = ecpair_js_1.ECPair.from(key);
             this._wasm.sign_with_privkey(inputIndex, wasmKey.wasm);
         }

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

@@ -146,6 +146,20 @@ export class BitGoPsbt {
    * Get the unsigned transaction ID
    */
   unsigned_txid(): string;
+  /**
+   * Check if an input is a MuSig2 keypath input.
+   *
+   * MuSig2 inputs require special handling: nonces must be generated first with
+   * `generate_musig2_nonces()`, then signed with `sign_musig2_input()`.
+   *
+   * # Arguments
+   * - `input_index`: The index of the input to check (0-based)
+   *
+   * # Returns
+   * - `true` if the input is a MuSig2 keypath input
+   * - `false` otherwise (or if input_index is out of bounds)
+   */
+  is_musig2_input(input_index: number): boolean;
   /**
    * Sign a single input with an extended private key (xpriv)
    *
@@ -208,6 +222,45 @@ export class BitGoPsbt {
    * The index of the newly added output
    */
   add_wallet_output(chain: number, index: number, value: bigint, wallet_keys: WasmRootWalletKeys): number;
+  /**
+   * Sign a single MuSig2 keypath input.
+   *
+   * This uses the FirstRound state generated by `generate_musig2_nonces()`.
+   * Each FirstRound can only be used once (nonce reuse is a security risk).
+   *
+   * For non-MuSig2 inputs, returns an error (use `sign_wallet_input` instead).
+   *
+   * # Arguments
+   * - `input_index`: The index of the input to sign (0-based)
+   * - `xpriv`: The extended private key as a WasmBIP32 instance
+   *
+   * # Returns
+   * - `Ok(())` if signing was successful
+   * - `Err(WasmUtxoError)` if signing fails, no FirstRound exists, or not a MuSig2 input
+   */
+  sign_musig2_input(input_index: number, xpriv: WasmBIP32): void;
+  /**
+   * Sign a single non-MuSig2 wallet input using save/restore pattern.
+   *
+   * For MuSig2 inputs, returns an error (use `sign_musig2_input` instead).
+   * For ECDSA inputs, this uses a save/restore pattern: clones the PSBT,
+   * signs all inputs on the clone, then copies only the target input's
+   * signatures back.
+   *
+   * **Important:** This is NOT faster than `sign_all_wallet_inputs()` for ECDSA inputs.
+   * The underlying library signs all inputs regardless. This method just ensures
+   * that only the specified input gets signatures added to the PSBT.
+   * Use `sign_all_wallet_inputs()` when signing multiple inputs with the same key.
+   *
+   * # Arguments
+   * - `input_index`: The index of the input to sign (0-based)
+   * - `xpriv`: The extended private key as a WasmBIP32 instance
+   *
+   * # Returns
+   * - `Ok(())` if the input was signed
+   * - `Err(WasmUtxoError)` if signing fails or input is MuSig2
+   */
+  sign_wallet_input(input_index: number, xpriv: WasmBIP32): void;
   /**
    * Sign a single input with a raw private key
    *
@@ -266,6 +319,24 @@ export class BitGoPsbt {
    * - `Err(WasmUtxoError)` if any input failed to finalize
    */
   finalize_all_inputs(): void;
+  /**
+   * Sign all non-MuSig2 inputs with an extended private key (xpriv) in a single pass.
+   *
+   * This is more efficient than calling `sign_with_xpriv` for each input individually.
+   * The underlying miniscript library's `sign` method signs all matching inputs at once.
+   *
+   * **Note:** MuSig2 inputs are skipped by this method because they require FirstRound
+   * state from nonce generation. After calling this method, sign MuSig2 inputs
+   * individually using `sign_with_xpriv`.
+   *
+   * # Arguments
+   * - `xpriv`: The extended private key as a WasmBIP32 instance
+   *
+   * # Returns
+   * - `Ok(JsValue)` with an array of input indices that were signed
+   * - `Err(WasmUtxoError)` if signing fails
+   */
+  sign_all_with_xpriv(xpriv: WasmBIP32): any;
   /**
    * Add a PayGo attestation to a PSBT output
    *
@@ -325,6 +396,41 @@ export class BitGoPsbt {
    * generated for security. Custom session_id is only allowed on testnets for testing purposes.
    */
   generate_musig2_nonces(xpriv: WasmBIP32, session_id_bytes?: Uint8Array | null): void;
+  /**
+   * Sign all MuSig2 keypath inputs in a single pass with optimized sighash computation.
+   *
+   * This is more efficient than calling `sign_musig2_input()` for each input because
+   * it reuses the SighashCache across all inputs, avoiding redundant computation of
+   * sha_prevouts, sha_amounts, sha_scriptpubkeys, sha_sequences, and sha_outputs.
+   *
+   * Each MuSig2 input requires a FirstRound from `generate_musig2_nonces()`.
+   * FirstRounds that have already been consumed (signed) are skipped.
+   *
+   * # Arguments
+   * - `xpriv`: The extended private key as a WasmBIP32 instance
+   *
+   * # Returns
+   * - `Ok(JsValue)` with an array of input indices that were signed
+   * - `Err(WasmUtxoError)` if signing fails
+   */
+  sign_all_musig2_inputs(xpriv: WasmBIP32): any;
+  /**
+   * Sign all non-MuSig2 wallet inputs in a single efficient pass.
+   *
+   * This signs all ECDSA (P2SH, P2SH-P2WSH, P2WSH) and Taproot script path (P2TR)
+   * inputs that match the provided xpriv. MuSig2 keypath inputs are skipped.
+   *
+   * This is the most efficient way to sign wallet inputs. After calling this,
+   * sign any MuSig2 inputs using `sign_all_musig2_inputs()` or `sign_musig2_input()`.
+   *
+   * # Arguments
+   * - `xpriv`: The extended private key as a WasmBIP32 instance
+   *
+   * # Returns
+   * - `Ok(JsValue)` with an array of input indices that were signed
+   * - `Err(WasmUtxoError)` if signing fails
+   */
+  sign_all_wallet_inputs(xpriv: WasmBIP32): any;
   /**
    * Add an output to the PSBT by address
    *
@@ -411,12 +517,79 @@ export class BitGoPsbt {
    * Returns error if block height is before Overwinter activation
    */
   static create_empty_zcash_at_height(network: string, wallet_keys: WasmRootWalletKeys, block_height: number, version?: number | null, lock_time?: number | null, version_group_id?: number | null, expiry_height?: number | null): BitGoPsbt;
+  /**
+   * Sign a single input with an extended private key, using save/restore for ECDSA inputs.
+   *
+   * For MuSig2 inputs, this returns an error (use sign_with_xpriv which handles FirstRound).
+   * For ECDSA inputs, this clones the PSBT, signs all, then copies only the target
+   * input's signatures back.
+   *
+   * **Important:** This is NOT faster than `sign_all_with_xpriv` for ECDSA inputs.
+   * The underlying miniscript library signs all inputs regardless. This method
+   * just prevents signatures from being added to other inputs.
+   *
+   * # Arguments
+   * - `input_index`: The index of the input to sign (0-based)
+   * - `xpriv`: The extended private key as a WasmBIP32 instance
+   *
+   * # Returns
+   * - `Ok(())` if the input was signed
+   * - `Err(WasmUtxoError)` if signing fails
+   */
+  sign_single_input_with_xpriv(input_index: number, xpriv: WasmBIP32): void;
+  /**
+   * Sign all replay protection inputs with a raw private key.
+   *
+   * This iterates through all inputs looking for P2SH-P2PK (replay protection) inputs
+   * that match the provided public key and signs them.
+   *
+   * # Arguments
+   * - `ecpair`: The ECPair containing the private key
+   *
+   * # Returns
+   * - `Ok(JsValue)` with an array of input indices that were signed
+   * - `Err(WasmUtxoError)` if signing fails
+   */
+  sign_replay_protection_inputs(ecpair: WasmECPair): any;
   /**
    * Parse outputs with wallet keys to identify which outputs belong to a wallet
    *
    * Note: This method does NOT validate wallet inputs. It only parses outputs.
    */
   parse_outputs_with_wallet_keys(wallet_keys: WasmRootWalletKeys, paygo_pubkeys?: WasmECPair[] | null): any;
+  /**
+   * Sign a single input with a raw private key, using save/restore for regular inputs.
+   *
+   * For replay protection inputs (P2SH-P2PK), this uses direct signing which is
+   * already single-input. For regular inputs, this clones the PSBT, signs all,
+   * then copies only the target input's signatures back.
+   *
+   * **Important:** This is NOT faster than signing all inputs for regular (non-RP) inputs.
+   * The underlying miniscript library signs all inputs regardless.
+   *
+   * # Arguments
+   * - `input_index`: The index of the input to sign (0-based)
+   * - `ecpair`: The ECPair containing the private key
+   *
+   * # Returns
+   * - `Ok(())` if the input was signed
+   * - `Err(WasmUtxoError)` if signing fails
+   */
+  sign_single_input_with_privkey(input_index: number, ecpair: WasmECPair): void;
+  /**
+   * Sign all replay protection inputs with a raw private key.
+   *
+   * This iterates through all inputs looking for P2SH-P2PK (replay protection) inputs
+   * that match the provided public key and signs them.
+   *
+   * # Arguments
+   * - `ecpair`: The ECPair containing the private key
+   *
+   * # Returns
+   * - `Ok(JsValue)` with an array of input indices that were signed
+   * - `Err(WasmUtxoError)` if signing fails
+   */
+  sign_all_replay_protection_inputs(ecpair: WasmECPair): any;
   /**
    * Parse transaction with wallet keys to identify wallet inputs/outputs
    */