@bitgo/wasm-utxo 1.6.0 → 1.8.0

package/dist/esm/js/bip32.js

@@ -0,0 +1,173 @@
+import { WasmBIP32 } from "./wasm/wasm_utxo.js";
+/**
+ * BIP32 wrapper class for extended key operations
+ */
+export class BIP32 {
+    _wasm;
+    constructor(_wasm) {
+        this._wasm = _wasm;
+    }
+    /**
+     * Create a BIP32 instance from a WasmBIP32 instance (internal use)
+     * @internal
+     */
+    static fromWasm(wasm) {
+        return new BIP32(wasm);
+    }
+    /**
+     * Convert BIP32Arg to BIP32 instance
+     * @param key - The BIP32 key in various formats
+     * @returns BIP32 instance
+     */
+    static from(key) {
+        // Short-circuit if already a BIP32 instance
+        if (key instanceof BIP32) {
+            return key;
+        }
+        // If it's a WasmBIP32 instance, wrap it
+        if (key instanceof WasmBIP32) {
+            return new BIP32(key);
+        }
+        // If it's a string, parse from base58
+        if (typeof key === "string") {
+            const wasm = WasmBIP32.from_base58(key);
+            return new BIP32(wasm);
+        }
+        // If it's an object (BIP32Interface), use from_bip32_interface
+        if (typeof key === "object" && key !== null) {
+            const wasm = WasmBIP32.from_bip32_interface(key);
+            return new BIP32(wasm);
+        }
+        throw new Error("Invalid BIP32Arg type");
+    }
+    /**
+     * Create a BIP32 key from a base58 string (xpub/xprv/tpub/tprv)
+     * @param base58Str - The base58-encoded extended key string
+     * @returns A BIP32 instance
+     */
+    static fromBase58(base58Str) {
+        const wasm = WasmBIP32.from_base58(base58Str);
+        return new BIP32(wasm);
+    }
+    /**
+     * Create a BIP32 master key from a seed
+     * @param seed - The seed bytes
+     * @param network - Optional network string
+     * @returns A BIP32 instance
+     */
+    static fromSeed(seed, network) {
+        const wasm = WasmBIP32.from_seed(seed, network);
+        return new BIP32(wasm);
+    }
+    /**
+     * Get the chain code as a Uint8Array
+     */
+    get chainCode() {
+        return this._wasm.chain_code;
+    }
+    /**
+     * Get the depth
+     */
+    get depth() {
+        return this._wasm.depth;
+    }
+    /**
+     * Get the child index
+     */
+    get index() {
+        return this._wasm.index;
+    }
+    /**
+     * Get the parent fingerprint
+     */
+    get parentFingerprint() {
+        return this._wasm.parent_fingerprint;
+    }
+    /**
+     * Get the private key as a Uint8Array (if available)
+     */
+    get privateKey() {
+        return this._wasm.private_key;
+    }
+    /**
+     * Get the public key as a Uint8Array
+     */
+    get publicKey() {
+        return this._wasm.public_key;
+    }
+    /**
+     * Get the identifier as a Uint8Array
+     */
+    get identifier() {
+        return this._wasm.identifier;
+    }
+    /**
+     * Get the fingerprint as a Uint8Array
+     */
+    get fingerprint() {
+        return this._wasm.fingerprint;
+    }
+    /**
+     * Check if this is a neutered (public) key
+     * @returns True if the key is public-only (neutered)
+     */
+    isNeutered() {
+        return this._wasm.is_neutered();
+    }
+    /**
+     * Get the neutered (public) version of this key
+     * @returns A new BIP32 instance containing only the public key
+     */
+    neutered() {
+        const wasm = this._wasm.neutered();
+        return new BIP32(wasm);
+    }
+    /**
+     * Serialize to base58 string
+     * @returns The base58-encoded extended key string
+     */
+    toBase58() {
+        return this._wasm.to_base58();
+    }
+    /**
+     * Get the WIF encoding of the private key
+     * @returns The WIF-encoded private key
+     */
+    toWIF() {
+        return this._wasm.to_wif();
+    }
+    /**
+     * Derive a normal (non-hardened) child key
+     * @param index - The child index
+     * @returns A new BIP32 instance for the derived key
+     */
+    derive(index) {
+        const wasm = this._wasm.derive(index);
+        return new BIP32(wasm);
+    }
+    /**
+     * Derive a hardened child key (only works for private keys)
+     * @param index - The child index
+     * @returns A new BIP32 instance for the derived key
+     */
+    deriveHardened(index) {
+        const wasm = this._wasm.derive_hardened(index);
+        return new BIP32(wasm);
+    }
+    /**
+     * Derive a key using a derivation path (e.g., "0/1/2" or "m/0/1/2")
+     * @param path - The derivation path string
+     * @returns A new BIP32 instance for the derived key
+     */
+    derivePath(path) {
+        const wasm = this._wasm.derive_path(path);
+        return new BIP32(wasm);
+    }
+    /**
+     * Get the underlying WASM instance (internal use only)
+     * @internal
+     */
+    get wasm() {
+        return this._wasm;
+    }
+}

