feat(wasm-utxo): add optional addressFormat parameter to address function

Add support for specifying the address format when generating addresses
in the fixedScriptWallet module. This allows controlling the output
format (e.g., cashaddr for BCH/ECASH) when needed.

Added JSDoc documentation explaining the addressFormat parameter usage
and the available format options for Bitcoin Cash and eCash networks.

Issue: BTC-2652

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

Author: OttoAllmendinger

packages/wasm-utxo/js/address.ts

@@ -1,6 +1,10 @@
 import { AddressNamespace } from "./wasm/wasm_utxo";
 import type { CoinName } from "./coinName";
 
+/**
+ * Most coins only have one unambiguous address format (base58check and bech32/bech32m)
+ * For Bitcoin Cash and eCash, we can select between base58check and cashaddr.
+ */
 export type AddressFormat = "default" | "cashaddr";
 
 export function toOutputScriptWithCoin(address: string, coin: CoinName): Uint8Array {

packages/wasm-utxo/js/fixedScriptWallet.ts

@@ -1,6 +1,7 @@
 import { FixedScriptWalletNamespace } from "./wasm/wasm_utxo";
 import type { UtxolibNetwork, UtxolibRootWalletKeys } from "./utxolibCompat";
 import { Triple } from "./triple";
+import { AddressFormat } from "./address";
 
 export type WalletKeys =
   /** Just an xpub triple, will assume default derivation prefixes  */
@@ -18,12 +19,21 @@ export function outputScript(keys: WalletKeys, chain: number, index: number): Ui
 /**
  * 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.
+ * @param keys - The wallet keys to use.
+ * @param chain - The chain to use.
+ * @param index - The index to use.
+ * @param network - The network to use.
+ * @param addressFormat - The address format to use.
+ *   Only relevant for Bitcoin Cash and eCash networks, where:
+ *   - "default" means base58check,
+ *   - "cashaddr" means cashaddr.
  */
 export function address(
   keys: WalletKeys,
   chain: number,
   index: number,
   network: UtxolibNetwork,
+  addressFormat?: AddressFormat,
 ): string {
-  return FixedScriptWalletNamespace.address(keys, chain, index, network);
+  return FixedScriptWalletNamespace.address(keys, chain, index, network, addressFormat);
 }

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

@@ -42,17 +42,20 @@ impl FixedScriptWalletNamespace {
         chain: u32,
         index: u32,
         network: JsValue,
+        address_format: Option<String>,
     ) -> Result<String, WasmMiniscriptError> {
         let network = Network::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);
         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)))?;
         let address = crate::address::utxolib_compat::from_output_script_with_network(
             &script,
             &network,
-            AddressFormat::Default,
+            address_format,
         )
         .map_err(|e| WasmMiniscriptError::new(&format!("Failed to generate address: {}", e)))?;
         Ok(address.to_string())

packages/wasm-utxo/test/fixedScript/address.ts

@@ -2,7 +2,7 @@ import assert from "node:assert";
 
 import * as utxolib from "@bitgo/utxo-lib";
 
-import { fixedScriptWallet } from "../../js";
+import { AddressFormat, fixedScriptWallet } from "../../js";
 
 type Triple<T> = [T, T, T];
 
@@ -11,6 +11,7 @@ function getAddressUtxoLib(
   chain: number,
   index: number,
   network: utxolib.Network,
+  addressFormat: AddressFormat,
 ): string {
   if (!utxolib.bitgo.isChainCode(chain)) {
     throw new Error(`Invalid chain code: ${chain}`);
@@ -21,11 +22,21 @@ function getAddressUtxoLib(
     derived.publicKeys,
     utxolib.bitgo.outputScripts.scriptTypeForChain(chain),
   );
-  const address = utxolib.address.fromOutputScript(script.scriptPubKey, network);
+  const address = utxolib.addressFormat.fromOutputScriptWithFormat(
+    script.scriptPubKey,
+    addressFormat,
+    network,
+  );
   return address;
 }
 
-function runTest(network: utxolib.Network, derivationPrefixes?: Triple<string>) {
+function runTest(
+  network: utxolib.Network,
+  {
+    derivationPrefixes,
+    addressFormat,
+  }: { derivationPrefixes?: Triple<string>; addressFormat?: AddressFormat } = {},
+) {
   describe(`address for network ${utxolib.getNetworkName(network)}, derivationPrefixes=${Boolean(derivationPrefixes)}`, function () {
     const keyTriple = utxolib.testutil.getKeyTriple("wasm");
 
@@ -41,8 +52,20 @@ function runTest(network: utxolib.Network, derivationPrefixes?: Triple<string>)
             keyTriple.map((k) => k.neutered()) as Triple<utxolib.BIP32Interface>,
             derivationPrefixes,
           );
-          const utxolibAddress = getAddressUtxoLib(rootWalletKeys, chainCode, index, network);
-          const wasmAddress = fixedScriptWallet.address(rootWalletKeys, chainCode, index, network);
+          const utxolibAddress = getAddressUtxoLib(
+            rootWalletKeys,
+            chainCode,
+            index,
+            network,
+            addressFormat ?? "default",
+          );
+          const wasmAddress = fixedScriptWallet.address(
+            rootWalletKeys,
+            chainCode,
+            index,
+            network,
+            addressFormat,
+          );
           assert.strictEqual(utxolibAddress, wasmAddress);
         }
       }
@@ -52,5 +75,11 @@ function runTest(network: utxolib.Network, derivationPrefixes?: Triple<string>)
 
 utxolib.getNetworkList().forEach((network) => {
   runTest(network);
-  runTest(network, ["m/1/2", "m/0/0", "m/0/0"]);
+  runTest(network, { derivationPrefixes: ["m/1/2", "m/0/0", "m/0/0"] });
+  if (
+    utxolib.getMainnet(network) === utxolib.networks.bitcoincash ||
+    utxolib.getMainnet(network) === utxolib.networks.ecash
+  ) {
+    runTest(network, { addressFormat: "cashaddr" });
+  }
 });