feat(wasm-utxo): implement namespace wrapper pattern for better TypeScript APIs

This PR introduces a cleaner, more type-safe architecture for WASM bindings:

1. Organizes related Rust functions into namespace classes
2. Wraps generated WASM bindings with precise TypeScript types
3. Creates dedicated wrapper modules for each feature area
4. Adds comprehensive documentation for the pattern

The pattern replaces loose types (`any`, `string | null`) with precise
TypeScript types, improving IDE autocompletion and compile-time safety.

Issue: BTC-2652

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

Author: OttoAllmendinger

packages/wasm-utxo/js/README.md

@@ -0,0 +1,89 @@
+# Purpose
+
+The primary purpose of this directory is to expose better TypeScript signatures than those
+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
+
+This directory implements a **namespace wrapper pattern** that provides a cleaner, more
+type-safe API over the raw WASM bindings.
+
+### Pattern Overview
+
+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 loose types (`any`, `string | null`) due to WASM-bindgen limitations
+
+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
+   - Re-export related types for convenience
+
+3. **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`)
+   - Uses `export * as` to group related functionality into namespaces
+   - Re-exports shared types for top-level access
+   - Augments WASM types with additional TypeScript declarations
+
+### Example
+
+Given a WASM-generated class:
+
+```typescript
+// wasm/wasm_utxo.d.ts (generated)
+export class AddressNamespace {
+  static to_output_script_with_coin(address: string, coin: string): Uint8Array;
+  static from_output_script_with_coin(
+    script: Uint8Array,
+    coin: string,
+    format?: string | null,
+  ): string;
+}
+```
+
+We create a wrapper module:
+
+```typescript
+// address.ts
+import { AddressNamespace } from "./wasm/wasm_utxo";
+import type { CoinName } from "./coinName";
+
+export type AddressFormat = "default" | "cashaddr";
+
+export function toOutputScriptWithCoin(address: string, coin: CoinName): Uint8Array {
+  return AddressNamespace.to_output_script_with_coin(address, coin);
+}
+
+export function fromOutputScriptWithCoin(
+  script: Uint8Array,
+  coin: CoinName,
+  format?: AddressFormat,
+): string {
+  return AddressNamespace.from_output_script_with_coin(script, coin, format);
+}
+```
+
+And expose it via the main entry point:
+
+```typescript
+// index.ts
+export * as address from "./address";
+```
+
+### Benefits
+
+- **Type Safety**: Replace loose `any` and `string` types with precise union types
+- **Better DX**: IDE autocomplete works better with concrete types
+- **Maintainability**: Centralized type definitions prevent duplication

packages/wasm-utxo/js/address.ts

@@ -0,0 +1,16 @@
+import { AddressNamespace } from "./wasm/wasm_utxo";
+import type { CoinName } from "./coinName";
+
+export type AddressFormat = "default" | "cashaddr";
+
+export function toOutputScriptWithCoin(address: string, coin: CoinName): Uint8Array {
+  return AddressNamespace.to_output_script_with_coin(address, coin);
+}
+
+export function fromOutputScriptWithCoin(
+  script: Uint8Array,
+  coin: CoinName,
+  format?: AddressFormat,
+): string {
+  return AddressNamespace.from_output_script_with_coin(script, coin, format);
+}

packages/wasm-utxo/js/coinName.ts

@@ -0,0 +1,23 @@
+// BitGo coin names (from Network::from_coin_name in src/networks.rs)
+export type CoinName =
+  | "btc"
+  | "tbtc"
+  | "tbtc4"
+  | "tbtcsig"
+  | "tbtcbgsig"
+  | "bch"
+  | "tbch"
+  | "bcha"
+  | "tbcha"
+  | "btg"
+  | "tbtg"
+  | "bsv"
+  | "tbsv"
+  | "dash"
+  | "tdash"
+  | "doge"
+  | "tdoge"
+  | "ltc"
+  | "tltc"
+  | "zec"
+  | "tzec";

packages/wasm-utxo/js/fixedScriptWallet.ts

@@ -0,0 +1,29 @@
+import { FixedScriptWalletNamespace } from "./wasm/wasm_utxo";
+import type { UtxolibNetwork, UtxolibRootWalletKeys } from "./utxolibCompat";
+import { Triple } from "./triple";
+
+export type WalletKeys =
+  /** Just an xpub triple, will assume default derivation prefixes  */
+  | Triple<string>
+  /** Compatible with utxolib RootWalletKeys */
+  | UtxolibRootWalletKeys;
+
+/**
+ * Create the output script for a given wallet keys and chain and index
+ */
+export function outputScript(keys: WalletKeys, chain: number, index: number): Uint8Array {
+  return FixedScriptWalletNamespace.output_script(keys, chain, index);
+}
+
+/**
+ * Create the address for a given wallet keys and chain and index and network.
+ * Wrapper for outputScript that also encodes the script to an address.
+ */
+export function address(
+  keys: WalletKeys,
+  chain: number,
+  index: number,
+  network: UtxolibNetwork,
+): string {
+  return FixedScriptWalletNamespace.address(keys, chain, index, network);
+}

packages/wasm-utxo/js/index.ts

@@ -4,40 +4,23 @@ import * as wasm from "./wasm/wasm_utxo";
 // and forgets to include it in the bundle
 void wasm;
 
+export * as address from "./address";
+export * as ast from "./ast";
+export * as utxolibCompat from "./utxolibCompat";
+export * as fixedScriptWallet from "./fixedScriptWallet";
+
+export type { CoinName } from "./coinName";
+export type { Triple } from "./triple";
+export type { AddressFormat } from "./address";
+
 export type DescriptorPkType = "derivable" | "definite" | "string";
 
 export type ScriptContext = "tap" | "segwitv0" | "legacy";
 
-export type AddressFormat = "default" | "cashaddr";
-
 export type SignPsbtResult = {
   [inputIndex: number]: [pubkey: string][];
 };
 
-// BitGo coin names (from Network::from_coin_name in src/networks.rs)
-export type CoinName =
-  | "btc"
-  | "tbtc"
-  | "tbtc4"
-  | "tbtcsig"
-  | "tbtcbgsig"
-  | "bch"
-  | "tbch"
-  | "bcha"
-  | "tbcha"
-  | "btg"
-  | "tbtg"
-  | "bsv"
-  | "tbsv"
-  | "dash"
-  | "tdash"
-  | "doge"
-  | "tdoge"
-  | "ltc"
-  | "tltc"
-  | "zec"
-  | "tzec";
-
 declare module "./wasm/wasm_utxo" {
   interface WrapDescriptor {
     /** These are not the same types of nodes as in the ast module */
@@ -63,46 +46,8 @@ declare module "./wasm/wasm_utxo" {
     signWithXprv(this: WrapPsbt, xprv: string): SignPsbtResult;
     signWithPrv(this: WrapPsbt, prv: Uint8Array): SignPsbtResult;
   }
-
-  interface Address {
-    /**
-     * Convert output script to address string
-     * @param script - The output script as a byte array
-     * @param network - The utxolib Network object from JavaScript
-     * @param format - Optional address format: "default" or "cashaddr" (only applicable for Bitcoin Cash and eCash)
-     */
-    fromOutputScript(script: Uint8Array, network: any, format?: AddressFormat): string;
-    /**
-     * Convert address string to output script
-     * @param address - The address string
-     * @param network - The utxolib Network object from JavaScript
-     * @param format - Optional address format (currently unused for decoding as all formats are accepted)
-     */
-    toOutputScript(address: string, network: any, format?: AddressFormat): Uint8Array;
-  }
 }
 
-import { Address as WasmAddress } from "./wasm/wasm_utxo";
-
 export { WrapDescriptor as Descriptor } from "./wasm/wasm_utxo";
 export { WrapMiniscript as Miniscript } from "./wasm/wasm_utxo";
 export { WrapPsbt as Psbt } from "./wasm/wasm_utxo";
-export { FixedScriptWallet } from "./wasm/wasm_utxo";
-
-export namespace utxolibCompat {
-  export const Address = WasmAddress;
-}
-
-export function toOutputScriptWithCoin(address: string, coin: CoinName): Uint8Array {
-  return wasm.toOutputScriptWithCoin(address, coin);
-}
-
-export function fromOutputScriptWithCoin(
-  script: Uint8Array,
-  coin: CoinName,
-  format?: AddressFormat,
-): string {
-  return wasm.fromOutputScriptWithCoin(script, coin, format);
-}
-
-export * as ast from "./ast";

packages/wasm-utxo/js/triple.ts

@@ -0,0 +1 @@
+export type Triple<T> = [T, T, T];

packages/wasm-utxo/js/utxolibCompat.ts

@@ -0,0 +1,50 @@
+import type { AddressFormat } from "./address";
+import { Triple } from "./triple";
+import { UtxolibCompatNamespace } from "./wasm/wasm_utxo";
+
+export type BIP32Interface = {
+  network: {
+    bip32: {
+      public: number;
+    };
+  };
+  depth: number;
+  parentFingerprint: number;
+  index: number;
+  chainCode: Uint8Array;
+  publicKey: Uint8Array;
+
+  toBase58?(): string;
+};
+
+export type UtxolibRootWalletKeys = {
+  triple: Triple<BIP32Interface>;
+  derivationPrefixes: Triple<string>;
+};
+
+export type UtxolibNetwork = {
+  pubKeyHash: number;
+  scriptHash: number;
+  cashAddr?: {
+    prefix: string;
+    pubKeyHash: number;
+    scriptHash: number;
+  };
+  bech32?: string;
+};
+
+export function fromOutputScript(
+  script: Uint8Array,
+  network: UtxolibNetwork,
+  format?: AddressFormat,
+): string {
+  return UtxolibCompatNamespace.from_output_script(script, network, format);
+}
+
+export function toOutputScript(
+  address: string,
+  network: UtxolibNetwork,
+  format?: AddressFormat,
+): Uint8Array {
+  return UtxolibCompatNamespace.to_output_script(address, network, format);
+}

packages/wasm-utxo/src/address/networks.rs

@@ -211,36 +211,35 @@ pub fn from_output_script_with_coin_and_format(
 // WASM bindings
 use wasm_bindgen::prelude::*;
 
-/// WASM binding: Convert an address string to an output script using a BitGo coin name.
-#[wasm_bindgen(js_name = toOutputScriptWithCoin)]
-pub fn to_output_script_with_coin_js(
-    address: &str,
-    coin: &str,
-) -> std::result::Result<Vec<u8>, JsValue> {
-    to_output_script_with_coin(address, coin)
-        .map(|script| script.to_bytes())
-        .map_err(|e| JsValue::from_str(&e.to_string()))
-}
+#[wasm_bindgen]
+pub struct AddressNamespace;
+
+#[wasm_bindgen]
+impl AddressNamespace {
+    #[wasm_bindgen]
+    pub fn to_output_script_with_coin(
+        address: &str,
+        coin: &str,
+    ) -> std::result::Result<Vec<u8>, JsValue> {
+        to_output_script_with_coin(address, coin)
+            .map(|script| script.to_bytes())
+            .map_err(|e| JsValue::from_str(&e.to_string()))
+    }
 
-/// WASM binding: Convert an output script to an address string using a BitGo coin name.
-///
-/// # Arguments
-/// * `script` - The output script bytes
-/// * `coin` - The BitGo coin name (e.g., "btc", "bch", "ecash")
-/// * `format` - Optional address format: "default" or "cashaddr" (only applicable for Bitcoin Cash and eCash)
-#[wasm_bindgen(js_name = fromOutputScriptWithCoin)]
-pub fn from_output_script_with_coin_js(
-    script: &[u8],
-    coin: &str,
-    format: Option<String>,
-) -> std::result::Result<String, JsValue> {
-    let script_obj = Script::from_bytes(script);
-    let format_str = format.as_deref();
-    let address_format = AddressFormat::from_optional_str(format_str)
-        .map_err(|e| JsValue::from_str(&e.to_string()))?;
-
-    from_output_script_with_coin_and_format(script_obj, coin, address_format)
-        .map_err(|e| JsValue::from_str(&e.to_string()))
+    #[wasm_bindgen]
+    pub fn from_output_script_with_coin(
+        script: &[u8],
+        coin: &str,
+        format: Option<String>,
+    ) -> std::result::Result<String, JsValue> {
+        let script_obj = Script::from_bytes(script);
+        let format_str = format.as_deref();
+        let address_format = AddressFormat::from_optional_str(format_str)
+            .map_err(|e| JsValue::from_str(&e.to_string()))?;
+
+        from_output_script_with_coin_and_format(script_obj, coin, address_format)
+            .map_err(|e| JsValue::from_str(&e.to_string()))
+    }
 }
 
 #[cfg(test)]