libcrypto 1.0.1__py3-none-any.whl

libcrypto/keys.py

@@ -0,0 +1,149 @@
+"""
+Private and Public Key Classes
+
+This module provides classes for handling private and public keys with
+format conversions, WIF support, and cryptographic operations.
+"""
+from typing import Union
+from .secp256k1 import (
+    private_key_to_public_key, compress_public_key, decompress_public_key
+)
+from .hash import secure_random_bytes
+from .constants import MAX_PRIVATE_KEY
+from .formats import (
+    private_key_to_wif, wif_to_private_key, bytes_to_hex, hex_to_bytes,
+    int_to_bytes, bytes_to_int, InvalidFormatError
+)
+from .addresses import AddressGenerator
+
+
+class KeyError(ValueError):
+    """Raised when key operations fail."""
+    pass
+
+
+class PrivateKey:
+    """
+    Represents a secp256k1 private key.
+    """
+
+    def __init__(self, key: Union[bytes, int, str, None] = None, network: str = 'bitcoin'):
+        self.network = network
+        if key is None:
+            self._key_int = self._generate_random_key()
+        else:
+            self._key_int = self._normalize_key(key)
+
+        if not (1 <= self._key_int <= MAX_PRIVATE_KEY):
+            raise KeyError(f"Private key is out of valid range (1 to N-1).")
+
+        self._key_bytes = int_to_bytes(self._key_int, 32)
+        self._public_key_cache = {}
+
+    @staticmethod
+    def _generate_random_key() -> int:
+        """Generate a cryptographically secure random private key."""
+        while True:
+            key_bytes = secure_random_bytes(32)
+            key_int = bytes_to_int(key_bytes)
+            if 1 <= key_int <= MAX_PRIVATE_KEY:
+                return key_int
+
+    def _normalize_key(self, key: Union[bytes, int, str]) -> int:
+        """Normalize various key formats to an integer."""
+        if isinstance(key, int):
+            return key
+        if isinstance(key, bytes):
+            if len(key) != 32:
+                raise KeyError(f"Private key bytes must be 32 bytes, got {len(key)}")
+            return bytes_to_int(key)
+        if isinstance(key, str):
+            try:
+                # First, try to decode as WIF
+                key_bytes, _, _ = wif_to_private_key(key)
+                self.network = _[2]  # Update network from WIF
+                return bytes_to_int(key_bytes)
+            except InvalidFormatError:
+                # If WIF fails, try to decode as hex
+                try:
+                    if len(key) != 64:
+                        raise InvalidFormatError("Hex key must be 64 characters.")
+                    key_bytes = hex_to_bytes(key)
+                    return bytes_to_int(key_bytes)
+                except InvalidFormatError as e:
+                    raise KeyError(f"Invalid private key format. Not valid WIF or Hex: {e}") from e
+        raise KeyError(f"Unsupported key type: {type(key)}")
+
+    @property
+    def hex(self) -> str:
+        return bytes_to_hex(self._key_bytes)
+
+    @property
+    def bytes(self) -> bytes:
+        return self._key_bytes
+
+    @property
+    def int(self) -> int:
+        return self._key_int
+
+    def to_wif(self, compressed: bool = True) -> str:
+        return private_key_to_wif(self._key_bytes, compressed, self.network)
+
+    def get_public_key(self, compressed: bool = True) -> 'PublicKey':
+        """Get the corresponding public key, using a cache for efficiency."""
+        if compressed not in self._public_key_cache:
+            public_key_bytes = private_key_to_public_key(self._key_int, compressed)
+            self._public_key_cache[compressed] = PublicKey(public_key_bytes)
+        return self._public_key_cache[compressed]
+
+    @classmethod
+    def generate(cls, network: str = 'bitcoin') -> 'PrivateKey':
+        """Generate a new random private key."""
+        return cls(None, network)
+
+    def __repr__(self) -> str:
+        return f"PrivateKey(network='{self.network}')"
+
+
+class PublicKey:
+    """
+    Represents a secp256k1 public key.
+    """
+
+    def __init__(self, key: Union[bytes, str]):
+        if isinstance(key, str):
+            key = hex_to_bytes(key)
+
+        if len(key) not in [33, 65]:
+            raise KeyError(f"Invalid public key length: {len(key)}. Must be 33 or 65 bytes.")
+
+        self._key_bytes = key
+        self.compressed = (len(key) == 33)
+
+    @property
+    def hex(self) -> str:
+        return bytes_to_hex(self._key_bytes)
+
+    @property
+    def bytes(self) -> bytes:
+        return self._key_bytes
+
+    def get_address(self, address_type: str = 'p2pkh', network: str = 'bitcoin') -> str:
+        """
+        Generate an address from this public key.
+        This is a method, not a property, as it requires arguments.
+        """
+        return AddressGenerator.from_public_key(self.bytes, address_type, network)
+
+    def to_compressed(self) -> 'PublicKey':
+        if self.compressed:
+            return self
+        return PublicKey(compress_public_key(self.bytes))
+
+    def to_uncompressed(self) -> 'PublicKey':
+        if not self.compressed:
+            return self
+        return PublicKey(decompress_public_key(self.bytes))
+
+    def __repr__(self) -> str:
+        return f"PublicKey('{self.hex}', compressed={self.compressed})"

