Validate Bitcoin Addresses

Overview

Validate Bitcoin addresses before sending payments. This code handles all address formats: legacy (P2PKH), script hash (P2SH), native SegWit (P2WPKH/P2WSH), and Taproot (P2TR).

The Code

"""
Bitcoin Address Validator
Validates all Bitcoin address formats without external dependencies

Supports:
- P2PKH (1...) - Legacy
- P2SH (3...) - Script hash / wrapped SegWit
- P2WPKH/P2WSH (bc1q...) - Native SegWit v0
- P2TR (bc1p...) - Taproot (SegWit v1)
"""

import hashlib
from typing import Optional, Tuple

# Base58 alphabet
BASE58_ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz"

# Bech32 charset
BECH32_CHARSET = "qpzry9x8gf2tvdw0s3jn54khce6mua7l"


def base58_decode(s: str) -> bytes:
    """Decode a Base58Check string to bytes."""
    n = 0
    for char in s:
        n = n * 58 + BASE58_ALPHABET.index(char)

    # Convert to bytes
    result = []
    while n > 0:
        result.append(n % 256)
        n //= 256

    # Add leading zeros for leading '1's
    for char in s:
        if char == '1':
            result.append(0)
        else:
            break

    return bytes(reversed(result))


def validate_base58_address(address: str) -> Tuple[bool, Optional[str], Optional[str]]:
    """
    Validate a Base58Check Bitcoin address.

    Returns:
        Tuple of (is_valid, address_type, network)
    """
    try:
        decoded = base58_decode(address)

        if len(decoded) != 25:
            return False, None, None

        # Checksum validation
        checksum = decoded[-4:]
        payload = decoded[:-4]
        expected = hashlib.sha256(hashlib.sha256(payload).digest()).digest()[:4]

        if checksum != expected:
            return False, None, None

        version = decoded[0]

        # Version byte mapping
        if version == 0x00:
            return True, "P2PKH", "mainnet"
        elif version == 0x05:
            return True, "P2SH", "mainnet"
        elif version == 0x6f:
            return True, "P2PKH", "testnet"
        elif version == 0xc4:
            return True, "P2SH", "testnet"
        else:
            return False, None, None

    except Exception:
        return False, None, None


def bech32_polymod(values: list) -> int:
    """Bech32 checksum calculation."""
    generator = [0x3b6a57b2, 0x26508e6d, 0x1ea119fa, 0x3d4233dd, 0x2a1462b3]
    chk = 1
    for value in values:
        top = chk >> 25
        chk = (chk & 0x1ffffff) << 5 ^ value
        for i in range(5):
            chk ^= generator[i] if ((top >> i) & 1) else 0
    return chk


def bech32_hrp_expand(hrp: str) -> list:
    """Expand HRP for checksum calculation."""
    return [ord(x) >> 5 for x in hrp] + [0] + [ord(x) & 31 for x in hrp]


def bech32_verify_checksum(hrp: str, data: list, spec: str) -> bool:
    """Verify bech32/bech32m checksum."""
    const = 0x2bc830a3 if spec == "bech32m" else 1
    return bech32_polymod(bech32_hrp_expand(hrp) + data) == const


def validate_bech32_address(address: str) -> Tuple[bool, Optional[str], Optional[str]]:
    """
    Validate a Bech32/Bech32m Bitcoin address.

    Returns:
        Tuple of (is_valid, address_type, network)
    """
    try:
        address = address.lower()

        # Find separator
        pos = address.rfind('1')
        if pos < 1 or pos + 7 > len(address):
            return False, None, None

        hrp = address[:pos]
        data_part = address[pos + 1:]

        # Validate HRP
        if hrp not in ["bc", "tb", "bcrt"]:
            return False, None, None

        # Decode data
        data = []
        for char in data_part:
            idx = BECH32_CHARSET.find(char)
            if idx == -1:
                return False, None, None
            data.append(idx)

        # Check length
        if len(data) < 6:
            return False, None, None

        # Get witness version
        witness_version = data[0]

        # Determine spec (bech32 for v0, bech32m for v1+)
        spec = "bech32" if witness_version == 0 else "bech32m"

        # Verify checksum
        if not bech32_verify_checksum(hrp, data, spec):
            return False, None, None

        # Decode witness program length
        program_len = len(data) - 6  # Minus checksum

        # Validate witness version and program length
        if witness_version == 0:
            if program_len == 20:
                addr_type = "P2WPKH"
            elif program_len == 32:
                addr_type = "P2WSH"
            else:
                return False, None, None
        elif witness_version == 1:
            if program_len == 32:
                addr_type = "P2TR"
            else:
                return False, None, None
        else:
            addr_type = f"P2W_V{witness_version}"

        network = "mainnet" if hrp == "bc" else "testnet"

        return True, addr_type, network

    except Exception:
        return False, None, None


def validate_address(address: str) -> dict:
    """
    Validate any Bitcoin address format.

    Args:
        address: Bitcoin address string

    Returns:
        dict with validation result and metadata
    """
    # Try Base58 first
    if address[0] in "13mn2":
        valid, addr_type, network = validate_base58_address(address)
        if valid:
            return {
                "valid": True,
                "address": address,
                "type": addr_type,
                "network": network,
                "encoding": "base58check"
            }

    # Try Bech32
    if address.lower().startswith(("bc1", "tb1", "bcrt1")):
        valid, addr_type, network = validate_bech32_address(address)
        if valid:
            return {
                "valid": True,
                "address": address,
                "type": addr_type,
                "network": network,
                "encoding": "bech32" if addr_type in ["P2WPKH", "P2WSH"] else "bech32m"
            }

    return {
        "valid": False,
        "address": address,
        "type": None,
        "network": None,
        "encoding": None
    }


# Example usage
if __name__ == "__main__":
    test_addresses = [
        "1BvBMSEYstWetqTFn5Au4m4GFg7xJaNVN2",           # P2PKH mainnet
        "3J98t1WpEZ73CNmQviecrnyiWrnqRhWNLy",           # P2SH mainnet
        "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq",  # P2WPKH mainnet
        "bc1p5d7rjq7g6rdk2yhzks9smlaqtedr4dekq08ge8ztwac72sfr9rusxg3297",  # P2TR
        "invalid_address",                               # Invalid
    ]

    for addr in test_addresses:
        result = validate_address(addr)
        status = "✓" if result["valid"] else "✗"
        print(f"{status} {addr[:40]}...")
        if result["valid"]:
            print(f"   Type: {result['type']}, Network: {result['network']}")

Usage

# No external dependencies required
python validate_address.py

Example Output

✓ 1BvBMSEYstWetqTFn5Au4m4GFg7xJaNVN2...
   Type: P2PKH, Network: mainnet
✓ 3J98t1WpEZ73CNmQviecrnyiWrnqRhWNLy...
   Type: P2SH, Network: mainnet
✓ bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq...
   Type: P2WPKH, Network: mainnet
✓ bc1p5d7rjq7g6rdk2yhzks9smlaqtedr4dekq08ge8...
   Type: P2TR, Network: mainnet
✗ invalid_address...

Agent Notes

Always validate before sending. An invalid address will result in permanently lost funds.

Address type selection for agents:

• P2WPKH (bc1q…): Lowest fees, best for frequent transactions
• P2TR (bc1p…): Best privacy, recommended for new wallets
• P2SH (3…): Good compatibility, slightly higher fees
• P2PKH (1…): Legacy, highest fees, avoid if possible