package/dist/esm/js/ecpair.d.ts

@@ -0,0 +1,96 @@
+import { WasmECPair } from "./wasm/wasm_utxo.js";
+/**
+ * ECPairArg represents the various forms that ECPair keys can take
+ * before being converted to a WasmECPair instance
+ */
+export type ECPairArg = 
+/** Private key (32 bytes) or compressed public key (33 bytes) as Buffer/Uint8Array */
+Uint8Array
+/** ECPair instance */
+ | ECPair
+/** WasmECPair instance */
+ | WasmECPair;
+/**
+ * ECPair interface for elliptic curve key pair operations
+ */
+export interface ECPairInterface {
+    publicKey: Uint8Array;
+    privateKey?: Uint8Array;
+    toWIF(): string;
+}
+/**
+ * ECPair wrapper class for elliptic curve key pair operations
+ */
+export declare class ECPair implements ECPairInterface {
+    private _wasm;
+    private constructor();
+    /**
+     * Create an ECPair instance from a WasmECPair instance (internal use)
+     * @internal
+     */
+    static fromWasm(wasm: WasmECPair): ECPair;
+    /**
+     * Convert ECPairArg to ECPair instance
+     * @param key - The ECPair key in various formats
+     * @returns ECPair instance
+     */
+    static from(key: ECPairArg): ECPair;
+    /**
+     * Create an ECPair from a private key (always uses compressed keys)
+     * @param buffer - The 32-byte private key
+     * @returns An ECPair instance
+     */
+    static fromPrivateKey(buffer: Uint8Array): ECPair;
+    /**
+     * Create an ECPair from a compressed public key
+     * @param buffer - The compressed public key bytes (33 bytes)
+     * @returns An ECPair instance
+     */
+    static fromPublicKey(buffer: Uint8Array): ECPair;
+    /**
+     * Create an ECPair from a WIF string (auto-detects network from WIF)
+     * @param wifString - The WIF-encoded private key string
+     * @returns An ECPair instance
+     */
+    static fromWIF(wifString: string): ECPair;
+    /**
+     * Create an ECPair from a mainnet WIF string
+     * @param wifString - The WIF-encoded private key string
+     * @returns An ECPair instance
+     */
+    static fromWIFMainnet(wifString: string): ECPair;
+    /**
+     * Create an ECPair from a testnet WIF string
+     * @param wifString - The WIF-encoded private key string
+     * @returns An ECPair instance
+     */
+    static fromWIFTestnet(wifString: string): ECPair;
+    /**
+     * Get the private key as a Uint8Array (if available)
+     */
+    get privateKey(): Uint8Array | undefined;
+    /**
+     * Get the public key as a Uint8Array
+     */
+    get publicKey(): Uint8Array;
+    /**
+     * Convert to WIF string (mainnet)
+     * @returns The WIF-encoded private key
+     */
+    toWIF(): string;
+    /**
+     * Convert to mainnet WIF string
+     * @returns The WIF-encoded private key
+     */
+    toWIFMainnet(): string;
+    /**
+     * Convert to testnet WIF string
+     * @returns The WIF-encoded private key
+     */
+    toWIFTestnet(): string;
+    /**
+     * Get the underlying WASM instance (internal use only)
+     * @internal
+     */
+    get wasm(): WasmECPair;
+}

package/dist/esm/js/ecpair.js

