rustywallet-address

Comprehensive cryptocurrency address generation and validation library for Bitcoin and Ethereum networks.

Features

• Bitcoin Legacy (P2PKH) - Pay-to-Public-Key-Hash addresses (1... mainnet, m/n testnet)
• Bitcoin SegWit (P2WPKH) - Pay-to-Witness-Public-Key-Hash addresses (bc1q... mainnet, tb1q... testnet)
• Bitcoin Taproot (P2TR) - Pay-to-Taproot addresses (bc1p... mainnet, tb1p... testnet)
• Silent Payments (BIP352) - Privacy-preserving addresses (sp1... mainnet, tsp1... testnet)
• Ethereum - Ethereum addresses with EIP-55 checksum validation (0x...)
• Descriptor Derivation - Derive addresses from output descriptors (BIP380-386)
• Multi-network support - Bitcoin mainnet, testnet, regtest, signet
• Address validation - Comprehensive validation with detailed error reporting
• Type-safe API - Rust's type system prevents address format errors
• Zero-copy parsing - Efficient address parsing and validation
• Serde support - Serialization and deserialization support

Installation

Add this to your Cargo.toml:

[dependencies]
rustywallet-address = "0.3"
rustywallet-keys = "0.1"

Quick Start

use rustywallet_keys::prelude::PrivateKey;
use rustywallet_address::prelude::*;

// Generate a random private key
let private_key = PrivateKey::random();
let public_key = private_key.public_key();

// Bitcoin Legacy (P2PKH)
let p2pkh = P2PKHAddress::from_public_key(&public_key, Network::BitcoinMainnet)?;
println!("P2PKH: {}", p2pkh); // 1BvBMSEYstWetqTFn5Au4m4GFg7xJaNVN2

// Bitcoin SegWit (P2WPKH)
let p2wpkh = P2WPKHAddress::from_public_key(&public_key, Network::BitcoinMainnet)?;
println!("P2WPKH: {}", p2wpkh); // bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4

// Bitcoin Taproot (P2TR)
let p2tr = P2TRAddress::from_public_key(&public_key, Network::BitcoinMainnet)?;
println!("P2TR: {}", p2tr); // bc1p5d7rjq7g6rdk2yhzks9smlaqtedr4dekq08ge8ztwac72sfr9rusxg3297

// Ethereum
let eth = EthereumAddress::from_public_key(&public_key)?;
println!("Ethereum: {}", eth); // 0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed

Descriptor-Based Derivation

Derive addresses from output descriptors (BIP380-386):

use rustywallet_address::prelude::*;

// Derive from wpkh descriptor
let addr = Address::from_descriptor(
    "wpkh(02c6047f9441ed7d6d3045406e95c07cd85c778e4b8cef3ca7abac09b95c709ee5)",
    0,
    Network::BitcoinMainnet,
)?;
assert!(addr.to_string().starts_with("bc1q"));

// Derive from Taproot descriptor
let addr = Address::from_descriptor(
    "tr(02c6047f9441ed7d6d3045406e95c07cd85c778e4b8cef3ca7abac09b95c709ee5)",
    0,
    Network::BitcoinMainnet,
)?;
assert!(addr.to_string().starts_with("bc1p"));

// Derive from nested SegWit descriptor
let addr = Address::from_descriptor(
    "sh(wpkh(02c6047f9441ed7d6d3045406e95c07cd85c778e4b8cef3ca7abac09b95c709ee5))",
    0,
    Network::BitcoinMainnet,
)?;
assert!(addr.to_string().starts_with("3"));

// Derive multiple addresses from ranged descriptor
let addrs = Address::from_descriptor_range(
    "wpkh(xpub.../0/*)",
    0,    // start index
    10,   // count
    Network::BitcoinMainnet,
)?;

Supported Descriptor Types

Descriptor Utilities

use rustywallet_address::descriptor::*;

// Get descriptor type
let desc_type = get_descriptor_type("wpkh(KEY)")?;
assert_eq!(desc_type, DescriptorType::Wpkh);
assert!(desc_type.is_segwit());

// Check for wildcard
let has_wildcard = descriptor_has_wildcard("wpkh(xpub.../0/*)")?;
assert!(has_wildcard);

// Direct address derivation
let addr = derive_address_from_descriptor(
    "tr(KEY)",
    0,
    Network::BitcoinMainnet,
)?;

Address Types

P2PKH (Pay-to-Public-Key-Hash)

Legacy Bitcoin addresses using Base58Check encoding:

use rustywallet_address::prelude::*;

// From public key
let address = P2PKHAddress::from_public_key(&public_key, Network::BitcoinMainnet)?;

// From string
let address = P2PKHAddress::from_str("1BvBMSEYstWetqTFn5Au4m4GFg7xJaNVN2")?;

// Validate
P2PKHAddress::validate("1BvBMSEYstWetqTFn5Au4m4GFg7xJaNVN2")?;

P2WPKH (Pay-to-Witness-Public-Key-Hash)

SegWit v0 addresses using Bech32 encoding:

use rustywallet_address::prelude::*;

// From public key
let address = P2WPKHAddress::from_public_key(&public_key, Network::BitcoinMainnet)?;

