feat(wasm-utxo): rename Network to UtxolibNetwork for better semantics

Rename Network class to UtxolibNetwork to better represent its purpose
as a compatibility layer with utxo-lib. This helps avoid confusion with
other network objects while maintaining functionality.

Issue: BTC-2652

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

Author: OttoAllmendinger

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

@@ -17,18 +17,23 @@ pub struct CashAddr {
     pub script_hash: u32,
 }
 
-pub struct Network {
+/// This maps to the structure of `utxolib.Network` so that we can use it for address encoding/decoding.
+/// We also use it to infer the output script support for the network.
+///
+/// We cannot precisely map it to the proper `networks::Network` enum because certain
+/// different networks are structurally identical (all bitcoin testnets).
+pub struct UtxolibNetwork {
     pub pub_key_hash: u32,
     pub script_hash: u32,
     pub cash_addr: Option<CashAddr>,
     pub bech32: Option<String>,
 }
 
-impl Network {
-    /// Parse a Network object from a JavaScript value
+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;
-        Network::try_from_js_value(js_network)
+        UtxolibNetwork::try_from_js_value(js_network)
             .map_err(|e| AddressError::InvalidAddress(e.to_string()))
     }
     pub fn output_script_support(&self) -> OutputScriptSupport {
@@ -46,10 +51,10 @@ impl Network {
     }
 }
 
-/// Convert output script to address string using a utxolib Network object
+/// Convert output script to address string using a utxolib UtxolibNetwork object
 pub fn from_output_script_with_network(
     script: &Script,
-    network: &Network,
+    network: &UtxolibNetwork,
     format: AddressFormat,
 ) -> Result<String> {
     network.output_script_support().assert_support(script)?;
@@ -94,8 +99,8 @@ pub fn from_output_script_with_network(
     }
 }
 
-/// Convert address string to output script using a utxolib Network object
-pub fn to_output_script_with_network(address: &str, network: &Network) -> Result<ScriptBuf> {
+/// Convert address string to output script using a utxolib UtxolibNetwork object
+pub fn to_output_script_with_network(address: &str, network: &UtxolibNetwork) -> Result<ScriptBuf> {
     use crate::address::AddressCodec;
     use crate::bitcoin::hashes::Hash;
     use crate::bitcoin::{PubkeyHash, ScriptHash};
@@ -148,16 +153,16 @@ impl UtxolibCompatNamespace {
     ///
     /// # Arguments
     /// * `script` - The output script as a byte array
-    /// * `network` - The utxolib Network object from JavaScript
+    /// * `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 =
-            Network::from_js_value(&network).map_err(|e| JsValue::from_str(&e.to_string()))?;
+        let network = UtxolibNetwork::from_js_value(&network)
+            .map_err(|e| JsValue::from_str(&e.to_string()))?;
 
         let script_obj = Script::from_bytes(script);
 
@@ -173,16 +178,16 @@ impl UtxolibCompatNamespace {
     ///
     /// # Arguments
     /// * `address` - The address string
-    /// * `network` - The utxolib Network object from JavaScript
+    /// * `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 =
-            Network::from_js_value(&network).map_err(|e| JsValue::from_str(&e.to_string()))?;
+        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 {

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

@@ -12,10 +12,10 @@ pub use wallet_keys::*;
 pub use wallet_scripts::*;
 use wasm_bindgen::prelude::*;
 
-use crate::address::networks::{AddressFormat};
+use crate::address::networks::AddressFormat;
 use crate::error::WasmMiniscriptError;
 use crate::try_from_js_value::TryFromJsValue;
-use crate::utxolib_compat::Network;
+use crate::utxolib_compat::UtxolibNetwork;
 
 #[wasm_bindgen]
 pub struct FixedScriptWalletNamespace;
@@ -29,12 +29,17 @@ impl FixedScriptWalletNamespace {
         index: u32,
         network: JsValue,
     ) -> Result<Vec<u8>, WasmMiniscriptError> {
-        let network = Network::try_from_js_value(&network)?;
+        let network = UtxolibNetwork::try_from_js_value(&network)?;
         let chain = Chain::try_from(chain)
             .map_err(|e| WasmMiniscriptError::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())?;
+        let scripts = WalletScripts::from_wallet_keys(
+            &wallet_keys,
+            chain,
+            index,
+            &network.output_script_support(),
+        )?;
         Ok(scripts.output_script().to_bytes())
     }
 
@@ -46,11 +51,16 @@ impl FixedScriptWalletNamespace {
         network: JsValue,
         address_format: Option<String>,
     ) -> Result<String, WasmMiniscriptError> {
-        let network = Network::try_from_js_value(&network)?;
+        let network = UtxolibNetwork::try_from_js_value(&network)?;
         let wallet_keys = RootWalletKeys::from_jsvalue(&keys)?;
         let chain = Chain::try_from(chain)
             .map_err(|e| WasmMiniscriptError::new(&format!("Invalid chain: {}", e)))?;
-        let scripts = WalletScripts::from_wallet_keys(&wallet_keys, chain, index, &network.output_script_support())?;
+        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| WasmMiniscriptError::new(&format!("Invalid address format: {}", e)))?;

packages/wasm-utxo/src/try_from_js_value.rs

@@ -1,4 +1,4 @@
-use crate::address::utxolib_compat::{CashAddr, Network};
+use crate::address::utxolib_compat::{CashAddr, UtxolibNetwork};
 use crate::error::WasmMiniscriptError;
 use wasm_bindgen::JsValue;
 
@@ -119,14 +119,14 @@ pub(crate) fn get_buffer_field_vec(
     Ok(bytes)
 }
 
-impl TryFromJsValue for Network {
+impl TryFromJsValue for UtxolibNetwork {
     fn try_from_js_value(value: &JsValue) -> Result<Self, WasmMiniscriptError> {
         let pub_key_hash = get_field(value, "pubKeyHash")?;
         let script_hash = get_field(value, "scriptHash")?;
         let bech32 = get_field(value, "bech32")?;
         let cash_addr = get_field(value, "cashAddr")?;
 
-        Ok(Network {
+        Ok(UtxolibNetwork {
             pub_key_hash,
             script_hash,
             cash_addr,