feat(wasm-utxo): add RootWalletKeys class wrapper for wallet keys

Added a new TypeScript class wrapper for wallet keys that provides a more
type-safe and consistent API over the raw WASM bindings.

- Created RootWalletKeys class with proper static factory methods
- Updated fixedScriptWallet to work with the new RootWalletKeys class
- Extended BitGoPsbt.verifySignature to support both BIP32 and ECPair
- Improved README.md with detailed architecture patterns documentation
- Updated tests to use the new API

This implements a clean class wrapper pattern similar to BIP32 and ECPair,
maintaining a consistent API style across the library.

Issue: BTC-2786

Co-authored-by: llm-git <[email protected]>

Author: OttoAllmendinger

packages/wasm-utxo/js/README.md

@@ -6,42 +6,61 @@ generated by the `wasm-pack` command (which uses `wasm-bindgen`).
 While the `wasm-bindgen` crate allows some customization of the emitted type signatures, it
 is a bit painful to use and has certain limitations that cannot be easily worked around.
 
-## Architecture Pattern
+## Architecture Patterns
 
-This directory implements a **namespace wrapper pattern** that provides a cleaner, more
-type-safe API over the raw WASM bindings.
+This directory implements two complementary patterns to provide cleaner, more type-safe APIs over the raw WASM bindings:
 
-### Pattern Overview
+1. **Namespace Wrapper Pattern** - For static utility functions
+2. **Class Wrapper Pattern** - For stateful objects with methods
+
+### Common Elements
 
 1. **WASM Generation** (`wasm/wasm_utxo.d.ts`)
 
    - Generated by `wasm-bindgen` from Rust code
-   - Exports classes with static methods (e.g., `AddressNamespace`, `UtxolibCompatNamespace`)
-   - Uses `snake_case` naming (Rust convention)
+   - Uses `snake_case` naming (Rust convention) - **no `js_name` overrides in Rust**
    - Uses loose types (`any`, `string | null`) due to WASM-bindgen limitations
+   - TypeScript wrapper layer handles conversion to `camelCase`
 
-2. **Namespace Wrapper Files** (e.g., `address.ts`, `utxolibCompat.ts`, `fixedScriptWallet.ts`)
-
-   - Import the generated WASM namespace classes
-   - Define precise TypeScript types to replace `any` types
-   - Export individual functions that wrap the static WASM methods
-   - Convert `snake_case` WASM methods to `camelCase` (JavaScript convention)
-   - Re-export related types for convenience
-
-3. **Shared Type Files** (e.g., `coinName.ts`, `triple.ts`)
+2. **Shared Type Files** (e.g., `coinName.ts`, `triple.ts`)
 
    - Define common types used across multiple modules
    - Single source of truth to avoid duplication
    - Imported by wrapper files as needed
 
-4. **Main Entry Point** (`index.ts`)
+3. **Main Entry Point** (`index.ts`)
    - Uses `export * as` to group related functionality into namespaces
-   - Re-exports shared types for top-level access
+   - Re-exports shared types and classes for top-level access
    - Augments WASM types with additional TypeScript declarations
 
-### Example
+### Pattern 1: Namespace Wrapper Pattern
+
+Used for static utility functions (e.g., `address.ts`, `utxolibCompat.ts`).
+
+**Characteristics:**
+
+- Import the generated WASM namespace classes
+- Define precise TypeScript types to replace `any` types
+- Export individual functions that wrap the static WASM methods
+- Convert `snake_case` WASM methods to `camelCase` (JavaScript convention)
+- Re-export related types for convenience
+
+### Pattern 2: Class Wrapper Pattern
+
+Used for stateful objects that maintain WASM instances (e.g., `BIP32`, `RootWalletKeys`, `BitGoPsbt`).
+
+**Characteristics:**
 
-Given a WASM-generated class:
+- Private `_wasm` property holds the underlying WASM instance
+- Private constructor prevents direct instantiation
+- Static factory methods (camelCase) for object creation
+- Instance methods (camelCase) wrap WASM methods and return wrapped instances when appropriate
+- Public `wasm` getter for internal access to WASM instance (marked `@internal`)
+- Implements interfaces to ensure compatibility with existing code
+
+### Example 1: Namespace Wrapper Pattern
+
+Given a WASM-generated namespace class:
 
 ```typescript
 // wasm/wasm_utxo.d.ts (generated by wasm-bindgen)
@@ -88,10 +107,110 @@ And expose it via the main entry point:
 export * as address from "./address";
 ```
 