@@ -0,0 +1,130 @@
+import { WasmECPair } from "./wasm/wasm_utxo.js";
+/**
+ * ECPair wrapper class for elliptic curve key pair operations
+ */
+export class ECPair {
+    _wasm;
+    constructor(_wasm) {
+        this._wasm = _wasm;
+    }
+    /**
+     * Create an ECPair instance from a WasmECPair instance (internal use)
+     * @internal
+     */
+    static fromWasm(wasm) {
+        return new ECPair(wasm);
+    }
+    /**
+     * Convert ECPairArg to ECPair instance
+     * @param key - The ECPair key in various formats
+     * @returns ECPair instance
+     */
+    static from(key) {
+        // Short-circuit if already an ECPair instance
+        if (key instanceof ECPair) {
+            return key;
+        }
+        // If it's a WasmECPair instance, wrap it
+        if (key instanceof WasmECPair) {
+            return new ECPair(key);
+        }
+        // Parse from Buffer/Uint8Array
+        // Check length to determine if it's a private key (32 bytes) or public key (33 bytes)
+        if (key.length === 32) {
+            const wasm = WasmECPair.from_private_key(key);
+            return new ECPair(wasm);
+        }
+        else if (key.length === 33) {
+            const wasm = WasmECPair.from_public_key(key);
+            return new ECPair(wasm);
+        }
+        else {
+            throw new Error(`Invalid key length: ${key.length}. Expected 32 bytes (private key) or 33 bytes (compressed public key)`);
+        }
+    }
+    /**
+     * Create an ECPair from a private key (always uses compressed keys)
+     * @param buffer - The 32-byte private key
+     * @returns An ECPair instance
+     */
+    static fromPrivateKey(buffer) {
+        const wasm = WasmECPair.from_private_key(buffer);
+        return new ECPair(wasm);
+    }
+    /**
+     * Create an ECPair from a compressed public key
+     * @param buffer - The compressed public key bytes (33 bytes)
+     * @returns An ECPair instance
+     */
+    static fromPublicKey(buffer) {
+        const wasm = WasmECPair.from_public_key(buffer);
+        return new ECPair(wasm);
+    }
+    /**
+     * Create an ECPair from a WIF string (auto-detects network from WIF)
+     * @param wifString - The WIF-encoded private key string
+     * @returns An ECPair instance
+     */
+    static fromWIF(wifString) {
+        const wasm = WasmECPair.from_wif(wifString);
+        return new ECPair(wasm);
+    }
+    /**
+     * Create an ECPair from a mainnet WIF string
+     * @param wifString - The WIF-encoded private key string
+     * @returns An ECPair instance
+     */
+    static fromWIFMainnet(wifString) {
+        const wasm = WasmECPair.from_wif_mainnet(wifString);
+        return new ECPair(wasm);
+    }
+    /**
+     * Create an ECPair from a testnet WIF string
+     * @param wifString - The WIF-encoded private key string
+     * @returns An ECPair instance
+     */
+    static fromWIFTestnet(wifString) {
+        const wasm = WasmECPair.from_wif_testnet(wifString);
+        return new ECPair(wasm);
+    }
+    /**
+     * Get the private key as a Uint8Array (if available)
+     */
+    get privateKey() {
+        return this._wasm.private_key;
+    }
+    /**
+     * Get the public key as a Uint8Array
+     */
+    get publicKey() {
+        return this._wasm.public_key;
+    }
+    /**
+     * Convert to WIF string (mainnet)
+     * @returns The WIF-encoded private key
+     */
+    toWIF() {
+        return this._wasm.to_wif();
+    }
+    /**
+     * Convert to mainnet WIF string
+     * @returns The WIF-encoded private key
+     */
+    toWIFMainnet() {
+        return this._wasm.to_wif_mainnet();
+    }
+    /**
+     * Convert to testnet WIF string
+     * @returns The WIF-encoded private key
+     */
+    toWIFTestnet() {
+        return this._wasm.to_wif_testnet();
+    }
+    /**
+     * Get the underlying WASM instance (internal use only)
+     * @internal
+     */
+    get wasm() {
+        return this._wasm;
+    }
+}

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

