@bitgo/wasm-utxo 1.6.0 → 1.8.0

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

@@ -20,22 +20,45 @@ export class BitGoPsbt {
    */
   unsigned_txid(): string;
   /**
-   * Verify if a valid signature exists for a given xpub at the specified input index
+   * Sign a single input with an extended private key (xpriv)
    *
-   * This method derives the public key from the xpub using the derivation path found in the
-   * PSBT input, then verifies the signature. It supports both ECDSA signatures (for legacy/SegWit
-   * inputs) and Schnorr signatures (for Taproot script path inputs).
+   * 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 check
-   * - `xpub_str`: The extended public key as a base58-encoded string
+   * - `input_index`: The index of the input to sign (0-based)
+   * - `xpriv`: The extended private key as a WasmBIP32 instance
    *
    * # Returns
-   * - `Ok(true)` if a valid signature exists for the derived public key
-   * - `Ok(false)` if no signature exists for the derived public key
-   * - `Err(WasmUtxoError)` if the input index is out of bounds, xpub is invalid, derivation fails, or verification fails
+   * - `Ok(())` if signing was successful
+   * - `Err(WasmUtxoError)` if signing fails
    */
-  verify_signature(input_index: number, xpub_str: string): boolean;
+  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
    *
@@ -58,16 +81,101 @@ 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
+   *
+   * This method verifies the signature directly with the provided ECPair's public key. It supports:
+   * - ECDSA signatures (for legacy/SegWit inputs)
+   * - Schnorr signatures (for Taproot script path inputs)
+   *
+   * Note: This method does NOT support MuSig2 inputs, as MuSig2 requires derivation from xpubs.
+   * Use `verify_signature_with_xpub` for MuSig2 inputs.
+   *
+   * # Arguments
+   * - `input_index`: The index of the input to check
+   * - `ecpair`: The ECPair key (uses the public key for verification)
+   *
+   * # Returns
+   * - `Ok(true)` if a valid signature exists for the public key
+   * - `Ok(false)` if no signature exists for the public key
+   * - `Err(WasmUtxoError)` if the input index is out of bounds or verification fails
+   */
+  verify_signature_with_pub(input_index: number, ecpair: WasmECPair): boolean;
+  /**
+   * Verify if a valid signature exists for a given xpub at the specified input index
+   *
+   * This method derives the public key from the xpub using the derivation path found in the
+   * PSBT input, then verifies the signature. It supports:
+   * - ECDSA signatures (for legacy/SegWit inputs)
+   * - Schnorr signatures (for Taproot script path inputs)
+   * - MuSig2 partial signatures (for Taproot keypath MuSig2 inputs)
+   *
+   * # Arguments
+   * - `input_index`: The index of the input to check
+   * - `xpub`: The extended public key as a WasmBIP32 instance
+   *
+   * # Returns
+   * - `Ok(true)` if a valid signature exists for the derived public key
+   * - `Ok(false)` if no signature exists for the derived public key
+   * - `Err(WasmUtxoError)` if the input index is out of bounds, derivation fails, or verification fails
+   */
+  verify_signature_with_xpub(input_index: number, xpub: WasmBIP32): boolean;
   /**
    * 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: any): any;
+  parse_outputs_with_wallet_keys(wallet_keys: WasmRootWalletKeys): any;
   /**
    * Parse transaction with wallet keys to identify wallet inputs/outputs
    */
-  parse_transaction_with_wallet_keys(wallet_keys: any, replay_protection: any): any;
+  parse_transaction_with_wallet_keys(wallet_keys: WasmRootWalletKeys, replay_protection: WasmReplayProtection): any;
   /**
    * Verify if a replay protection input has a valid signature
    *
@@ -85,7 +193,11 @@ export class BitGoPsbt {
    * - `Ok(false)` if the input is a replay protection input but has no valid signature
    * - `Err(WasmUtxoError)` if the input is not a replay protection input, index is out of bounds, or configuration is invalid
    */
-  verify_replay_protection_signature(input_index: number, replay_protection: any): boolean;
+  verify_replay_protection_signature(input_index: number, replay_protection: WasmReplayProtection): boolean;
+  /**
+   * Get the network of the PSBT
+   */
+  network(): string;
   /**
    * Serialize the PSBT to bytes
    *
@@ -98,8 +210,8 @@ export class FixedScriptWalletNamespace {
   private constructor();
   free(): void;
   [Symbol.dispose](): void;
-  static output_script(keys: any, chain: number, index: number, network: any): Uint8Array;
-  static address(keys: any, chain: number, index: number, network: any, address_format?: string | null): string;
+  static output_script(keys: WasmRootWalletKeys, chain: number, index: number, network: any): Uint8Array;
+  static address(keys: WasmRootWalletKeys, chain: number, index: number, network: any, address_format?: string | null): string;
 }
 export class UtxolibCompatNamespace {
   private constructor();
@@ -124,6 +236,212 @@ export class UtxolibCompatNamespace {
    */
   static from_output_script(script: Uint8Array, network: any, format?: string | null): string;
 }
