feat(wasm-utxo): add comprehensive address

Add new module with support for multiple address formats:
- Base58Check for traditional P2PKH/P2SH addresses
- Bech32/Bech32m for SegWit addresses (P2WPKH/P2WSH/P2TR)
- CashAddr for Bitcoin Cash and eCash
- Support for various cryptocurrencies (BTC, LTC, BCH, BSV, BTG, etc.)

The implementation passes all test vectors and provides a unified
interface for encoding/decoding addresses across different networks.

Issue: BTC-2650

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

Author: OttoAllmendinger

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

@@ -0,0 +1,129 @@
+//! Base58Check encoding/decoding for traditional Bitcoin addresses (P2PKH, P2SH).
+
+use super::{AddressCodec, AddressError, Result};
+use crate::bitcoin::hashes::Hash;
+use crate::bitcoin::{base58, PubkeyHash, Script, ScriptBuf, ScriptHash};
+
+/// Base58Check codec with network-specific version bytes
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct Base58CheckCodec {
+    /// Base58Check P2PKH version byte(s)
+    pub pub_key_hash: u32,
+    /// Base58Check P2SH version byte(s)
+    pub script_hash: u32,
+}
+
+impl Base58CheckCodec {
+    /// Create a new Base58Check codec with specified version bytes
+    pub const fn new(pub_key_hash: u32, script_hash: u32) -> Self {
+        Self {
+            pub_key_hash,
+            script_hash,
+        }
+    }
+}
+
+/// Encode a hash with version bytes to Base58Check format using bitcoin crate
+fn to_base58_check(hash: &[u8], version: u32) -> Result<String> {
+    let mut data = Vec::new();
+
+    // Encode version bytes (1-4 bytes depending on size)
+    if version <= 0xff {
+        data.push(version as u8);
+    } else if version <= 0xffff {
+        data.extend_from_slice(&(version as u16).to_be_bytes());
+    } else {
+        // For Zcash (up to 4 bytes)
+        let bytes = version.to_be_bytes();
+        let start = bytes.iter().position(|&b| b != 0).unwrap_or(0);
+        data.extend_from_slice(&bytes[start..]);
+    }
+
+    data.extend_from_slice(hash);
+
+    // Use bitcoin crate's base58 encode_check which adds the checksum
+    Ok(base58::encode_check(&data))
+}
+
+/// Decode a Base58Check address to (hash, version) using bitcoin crate
+fn from_base58_check(address: &str) -> Result<(Vec<u8>, u32)> {
+    // Use bitcoin crate's base58 decode_check which verifies the checksum
+    let payload =
+        base58::decode_check(address).map_err(|e| AddressError::Base58Error(e.to_string()))?;
+
+    if payload.is_empty() {
+        return Err(AddressError::Base58Error("Empty payload".to_string()));
+    }
+
+    // Extract version and hash
+    // Try different version byte lengths
+    let (version, hash) = if payload.len() >= 21 && (payload[0] == 0x1c || payload[0] == 0x1d) {
+        // Zcash uses 2-byte versions starting with 0x1c or 0x1d
+        if payload.len() >= 22 {
+            let version = u32::from_be_bytes([0, 0, payload[0], payload[1]]);
+            let hash = payload[2..].to_vec();
+            (version, hash)
+        } else {
+            // Single byte version
+            let version = payload[0] as u32;
+            let hash = payload[1..].to_vec();
+            (version, hash)
+        }
+    } else {
+        // Standard single-byte version
+        let version = payload[0] as u32;
+        let hash = payload[1..].to_vec();
+        (version, hash)
+    };
+
+    Ok((hash, version))
+}
+
+impl AddressCodec for Base58CheckCodec {
+    fn encode(&self, script: &Script) -> Result<String> {
+        if script.is_p2pkh() {
+            if script.len() != 25 {
+                return Err(AddressError::InvalidScript(
+                    "Invalid P2PKH script length".to_string(),
+                ));
+            }
+            let hash = &script.as_bytes()[3..23];
+            to_base58_check(hash, self.pub_key_hash)
+        } else if script.is_p2sh() {
+            if script.len() != 23 {
+                return Err(AddressError::InvalidScript(
+                    "Invalid P2SH script length".to_string(),
+                ));
+            }
+            let hash = &script.as_bytes()[2..22];
+            to_base58_check(hash, self.script_hash)
+        } else {
+            Err(AddressError::UnsupportedScriptType(
+                "Base58Check only supports P2PKH and P2SH".to_string(),
+            ))
+        }
+    }
+
+    fn decode(&self, address: &str) -> Result<ScriptBuf> {
+        let (hash, version) = from_base58_check(address)?;
+
+        if version == self.pub_key_hash {
+            let hash_array: [u8; 20] = hash.try_into().map_err(|_| {
+                AddressError::InvalidAddress("Invalid pubkey hash length".to_string())
+            })?;
+            let pubkey_hash = PubkeyHash::from_byte_array(hash_array);
+            Ok(ScriptBuf::new_p2pkh(&pubkey_hash))
+        } else if version == self.script_hash {
+            let hash_array: [u8; 20] = hash.try_into().map_err(|_| {
+                AddressError::InvalidAddress("Invalid script hash length".to_string())
+            })?;
+            let script_hash = ScriptHash::from_byte_array(hash_array);
+            Ok(ScriptBuf::new_p2sh(&script_hash))
+        } else {
+            Err(AddressError::InvalidAddress(format!(
+                "Version mismatch: expected {} or {}, got {}",
+                self.pub_key_hash, self.script_hash, version
+            )))
+        }
+    }
+}

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

