feat(wasm-utxo): isolate WASM bindings into separate module

Move all WASM-specific code into a dedicated module to improve
organization and separation of concerns. The core functionality remains
unchanged, but the binding layer is now cleanly separated from the
implementation.

This refactoring:
- Creates a new `wasm` module to contain all bindings
- Moves JS/WASM interface code out of core implementation files
- Maintains backward compatibility with existing JS API

Issue: BTC-2652

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

Author: OttoAllmendinger

packages/wasm-utxo/README.md

@@ -5,6 +5,11 @@ This project is the successor of the Javascript `utxo-lib` package.
 It provides WASM bindings for the `rust-bitcoin` and `rust-miniscript` crates
 that help verify and co-sign transactions built by the BitGo Wallet Platform API.
 
+## Documentation
+
+- **[`src/wasm-bindgen.md`](src/wasm-bindgen.md)** - Guide for creating WASM bindings using the namespace pattern
+- **[`js/README.md`](js/README.md)** - TypeScript wrapper layer architecture and best practices
+
 ## Status
 
 This project is under active development.

packages/wasm-utxo/package.json

@@ -26,7 +26,9 @@
     "./dist/node/js/index.js": "./dist/browser/js/index.js"
   },
   "scripts": {
-    "test": "mocha --recursive test",
+    "test": "npm run test:mocha && npm run test:wasm-pack",
+    "test:mocha": "mocha --recursive test",
+    "test:wasm-pack": "npm run test:wasm-pack-node && npm run test:wasm-pack-chrome",
     "test:wasm-pack-node": "wasm-pack test --node",
     "test:wasm-pack-chrome": "wasm-pack test --headless --chrome",
     "build:wasm": "make js/wasm/ && make dist/node/js/wasm/ && make dist/browser/js/wasm/",

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

@@ -14,6 +14,7 @@ use super::{
 };
 use crate::bitcoin::Script;
 use crate::networks::Network;
+use miniscript::bitcoin::WitnessVersion;
 
 /// Get codecs for decoding addresses for a given network.
 /// Returns multiple codecs to try in order (Base58Check, Bech32, CashAddr, etc.)
@@ -302,41 +303,6 @@ pub fn from_output_script_with_coin_and_format(
     from_output_script_with_network_and_format(script, network, format)
 }
 
-use miniscript::bitcoin::WitnessVersion;
-// WASM bindings
-use wasm_bindgen::prelude::*;
-
-#[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_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)]
 mod tests {
     use super::*;

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

@@ -1,8 +1,6 @@
 /// Helper structs for compatibility with npm @bitgo/utxo-lib
 /// Long-term we should not use the `Network` objects from @bitgo/utxo-lib any longer,
 /// but for now we need to keep this compatibility layer.
-use wasm_bindgen::JsValue;
-
 use crate::address::networks::{AddressFormat, OutputScriptSupport};
 use crate::address::{bech32, cashaddr, Base58CheckCodec};
 use crate::bitcoin::{Script, ScriptBuf};
@@ -30,12 +28,6 @@ pub struct UtxolibNetwork {
 }
 
 impl UtxolibNetwork {
-    /// Parse a UtxolibNetwork object from a JavaScript value
-    pub fn from_js_value(js_network: &JsValue) -> Result<Self> {
-        use crate::try_from_js_value::TryFromJsValue;
-        UtxolibNetwork::try_from_js_value(js_network)
-            .map_err(|e| AddressError::InvalidAddress(e.to_string()))
-    }
     pub fn output_script_support(&self) -> OutputScriptSupport {
         let segwit = self.bech32.is_some();
 
@@ -140,64 +132,3 @@ pub fn to_output_script_with_network(address: &str, network: &UtxolibNetwork) ->
         address
     )))
 }