libcrypto/mnemonic.py

@@ -0,0 +1,156 @@
+"""
+BIP39 Mnemonic Phrase Implementation
+
+This module provides comprehensive BIP39 mnemonic phrase functionality including:
+- Secure mnemonic generation with proper entropy
+- Mnemonic validation with checksum verification
+- Mnemonic to seed conversion with PBKDF2
+- Conversion between entropy and mnemonic phrases
+"""
+from typing import Union
+from .hash import sha256, bip39_pbkdf2, secure_random_bytes
+from .constants import (
+    BIP39_WORD_LIST,
+    BIP39_ENTROPY_BITS,
+    BIP39_CHECKSUM_BITS,
+    VALID_MNEMONIC_LENGTHS,
+    ERROR_MESSAGES
+)
+
+
+class InvalidMnemonicError(ValueError):
+    """Raised when a mnemonic phrase is invalid."""
+    pass
+
+
+class InvalidEntropyError(ValueError):
+    """Raised when entropy is invalid."""
+    pass
+
+
+def _entropy_to_mnemonic_bits(entropy: bytes) -> str:
+    """Internal helper to convert entropy to its bit representation with checksum."""
+    entropy_bits_len = len(entropy) * 8
+    if entropy_bits_len not in BIP39_ENTROPY_BITS.values():
+        raise InvalidEntropyError(f"Invalid entropy length: {len(entropy)} bytes")
+
+    checksum_len = BIP39_CHECKSUM_BITS[entropy_bits_len // 32 * 3]
+
+    # Calculate checksum
+    checksum_hash = sha256(entropy)
+    checksum_bits = bin(checksum_hash[0])[2:].zfill(8)[:checksum_len]
+
+    # Combine entropy and checksum
+    entropy_bits = bin(int.from_bytes(entropy, 'big'))[2:].zfill(entropy_bits_len)
+
+    return entropy_bits + checksum_bits
+
+
+def entropy_to_mnemonic(entropy: Union[bytes, str]) -> str:
+    """
+    Convert entropy to a BIP39 mnemonic phrase.
+    """
+    if isinstance(entropy, str):
+        try:
+            entropy = bytes.fromhex(entropy)
+        except ValueError as e:
+            raise InvalidEntropyError(f"Invalid hex string for entropy: {e}") from e
+
+    total_bits = _entropy_to_mnemonic_bits(entropy)
+
+    # Split into 11-bit chunks and map to words
+    words = []
+    for i in range(0, len(total_bits), 11):
+        chunk = total_bits[i:i + 11]
+        word_index = int(chunk, 2)
+        words.append(BIP39_WORD_LIST[word_index])
+
+    return ' '.join(words)
+
+
+def mnemonic_to_entropy(mnemonic: str) -> bytes:
+    """
+    Convert a BIP39 mnemonic phrase back to its original entropy.
+    """
+    words = mnemonic.strip().split()
+    word_count = len(words)
+
+    if word_count not in VALID_MNEMONIC_LENGTHS:
+        raise InvalidMnemonicError(ERROR_MESSAGES['invalid_mnemonic_length'])
+
+    # Convert words to a bit string
+    bit_string = ""
+    for word in words:
+        try:
+            index = BIP39_WORD_LIST.index(word)
+            bit_string += bin(index)[2:].zfill(11)
+        except ValueError:
+            raise InvalidMnemonicError(f"{ERROR_MESSAGES['invalid_mnemonic_word']}: '{word}'")
+
+    # Split data and checksum
+    entropy_len = BIP39_ENTROPY_BITS[word_count]
+    checksum_len = BIP39_CHECKSUM_BITS[word_count]
+
+    entropy_bits = bit_string[:entropy_len]
+    checksum_bits = bit_string[entropy_len:]
+
+    # Convert entropy bits to bytes
+    entropy_bytes = int(entropy_bits, 2).to_bytes(entropy_len // 8, 'big')
+
+    # Verify checksum
+    expected_checksum_hash = sha256(entropy_bytes)
+    expected_checksum = bin(expected_checksum_hash[0])[2:].zfill(8)[:checksum_len]
+
+    if checksum_bits != expected_checksum:
+        raise InvalidMnemonicError(ERROR_MESSAGES['invalid_mnemonic_checksum'])
+
+    return entropy_bytes
+
+
+def generate_mnemonic(word_count: int = 12) -> str:
+    """
+    Generates a cryptographically secure mnemonic phrase.
+    """
+    if word_count not in VALID_MNEMONIC_LENGTHS:
+        raise ValueError(ERROR_MESSAGES['invalid_mnemonic_length'])
+
+    entropy_bits = BIP39_ENTROPY_BITS[word_count]
+    entropy = secure_random_bytes(entropy_bits // 8)
+
+    return entropy_to_mnemonic(entropy)
+
+
+def validate_mnemonic(mnemonic: str) -> bool:
+    """
+    Validate a BIP39 mnemonic phrase by trying to convert it to entropy.
+    """
+    try:
+        mnemonic_to_entropy(mnemonic)
+        return True
+    except InvalidMnemonicError:
+        return False
+
+
+def mnemonic_to_seed(mnemonic: str, passphrase: str = "") -> bytes:
+    """
+    Convert a BIP39 mnemonic phrase to a seed using PBKDF2.
+    """
+    # NFKD normalization is recommended by BIP39 spec
+    import unicodedata
+    normalized_mnemonic = unicodedata.normalize('NFKD', mnemonic.strip())
+
+    if not validate_mnemonic(normalized_mnemonic):
+        raise InvalidMnemonicError("Invalid mnemonic phrase provided.")
+
+    return bip39_pbkdf2(normalized_mnemonic, passphrase)
+
+
+__all__ = [
+    'generate_mnemonic',
+    'validate_mnemonic',
+    'mnemonic_to_seed',
+    'mnemonic_to_entropy',
+    'entropy_to_mnemonic',
+    'InvalidMnemonicError',
+    'InvalidEntropyError'
+]

libcrypto/secp256k1.py

@@ -0,0 +1,117 @@
+"""
+Secp256k1 Elliptic Curve Operations (using the 'ecdsa' library)
+
+This module provides a robust interface for secp256k1 operations by
+wrapping the 'ecdsa' library, which is a highly stable and focused package
+for Elliptic Curve Digital Signature Algorithm.
+
+This implementation replaces the pycryptodome backend to avoid environment
+and installation issues.
+"""
+from typing import Tuple
+from ecdsa import SigningKey, VerifyingKey, SECP256k1
+from ecdsa.util import sigencode_string, sigdecode_string
+from .constants import MAX_PRIVATE_KEY
+
+
+class Secp256k1Error(ValueError):
+    """Custom exception for secp256k1 related errors."""
+    pass
+
+
+def private_key_to_public_key(private_key: int, compressed: bool = True) -> bytes:
+    """
+    Derives a public key from a private key integer using the 'ecdsa' library.
+
+    Args:
+        private_key: The private key as an integer.
+        compressed: If True, returns a 33-byte compressed public key.
+                    If False, returns a 65-byte uncompressed public key.
+
+    Returns:
+        The public key as a byte string.
+
+    Raises:
+        Secp256k1Error: If the private key is out of the valid range.
+    """
+    if not (1 <= private_key <= MAX_PRIVATE_KEY):
+        raise Secp256k1Error("Private key is out of the valid range (1 to N-1).")
+
+    try:
+        # Create a SigningKey object from the private key bytes.
+        private_key_bytes = private_key.to_bytes(32, 'big')
+        sk = SigningKey.from_string(private_key_bytes, curve=SECP256k1)
+
+        # Get the corresponding VerifyingKey (public key).
+        vk = sk.verifying_key
+
+        # Return the public key in the requested format.
+        if compressed:
+            return vk.to_string("compressed")
+        else:
+            return vk.to_string("uncompressed")
+    except Exception as e:
+        raise Secp256k1Error(f"Failed to generate public key with ecdsa: {e}") from e
+
+
+def public_key_to_point_coords(public_key: bytes) -> Tuple[int, int]:
+    """
+    Converts a public key byte string into its (x, y) integer coordinates.
+
+    Args:
+        public_key: The public key as bytes (compressed or uncompressed).
+
+    Returns:
+        A tuple containing the (x, y) coordinates as integers.
+    """
+    try:
+        vk = VerifyingKey.from_string(public_key, curve=SECP256k1)
+        # The public_point attribute holds the x and y coordinates.
+        return (vk.pubkey.point.x(), vk.pubkey.point.y())
+    except Exception as e:
+        raise Secp256k1Error(f"Failed to extract point from public key: {e}") from e
+
+
+def decompress_public_key(public_key: bytes) -> bytes:
+    """
+    Converts a public key to its uncompressed format (65 bytes) using 'ecdsa'.
+
+    Args:
+        public_key: The public key in either compressed or uncompressed format.
+
+    Returns:
+        The 65-byte uncompressed public key.
+    """
+    try:
+        # Create a VerifyingKey from the input bytes. It handles both formats.
+        vk = VerifyingKey.from_string(public_key, curve=SECP256k1)
+        return vk.to_string("uncompressed")
+    except Exception as e:
+        raise Secp256k1Error(f"Failed to decompress public key: {e}") from e
+
+
+def compress_public_key(public_key: bytes) -> bytes:
+    """
+    Converts a public key to its compressed format (33 bytes) using 'ecdsa'.
+
+    Args:
+        public_key: The public key in either compressed or uncompressed format.
+
+    Returns:
+        The 33-byte compressed public key.
+    """
+    try:
+        # Create a VerifyingKey from the input bytes.
+        vk = VerifyingKey.from_string(public_key, curve=SECP256k1)
+        return vk.to_string("compressed")
+    except Exception as e:
+        raise Secp256k1Error(f"Failed to compress public key: {e}") from e
+
+
+__all__ = [
+    'private_key_to_public_key',
+    'public_key_to_point_coords',
+    'decompress_public_key',
+    'compress_public_key',
+    'Secp256k1Error',
+]

libcrypto/wallet.py

@@ -0,0 +1,135 @@
+"""
+High-Level Wallet Interface
+
+This module provides a simple, high-level interface for creating cryptocurrency
+wallets from a single private key and generating addresses for various coins.
+"""
+from typing import Union, Dict, List
+from .keys import PrivateKey, PublicKey
+from .addresses import AddressGenerator, AddressError
+from .constants import BIP44_COIN_TYPES
+
+# Configuration for coins, especially for properties like required public key format.
+COIN_CONFIG = {
+    'ethereum': {'uncompressed_required': True, 'address_types': ['default']},
+    'tron': {'uncompressed_required': True, 'address_types': ['default']},
+    'ripple': {'uncompressed_required': False, 'address_types': ['default']},  # Prefers compressed
+    'bitcoin': {'uncompressed_required': False, 'address_types': ['p2pkh', 'p2sh-p2wpkh', 'p2wpkh']},
+    'litecoin': {'uncompressed_required': False, 'address_types': ['p2pkh', 'p2sh-p2wpkh', 'p2wpkh']},
+    'dogecoin': {'uncompressed_required': False, 'address_types': ['p2pkh']},
+    'dash': {'uncompressed_required': False, 'address_types': ['p2pkh']},
+    'bitcoin_cash': {'uncompressed_required': False, 'address_types': ['p2pkh']},
+    'testnet': {'uncompressed_required': False, 'address_types': ['p2pkh', 'p2sh-p2wpkh', 'p2wpkh']},
+}
+
+
+class Wallet:
+    """
+    A simple wallet class to manage a single private key and generate addresses.
+
+    This class serves as a high-level, easy-to-use wrapper around the library's
+    core functionalities. It is initialized with a single private key and can
+    generate corresponding addresses for multiple supported cryptocurrencies.
+    """
+
+    def __init__(self, private_key: Union[str, bytes, int, PrivateKey]):
+        """
+        Initializes the wallet with a private key.
+
+        Args:
+            private_key: The private key in WIF, hex, bytes, integer format,
+                         or as a PrivateKey object.
+        """
+        if isinstance(private_key, PrivateKey):
+            self.private_key = private_key
+        else:
+            self.private_key = PrivateKey(private_key)
+
+        self._public_key_compressed = self.private_key.get_public_key(compressed=True)
+        self._public_key_uncompressed = self.private_key.get_public_key(compressed=False)
+
+    def get_address(self, coin: str, address_type: str = 'p2pkh') -> str:
+        """
+        Generates a single address for a specific coin and address type.
+
+        Args:
+            coin (str): The name of the coin (e.g., 'bitcoin', 'ethereum').
+            address_type (str, optional): The type of address to generate.
+                For Bitcoin coins: 'p2pkh' (default), 'p2sh-p2wpkh', 'p2wpkh'.
+                For Ethereum coins, this is ignored.
+
+        Returns:
+            str: The generated address string.
+
+        Raises:
+            ValueError: If the coin or address type is not supported.
+            NotImplementedError: For coins requiring a different cryptographic curve (e.g., Ed25519).
+        """
+        coin = coin.lower()
+        if coin not in COIN_CONFIG:
+            # Check if it's a known coin but just not in the simple config
+            if coin in BIP44_COIN_TYPES:
+                raise ValueError(f"Coin '{coin}' is recognized but not configured for simple address generation.")
+            raise ValueError(f"Unsupported coin: '{coin}'")
+
+        config = COIN_CONFIG[coin]
+
+        # Select the correct public key format
+        public_key = self._public_key_uncompressed if config['uncompressed_required'] else self._public_key_compressed
+
+        # For coins with a single address type, override the user's choice
+        if len(config['address_types']) == 1 and config['address_types'][0] == 'default':
+            addr_type = 'default'  # A generic type for coins like ETH, TRX
+        else:
+            if address_type not in config['address_types']:
+                raise ValueError(f"Unsupported address type '{address_type}' for {coin}. "
+                                 f"Available types: {config['address_types']}")
+            addr_type = address_type
+
+        try:
+            # In AddressGenerator, 'default' type is handled internally for relevant networks
+            # and `addr_type` is used for Bitcoin-style networks.
+            effective_type_for_generator = 'default' if addr_type == 'default' else addr_type
+            return AddressGenerator.from_public_key(public_key.bytes, effective_type_for_generator, coin)
+        except AddressError as e:
+            raise ValueError(f"Could not generate address for {coin}: {e}")
+
+    def get_all_addresses(self, coin: str) -> Dict[str, str]:
+        """
+        Generates all supported address formats for a given coin.
+
+        Args:
+            coin (str): The name of the coin (e.g., 'bitcoin', 'ethereum').
+
+        Returns:
+            Dict[str, str]: A dictionary where keys are address types and
+                            values are the corresponding addresses.
+        """
+        coin = coin.lower()
+        if coin not in COIN_CONFIG:
+            raise ValueError(f"Unsupported coin: '{coin}'")
+
+        addresses = {}
+        config = COIN_CONFIG[coin]
+
+        for addr_type in config['address_types']:
+            try:
+                # Use the main get_address method to ensure consistent logic
+                addresses[addr_type] = self.get_address(coin, addr_type)
+            except (ValueError, NotImplementedError, AddressError) as e:
+                addresses[addr_type] = f"Error: {e}"
+
+        return addresses
+
+    @classmethod
+    def generate(cls) -> 'Wallet':
+        """
+        Creates a new Wallet instance with a newly generated private key.
+
+        Returns:
+            A new Wallet instance.
+        """
+        return cls(PrivateKey.generate())
+
+    def __repr__(self) -> str:
+        return f"Wallet(private_key='{self.private_key.hex}')"