// This software is licensed under the GNU Affero General Public License (AGPL), version 3.0 or later. // A copy of the license can be found in the LICENSE file or at https://www.gnu.org/licenses/agpl-3.0.html // // Copyright (C) 2019 Harry Barber // Copyright (C) 2022 Bitcoin Unlimited // Copyright (C) 2024-2026 Whiterun LLC pub mod errors; pub mod utiladdr; use anyhow::Result; use bitcoincash::Network; pub use errors::{DecodingError, EncodingError}; // Prefixes const MAINNET_PREFIX: &str = "bitcoincash"; const TESTNET_PREFIX: &str = "bchtest"; const REGNET_PREFIX: &str = "bchreg"; // The cashaddr character set for encoding const CHARSET: &[u8; 32] = b"qpzry9x8gf2tvdw0s3jn54khce6mua7l"; // The cashaddr character set for decoding #[rustfmt::skip] const CHARSET_REV: [Option; 128] = [ None, None, None, None, None, None, None, None, None, None, None, None, None, None, None, None, None, None, None, None, None, None, None, None, None, None, None, None, None, None, None, None, None, None, None, None, None, None, None, None, None, None, None, None, None, None, None, None, Some(15), None, Some(10), Some(17), Some(21), Some(20), Some(26), Some(30), Some(7), Some(5), None, None, None, None, None, None, None, Some(29), None, Some(24), Some(13), Some(25), Some(9), Some(8), Some(23), None, Some(18), Some(22), Some(31), Some(27), Some(19), None, Some(1), Some(0), Some(3), Some(16), Some(11), Some(28), Some(12), Some(14), Some(6), Some(4), Some(2), None, None, None, None, None, None, Some(29), None, Some(24), Some(13), Some(25), Some(9), Some(8), Some(23), None, Some(18), Some(22), Some(31), Some(27), Some(19), None, Some(1), Some(0), Some(3), Some(16), Some(11), Some(28), Some(12), Some(14), Some(6), Some(4), Some(2), None, None, None, None, None, ]; // Version byte flags #[allow(dead_code)] pub mod version_byte_flags { pub const TYPE_MASK: u8 = 0b1111000; pub const SIZE_MASK: u8 = 0b0000111; pub const TYPE_P2PKH: u8 = 0b00000; pub const TYPE_P2SH: u8 = 0b01000; pub const TYPE_P2PKH_TOKEN: u8 = 0b10000; pub const TYPE_P2SH_TOKEN: u8 = 0b11000; pub const SIZE_160: u8 = 0x00; pub const SIZE_192: u8 = 0x01; pub const SIZE_224: u8 = 0x02; pub const SIZE_256: u8 = 0x03; pub const SIZE_320: u8 = 0x04; pub const SIZE_384: u8 = 0x05; pub const SIZE_448: u8 = 0x06; pub const SIZE_512: u8 = 0x07; } // https://github.com/Bitcoin-ABC/bitcoin-abc/blob/2804a49bfc0764ba02ce2999809c52b3b9bb501e/src/cashaddr.cpp#L42 fn polymod(v: &[u8]) -> u64 { let mut c: u64 = 1; for d in v.iter() { let c0: u8 = (c >> 35) as u8; c = ((c & 0x0007_ffff_ffff) << 5) ^ u64::from(*d); if c0 & 0x01 != 0 { c ^= 0x0098_f2bc_8e61; } if c0 & 0x02 != 0 { c ^= 0x0079_b76d_99e2; } if c0 & 0x04 != 0 { c ^= 0x00f3_3e5f_b3c4; } if c0 & 0x08 != 0 { c ^= 0x00ae_2eab_e2a8; } if c0 & 0x10 != 0 { c ^= 0x001e_4f43_e470; } } c ^ 1 } // Expand the address prefix for the checksum operation. fn expand_prefix(prefix: &str) -> Vec { let mut ret: Vec = prefix.chars().map(|c| (c as u8) & 0x1f).collect(); ret.push(0); ret } fn convert_bits(data: &[u8], inbits: u8, outbits: u8, pad: bool) -> Vec { assert!(inbits <= 8 && outbits <= 8); let num_bytes = (data.len() * inbits as usize).div_ceil(outbits as usize); let mut ret = Vec::with_capacity(num_bytes); let mut acc: u16 = 0; // accumulator of bits let mut num: u8 = 0; // num bits in acc let groupmask = (1 << outbits) - 1; for d in data.iter() { // We push each input chunk into a 16-bit accumulator acc = (acc << inbits) | u16::from(*d); num += inbits; // Then we extract all the output groups we can while num > outbits { ret.push((acc >> (num - outbits)) as u8); acc &= !(groupmask << (num - outbits)); num -= outbits; } } if pad { // If there's some bits left, pad and add it if num > 0 { ret.push((acc << (outbits - num)) as u8); } } else { // If there's some bits left, figure out if we need to remove padding and add it let padding = (data.len() * inbits as usize) % outbits as usize; if num as usize > padding { ret.push((acc >> padding) as u8); } } ret } pub fn encode( raw: &[u8], hash_flag: u8, // see version_byte_flags network: Network, ) -> Result { // Calculate version byte let length = raw.len(); let version_byte = match length { 20 => version_byte_flags::SIZE_160, 24 => version_byte_flags::SIZE_192, 28 => version_byte_flags::SIZE_224, 32 => version_byte_flags::SIZE_256, 40 => version_byte_flags::SIZE_320, 48 => version_byte_flags::SIZE_384, 56 => version_byte_flags::SIZE_448, 64 => version_byte_flags::SIZE_512, _ => return Err(EncodingError(length)), } | hash_flag; // Get prefix let prefix = match network { Network::Bitcoin => MAINNET_PREFIX, Network::Testnet => TESTNET_PREFIX, Network::Testnet4 => TESTNET_PREFIX, Network::Scalenet => TESTNET_PREFIX, Network::Regtest => REGNET_PREFIX, Network::Chipnet => TESTNET_PREFIX, }; // Convert payload to 5 bit array let mut payload = Vec::with_capacity(1 + raw.len()); payload.push(version_byte); payload.extend(raw); let payload_5_bits = convert_bits(&payload, 8, 5, true); // Construct payload string using CHARSET let payload_str: String = payload_5_bits .iter() .map(|b| CHARSET[*b as usize] as char) .collect(); // Create checksum let expanded_prefix = expand_prefix(prefix); let checksum_input = [&expanded_prefix[..], &payload_5_bits, &[0; 8][..]].concat(); let checksum = polymod(&checksum_input); // Convert checksum to string let checksum_str: String = (0..8) .rev() .map(|i| CHARSET[((checksum >> (i * 5)) & 31) as usize] as char) .collect(); // Concatentate all parts let cashaddr = [prefix, ":", &payload_str, &checksum_str].concat(); Ok(cashaddr) } #[allow(dead_code)] pub fn decode(addr_str: &str) -> Result<(Vec, u8, Network), DecodingError> { // Delimit and extract prefix let parts: Vec<&str> = addr_str.split(':').collect(); let (prefix, payload_str) = match parts.len() { 1 => (MAINNET_PREFIX, parts[0]), 2 => (parts[0], parts[1]), _ => { return Err(DecodingError::Other(format!( "Invalid address: '{addr_str}'" ))) } }; // Match network let network = match prefix { MAINNET_PREFIX => Network::Bitcoin, TESTNET_PREFIX => Network::Testnet, REGNET_PREFIX => Network::Regtest, _ => return Err(DecodingError::InvalidPrefix(prefix.to_string())), }; // Do some sanity checks on the string let mut payload_chars = payload_str.chars(); if let Some(first_char) = payload_chars.next() { if first_char.is_lowercase() { if payload_chars.any(|c| c.is_uppercase()) { return Err(DecodingError::MixedCase); } } else if payload_chars.any(|c| c.is_lowercase()) { return Err(DecodingError::MixedCase); } } else { return Err(DecodingError::InvalidLength(0)); } // Decode payload to 5 bit array let payload_chars = payload_str.chars(); // Reintialize iterator here let payload_5_bits: Result, DecodingError> = payload_chars .map(|c| { let i = c as usize; if let Some(Some(d)) = CHARSET_REV.get(i) { Ok(*d) } else { Err(DecodingError::InvalidChar(c)) } }) .collect(); let payload_5_bits = payload_5_bits?; // Verify the checksum let checksum = polymod(&[&expand_prefix(prefix), &payload_5_bits[..]].concat()); if checksum != 0 { return Err(DecodingError::ChecksumFailed(checksum)); } // Convert from 5 bit array to byte array let len_5_bit = payload_5_bits.len(); let payload = convert_bits(&payload_5_bits[..(len_5_bit - 8)], 5, 8, false); // Verify the version byte let version = payload[0]; // Check length let body = &payload[1..]; let body_len = body.len(); let version_size = version & version_byte_flags::SIZE_MASK; if (version_size == version_byte_flags::SIZE_160 && body_len != 20) || (version_size == version_byte_flags::SIZE_192 && body_len != 24) || (version_size == version_byte_flags::SIZE_224 && body_len != 28) || (version_size == version_byte_flags::SIZE_256 && body_len != 32) || (version_size == version_byte_flags::SIZE_320 && body_len != 40) || (version_size == version_byte_flags::SIZE_384 && body_len != 48) || (version_size == version_byte_flags::SIZE_448 && body_len != 56) || (version_size == version_byte_flags::SIZE_512 && body_len != 64) { return Err(DecodingError::InvalidLength(body_len)); } // Extract the hash type and return let version_type = version & version_byte_flags::TYPE_MASK; Ok((body.to_vec(), version_type, network)) } #[cfg(test)] mod tests { use super::*; // token aware test vectors from: https://github.com/bitjson/cashtokens #[test] fn mainnet_20byte() { // 20-byte public key hash on mainnet verify( Network::Bitcoin, &hex::decode("F5BF48B397DAE70BE82B3CCA4793F8EB2B6CDAC9").unwrap(), "bitcoincash:qr6m7j9njldwwzlg9v7v53unlr4jkmx6eylep8ekg2", false, ); verify( Network::Bitcoin, &hex::decode("fc916f213a3d7f1369313d5fa30f6168f9446a2d").unwrap(), "bitcoincash:zr7fzmep8g7h7ymfxy74lgc0v950j3r295z4y4gq0v", true, ); verify_p2sh( Network::Bitcoin, &hex::decode("1948b5c4eacd0ca8d7f4e7f05c83d0c92425abea").unwrap(), "bitcoincash:pqv53dwyatxse2xh7nnlqhyr6ryjgfdtagkd4vc388", false, ); verify_p2sh( Network::Bitcoin, &hex::decode("1948b5c4eacd0ca8d7f4e7f05c83d0c92425abea").unwrap(), "bitcoincash:rqv53dwyatxse2xh7nnlqhyr6ryjgfdtag38xjkhc5", true, ); } #[test] fn mainnet_24byte() { // 24-byte public key hash on mainnet verify( Network::Bitcoin, &hex::decode("7ADBF6C17084BC86C1706827B41A56F5CA32865925E946EA").unwrap(), "bitcoincash:q9adhakpwzztepkpwp5z0dq62m6u5v5xtyj7j3h2ws4mr9g0", false, ); } #[test] fn mainnet_28byte() { // 28-byte public key hash on mainnet verify( Network::Bitcoin, &hex::decode("3A84F9CF51AAE98A3BB3A78BF16A6183790B18719126325BFC0C075B").unwrap(), "bitcoincash:qgagf7w02x4wnz3mkwnchut2vxphjzccwxgjvvjmlsxqwkcw59jxxuz", false, ); } #[test] fn mainnet_32byte() { // 32-byte public key hash on mainnet verify( Network::Bitcoin, &hex::decode("3173EF6623C6B48FFD1A3DCC0CC6489B0A07BB47A37F47CFEF4FE69DE825C060") .unwrap(), "bitcoincash:qvch8mmxy0rtfrlarg7ucrxxfzds5pamg73h7370aa87d80gyhqxq5nlegake", false, ); verify_p2sh( Network::Bitcoin, &hex::decode("ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff") .unwrap(), "bitcoincash:p0llllllllllllllllllllllllllllllllllllllllllllllllll7x3vthu35", false, ); verify_p2sh( Network::Bitcoin, &hex::decode("ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff") .unwrap(), "bitcoincash:r0llllllllllllllllllllllllllllllllllllllllllllllllll75zs2wagl", true, ); } #[test] fn mainnet_40byte() { // 40-byte public key hash on mainnet verify( Network::Bitcoin, &hex::decode("C07138323E00FA4FC122D3B85B9628EA810B3F381706385E289B0B25631197D194B5C238BEB136FB").unwrap(), "bitcoincash:qnq8zwpj8cq05n7pytfmskuk9r4gzzel8qtsvwz79zdskftrzxtar994cgutavfklv39gr3uvz", false, ); } #[test] fn mainnet_48byte() { // 48-byte public key hash on mainnet verify( Network::Bitcoin, &hex::decode("E361CA9A7F99107C17A622E047E3745D3E19CF804ED63C5C40C6BA763696B98241223D8CE62AD48D863F4CB18C930E4C").unwrap(), "bitcoincash:qh3krj5607v3qlqh5c3wq3lrw3wnuxw0sp8dv0zugrrt5a3kj6ucysfz8kxwv2k53krr7n933jfsunqex2w82sl", false, ); } #[test] fn mainnet_56byte() { // 56-byte public key hash on mainnet verify( Network::Bitcoin, &hex::decode("D9FA7C4C6EF56DC4FF423BAAE6D495DBFF663D034A72D1DC7D52CBFE7D1E6858F9D523AC0A7A5C34077638E4DD1A701BD017842789982041").unwrap(), "bitcoincash:qmvl5lzvdm6km38lgga64ek5jhdl7e3aqd9895wu04fvhlnare5937w4ywkq57juxsrhvw8ym5d8qx7sz7zz0zvcypqscw8jd03f", false ); } #[test] fn mainnet_64byte() { // 64-byte public key hash on mainnet verify( Network::Bitcoin, &hex::decode("D0F346310D5513D9E01E299978624BA883E6BDA8F4C60883C10F28C2967E67EC77ECC7EEEAEAFC6DA89FAD72D11AC961E164678B868AEEEC5F2C1DA08884175B").unwrap(), "bitcoincash:qlg0x333p4238k0qrc5ej7rzfw5g8e4a4r6vvzyrcy8j3s5k0en7calvclhw46hudk5flttj6ydvjc0pv3nchp52amk97tqa5zygg96mtky5sv5w", false ); } fn verify(network: Network, data: &Vec, cashaddr: &str, token_aware: bool) { let hash_type = if token_aware { version_byte_flags::TYPE_P2PKH_TOKEN } else { version_byte_flags::TYPE_P2PKH }; let output = encode(data, hash_type, network).unwrap(); assert_eq!(output, cashaddr.to_ascii_lowercase()); let decoded = decode(cashaddr).unwrap(); assert_eq!(decoded.0, *data); } fn verify_p2sh(network: Network, data: &Vec, cashaddr: &str, token_aware: bool) { let hash_type = if token_aware { version_byte_flags::TYPE_P2SH_TOKEN } else { version_byte_flags::TYPE_P2SH }; let output = encode(data, hash_type, network).unwrap(); assert_eq!(output, cashaddr.to_ascii_lowercase()); let decoded = decode(cashaddr).unwrap(); assert_eq!(decoded.0, *data); } }