@@ -0,0 +1,131 @@
+//! Bech32 and Bech32m encoding/decoding for Bitcoin witness addresses.
+//!
+//! Implements BIP 173 (Bech32) and BIP 350 (Bech32m) encoding schemes using the bitcoin crate.
+//! - Bech32 is used for witness version 0 (P2WPKH, P2WSH)
+//! - Bech32m is used for witness version 1+ (P2TR)
+
+use super::{AddressCodec, AddressError, Result};
+use crate::bitcoin::{Script, ScriptBuf, WitnessVersion};
+
+/// Bech32/Bech32m codec for witness addresses
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct Bech32Codec {
+    /// Bech32 Human Readable Part (HRP)
+    pub hrp: &'static str,
+}
+
+impl Bech32Codec {
+    /// Create a new Bech32 codec with the specified HRP
+    pub const fn new(hrp: &'static str) -> Self {
+        Self { hrp }
+    }
+}
+
+/// Encode witness program with custom HRP
+fn encode_witness_with_custom_hrp(
+    program: &[u8],
+    version: WitnessVersion,
+    hrp_str: &str,
+) -> Result<String> {
+    // Try using the bech32 functionality from bitcoin crate
+    // The bitcoin crate includes bech32 encoding via its dependencies
+    use bech32::{self, Hrp};
+
+    // Parse the HRP
+    let hrp = Hrp::parse(hrp_str)
+        .map_err(|e| AddressError::Bech32Error(format!("Invalid HRP '{}': {}", hrp_str, e)))?;
+
+    // Encode based on witness version
+    let address = if version == WitnessVersion::V0 {
+        // Use Bech32 for witness version 0
+        bech32::segwit::encode_v0(hrp, program)
+            .map_err(|e| AddressError::Bech32Error(format!("Bech32 encoding failed: {}", e)))?
+    } else {
+        // Use Bech32m for witness version 1+
+        bech32::segwit::encode_v1(hrp, program)
+            .map_err(|e| AddressError::Bech32Error(format!("Bech32m encoding failed: {}", e)))?
+    };
+
+    Ok(address)
+}
+
+/// Decode witness program with custom HRP
+fn decode_witness_with_custom_hrp(address: &str, expected_hrp: &str) -> Result<Vec<u8>> {
+    use bech32::{self, Hrp};
+
+    // Parse the expected HRP
+    let expected_hrp_parsed = Hrp::parse(expected_hrp)
+        .map_err(|e| AddressError::Bech32Error(format!("Invalid HRP '{}': {}", expected_hrp, e)))?;
+
+    // Decode the address
+    let (decoded_hrp, witness_version, witness_program) = bech32::segwit::decode(address)
+        .map_err(|e| AddressError::Bech32Error(format!("Failed to decode address: {}", e)))?;
+
+    // Verify HRP matches
+    if decoded_hrp != expected_hrp_parsed {
+        return Err(AddressError::Bech32Error(format!(
+            "HRP mismatch: expected '{}', got '{}'",
+            expected_hrp, decoded_hrp
+        )));
+    }
+
+    // Convert witness version (Fe32) to OP code
+    // Fe32 can be 0-31, but for segwit, we only care about 0-16
+    // OP_0 = 0x00, OP_1 = 0x51, OP_2 = 0x52, ... OP_16 = 0x60
+    let version_byte: u8 = witness_version.to_u8();
+    let version_opcode = if version_byte == 0 {
+        0x00 // OP_0
+    } else if version_byte <= 16 {
+        0x50 + version_byte // OP_1 through OP_16
+    } else {
+        return Err(AddressError::Bech32Error(format!(
+            "Invalid witness version: {}",
+            version_byte
+        )));
+    };
+
+    // Construct the script pubkey: <version> <length> <program>
+    let mut script = vec![version_opcode, witness_program.len() as u8];
+    script.extend_from_slice(&witness_program);
+    Ok(script)
+}
+
+impl AddressCodec for Bech32Codec {
+    fn encode(&self, script: &Script) -> Result<String> {
+        let (witness_version, program) = if script.is_p2wpkh() {
+            if script.len() != 22 {
+                return Err(AddressError::InvalidScript(
+                    "Invalid P2WPKH script length".to_string(),
+                ));
+            }
+            (WitnessVersion::V0, &script.as_bytes()[2..22])
+        } else if script.is_p2wsh() {
+            if script.len() != 34 {
+                return Err(AddressError::InvalidScript(
+                    "Invalid P2WSH script length".to_string(),
+                ));
+            }
+            (WitnessVersion::V0, &script.as_bytes()[2..34])
+        } else if script.is_p2tr() {
+            if script.len() != 34 {
+                return Err(AddressError::InvalidScript(
+                    "Invalid P2TR script length".to_string(),
+                ));
+            }
+            (WitnessVersion::V1, &script.as_bytes()[2..34])
+        } else {
+            return Err(AddressError::UnsupportedScriptType(
+                "Bech32 only supports witness programs (P2WPKH, P2WSH, P2TR)".to_string(),
+            ));
+        };
+
+        // Use custom HRP encoding for all networks
+        encode_witness_with_custom_hrp(program, witness_version, self.hrp)
+    }
+
+    fn decode(&self, address: &str) -> Result<ScriptBuf> {
+        // Use custom HRP decoding for all networks
+        let script_bytes = decode_witness_with_custom_hrp(address, self.hrp)?;
+        Ok(ScriptBuf::from(script_bytes))
+    }
+}