@bitgo/wasm-utxo 1.7.0 → 1.9.0

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

@@ -100,6 +100,46 @@ export declare class BitGoPsbt {
      * ```
      */
     verifySignature(inputIndex: number, key: BIP32Arg | ECPairArg): boolean;
+    /**
+     * 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
+     *
+     * 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
+     *
+     * @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 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(inputIndex: number, key: BIP32Arg | ECPairArg): void;
     /**
      * @deprecated - use verifySignature with the replay protection key instead
      *
@@ -127,6 +167,65 @@ export declare class BitGoPsbt {
      * @returns The serialized PSBT as a byte array
      */
     serialize(): Uint8Array;
+    /**
+     * Generate and store MuSig2 nonces for all MuSig2 inputs
+     *
+     * This method generates nonces using the State-Machine API and stores them in the PSBT.
+     * The nonces are stored as proprietary fields in the PSBT and will be included when serialized.
+     * After ALL participants have generated their nonces, you can sign MuSig2 inputs using
+     * sign().
+     *
+     * @param key - The extended private key (xpriv) for signing. Can be a base58 string, BIP32 instance, or WasmBIP32
+     * @param sessionId - Optional 32-byte session ID for nonce generation. **Only allowed on testnets**.
+     *                    On mainnets, a secure random session ID is always generated automatically.
+     *                    Must be unique per signing session.
+     * @throws Error if nonce generation fails, sessionId length is invalid, or custom sessionId is
+     *         provided on a mainnet (security restriction)
+     *
+     * @security The sessionId MUST be cryptographically random and unique for each signing session.
+     * Never reuse a sessionId with the same key! On mainnets, sessionId is always randomly
+     * generated for security. Custom sessionId is only allowed on testnets for testing purposes.
+     *
+     * @example
+     * ```typescript
+     * // Phase 1: Both parties generate nonces (with auto-generated session ID)
+     * psbt.generateMusig2Nonces(userXpriv);
+     * // Nonces are stored in the PSBT
+     * // Send PSBT to counterparty
+     *
+     * // Phase 2: After receiving counterparty PSBT with their nonces
+     * 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++) {
+     *   if (parsed.inputs[i].scriptType === "p2trMusig2KeyPath") {
+     *     psbt.sign(i, userXpriv);
+     *   }
+     * }
+     * ```
+     */
+    generateMusig2Nonces(key: BIP32Arg, sessionId?: Uint8Array): void;
+    /**
+     * 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;
     /**
      * Finalize all inputs in the PSBT
      *

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

@@ -99,6 +99,64 @@ class BitGoPsbt {
         const wasmECPair = ecpair_js_1.ECPair.from(key).wasm;
         return this.wasm.verify_signature_with_pub(inputIndex, wasmECPair);
     }
+    /**
+     * 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
+     *
+     * 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
+     *
+     * @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 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(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")) {
+            // It's a BIP32Arg
+            const wasmKey = bip32_js_1.BIP32.from(key);
+            this.wasm.sign_with_xpriv(inputIndex, wasmKey.wasm);
+        }
+        else {
+            // It's an ECPairArg
+            const wasmKey = ecpair_js_1.ECPair.from(key);
+            this.wasm.sign_with_privkey(inputIndex, wasmKey.wasm);
+        }
+    }
     /**
      * @deprecated - use verifySignature with the replay protection key instead
      *
@@ -131,6 +189,70 @@ class BitGoPsbt {
     serialize() {
         return this.wasm.serialize();
     }
+    /**
+     * Generate and store MuSig2 nonces for all MuSig2 inputs
+     *
+     * This method generates nonces using the State-Machine API and stores them in the PSBT.
+     * The nonces are stored as proprietary fields in the PSBT and will be included when serialized.
+     * After ALL participants have generated their nonces, you can sign MuSig2 inputs using
+     * sign().
+     *
+     * @param key - The extended private key (xpriv) for signing. Can be a base58 string, BIP32 instance, or WasmBIP32
+     * @param sessionId - Optional 32-byte session ID for nonce generation. **Only allowed on testnets**.
+     *                    On mainnets, a secure random session ID is always generated automatically.
+     *                    Must be unique per signing session.
+     * @throws Error if nonce generation fails, sessionId length is invalid, or custom sessionId is
+     *         provided on a mainnet (security restriction)
+     *
+     * @security The sessionId MUST be cryptographically random and unique for each signing session.
+     * Never reuse a sessionId with the same key! On mainnets, sessionId is always randomly
+     * generated for security. Custom sessionId is only allowed on testnets for testing purposes.
+     *
+     * @example
+     * ```typescript
+     * // Phase 1: Both parties generate nonces (with auto-generated session ID)
+     * psbt.generateMusig2Nonces(userXpriv);
+     * // Nonces are stored in the PSBT
+     * // Send PSBT to counterparty
+     *
+     * // Phase 2: After receiving counterparty PSBT with their nonces
+     * 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++) {
+     *   if (parsed.inputs[i].scriptType === "p2trMusig2KeyPath") {
+     *     psbt.sign(i, userXpriv);
+     *   }
+     * }
+     * ```
+     */
+    generateMusig2Nonces(key, sessionId) {
+        const wasmKey = bip32_js_1.BIP32.from(key);
+        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) {
+        this.wasm.combine_musig2_nonces(sourcePsbt.wasm);
+    }
     /**
      * Finalize all inputs in the PSBT
      *

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

@@ -19,6 +19,46 @@ export class BitGoPsbt {
    * Get the unsigned transaction ID
    */
   unsigned_txid(): string;
+  /**
+   * Sign a single input with an extended private key (xpriv)
+   *
+   * This method signs a specific input using the provided xpriv. It accepts:
+   * - An xpriv (WasmBIP32) for wallet inputs - derives the key and signs
+   *
+   * 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 generate_musig2_nonces()
+   * - For replay protection inputs: returns error (use sign_with_privkey 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
+   */
+  sign_with_xpriv(input_index: number, xpriv: WasmBIP32): void;
+  /**
+   * Sign a single input with a raw private key
+   *
+   * This method signs a specific input using the provided ECPair. It accepts:
+   * - A raw privkey (WasmECPair) for replay protection inputs - signs directly
+   *
+   * This method automatically detects and handles different input types:
+   * - For replay protection inputs: signs with legacy P2SH sighash
+   * - For regular inputs: uses standard PSBT signing
+   * - For MuSig2 inputs: returns error (requires FirstRound, use sign_with_xpriv instead)
+   *
+   * # Arguments
+   * - `input_index`: The index of the input to sign (0-based)
+   * - `ecpair`: The ECPair containing the private key
+   *
+   * # Returns
+   * - `Ok(())` if signing was successful
+   * - `Err(WasmUtxoError)` if signing fails
+   */
+  sign_with_privkey(input_index: number, ecpair: WasmECPair): void;
   /**
    * Extract the final transaction from a finalized PSBT
    *
@@ -41,6 +81,52 @@ export class BitGoPsbt {
    * - `Err(WasmUtxoError)` if any input failed to finalize
    */
   finalize_all_inputs(): void;
+  /**
+   * 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
+   */
+  combine_musig2_nonces(source_psbt: BitGoPsbt): void;
+  /**
+   * Generate and store MuSig2 nonces for all MuSig2 inputs
+   *
+   * This method generates nonces using the State-Machine API and stores them in the PSBT.
+   * The nonces are stored as proprietary fields in the PSBT and will be included when serialized.
+   * After ALL participants have generated their nonces, they can sign MuSig2 inputs using
+   * sign_with_xpriv().
+   *
+   * # Arguments
+   * * `xpriv` - The extended private key (xpriv) for signing
+   * * `session_id_bytes` - Optional 32-byte session ID for nonce generation. **Only allowed on testnets**.
+   *                        On mainnets, a secure random session ID is always generated automatically.
+   *                        Must be unique per signing session.
+   *
+   * # Returns
+   * Ok(()) if nonces were successfully generated and stored
+   *
+   * # Errors
+   * Returns error if:
+   * - Nonce generation fails
+   * - session_id length is invalid
+   * - Custom session_id is provided on a mainnet (security restriction)
+   *
+   * # Security
+   * The session_id MUST be cryptographically random and unique for each signing session.
+   * Never reuse a session_id with the same key! On mainnets, session_id is always randomly
+   * 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;
   /**
    * Verify if a valid signature exists for a given ECPair key at the specified input index
    *