feat(wasm-utxo): redesign PSBT signing API for clarity and performance

Problem:
The previous signing API had several issues:
1. `signInput(index, key)` claimed to sign only one input but actually
   signed ALL inputs internally (for ECDSA), which was misleading
2. MuSig2 bulk signing was inefficient - it recreated SighashCache for
   each input, recomputing sha_prevouts, sha_amounts, sha_scriptpubkeys,
   sha_sequences, and sha_outputs redundantly
3. The API didn't clearly communicate performance characteristics

Solution:
Implement an honest, clean WASM/Rust API that explicitly communicates
what each method does and its performance implications.

New WASM API (backward compatible - old methods kept as deprecated):
- is_musig2_input(index) - check if input is MuSig2 keypath
- sign_all_wallet_inputs(xpriv) - bulk sign ECDSA/Schnorr script path
- sign_wallet_input(index, xpriv) - single input with save/restore
  (documented as NOT faster than bulk)
- sign_musig2_input(index, xpriv) - single MuSig2 input
- sign_all_musig2_inputs(xpriv) - NEW: bulk MuSig2 with SighashCache
  reuse for 2x performance improvement
- sign_replay_protection_inputs(ecpair) - bulk replay protection

TypeScript changes:
- Added isBIP32Arg() type guard to js/bip32.ts
- Updated sign(key) to call both sign_all_wallet_inputs and
  sign_all_musig2_inputs for optimal bulk performance
- Updated signInput() to route to appropriate method based on input type

Rust changes:
- Added sign_with_first_round_and_cache() to Musig2Context that accepts
  external SighashCache and prevouts for efficient batch MuSig2 signing
- Added corresponding wrapper in BitGoPsbt

Performance results (1000 inputs):
- ECDSA bulk: ~1.7ms per input (unchanged)
- MuSig2 bulk: ~4.5ms per input (was ~9.5ms - 2x improvement!)

The MuSig2 improvement comes from reusing SighashCache which caches
the shared BIP-341 sighash components across all inputs.

Issue: BTC-2980

Author: OttoAllmendinger

packages/wasm-utxo/js/bip32.ts

@@ -224,3 +224,21 @@ export class BIP32 implements BIP32Interface {
     return this._wasm;
   }
 }
+
+/**
+ * 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 function isBIP32Arg(key: unknown): key is BIP32Arg {
+  return (
+    typeof key === "string" ||
+    key instanceof BIP32 ||
+    key instanceof WasmBIP32 ||
+    (typeof key === "object" &&
+      key !== null &&
+      "derive" in key &&
+      typeof (key as BIP32Interface).derive === "function")
+  );
+}

packages/wasm-utxo/js/fixedScriptWallet/BitGoPsbt.ts

@@ -1,7 +1,7 @@
 import { BitGoPsbt as WasmBitGoPsbt } from "../wasm/wasm_utxo.js";
 import { type WalletKeysArg, RootWalletKeys } from "./RootWalletKeys.js";
 import { type ReplayProtectionArg, ReplayProtection } from "./ReplayProtection.js";
-import { type BIP32Arg, BIP32 } from "../bip32.js";
+import { type BIP32Arg, BIP32, isBIP32Arg } from "../bip32.js";
 import { type ECPairArg, ECPair } from "../ecpair.js";
 import type { UtxolibName } from "../utxolibCompat.js";
 import type { CoinName } from "../coinName.js";
@@ -515,60 +515,126 @@ export class BitGoPsbt {
   }
 
   /**
-   * 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(
+    inputIndexOrKey: number | BIP32Arg | ECPairArg,
+    key?: BIP32Arg | ECPairArg,
+  ): number[] | void {
+    // 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) as number[];
+      // Sign all MuSig2 keypath inputs (more efficient - reuses SighashCache)
+      const musig2Signed = this._wasm.sign_all_musig2_inputs(wasmKey.wasm) as number[];
+      return [...walletSigned, ...musig2Signed];
+    } else {
+      // It's an ECPairArg - sign all replay protection inputs
+      const wasmKey = ECPair.from(keyArg as ECPairArg);
+      return this._wasm.sign_replay_protection_inputs(wasmKey.wasm) as number[];
+    }
+  }
+
+  /**
+   * 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)
    * @throws Error if signing fails, or if generateMusig2Nonces() was not called first for MuSig2 inputs
    *
    * @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 {
-    // 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: number, key: BIP32Arg | ECPairArg): void {
+    if (isBIP32Arg(key)) {
       // It's a BIP32Arg
-      const wasmKey = BIP32.from(key as BIP32Arg);
-      this._wasm.sign_with_xpriv(inputIndex, wasmKey.wasm);
+      const wasmKey = BIP32.from(key);
+      // 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 as ECPairArg);
       this._wasm.sign_with_privkey(inputIndex, wasmKey.wasm);
     }