+### Example 2: Class Wrapper Pattern
+
+Given a WASM-generated class with instance methods:
+
+```typescript
+// wasm/wasm_utxo.d.ts (generated by wasm-bindgen)
+export class WasmBIP32 {
+  private constructor();
+  // Note: snake_case naming from Rust (no js_name overrides)
+  static from_base58(base58_str: string): WasmBIP32;
+  derive(index: number): WasmBIP32;
+  derive_path(path: string): WasmBIP32;
+  to_base58(): string;
+  readonly public_key: Uint8Array;
+}
+```
+
+We create a wrapper class that encapsulates the WASM instance:
+
+```typescript
+// bip32.ts
+import { WasmBIP32 } from "./wasm/wasm_utxo";
+
+export class BIP32 {
+  // Private property with underscore prefix
+  private constructor(private _wasm: WasmBIP32) {}
+
+  // Static factory method (camelCase) calls snake_case WASM method
+  static fromBase58(base58Str: string): BIP32 {
+    const wasm = WasmBIP32.from_base58(base58Str);
+    return new BIP32(wasm);
+  }
+
+  // Property getter (camelCase) accesses snake_case WASM property
+  get publicKey(): Uint8Array {
+    return this._wasm.public_key;
+  }
+
+  // Instance method (camelCase) returns wrapped instance
+  derive(index: number): BIP32 {
+    const wasm = this._wasm.derive(index);
+    return new BIP32(wasm);
+  }
+
+  // Convert snake_case to camelCase
+  derivePath(path: string): BIP32 {
+    const wasm = this._wasm.derive_path(path);
+    return new BIP32(wasm);
+  }
+
+  // Convert snake_case to camelCase
+  toBase58(): string {
+    return this._wasm.to_base58();
+  }
+
+  // Public getter for internal use (marked @internal)
+  /**
+   * @internal
+   */
+  get wasm(): WasmBIP32 {
+    return this._wasm;
+  }
+}
+```
+
+And expose it directly:
+
+```typescript
+// index.ts
+export { BIP32 } from "./bip32";
+```
+
 ### Benefits
 
+**Common to Both Patterns:**
+
 - **Type Safety**: Replace loose `any` and `string` types with precise union types
-- **Idiomatic Naming**: Each layer uses its native convention (`snake_case` in Rust, `camelCase` in JavaScript)
+- **Idiomatic Naming**: Each layer uses its native convention (`snake_case` in Rust/WASM, `camelCase` in TypeScript/JavaScript)
+  - Rust exports use `snake_case` (no `js_name` overrides)
+  - TypeScript wrappers provide `camelCase` API
 - **Better DX**: IDE autocomplete works better with concrete types and familiar naming
 - **Maintainability**: Centralized type definitions prevent duplication
 - **Clear Separation**: WASM bindings stay pure to Rust conventions, TypeScript handles JS conventions
+
+**Class Wrapper Pattern Specific:**
+
+- **Encapsulation**: Private `_wasm` property hides implementation details
+- **Controlled Access**: Private constructor forces use of factory methods
+- **Consistent Returns**: Methods that return new instances automatically wrap them
+- **Internal Access**: Public `wasm` getter allows internal code to access WASM instance when needed
+- **Type Compatibility**: Can implement interfaces to maintain backward compatibility
+
+### When to Use Which Pattern
+
+**Use Namespace Wrapper Pattern when:**
+
+- Functions are stateless utilities
+- No need to maintain WASM instance state
+- Simple input → output transformations
+- Examples: address encoding/decoding, network conversions
+
+**Use Class Wrapper Pattern when:**
+
+- Object represents stateful data (keys, PSBTs, etc.)
+- Methods need to return new instances of the same type
+- Need to encapsulate underlying WASM instance
+- Examples: BIP32 keys, RootWalletKeys, BitGoPsbt

packages/wasm-utxo/js/WalletKeys.ts

