c32address 0.1.0

Crockford Base32Check encoding for Stacks addresses
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83

// Copyright (c) 2025 New Internet Labs Limited
// SPDX-License-Identifier: MIT
#![doc = include_str!("../README.md")]
use thiserror::Error;
use log::{debug, error, info};

/// The prefix character used for all Stacks addresses
pub const STACKS_ADDRESS_PREFIX: char = 'S';

#[derive(Debug, Error)]
pub enum AddressError {
    #[error("Invalid hash160 length: expected 20 bytes, got {0}")]
    InvalidLength(usize),
    #[error("Invalid address format: {0}")]
    InvalidFormat(String),
    #[error("Invalid version: {0}")]
    InvalidVersion(u8),
    #[error("Base58 decode error: {0}")]
    Base58Error(String),
}

/// Encode a Stacks address from version byte and hash160
pub fn encode_address(version: u8, hash160: &[u8]) -> Result<String, AddressError> {
    debug!("Encoding address with version {} and hash160 length {}", version, hash160.len());
    
    // Validate version
    if version >= 32 {
        error!("Invalid version {}: must be less than 32", version);
        return Err(AddressError::InvalidVersion(version));
    }

    // Validate hash160 length
    if hash160.len() != 20 {
        error!("Invalid hash160 length {}: must be 20 bytes", hash160.len());
        return Err(AddressError::InvalidLength(hash160.len()));
    }

    let c32string_result = c32::encode_check(hash160, version);

    // Prepend 'S'
    match c32string_result {    
        Ok(c32string) => {
            let address = format!("{}{}", STACKS_ADDRESS_PREFIX, c32string);
            info!("Successfully encoded address: {}", address);
            Ok(address)
        },
        Err(e) => {
            error!("Failed to encode c32check string: {}", e);
            Err(AddressError::InvalidFormat(e.to_string()))
        }
    }
}

/// Decode a Stacks address into version byte and hash160
pub fn decode_address(address: &str) -> Result<(u8, Vec<u8>), AddressError> {
    debug!("Decoding address: {}", address);
    
    // Basic format validation
    if address.len() < 5 {
        error!("Address too short: length {}", address.len());
        return Err(AddressError::InvalidFormat(
            "Address too short".to_string()
        ));
    }

    if !address.starts_with(STACKS_ADDRESS_PREFIX) {
        error!("Invalid address prefix: must start with '{}'", STACKS_ADDRESS_PREFIX);
        return Err(AddressError::InvalidFormat(
            format!("Address must start with '{}'", STACKS_ADDRESS_PREFIX)
        ));
    }

    match c32::decode_check(&address[1..]) {
        Ok((version, hash)) => {
            info!("Successfully decoded address {} to version {} and hash160", address, version);
            Ok((version, hash))
        },
        Err(e) => {
            error!("Failed to decode c32check string: {}", e);
            Err(AddressError::InvalidFormat(e.to_string()))
        }
    }
}