feat(wasm-utxo): add combineMusig2Nonces method

Implements new combineMusig2Nonces method to merge MuSig2 nonces from
different PSBTs. This enables proper nonce exchange between cosigners
during the MuSig2 signing workflow. The method copies nonces and
partial signatures between PSBTs, validates network compatibility,
and handles input count matching.

Includes comprehensive tests and updated documentation with examples
showing the complete MuSig2 signing workflow.

Issue: BTC-2786

Co-authored-by: llm-git <llm-git@ttll.de>

Author: OttoAllmendinger

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

@@ -260,7 +260,8 @@ export class BitGoPsbt {
    * // Send PSBT to counterparty
    *
    * // Phase 2: After receiving counterparty PSBT with their nonces
-   * psbt.combine(counterpartyPsbtBytes);
+   * const counterpartyPsbt = BitGoPsbt.fromBytes(counterpartyPsbtBytes, network);
+   * psbt.combineMusig2Nonces(counterpartyPsbt);
    * // Sign MuSig2 key path inputs
    * const parsed = psbt.parseTransactionWithWalletKeys(walletKeys, replayProtection);
    * for (let i = 0; i < parsed.inputs.length; i++) {
@@ -275,6 +276,29 @@ export class BitGoPsbt {
     this.wasm.generate_musig2_nonces(wasmKey.wasm, sessionId);
   }
 
+  /**
+   * Combine/merge data from another PSBT into this one
+   *
+   * This method copies MuSig2 nonces and signatures (proprietary key-value pairs) from the
+   * source PSBT to this PSBT. This is useful for merging PSBTs during the nonce exchange
+   * and signature collection phases.
+   *
+   * @param sourcePsbt - The source PSBT containing data to merge
+   * @throws Error if networks don't match
+   *
+   * @example
+   * ```typescript
+   * // After receiving counterparty's PSBT with their nonces
+   * const counterpartyPsbt = BitGoPsbt.fromBytes(counterpartyPsbtBytes, network);
+   * psbt.combineMusig2Nonces(counterpartyPsbt);
+   * // Now can sign with all nonces present
+   * psbt.sign(0, userXpriv);
+   * ```
+   */
+  combineMusig2Nonces(sourcePsbt: BitGoPsbt): void {
+    this.wasm.combine_musig2_nonces(sourcePsbt.wasm);
+  }
+
   /**
    * Finalize all inputs in the PSBT
    *

packages/wasm-utxo/src/fixed_script_wallet/bitgo_psbt/mod.rs

@@ -204,6 +204,71 @@ impl BitGoPsbt {
         }
     }
 
+    /// Combine/merge data from another PSBT into this one
+    ///
+    /// This method copies MuSig2 nonces and signatures (proprietary key-value pairs) from the
+    /// source PSBT to this PSBT. This is useful for merging PSBTs during the nonce exchange
+    /// and signature collection phases.
+    ///
+    /// # Arguments
+    /// * `source_psbt` - The source PSBT containing data to merge
+    ///
+    /// # Returns
+    /// Ok(()) if data was successfully merged
+    ///
+    /// # Errors
+    /// Returns error if networks don't match
+    pub fn combine_musig2_nonces(&mut self, source_psbt: &BitGoPsbt) -> Result<(), String> {
+        // Check network match
+        if self.network() != source_psbt.network() {
+            return Err(format!(
+                "Network mismatch: destination is {}, source is {}",
+                self.network(),
+                source_psbt.network()
+            ));
+        }
+
+        let source = source_psbt.psbt();
+        let dest = self.psbt_mut();
+
+        // Check that both PSBTs have the same number of inputs
+        if source.inputs.len() != dest.inputs.len() {
+            return Err(format!(
+                "PSBT input count mismatch: source has {} inputs, destination has {}",
+                source.inputs.len(),
+                dest.inputs.len()
+            ));
+        }
+
+        // Copy MuSig2 nonces and partial signatures (proprietary key-values with BITGO identifier)
+        for (source_input, dest_input) in source.inputs.iter().zip(dest.inputs.iter_mut()) {
+            // Only process if the input is a MuSig2 input
+            if !p2tr_musig2_input::Musig2Input::is_musig2_input(source_input) {
+                continue;
+            }
+
+            // Parse nonces from source input using native Musig2 functions
+            let nonces = p2tr_musig2_input::parse_musig2_nonces(source_input)
+                .map_err(|e| format!("Failed to parse MuSig2 nonces from source: {}", e))?;
+
+            // Copy each nonce to the destination input
+            for nonce in nonces {
+                let (key, value) = nonce.to_key_value().to_key_value();
+                dest_input.proprietary.insert(key, value);
+            }
+
+            // Also copy partial signatures if present
+            // Partial sigs are stored as tap_script_sigs in the PSBT input
+            for (control_block, leaf_script) in &source_input.tap_script_sigs {
+                dest_input
+                    .tap_script_sigs
+                    .insert(*control_block, *leaf_script);
+            }
+        }
+
+        Ok(())
+    }
+
     /// Serialize the PSBT to bytes, using network-specific logic
     pub fn serialize(&self) -> Result<Vec<u8>, SerializeError> {
         match self {

packages/wasm-utxo/src/wasm/fixed_script_wallet.rs

@@ -504,6 +504,26 @@ impl BitGoPsbt {
             .map_err(|e| WasmUtxoError::new(&format!("Failed to sign input: {}", e)))
     }
 
+    /// Combine/merge data from another PSBT into this one
+    ///
+    /// This method copies MuSig2 nonces and signatures (proprietary key-value pairs) from the
+    /// source PSBT to this PSBT. This is useful for merging PSBTs during the nonce exchange
+    /// and signature collection phases.
+    ///
+    /// # Arguments
+    /// * `source_psbt` - The source PSBT containing data to merge
+    ///
+    /// # Returns
+    /// Ok(()) if data was successfully merged
+    ///
+    /// # Errors
+    /// Returns error if networks don't match
+    pub fn combine_musig2_nonces(&mut self, source_psbt: &BitGoPsbt) -> Result<(), WasmUtxoError> {
+        self.psbt
+            .combine_musig2_nonces(&source_psbt.psbt)
+            .map_err(|e| WasmUtxoError::new(&format!("Failed to combine PSBTs: {}", e)))
+    }
+
     /// Finalize all inputs in the PSBT
     ///
     /// This method attempts to finalize all inputs in the PSBT, computing the final

packages/wasm-utxo/test/fixedScript/musig2Nonces.ts

@@ -1,37 +1,89 @@
 import assert from "assert";
-import { BitGoPsbt } from "../../js/fixedScriptWallet/index.js";
 import { BIP32 } from "../../js/bip32.js";
-import {
-  loadPsbtFixture,
-  getBitGoPsbt,
-  type Fixture,
-} from "./fixtureUtil.js";
+import { loadPsbtFixture, getBitGoPsbt, type Fixture } from "./fixtureUtil.js";
 
 describe("MuSig2 nonce management", function () {
   describe("Bitcoin mainnet", function () {
     const networkName = "bitcoin";
     let fixture: Fixture;
-    let unsignedBitgoPsbt: BitGoPsbt;
     let userKey: BIP32;
+    let backupKey: BIP32;
+    let bitgoKey: BIP32;
 
     before(function () {
       fixture = loadPsbtFixture(networkName, "unsigned");
-      unsignedBitgoPsbt = getBitGoPsbt(fixture, networkName);
       userKey = BIP32.fromBase58(fixture.walletKeys[0]);
+      backupKey = BIP32.fromBase58(fixture.walletKeys[1]);
+      bitgoKey = BIP32.fromBase58(fixture.walletKeys[2]);
     });
 
     it("should generate nonces for MuSig2 inputs with auto-generated session ID", function () {
+      const unsignedBitgoPsbt = getBitGoPsbt(fixture, networkName);
       // Generate nonces with auto-generated session ID (no second parameter)
       assert.doesNotThrow(() => {
         unsignedBitgoPsbt.generateMusig2Nonces(userKey);
       });
-
       // Verify nonces were stored by serializing and deserializing
-      const serialized = unsignedBitgoPsbt.serialize();
-      assert.ok(serialized.length > getBitGoPsbt(fixture, networkName).serialize().length);
+      const serializedWithUserNonces = unsignedBitgoPsbt.serialize();
+      assert.ok(
+        serializedWithUserNonces.length > getBitGoPsbt(fixture, networkName).serialize().length,
+      );
+
+      assert.doesNotThrow(() => {
+        unsignedBitgoPsbt.generateMusig2Nonces(bitgoKey);
+      });
+
+      const serializedWithBitgoNonces = unsignedBitgoPsbt.serialize();
+      assert.ok(serializedWithBitgoNonces.length > serializedWithUserNonces.length);
+
+      assert.throws(() => {
+        unsignedBitgoPsbt.generateMusig2Nonces(backupKey);
+      }, "Should throw error when generating nonces for backup key");
+    });
+
+    it("implements combineMusig2Nonces", function () {
+      const unsignedBitgoPsbtWithUserNonces = getBitGoPsbt(fixture, networkName);
+      unsignedBitgoPsbtWithUserNonces.generateMusig2Nonces(userKey);
+
+      const unsignedBitgoPsbtWithBitgoNonces = getBitGoPsbt(fixture, networkName);
+      unsignedBitgoPsbtWithBitgoNonces.generateMusig2Nonces(bitgoKey);
+
+      const unsignedBitgoPsbtWithBothNonces = getBitGoPsbt(fixture, networkName);
+      unsignedBitgoPsbtWithBothNonces.combineMusig2Nonces(unsignedBitgoPsbtWithUserNonces);
+      unsignedBitgoPsbtWithBothNonces.combineMusig2Nonces(unsignedBitgoPsbtWithBitgoNonces);
+
+      {
+        const psbt = getBitGoPsbt(fixture, networkName);
+        psbt.combineMusig2Nonces(unsignedBitgoPsbtWithUserNonces);
+        assert.strictEqual(
+          psbt.serialize().length,
+          unsignedBitgoPsbtWithUserNonces.serialize().length,
+        );
+      }
+
+      {
+        const psbt = getBitGoPsbt(fixture, networkName);
+        psbt.combineMusig2Nonces(unsignedBitgoPsbtWithBitgoNonces);
+        assert.strictEqual(
+          psbt.serialize().length,
+          unsignedBitgoPsbtWithBitgoNonces.serialize().length,
+        );
+      }
+
+      {
+        const psbt = getBitGoPsbt(fixture, networkName);
+        psbt.combineMusig2Nonces(unsignedBitgoPsbtWithUserNonces);
+        psbt.combineMusig2Nonces(unsignedBitgoPsbtWithBitgoNonces);
+        assert.strictEqual(
+          psbt.serialize().length,
+          unsignedBitgoPsbtWithBothNonces.serialize().length,
+        );
+      }
     });
 
     it("should reject invalid session ID length", function () {
+      const unsignedBitgoPsbt = getBitGoPsbt(fixture, networkName);
+
       // Invalid session ID (wrong length)
       const invalidSessionId = new Uint8Array(16); // Should be 32 bytes
 
@@ -41,6 +93,7 @@ describe("MuSig2 nonce management", function () {
     });
 
     it("should reject custom session ID on mainnet (security)", function () {
+      const unsignedBitgoPsbt = getBitGoPsbt(fixture, "bitcoin");
       // Custom session ID should be rejected on mainnet for security
       const customSessionId = new Uint8Array(32).fill(1);