// From string
let address = P2WPKHAddress::from_str("bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4")?;

// Validate
P2WPKHAddress::validate("bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4")?;

P2TR (Pay-to-Taproot)

Taproot addresses using Bech32m encoding:

use rustywallet_address::prelude::*;

// From public key
let address = P2TRAddress::from_public_key(&public_key, Network::BitcoinMainnet)?;

// From string
let address = P2TRAddress::from_str("bc1p5d7rjq7g6rdk2yhzks9smlaqtedr4dekq08ge8ztwac72sfr9rusxg3297")?;

// Validate
P2TRAddress::validate("bc1p5d7rjq7g6rdk2yhzks9smlaqtedr4dekq08ge8ztwac72sfr9rusxg3297")?;

Silent Payments (BIP352)

Privacy-preserving addresses using Bech32m encoding:

use rustywallet_address::prelude::*;
use rustywallet_address::silent_payments::{SilentPaymentAddress, SilentPaymentLabel};

// Create from scan and spend keys
let scan_key = PrivateKey::random();
let spend_key = PrivateKey::random();
let address = SilentPaymentAddress::new(
    &scan_key.public_key(),
    &spend_key.public_key(),
    Network::BitcoinMainnet,
)?;
println!("SP Address: {}", address); // sp1q...

// Single-key mode (scan = spend)
let key = PrivateKey::random();
let address = SilentPaymentAddress::from_single_key(&key.public_key(), Network::BitcoinMainnet)?;

// Parse from string
let address = SilentPaymentAddress::parse("sp1q...")?;

// Labels for multiple addresses
let label = SilentPaymentLabel::new(1);

Ethereum

Ethereum addresses with EIP-55 checksum support:

use rustywallet_address::prelude::*;

// From public key
let address = EthereumAddress::from_public_key(&public_key)?;

// From string
let address = EthereumAddress::from_str("0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed")?;

// Validate with checksum
EthereumAddress::validate_checksum("0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed")?;

// Convert to checksummed format
let checksummed = address.to_checksum();

Validation Examples

use rustywallet_address::prelude::*;

// Generic address validation with auto-detection
let result = Address::validate("bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4");
assert!(result.is_ok());

// Specific type validation
assert!(P2PKHAddress::validate("1BvBMSEYstWetqTFn5Au4m4GFg7xJaNVN2").is_ok());
assert!(P2WPKHAddress::validate("bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4").is_ok());
assert!(P2TRAddress::validate("bc1p5d7rjq7g6rdk2yhzks9smlaqtedr4dekq08ge8ztwac72sfr9rusxg3297").is_ok());
assert!(EthereumAddress::validate("0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed").is_ok());

// Network-specific validation
let mainnet_addr = "1BvBMSEYstWetqTFn5Au4m4GFg7xJaNVN2";
let testnet_addr = "mipcBbFg9gMiCh81Kj8tqqdgoZub1ZJRfn";

assert!(P2PKHAddress::validate_network(mainnet_addr, Network::BitcoinMainnet).is_ok());
assert!(P2PKHAddress::validate_network(testnet_addr, Network::BitcoinTestnet).is_ok());

// Invalid addresses return detailed errors
match Address::validate("invalid_address") {
    Err(AddressError::InvalidFormat(_)) => println!("Invalid format"),
    Err(AddressError::ChecksumMismatch) => println!("Invalid checksum"),
    _ => {}
}

Network Support

API Reference

Core Types

• Address - Generic address enum supporting all types
• P2PKHAddress - Bitcoin Legacy addresses
• P2WPKHAddress - Bitcoin SegWit v0 addresses
• P2TRAddress - Bitcoin Taproot addresses
• EthereumAddress - Ethereum addresses
• Network - Supported network types
• AddressError - Comprehensive error types
• DescriptorType - Supported descriptor types
• AddressFromDescriptor - Trait for descriptor-based derivation

Key Methods

// Address creation
Address::from_str(s: &str) -> Result<Address, AddressError>
Address::from_public_key(pk: &PublicKey, network: Network) -> Result<Address, AddressError>
Address::from_descriptor(desc: &str, index: u32, network: Network) -> Result<Address, AddressError>
Address::from_descriptor_range(desc: &str, start: u32, count: u32, network: Network) -> Result<Vec<Address>, AddressError>

// Validation
Address::validate(s: &str) -> Result<(), AddressError>
Address::validate_network(s: &str, network: Network) -> Result<(), AddressError>

// Type checking
address.is_bitcoin() -> bool
address.is_ethereum() -> bool
address.address_type() -> AddressType
address.network() -> Option<Network>

// Conversion
address.to_string() -> String
address.as_bytes() -> &[u8]

Error Handling

use rustywallet_address::AddressError;

match Address::validate("invalid") {
    Err(AddressError::InvalidFormat(_)) => "Invalid address format",
    Err(AddressError::ChecksumMismatch) => "Checksum validation failed", 
    Err(AddressError::UnsupportedAddressType(_)) => "Address type not supported",
    Ok(_) => "Valid address",
};

License

Licensed under the MIT License. See LICENSE for details.