+/**
+ * WASM wrapper for BIP32 extended keys (Xpub/Xpriv)
+ * Implements the BIP32Interface TypeScript interface
+ */
+export class WasmBIP32 {
+  private constructor();
+  free(): void;
+  [Symbol.dispose](): void;
+  /**
+   * Derive a key using a derivation path (e.g., "0/1/2" or "m/0/1/2")
+   */
+  derive_path(path: string): WasmBIP32;
+  /**
+   * Create a BIP32 key from a base58 string (xpub/xprv/tpub/tprv)
+   */
+  static from_base58(base58_str: string): WasmBIP32;
+  /**
+   * Check if this is a neutered (public) key
+   */
+  is_neutered(): boolean;
+  /**
+   * Derive a hardened child key (only works for private keys)
+   */
+  derive_hardened(index: number): WasmBIP32;
+  /**
+   * Create a BIP32 key from a BIP32Interface JavaScript object properties
+   * Expects an object with: network.bip32.public, depth, parentFingerprint,
+   * index, chainCode, and publicKey properties
+   */
+  static from_bip32_interface(bip32_key: any): WasmBIP32;
+  /**
+   * Create a BIP32 key from BIP32 properties
+   * Extracts properties from a JavaScript object and constructs an xpub
+   */
+  static from_bip32_properties(bip32_key: any): WasmBIP32;
+  /**
+   * Derive a normal (non-hardened) child key
+   */
+  derive(index: number): WasmBIP32;
+  /**
+   * Get the WIF encoding of the private key
+   */
+  to_wif(): string;
+  /**
+   * Get the neutered (public) version of this key
+   */
+  neutered(): WasmBIP32;
+  /**
+   * Create a BIP32 master key from a seed
+   */
+  static from_seed(seed: Uint8Array, network?: string | null): WasmBIP32;
+  /**
+   * Create a BIP32 key from an xprv string (base58-encoded)
+   */
+  static from_xprv(xprv_str: string): WasmBIP32;
+  /**
+   * Create a BIP32 key from an xpub string (base58-encoded)
+   */
+  static from_xpub(xpub_str: string): WasmBIP32;
+  /**
+   * Serialize to base58 string
+   */
+  to_base58(): string;
+  /**
+   * Get the chain code as a Uint8Array
+   */
+  readonly chain_code: Uint8Array;
+  /**
+   * Get the identifier as a Uint8Array
+   */
+  readonly identifier: Uint8Array;
+  /**
+   * Get the public key as a Uint8Array
+   */
+  readonly public_key: Uint8Array;
+  /**
+   * Get the fingerprint as a Uint8Array
+   */
+  readonly fingerprint: Uint8Array;
+  /**
+   * Get the private key as a Uint8Array (if available)
+   */
+  readonly private_key: Uint8Array | undefined;
+  /**
+   * Get the parent fingerprint
+   */
+  readonly parent_fingerprint: number;
+  /**
+   * Get the depth
+   */
+  readonly depth: number;
+  /**
+   * Get the child index
+   */
+  readonly index: number;
+}
+/**
+ * WASM wrapper for elliptic curve key pairs (always uses compressed keys)
+ */
+export class WasmECPair {
+  private constructor();
+  free(): void;
+  [Symbol.dispose](): void;
+  /**
+   * Convert to mainnet WIF string
+   */
+  to_wif_mainnet(): string;
+  /**
+   * Convert to testnet WIF string
+   */
+  to_wif_testnet(): string;
+  /**
+   * Create an ECPair from a public key (always uses compressed keys)
+   */
+  static from_public_key(public_key: Uint8Array): WasmECPair;
+  /**
+   * Create an ECPair from a private key (always uses compressed keys)
+   */
+  static from_private_key(private_key: Uint8Array): WasmECPair;
+  /**
+   * Create an ECPair from a mainnet WIF string
+   */
+  static from_wif_mainnet(wif_string: string): WasmECPair;
+  /**
+   * Create an ECPair from a testnet WIF string
+   */
+  static from_wif_testnet(wif_string: string): WasmECPair;
+  /**
+   * Convert to WIF string (mainnet)
+   */
+  to_wif(): string;
+  /**
+   * Create an ECPair from a WIF string (auto-detects network)
+   */
+  static from_wif(wif_string: string): WasmECPair;
+  /**
+   * Get the compressed public key as a Uint8Array (always 33 bytes)
+   */
+  readonly public_key: Uint8Array;
+  /**
+   * Get the private key as a Uint8Array (if available)
+   */
+  readonly private_key: Uint8Array | undefined;
+}
+/**
+ * WASM wrapper for ReplayProtection
+ */
+export class WasmReplayProtection {
+  private constructor();
+  free(): void;
+  [Symbol.dispose](): void;
+  /**
+   * Create from addresses (requires network for decoding)
+   */
+  static from_addresses(addresses: any[], network: string): WasmReplayProtection;
+  /**
+   * Create from public keys (derives P2SH-P2PK output scripts)
+   */
+  static from_public_keys(public_keys: Uint8Array[]): WasmReplayProtection;
+  /**
+   * Create from output scripts directly
+   */
+  static from_output_scripts(output_scripts: Uint8Array[]): WasmReplayProtection;
+}
+/**
+ * WASM wrapper for RootWalletKeys
+ * Represents a set of three extended public keys with their derivation prefixes
+ */
+export class WasmRootWalletKeys {
+  free(): void;
+  [Symbol.dispose](): void;
+  /**
+   * Get the backup key (second xpub)
+   */
+  backup_key(): WasmBIP32;
+  /**
+   * Create a RootWalletKeys from three BIP32 keys with custom derivation prefixes
+   *
+   * # Arguments
+   * - `user`: User key (first xpub)
+   * - `backup`: Backup key (second xpub)
+   * - `bitgo`: BitGo key (third xpub)
+   * - `user_derivation`: Derivation path for user key (e.g., "m/0/0")
+   * - `backup_derivation`: Derivation path for backup key (e.g., "m/0/0")
+   * - `bitgo_derivation`: Derivation path for bitgo key (e.g., "m/0/0")
+   */
+  static with_derivation_prefixes(user: WasmBIP32, backup: WasmBIP32, bitgo: WasmBIP32, user_derivation: string, backup_derivation: string, bitgo_derivation: string): WasmRootWalletKeys;
+  /**
+   * Create a RootWalletKeys from three BIP32 keys
+   * Uses default derivation prefix of m/0/0 for all three keys
+   *
+   * # Arguments
+   * - `user`: User key (first xpub)
+   * - `backup`: Backup key (second xpub)
+   * - `bitgo`: BitGo key (third xpub)
+   */
+  constructor(user: WasmBIP32, backup: WasmBIP32, bitgo: WasmBIP32);
+  /**
+   * Get the user key (first xpub)
+   */
+  user_key(): WasmBIP32;
+  /**
+   * Get the bitgo key (third xpub)
+   */
+  bitgo_key(): WasmBIP32;
+}
 export class WrapDescriptor {
   private constructor();
   free(): void;