@bitgo/wasm-utxo 1.27.0 → 1.28.0

package/dist/esm/js/fixedScriptWallet/BitGoPsbt.js

@@ -1,7 +1,7 @@
 import { BitGoPsbt as WasmBitGoPsbt } from "../wasm/wasm_utxo.js";
 import { RootWalletKeys } from "./RootWalletKeys.js";
 import { ReplayProtection } from "./ReplayProtection.js";
-import { BIP32 } from "../bip32.js";
+import { BIP32, isBIP32Arg } from "../bip32.js";
 import { ECPair } from "../ecpair.js";
 export class BitGoPsbt {
     _wasm;
@@ -303,17 +303,49 @@ export class BitGoPsbt {
         const wasmECPair = 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 (isBIP32Arg(keyArg)) {
+            // It's a BIP32Arg - sign all wallet inputs (ECDSA + MuSig2)
+            const wasmKey = 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.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)
@@ -321,42 +353,30 @@ export 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 (isBIP32Arg(key)) {
             // It's a BIP32Arg
             const wasmKey = 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.from(key);
             this._wasm.sign_with_privkey(inputIndex, wasmKey.wasm);
         }

package/dist/esm/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
    */