@@ -0,0 +1,156 @@
+import type { BIP32Interface } from "./bip32.js";
+import { BIP32 } from "./bip32.js";
+import { Triple } from "./triple.js";
+import { WasmRootWalletKeys, WasmBIP32 } from "./wasm/wasm_utxo.js";
+
+/**
+ * IWalletKeys represents the various forms that wallet keys can take
+ * before being converted to a RootWalletKeys instance
+ */
+export type IWalletKeys = {
+  triple: Triple<BIP32Interface>;
+  derivationPrefixes: Triple<string>;
+};
+
+export type WalletKeysArg =
+  /** Just an xpub triple, will assume default derivation prefixes  */
+  | Triple<string>
+  /** Compatible with utxolib RootWalletKeys */
+  | IWalletKeys
+  /** RootWalletKeys instance */
+  | RootWalletKeys;
+
+/**
+ * Convert WalletKeysArg to a triple of WasmBIP32 instances
+ */
+function toBIP32Triple(keys: WalletKeysArg): Triple<WasmBIP32> {
+  if (keys instanceof RootWalletKeys) {
+    return [keys.userKey().wasm, keys.backupKey().wasm, keys.bitgoKey().wasm];
+  }
+
+  // Check if it's an IWalletKeys object
+  if (typeof keys === "object" && "triple" in keys) {
+    // Extract BIP32 keys from the triple
+    return keys.triple.map((key) => BIP32.from(key).wasm) as Triple<WasmBIP32>;
+  }
+
+  // Otherwise it's a triple of strings (xpubs)
+  return keys.map((xpub) => WasmBIP32.from_xpub(xpub)) as Triple<WasmBIP32>;
+}
+
+/**
+ * Extract derivation prefixes from WalletKeysArg, if present
+ */
+function extractDerivationPrefixes(keys: WalletKeysArg): Triple<string> | null {
+  if (typeof keys === "object" && "derivationPrefixes" in keys) {
+    return keys.derivationPrefixes;
+  }
+  return null;
+}
+
+/**
+ * RootWalletKeys represents a set of three extended public keys with their derivation prefixes
+ */
+export class RootWalletKeys {
+  private constructor(private _wasm: WasmRootWalletKeys) {}
+
+  /**
+   * Create a RootWalletKeys from various input formats
+   * @param keys - Can be a triple of xpub strings, an IWalletKeys object, or another RootWalletKeys instance
+   * @returns A RootWalletKeys instance
+   */
+  static from(keys: WalletKeysArg): RootWalletKeys {
+    if (keys instanceof RootWalletKeys) {
+      return keys;
+    }
+
+    const [user, backup, bitgo] = toBIP32Triple(keys);
+    const derivationPrefixes = extractDerivationPrefixes(keys);
+
+    const wasm = derivationPrefixes
+      ? WasmRootWalletKeys.with_derivation_prefixes(
+          user,
+          backup,
+          bitgo,
+          derivationPrefixes[0],
+          derivationPrefixes[1],
+          derivationPrefixes[2],
+        )
+      : new WasmRootWalletKeys(user, backup, bitgo);
+
+    return new RootWalletKeys(wasm);
+  }
+
+  /**
+   * Create a RootWalletKeys from three xpub strings
+   * Uses default derivation prefix of m/0/0 for all three keys
+   * @param xpubs - Triple of xpub strings
+   * @returns A RootWalletKeys instance
+   */
+  static fromXpubs(xpubs: Triple<string>): RootWalletKeys {
+    const [user, backup, bitgo] = xpubs.map((xpub) =>
+      WasmBIP32.from_xpub(xpub),
+    ) as Triple<WasmBIP32>;
+    const wasm = new WasmRootWalletKeys(user, backup, bitgo);
+    return new RootWalletKeys(wasm);
+  }
+
+  /**
+   * Create a RootWalletKeys from three xpub strings with custom derivation prefixes
+   * @param xpubs - Triple of xpub strings
+   * @param derivationPrefixes - Triple of derivation path strings (e.g., ["0/0", "0/0", "0/0"])
+   * @returns A RootWalletKeys instance
+   */
+  static withDerivationPrefixes(
+    xpubs: Triple<string>,
+    derivationPrefixes: Triple<string>,
+  ): RootWalletKeys {
+    const [user, backup, bitgo] = xpubs.map((xpub) =>
+      WasmBIP32.from_xpub(xpub),
+    ) as Triple<WasmBIP32>;
+    const wasm = WasmRootWalletKeys.with_derivation_prefixes(
+      user,
+      backup,
+      bitgo,
+      derivationPrefixes[0],
+      derivationPrefixes[1],
+      derivationPrefixes[2],
+    );
+    return new RootWalletKeys(wasm);
+  }
+
+  /**
+   * Get the user key (first xpub)
+   * @returns The user key as a BIP32 instance
+   */
+  userKey(): BIP32 {
+    const wasm = this._wasm.user_key();
+    return BIP32.fromWasm(wasm);
+  }
+
+  /**
+   * Get the backup key (second xpub)
+   * @returns The backup key as a BIP32 instance
+   */
+  backupKey(): BIP32 {
+    const wasm = this._wasm.backup_key();
+    return BIP32.fromWasm(wasm);
+  }
+
+  /**
+   * Get the BitGo key (third xpub)
+   * @returns The BitGo key as a BIP32 instance
+   */
+  bitgoKey(): BIP32 {
+    const wasm = this._wasm.bitgo_key();
+    return BIP32.fromWasm(wasm);
+  }
+
+  /**
+   * Get the underlying WASM instance (internal use only)
+   * @internal
+   */
+  get wasm(): WasmRootWalletKeys {
+    return this._wasm;
+  }
+}