-
-// WASM bindings for utxolib-compatible address functions
-use wasm_bindgen::prelude::*;
-
-#[wasm_bindgen]
-pub struct UtxolibCompatNamespace;
-
-#[wasm_bindgen]
-impl UtxolibCompatNamespace {
-    /// Convert output script to address string
-    ///
-    /// # Arguments
-    /// * `script` - The output script as a byte array
-    /// * `network` - The UtxolibNetwork object from JavaScript
-    /// * `format` - Optional address format: "default" or "cashaddr" (only applicable for Bitcoin Cash and eCash)
-    #[wasm_bindgen]
-    pub fn from_output_script(
-        script: &[u8],
-        network: JsValue,
-        format: Option<String>,
-    ) -> std::result::Result<String, JsValue> {
-        let network = UtxolibNetwork::from_js_value(&network)
-            .map_err(|e| JsValue::from_str(&e.to_string()))?;
-
-        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_network(script_obj, &network, address_format)
-            .map_err(|e| JsValue::from_str(&e.to_string()))
-    }
-
-    /// Convert address string to output script
-    ///
-    /// # Arguments
-    /// * `address` - The address string
-    /// * `network` - The UtxolibNetwork object from JavaScript
-    /// * `format` - Optional address format (currently unused for decoding as all formats are accepted)
-    #[wasm_bindgen]
-    pub fn to_output_script(
-        address: &str,
-        network: JsValue,
-        format: Option<String>,
-    ) -> std::result::Result<Vec<u8>, JsValue> {
-        let network = UtxolibNetwork::from_js_value(&network)
-            .map_err(|e| JsValue::from_str(&e.to_string()))?;
-
-        // Validate format parameter even though we don't use it for decoding
-        if let Some(fmt) = format {
-            let format_str = Some(fmt.as_str());
-            AddressFormat::from_optional_str(format_str)
-                .map_err(|e| JsValue::from_str(&e.to_string()))?;
-        }
-
-        to_output_script_with_network(address, &network)
-            .map(|script| script.to_bytes())
-            .map_err(|e| JsValue::from_str(&e.to_string()))
-    }
-}

packages/wasm-utxo/src/fixed_script_wallet/mod.rs

@@ -1,6 +1,5 @@
 /// This module contains code for the BitGo Fixed Script Wallets.
 /// These are not based on descriptors.
-mod bip32interface;
 mod wallet_keys;
 
 pub mod wallet_scripts;
@@ -10,66 +9,3 @@ pub mod test_utils;
 
 pub use wallet_keys::*;
 pub use wallet_scripts::*;
-use wasm_bindgen::prelude::*;
-
-use crate::address::networks::AddressFormat;
-use crate::error::WasmUtxoError;
-use crate::try_from_js_value::TryFromJsValue;
-use crate::utxolib_compat::UtxolibNetwork;
-
-#[wasm_bindgen]
-pub struct FixedScriptWalletNamespace;
-
-#[wasm_bindgen]
-impl FixedScriptWalletNamespace {
-    #[wasm_bindgen]
-    pub fn output_script(
-        keys: JsValue,
-        chain: u32,
-        index: u32,
-        network: JsValue,
-    ) -> Result<Vec<u8>, WasmUtxoError> {
-        let network = UtxolibNetwork::try_from_js_value(&network)?;
-        let chain = Chain::try_from(chain)
-            .map_err(|e| WasmUtxoError::new(&format!("Invalid chain: {}", e)))?;
-
-        let wallet_keys = RootWalletKeys::from_jsvalue(&keys)?;
-        let scripts = WalletScripts::from_wallet_keys(
-            &wallet_keys,
-            chain,
-            index,
-            &network.output_script_support(),
-        )?;
-        Ok(scripts.output_script().to_bytes())
-    }
-
-    #[wasm_bindgen]
-    pub fn address(
-        keys: JsValue,
-        chain: u32,
-        index: u32,
-        network: JsValue,
-        address_format: Option<String>,
-    ) -> Result<String, WasmUtxoError> {
-        let network = UtxolibNetwork::try_from_js_value(&network)?;
-        let wallet_keys = RootWalletKeys::from_jsvalue(&keys)?;
-        let chain = Chain::try_from(chain)
-            .map_err(|e| WasmUtxoError::new(&format!("Invalid chain: {}", e)))?;
-        let scripts = WalletScripts::from_wallet_keys(
-            &wallet_keys,
-            chain,
-            index,
-            &network.output_script_support(),
-        )?;
-        let script = scripts.output_script();
-        let address_format = AddressFormat::from_optional_str(address_format.as_deref())
-            .map_err(|e| WasmUtxoError::new(&format!("Invalid address format: {}", e)))?;
-        let address = crate::address::utxolib_compat::from_output_script_with_network(
-            &script,
-            &network,
-            address_format,
-        )
-        .map_err(|e| WasmUtxoError::new(&format!("Failed to generate address: {}", e)))?;
-        Ok(address.to_string())
-    }
-}