@@ -0,0 +1,242 @@
+import { type WalletKeysArg } from "./RootWalletKeys.js";
+import { type ReplayProtectionArg } from "./ReplayProtection.js";
+import { type BIP32Arg } from "../bip32.js";
+import { type ECPairArg } from "../ecpair.js";
+import type { UtxolibName } from "../utxolibCompat.js";
+import type { CoinName } from "../coinName.js";
+export type NetworkName = UtxolibName | CoinName;
+export type ScriptId = {
+    chain: number;
+    index: number;
+};
+export type InputScriptType = "p2shP2pk" | "p2sh" | "p2shP2wsh" | "p2wsh" | "p2trLegacy" | "p2trMusig2ScriptPath" | "p2trMusig2KeyPath";
+export type ParsedInput = {
+    address: string;
+    script: Uint8Array;
+    value: bigint;
+    scriptId: ScriptId | null;
+    scriptType: InputScriptType;
+};
+export type ParsedOutput = {
+    address: string | null;
+    script: Uint8Array;
+    value: bigint;
+    scriptId: ScriptId | null;
+};
+export type ParsedTransaction = {
+    inputs: ParsedInput[];
+    outputs: ParsedOutput[];
+    spendAmount: bigint;
+    minerFee: bigint;
+    virtualSize: number;
+};
+export declare class BitGoPsbt {
+    private wasm;
+    private constructor();
+    /**
+     * Deserialize a PSBT from bytes
+     * @param bytes - The PSBT bytes
+     * @param network - The network to use for deserialization (either utxolib name like "bitcoin" or coin name like "btc")
+     * @returns A BitGoPsbt instance
+     */
+    static fromBytes(bytes: Uint8Array, network: NetworkName): BitGoPsbt;
+    /**
+     * Get the unsigned transaction ID
+     * @returns The unsigned transaction ID
+     */
+    unsignedTxid(): string;
+    /**
+     * Parse transaction with wallet keys to identify wallet inputs/outputs
+     * @param walletKeys - The wallet keys to use for identification
+     * @param replayProtection - Scripts that are allowed as inputs without wallet validation
+     * @returns Parsed transaction information
+     */
+    parseTransactionWithWalletKeys(walletKeys: WalletKeysArg, replayProtection: ReplayProtectionArg): ParsedTransaction;
+    /**
+     * Parse outputs with wallet keys to identify which outputs belong to a wallet
+     * with the given wallet keys.
+     *
+     * This is useful in cases where we want to identify outputs that belong to a different
+     * wallet than the inputs.
+     *
+     * @param walletKeys - The wallet keys to use for identification
+     * @returns Array of parsed outputs
+     * @note This method does NOT validate wallet inputs. It only parses outputs.
+     */
+    parseOutputsWithWalletKeys(walletKeys: WalletKeysArg): ParsedOutput[];
+    /**
+     * Verify if a valid signature exists for a given key at the specified input index.
+     *
+     * This method can verify signatures using either:
+     * - Extended public key (xpub): Derives the public key using the derivation path from PSBT
+     * - ECPair (private key): Extracts the public key and verifies directly
+     *
+     * When using xpub, it supports:
+     * - ECDSA signatures (for legacy/SegWit inputs)
+     * - Schnorr signatures (for Taproot script path inputs)
+     * - MuSig2 partial signatures (for Taproot keypath MuSig2 inputs)
+     *
+     * When using ECPair, it supports:
+     * - ECDSA signatures (for legacy/SegWit inputs)
+     * - Schnorr signatures (for Taproot script path inputs)
+     * Note: MuSig2 inputs require xpubs for derivation
+     *
+     * @param inputIndex - The index of the input to check (0-based)
+     * @param key - Either an extended public key (base58 string, BIP32 instance, or WasmBIP32) or an ECPair (private key Buffer, ECPair instance, or WasmECPair)
+     * @returns true if a valid signature exists, false if no signature exists
+     * @throws Error if input index is out of bounds, key is invalid, or verification fails
+     *
+     * @example
+     * ```typescript
+     * // Verify wallet input signature with xpub
+     * const hasUserSig = psbt.verifySignature(0, userXpub);
+     *
+     * // Verify signature with ECPair (private key)
+     * const ecpair = ECPair.fromPrivateKey(privateKeyBuffer);
+     * const hasReplaySig = psbt.verifySignature(1, ecpair);
+     *
+     * // Or pass private key directly
+     * const hasReplaySig2 = psbt.verifySignature(1, privateKeyBuffer);
+     * ```
+     */
+    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
+     *
+     * Verify if a replay protection input has a valid signature.
+     *
+     * This method checks if a given input is a replay protection input (like P2shP2pk) and verifies
+     * the signature. Replay protection inputs don't use standard derivation paths, so this method
+     * verifies signatures without deriving from xpub.
+     *
+     * For P2PK replay protection inputs, this:
+     * - Extracts the signature from final_script_sig
+     * - Extracts the public key from redeem_script
+     * - Computes the legacy P2SH sighash
+     * - Verifies the ECDSA signature cryptographically
+     *
+     * @param inputIndex - The index of the input to check (0-based)
+     * @param replayProtection - Scripts that identify replay protection inputs (same format as parseTransactionWithWalletKeys)
+     * @returns true if the input is a replay protection input and has a valid signature, false if no valid signature
+     * @throws Error if the input is not a replay protection input, index is out of bounds, or scripts are invalid
+     */
+    verifyReplayProtectionSignature(inputIndex: number, replayProtection: ReplayProtectionArg): boolean;
+    /**
+     * Serialize the PSBT to bytes
+     *
+     * @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
+     *
+     * @throws Error if any input failed to finalize
+     */
+    finalizeAllInputs(): void;
+    /**
+     * Extract the final transaction from a finalized PSBT
+     *
+     * @returns The serialized transaction bytes
+     * @throws Error if the PSBT is not fully finalized or extraction fails
+     */
+    extractTransaction(): Uint8Array;
+}