htcli 1.1.0__py3-none-any.whl

src/htcli/utils/legacy/crypto.py

@@ -0,0 +1,1176 @@
+"""
+Cryptographic utility functions for the Hypertensor CLI.
+"""
+
+import base64
+import hmac
+import json
+import secrets
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+from cryptography.fernet import Fernet
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives.kdf.pbkdf2 import PBKDF2HMAC
+from substrateinterface import Keypair
+
+from ..wallet.auth import get_unlock_password
+
+
+def get_network_appropriate_key_type() -> str:
+    """
+    Get the appropriate key type based on current network configuration.
+
+    Returns:
+        The recommended key type for the current network
+    """
+    try:
+        from ..dependencies import get_config
+
+        config = get_config()
+
+        # If we're on mainnet or EVM-compatible network, use ECDSA for Bytes20 addresses
+        if config.network.network_type == "mainnet" or config.network.evm_compatible:
+            return config.wallet.mainnet_key_type
+        else:
+            return config.wallet.testnet_key_type
+
+    except Exception:
+        # Fallback to ECDSA if config is not available
+        return "ecdsa"
+
+
+def validate_key_type_for_network(key_type: str) -> tuple[bool, str]:
+    """
+    Validate if a key type is appropriate for the current network.
+
+    Args:
+        key_type: The key type to validate
+
+    Returns:
+        Tuple of (is_valid, message)
+    """
+    try:
+        from ..dependencies import get_config
+
+        config = get_config()
+
+        # For mainnet/EVM networks, strongly recommend ECDSA
+        if config.network.network_type == "mainnet" or config.network.evm_compatible:
+            if key_type != "ecdsa":
+                return (
+                    False,
+                    f"For mainnet/EVM compatibility, ECDSA keys are required. You specified '{key_type}'.",
+                )
+
+        return True, ""
+
+    except Exception:
+        # If config unavailable, allow all types but warn
+        if key_type == "ecdsa":
+            return True, ""
+        else:
+            return (
+                True,
+                "Warning: ECDSA keys are recommended for mainnet compatibility.",
+            )
+
+
+def detect_address_type(address: str) -> tuple[str, str, bool]:
+    """
+    Detect the type and format of an address.
+
+    Args:
+        address: The address to analyze
+
+    Returns:
+        Tuple of (address_type, format_name, is_evm_compatible)
+    """
+    if not address:
+        return "unknown", "Invalid", False
+
+    # EVM/ECDSA format (0x + 40 hex chars = 42 total)
+    if address.startswith("0x"):
+        if len(address) == 42:
+            return "ecdsa", "EVM/ECDSA (20-byte)", True
+        else:
+            return (
+                "invalid_evm",
+                f"Invalid EVM (expected 42 chars, got {len(address)})",
+                False,
+            )
+
+    # SS58/Substrate format (typically starts with 1-5, ~48 chars)
+    elif len(address) > 40 and address[0].isdigit():
+        return "ss58", "SS58/Substrate (32-byte)", False
+
+    # Short addresses or other formats
+    elif len(address) < 20:
+        return "unknown", "Too Short", False
+
+    else:
+        return "unknown", "Unknown Format", False
+
+
+def format_address_display(
+    address: str, key_type: str = None, max_length: int = None
+) -> str:
+    """
+    Format address display with type information.
+
+    Args:
+        address: The address to format
+        key_type: Optional key type hint
+        max_length: Optional maximum length for truncation
+
+    Returns:
+        Formatted address string with type info
+    """
+    if not address or address == "N/A":
+        return "N/A"
+
+    # Apply truncation if requested
+    display_address = address
+    if max_length and len(address) > max_length:
+        display_address = address[:20] + "..." + address[-20:]
+
+    addr_type, format_name, is_compatible = detect_address_type(address)
+
+    if addr_type == "ecdsa":
+        return f"{display_address} [EVM/ECDSA]"
+    elif addr_type == "ss58":
+        return f"{display_address} [SS58/Substrate]"
+    else:
+        return f"{display_address} [{format_name}]"
+
+
+def can_convert_to_ecdsa(address: str, key_type: str = None) -> tuple[bool, str]:
+    """
+    Check if an address can be converted to ECDSA format.
+
+    Args:
+        address: The address to check
+        key_type: The key type if known
+
+    Returns:
+        Tuple of (can_convert, explanation)
+    """
+    addr_type, format_name, is_compatible = detect_address_type(address)
+
+    if addr_type == "ecdsa":
+        return False, "Already in ECDSA format"
+    elif addr_type == "ss58":
+        return False, (
+            "Cannot convert SS58 addresses to ECDSA format. "
+            "SS58 addresses use different cryptographic keys (SR25519/Ed25519) "
+            "which are incompatible with ECDSA. You must generate a new ECDSA wallet."
+        )
+    else:
+        return False, f"Unknown address format: {format_name}"
+
+
+def generate_password_hash(password: str, salt: bytes) -> bytes:
+    """
+    Generate a secure password hash using PBKDF2.
+
+    Args:
+        password: The password to hash
+        salt: Random salt for the hash
+
+    Returns:
+        The password hash
+    """
+    kdf = PBKDF2HMAC(
+        algorithm=hashes.SHA256(),
+        length=32,
+        salt=salt,
+        iterations=100000,
+    )
+    return kdf.derive(password.encode("utf-8"))
+
+
+def verify_password(password: str, stored_hash: bytes, salt: bytes) -> bool:
+    """
+    Verify a password against a stored hash.
+
+    Args:
+        password: The password to verify
+        stored_hash: The stored password hash
+        salt: The salt used for the hash
+
+    Returns:
+        True if password matches, False otherwise
+    """
+    try:
+        kdf = PBKDF2HMAC(
+            algorithm=hashes.SHA256(),
+            length=32,
+            salt=salt,
+            iterations=100000,
+        )
+        computed_hash = kdf.derive(password.encode("utf-8"))
+        return hmac.compare_digest(computed_hash, stored_hash)
+    except Exception:
+        return False
+
+
+def encrypt_private_key(
+    private_key: bytes, password: str
+) -> tuple[bytes, bytes, bytes, bytes]:
+    """
+    Encrypt private key with password and generate validation hash.
+
+    Args:
+        private_key: The private key to encrypt
+        password: The password for encryption
+
+    Returns:
+        Tuple of (encrypted_key, password_hash, password_salt, encryption_salt)
+    """
+    # Generate salt for password hashing
+    password_salt = secrets.token_bytes(16)
+
+    # Generate password hash for validation
+    password_hash = generate_password_hash(password, password_salt)
+
+    # Generate encryption key from password
+    encryption_salt = secrets.token_bytes(16)
+    encryption_key = generate_password_hash(password, encryption_salt)
+
+    # Encrypt private key
+    cipher = Fernet(base64.urlsafe_b64encode(encryption_key))
+    encrypted_key = cipher.encrypt(private_key)
+
+    return encrypted_key, password_hash, password_salt, encryption_salt
+
+
+def decrypt_private_key(
+    encrypted_key: bytes,
+    password: str,
+    password_hash: bytes,
+    password_salt: bytes,
+    encryption_salt: bytes,
+) -> bytes:
+    """
+    Decrypt private key and validate password.
+
+    Args:
+        encrypted_key: The encrypted private key
+        password: The password for decryption
+        password_hash: The stored password hash for validation
+        password_salt: The salt used for password hashing
+        encryption_salt: The salt used for encryption key generation
+
+    Returns:
+        The decrypted private key
+
+    Raises:
+        ValueError: If password is incorrect
+    """
+    # Verify password first
+    if not verify_password(password, password_hash, password_salt):
+        raise ValueError("Invalid password")
+
+    # Generate encryption key from password
+    encryption_key = generate_password_hash(password, encryption_salt)
+
+    # Decrypt private key
+    cipher = Fernet(base64.urlsafe_b64encode(encryption_key))
+    return cipher.decrypt(encrypted_key)
+
+
+def get_wallet_with_retry(name: str, max_attempts: int = 3) -> tuple[Keypair, dict]:
+    """
+    Get wallet with password retry attempts.
+
+    Args:
+        name: Wallet name
+        max_attempts: Maximum password attempts
+
+    Returns:
+        Tuple of (keypair, wallet_info)
+
+    Raises:
+        Exception: If all attempts fail
+    """
+    wallet_info = get_wallet_info_by_name(name)
+
+    if not wallet_info.get("is_encrypted", True):
+        # Unencrypted wallet, load directly
+        return load_keypair(name), wallet_info
+
+    attempts = 0
+    while attempts < max_attempts:
+        try:
+            attempts += 1
+            remaining = max_attempts - attempts + 1
+
+            password = get_unlock_password(
+                name,
+                prompt_message=f"Enter password for wallet '{name}'",
+                max_attempts=1,  # Single attempt per call
+            )
+
+            keypair = load_keypair(name, password)
+            return keypair, wallet_info
+
+        except ValueError as e:
+            if "Invalid password" in str(e):
+                if remaining > 1:
+                    print(f"❌ Invalid password. {remaining - 1} attempts remaining.")
+                else:
+                    raise Exception(
+                        f"Failed to unlock wallet '{name}' after {max_attempts} attempts"
+                    ) from e
+            else:
+                raise
+        except Exception as e:
+            if attempts < max_attempts:
+                print(f"❌ Error: {str(e)}. {remaining - 1} attempts remaining.")
+            else:
+                raise Exception(f"Failed to load wallet '{name}': {str(e)}") from e
+
+    raise Exception(f"Failed to unlock wallet '{name}' after {max_attempts} attempts")
+
+
+@dataclass
+class KeypairInfo:
+    """Information about a keypair."""
+
+    name: str
+    key_type: str
+    public_key: str
+    ss58_address: str
+    mnemonic: Optional[str] = None  # Recovery phrase
+    owner_address: Optional[str] = None  # For hotkeys
+
+
+def generate_coldkey_pair(
+    name: str, key_type: str = "ecdsa", password: Optional[str] = None
+) -> KeypairInfo:
+    """Generate a new coldkey pair."""
+    try:
+        # Generate random keypair
+        if key_type == "ecdsa":
+            mnemonic = Keypair.generate_mnemonic()
+            keypair = Keypair.create_from_mnemonic(mnemonic, crypto_type=2)
+        elif key_type == "sr25519":
+            mnemonic = Keypair.generate_mnemonic()
+            keypair = Keypair.create_from_uri(mnemonic)
+        elif key_type == "ed25519":
+            mnemonic = Keypair.generate_mnemonic()
+            keypair = Keypair.create_from_uri(
+                mnemonic, crypto_type=0
+            )  # 0 for ed25519, 1 for sr25519
+        else:
+            raise ValueError(f"Unsupported key type: {key_type}")
+
+        # Create keypair info
+        keypair_info = KeypairInfo(
+            name=name,
+            key_type=key_type,
+            public_key=keypair.public_key.hex(),
+            ss58_address=keypair.ss58_address,
+            mnemonic=mnemonic,  # Include the recovery phrase
+            owner_address=None,  # Coldkeys don't have owners
+        )
+
+        # Use the password directly from the CLI function
+        # The CLI function already handles the password prompting
+        save_coldkey(name, keypair, password)
+
+        return keypair_info
+
+    except Exception as e:
+        raise Exception(f"Failed to generate coldkey: {str(e)}") from e
+
+
+def generate_hotkey_pair(
+    name: str,
+    owner_address: str,
+    key_type: str = "ecdsa",
+    password: Optional[str] = None,
+) -> KeypairInfo:
+    """Generate a new hotkey pair owned by a coldkey."""
+    try:
+        # Generate random keypair
+        if key_type == "ecdsa":
+            mnemonic = Keypair.generate_mnemonic()
+            keypair = Keypair.create_from_mnemonic(mnemonic, crypto_type=2)
+        elif key_type == "sr25519":
+            mnemonic = Keypair.generate_mnemonic()
+            keypair = Keypair.create_from_uri(mnemonic)
+        elif key_type == "ed25519":
+            mnemonic = Keypair.generate_mnemonic()
+            keypair = Keypair.create_from_uri(
+                mnemonic, crypto_type=0
+            )  # 0 for ed25519, 1 for sr25519
+        else:
+            raise ValueError(f"Unsupported key type: {key_type}")
+
+        # Create keypair info
+        keypair_info = KeypairInfo(
+            name=name,
+            key_type=key_type,
+            public_key=keypair.public_key.hex(),
+            ss58_address=keypair.ss58_address,
+            mnemonic=mnemonic,  # Include the recovery phrase
+            owner_address=owner_address,  # Hotkeys have owners
+        )
+
+        # Use the password directly from the CLI function
+        # The CLI function already handles the password prompting
+        save_hotkey(name, keypair, owner_address, password)
+
+        return keypair_info
+
+    except Exception as e:
+        raise Exception(f"Failed to generate hotkey: {str(e)}") from e
+
+
+def import_keypair(
+    name: str,
+    private_key: str,
+    key_type: str = "ecdsa",
+    password: Optional[str] = None,
+) -> KeypairInfo:
+    """Import a keypair from private key."""
+    try:
+        # Remove 0x prefix if present
+        if private_key.startswith("0x"):
+            private_key = private_key[2:]
+
+        # Validate private key length based on key type
+        if key_type == "ecdsa":
+            if len(private_key) != 64:
+                raise ValueError("ECDSA private key must be 64 characters (32 bytes)")
+        else:
+            if len(private_key) != 64:
+                raise ValueError("Private key must be 64 characters (32 bytes)")
+
+        # Create keypair from private key
+        if key_type == "ecdsa":
+            keypair = Keypair.create_from_private_key(private_key, crypto_type=2)
+        elif key_type == "sr25519":
+            keypair = Keypair.create_from_private_key(private_key, ss58_format=42)
+        elif key_type == "ed25519":
+            keypair = Keypair.create_from_private_key(
+                private_key, crypto_type=0, ss58_format=42
+            )
+        else:
+            raise ValueError(f"Unsupported key type: {key_type}")
+
+        # Create keypair info
+        keypair_info = KeypairInfo(
+            name=name,
+            key_type=key_type,
+            public_key=keypair.public_key.hex(),
+            ss58_address=keypair.ss58_address,
+            mnemonic=None,  # No mnemonic when importing from private key
+            owner_address=None,  # This is for coldkeys
+        )
+
+        # Save the keypair
+        save_coldkey(name, keypair, password)
+
+        return keypair_info
+
+    except Exception as e:
+        raise Exception(f"Failed to import keypair: {str(e)}") from e
+
+
+# Preseeded wallet private keys for development/testing
+PRESEEDED_WALLETS = {
+    "alith": "0x5fb92d6e98884f76de468fa3f6278f8807c48bebc13595d45af5bdc4da702133",
+    "baltathar": "0x8075991ce870b93a8870eca0c0f91913d12f47948ca0fd25b49c6fa7cdbeee8b",
+    "charleth": "0x0b6e18cafb6ed99687ec547bd28139cafdd2bffe70e6b688025de6b445aa5c5b",
+    "dorothy": "0x39539ab1876910bbf3a223d84a29e28f1cb4e2e456503e7e91ed39b2e7223d68",
+    "ethan": "0x7dce9bc8babb68fec1409be38c8e1a52650206a7ed90ff956ae8a6d15eeaaef4",
+    "faith": "0xb9d2ea9a615f3165812e8d44de0d24da9bbd164b65c4f0573e1ce2c8dbd9c8df",
+}
+
+
+def get_preseeded_wallet_info():
+    """Get information about available preseeded wallets."""
+    return {
+        "alith": {
+            "name": "Alith",
+            "private_key": PRESEEDED_WALLETS["alith"],
+            "address": "0xf24FF3a9CF04c71Dbc94D0b566f7A27B94566cac",
+            "description": "Default development account with pre-funded balance",
+        },
+        "baltathar": {
+            "name": "Baltathar",
+            "private_key": PRESEEDED_WALLETS["baltathar"],
+            "address": "0x3Cd0A705a2DC65e5b1E1205896BaA2be8A07c6e0",
+            "description": "Second development account with pre-funded balance",
+        },
+        "charleth": {
+            "name": "Charleth",
+            "private_key": PRESEEDED_WALLETS["charleth"],
+            "address": "0x798d4Ba9baf0064Ec19eB4F0a1a45785ae9D6DFc",
+            "description": "Third development account",
+        },
+        "dorothy": {
+            "name": "Dorothy",
+            "private_key": PRESEEDED_WALLETS["dorothy"],
+            "address": "0x773539d4Ac0e786233D90A233654ccEE26a613D9",
+            "description": "Fourth development account",
+        },
+        "ethan": {
+            "name": "Ethan",
+            "private_key": PRESEEDED_WALLETS["ethan"],
+            "address": "0xFf64d3F6efE2317EE2807d223a0Bdc4c0c49dfDB",
+            "description": "Fifth development account",
+        },
+        "faith": {
+            "name": "Faith",
+            "private_key": PRESEEDED_WALLETS["faith"],
+            "address": "0xC0F0f4ab324C46e55D02D0033343B4Be8A55532d",
+            "description": "Sixth development account",
+        },
+    }
+
+
+def import_preseeded_wallet(
+    preseeded_name: str,
+    wallet_name: Optional[str] = None,
+    password: Optional[str] = None,
+) -> KeypairInfo:
+    """Import a preseeded development wallet (Alith, Baltathar, etc.)."""
+    preseeded_name = preseeded_name.lower()
+
+    if preseeded_name not in PRESEEDED_WALLETS:
+        available = ", ".join(PRESEEDED_WALLETS.keys())
+        raise ValueError(
+            f"Unknown preseeded wallet '{preseeded_name}'. Available: {available}"
+        )
+
+    private_key = PRESEEDED_WALLETS[preseeded_name]
+
+    # Use preseeded name as wallet name if not provided
+    if wallet_name is None:
+        wallet_name = preseeded_name
+
+    # Import using the existing private key import function
+    return import_keypair(
+        name=wallet_name,
+        private_key=private_key,
+        key_type="ecdsa",  # All preseeded wallets are ECDSA
+        password=password,
+    )
+
+
+def import_keypair_from_mnemonic(
+    name: str,
+    mnemonic: str,
+    key_type: str = "ecdsa",
+    password: Optional[str] = None,
+) -> KeypairInfo:
+    """Import an existing keypair from mnemonic phrase."""
+    try:
+        # Import keypair from mnemonic
+        if key_type == "ecdsa":
+            keypair = Keypair.create_from_mnemonic(mnemonic, crypto_type=2)
+        elif key_type == "sr25519":
+            keypair = Keypair.create_from_mnemonic(
+                mnemonic, ss58_format=42, crypto_type=1
+            )
+        elif key_type == "ed25519":
+            keypair = Keypair.create_from_mnemonic(
+                mnemonic, ss58_format=42, crypto_type=0
+            )
+        else:
+            raise ValueError(f"Unsupported key type: {key_type}")
+
+        # Create keypair info
+        keypair_info = KeypairInfo(
+            name=name,
+            key_type=key_type,
+            public_key=keypair.public_key.hex(),
+            ss58_address=keypair.ss58_address,
+            owner_address=None,  # Coldkeys don't have owners
+        )
+
+        # Use provided password or None (no prompting)
+        save_keypair(name, keypair, password)
+
+        return keypair_info
+
+    except Exception as e:
+        raise Exception(f"Failed to import keypair from mnemonic: {str(e)}") from e
+
+
+def import_hotkey_from_private_key(
+    name: str,
+    private_key: str,
+    owner_address: str,
+    key_type: str = "ecdsa",
+    password: Optional[str] = None,
+) -> KeypairInfo:
+    """Import an existing hotkey from private key."""
+    try:
+        # Import keypair
+        if key_type == "ecdsa":
+            keypair = Keypair.create_from_private_key(private_key, crypto_type=2)
+        elif key_type == "sr25519":
+            keypair = Keypair.create_from_private_key(private_key)
+        elif key_type == "ed25519":
+            keypair = Keypair.create_from_private_key(
+                private_key, crypto_type=0
+            )  # 0 for ed25519, 1 for sr25519
+        else:
+            raise ValueError(f"Unsupported key type: {key_type}")
+
+        # Create keypair info
+        keypair_info = KeypairInfo(
+            name=name,
+            key_type=key_type,
+            public_key=keypair.public_key.hex(),
+            ss58_address=keypair.ss58_address,
+            owner_address=owner_address,  # Hotkeys have owners
+        )
+
+        # Use provided password or None (no prompting)
+        save_hotkey(name, keypair, owner_address, password)
+
+        return keypair_info
+
+    except Exception as e:
+        raise Exception(f"Failed to import hotkey from private key: {str(e)}") from e
+
+
+def import_hotkey_from_mnemonic(
+    name: str,
+    mnemonic: str,
+    owner_address: str,
+    key_type: str = "ecdsa",
+    password: Optional[str] = None,
+) -> KeypairInfo:
+    """Import an existing hotkey from mnemonic phrase."""
+    try:
+        # Import keypair from mnemonic
+        if key_type == "ecdsa":
+            keypair = Keypair.create_from_mnemonic(mnemonic, crypto_type=2)
+        elif key_type == "sr25519":
+            keypair = Keypair.create_from_mnemonic(
+                mnemonic, ss58_format=42, crypto_type=1
+            )
+        elif key_type == "ed25519":
+            keypair = Keypair.create_from_mnemonic(
+                mnemonic, ss58_format=42, crypto_type=0
+            )
+        else:
+            raise ValueError(f"Unsupported key type: {key_type}")
+
+        # Create keypair info
+        keypair_info = KeypairInfo(
+            name=name,
+            key_type=key_type,
+            public_key=keypair.public_key.hex(),
+            ss58_address=keypair.ss58_address,
+            owner_address=owner_address,  # Hotkeys have owners
+        )
+
+        # Use provided password or None (no prompting)
+        save_hotkey(name, keypair, owner_address, password)
+
+        return keypair_info
+
+    except Exception as e:
+        raise Exception(f"Failed to import hotkey from mnemonic: {str(e)}") from e
+
+
+def save_coldkey(name: str, keypair: Keypair, password: Optional[str]):
+    """Save a coldkey to disk with encryption."""
+    try:
+        # Create wallet directory
+        wallet_dir = Path.home() / ".htcli" / "wallets"
+        wallet_dir.mkdir(parents=True, exist_ok=True)
+
+        if password is not None:
+            # Encrypt private key with password and generate validation hash
+            encrypted_key, password_hash, password_salt, encryption_salt = (
+                encrypt_private_key(keypair.private_key, password)
+            )
+
+            # Create wallet data with encryption
+            wallet_data = {
+                "name": name,
+                "key_type": (
+                    "ecdsa"
+                    if keypair.crypto_type == 2
+                    else ("sr25519" if keypair.crypto_type == 1 else "ed25519")
+                ),
+                "public_key": keypair.public_key.hex(),
+                "ss58_address": keypair.ss58_address,
+                "encrypted_private_key": base64.b64encode(encrypted_key).decode(),
+                "password_hash": base64.b64encode(password_hash).decode(),
+                "password_salt": base64.b64encode(password_salt).decode(),
+                "encryption_salt": base64.b64encode(encryption_salt).decode(),
+                "is_hotkey": False,  # This is a coldkey
+                "owner_address": None,  # Coldkeys don't have owners
+                "is_encrypted": True,
+            }
+        else:
+            # Store private key without encryption (less secure but user's choice)
+            private_key_bytes = keypair.private_key
+
+            # Create wallet data without encryption
+            wallet_data = {
+                "name": name,
+                "key_type": (
+                    "ecdsa"
+                    if keypair.crypto_type == 2
+                    else ("sr25519" if keypair.crypto_type == 1 else "ed25519")
+                ),
+                "public_key": keypair.public_key.hex(),
+                "ss58_address": keypair.ss58_address,
+                "private_key": private_key_bytes.hex(),  # Store unencrypted
+                "is_hotkey": False,  # This is a coldkey
+                "owner_address": None,  # Coldkeys don't have owners
+                "is_encrypted": False,
+            }
+
+        # Save to file
+        wallet_file = wallet_dir / f"{name}.json"
+        with open(wallet_file, "w") as f:
+            json.dump(wallet_data, f, indent=2)
+
+        # Set secure permissions
+        wallet_file.chmod(0o600)
+
+    except Exception as e:
+        raise Exception(f"Failed to save coldkey: {str(e)}") from e
+
+
+def save_hotkey(
+    name: str, keypair: Keypair, owner_address: str, password: Optional[str]
+):
+    """Save a hotkey to disk with encryption."""
+    try:
+        # Create wallet directory
+        wallet_dir = Path.home() / ".htcli" / "wallets"
+        wallet_dir.mkdir(parents=True, exist_ok=True)
+
+        if password is not None:
+            # Encrypt private key with password and generate validation hash
+            encrypted_key, password_hash, password_salt, encryption_salt = (
+                encrypt_private_key(keypair.private_key, password)
+            )
+
+            # Create wallet data with encryption
+            wallet_data = {
+                "name": name,
+                "key_type": (
+                    "ecdsa"
+                    if keypair.crypto_type == 2
+                    else ("sr25519" if keypair.crypto_type == 1 else "ed25519")
+                ),
+                "public_key": keypair.public_key.hex(),
+                "ss58_address": keypair.ss58_address,
+                "encrypted_private_key": base64.b64encode(encrypted_key).decode(),
+                "password_hash": base64.b64encode(password_hash).decode(),
+                "password_salt": base64.b64encode(password_salt).decode(),
+                "encryption_salt": base64.b64encode(encryption_salt).decode(),
+                "is_hotkey": True,  # This is a hotkey
+                "owner_address": owner_address,  # Hotkeys have owners
+                "is_encrypted": True,
+            }
+        else:
+            # Store private key without encryption (less secure but user's choice)
+            private_key_bytes = keypair.private_key
+
+            # Create wallet data without encryption
+            wallet_data = {
+                "name": name,
+                "key_type": (
+                    "ecdsa"
+                    if keypair.crypto_type == 2
+                    else ("sr25519" if keypair.crypto_type == 1 else "ed25519")
+                ),
+                "public_key": keypair.public_key.hex(),
+                "ss58_address": keypair.ss58_address,
+                "private_key": private_key_bytes.hex(),  # Store unencrypted
+                "is_hotkey": True,  # This is a hotkey
+                "owner_address": owner_address,  # Hotkeys have owners
+                "is_encrypted": False,
+            }
+
+        # Save to file
+        wallet_file = wallet_dir / f"{name}.json"
+        with open(wallet_file, "w") as f:
+            json.dump(wallet_data, f, indent=2)
+
+        # Set secure permissions
+        wallet_file.chmod(0o600)
+
+    except Exception as e:
+        raise Exception(f"Failed to save hotkey: {str(e)}") from e
+
+
+def save_keypair(name: str, keypair: Keypair, password: str):
+    """Save a keypair to disk with encryption (legacy function)."""
+    save_coldkey(name, keypair, password)
+
+
+def load_keypair(name: str, password: Optional[str] = None) -> Keypair:
+    """Load a keypair from disk."""
+    try:
+        wallet_dir = Path.home() / ".htcli" / "wallets"
+        keypair_file = wallet_dir / f"{name}.json"
+
+        if not keypair_file.exists():
+            raise FileNotFoundError(f"Keypair '{name}' not found")
+
+        with open(keypair_file) as f:
+            keypair_data = json.load(f)
+
+        # Check if the key is encrypted
+        is_encrypted = keypair_data.get(
+            "is_encrypted", True
+        )  # Default to True for backward compatibility
+
+        if is_encrypted:
+            # Get password for decryption (no length validation for existing wallets)
+            decrypt_password = password or get_unlock_password(
+                name,
+                prompt_message="Enter password to unlock this keypair",
+            )
+
+            # Handle new encryption format (with password hash validation)
+            if "password_hash" in keypair_data and "password_salt" in keypair_data:
+                # New format with password hash validation
+                encrypted_private_key = base64.b64decode(
+                    keypair_data["encrypted_private_key"]
+                )
+                password_hash = base64.b64decode(keypair_data["password_hash"])
+                password_salt = base64.b64decode(keypair_data["password_salt"])
+                encryption_salt = base64.b64decode(keypair_data["encryption_salt"])
+
+                private_key_bytes = decrypt_private_key(
+                    encrypted_private_key,
+                    decrypt_password,
+                    password_hash,
+                    password_salt,
+                    encryption_salt,
+                )
+            else:
+                # Legacy format (backward compatibility)
+                salt = base64.b64decode(keypair_data["salt"])
+                encrypted_private_key = base64.b64decode(
+                    keypair_data["encrypted_private_key"]
+                )
+
+                # Try to decrypt with legacy method
+                try:
+                    cipher = Fernet(salt)
+                    private_key_bytes = cipher.decrypt(encrypted_private_key)
+                except Exception as e:
+                    raise ValueError("Invalid password or corrupted wallet file") from e
+        else:
+            # Key is not encrypted, load directly
+            if "private_key" in keypair_data:
+                private_key_bytes = bytes.fromhex(keypair_data["private_key"])
+            else:
+                raise ValueError("Key file is corrupted: missing private key")
+
+        # Create keypair based on key type
+        # Match mesh-template pattern - no ss58_format for ECDSA
+        key_type = keypair_data["key_type"].lower()
+        if key_type == "sr25519":
+            keypair = Keypair.create_from_private_key(
+                private_key_bytes.hex()
+            )
+        elif key_type == "ecdsa":
+            # For ECDSA keys, use crypto_type=2 (match mesh-template)
+            keypair = Keypair.create_from_private_key(
+                private_key_bytes.hex(), crypto_type=2
+            )
+        else:  # ed25519
+            keypair = Keypair.create_from_private_key(
+                private_key_bytes.hex(), crypto_type=0
+            )
+
+        return keypair
+
+    except ValueError as e:
+        # Re-raise ValueError directly for password validation
+        raise e
+    except Exception as e:
+        raise Exception(f"Failed to load keypair: {str(e)}") from e
+
+
+def list_keys() -> list[dict]:
+    """List all available keys."""
+    try:
+        wallet_dir = Path.home() / ".htcli" / "wallets"
+        if not wallet_dir.exists():
+            return []
+
+        keys = []
+        for keypair_file in wallet_dir.glob("*.json"):
+            try:
+                with open(keypair_file) as f:
+                    keypair_data = json.load(f)
+
+                # Return as dictionary for compatibility with wallet commands
+                key_info = {
+                    "name": keypair_data["name"],
+                    "key_type": keypair_data["key_type"],
+                    "public_key": keypair_data["public_key"],
+                    "ss58_address": keypair_data["ss58_address"],
+                    "address": keypair_data[
+                        "ss58_address"
+                    ],  # Alias for ownership utils
+                    # Add hotkey/coldkey information
+                    "is_hotkey": keypair_data.get("is_hotkey", False),
+                    "owner_address": keypair_data.get("owner_address", None),
+                    # Add encryption status
+                    "is_encrypted": keypair_data.get("is_encrypted", True),
+                }
+                keys.append(key_info)
+            except Exception:
+                # Skip corrupted files
+                continue
+
+        return keys
+
+    except Exception as e:
+        raise Exception(f"Failed to list keys: {str(e)}") from e
+
+
+def get_wallet_info_by_name(name: str) -> dict:
+    """Get wallet information by name without loading the private key."""
+    try:
+        wallet_dir = Path.home() / ".htcli" / "wallets"
+        keypair_file = wallet_dir / f"{name}.json"
+
+        if not keypair_file.exists():
+            raise FileNotFoundError(f"Wallet '{name}' not found")
+
+        with open(keypair_file) as f:
+            keypair_data = json.load(f)
+
+        # Return wallet info without private key
+        wallet_info = {
+            "name": keypair_data["name"],
+            "key_type": keypair_data["key_type"],
+            "public_key": keypair_data["public_key"],
+            "ss58_address": keypair_data["ss58_address"],
+            "address": keypair_data["ss58_address"],  # Alias for compatibility
+            "is_hotkey": keypair_data.get("is_hotkey", False),
+            "owner_address": keypair_data.get("owner_address", None),
+            "is_encrypted": keypair_data.get("is_encrypted", True),
+        }
+
+        return wallet_info
+
+    except Exception as e:
+        raise Exception(f"Failed to get wallet info: {str(e)}") from e
+
+
+def wallet_name_exists(name: str) -> bool:
+    """Check if a wallet name already exists."""
+    try:
+        wallet_dir = Path.home() / ".htcli" / "wallets"
+        keypair_file = wallet_dir / f"{name}.json"
+        return keypair_file.exists()
+    except Exception:
+        return False
+
+
+def delete_keypair(name: str) -> bool:
+    """Delete a keypair from disk."""
+    try:
+        wallet_dir = Path.home() / ".htcli" / "wallets"
+        keypair_file = wallet_dir / f"{name}.json"
+
+        if keypair_file.exists():
+            keypair_file.unlink()
+            return True
+        else:
+            return False
+
+    except Exception as e:
+        raise Exception(f"Failed to delete keypair: {str(e)}") from e
+
+
+def delete_coldkey_and_hotkeys(coldkey_name: str) -> dict:
+    """Delete a coldkey and all its associated hotkeys."""
+    try:
+        # First, get the coldkey info to get its address
+        coldkey_info = get_wallet_info_by_name(coldkey_name)
+        coldkey_address = coldkey_info["ss58_address"]
+
+        # Check if it's actually a coldkey
+        if coldkey_info.get("is_hotkey", False):
+            raise Exception(f"'{coldkey_name}' is a hotkey, not a coldkey")
+
+        # Find all hotkeys owned by this coldkey
+        all_keys = list_keys()
+        associated_hotkeys = []
+
+        for key_info in all_keys:
+            if (
+                key_info.get("is_hotkey", False)
+                and key_info.get("owner_address") == coldkey_address
+            ):
+                associated_hotkeys.append(key_info["name"])
+
+        # Delete the coldkey first
+        coldkey_deleted = delete_keypair(coldkey_name)
+        if not coldkey_deleted:
+            raise Exception(f"Failed to delete coldkey '{coldkey_name}'")
+
+        # Delete all associated hotkeys
+        hotkeys_deleted = []
+        for hotkey_name in associated_hotkeys:
+            try:
+                if delete_keypair(hotkey_name):
+                    hotkeys_deleted.append(hotkey_name)
+                else:
+                    print(f"Warning: Failed to delete hotkey '{hotkey_name}'")
+            except Exception as e:
+                print(f"Warning: Error deleting hotkey '{hotkey_name}': {str(e)}")
+
+        return {
+            "coldkey_deleted": coldkey_name,
+            "coldkey_address": coldkey_address,
+            "hotkeys_deleted": hotkeys_deleted,
+            "total_hotkeys_deleted": len(hotkeys_deleted),
+        }
+
+    except Exception as e:
+        raise Exception(f"Failed to delete coldkey and hotkeys: {str(e)}") from e
+
+
+def update_coldkey(
+    current_name: str,
+    new_name: Optional[str] = None,
+    new_password: Optional[str] = None,
+    remove_password: bool = False,
+) -> dict:
+    """Update a coldkey's properties."""
+    try:
+        # Load the current keypair
+        keypair = load_keypair(current_name)
+
+        # Get current wallet info
+        wallet_info = get_wallet_info_by_name(current_name)
+
+        # Verify it's a coldkey
+        if wallet_info.get("is_hotkey", False):
+            raise Exception(f"'{current_name}' is a hotkey, not a coldkey")
+
+        # Determine new name
+        final_name = new_name if new_name else current_name
+
+        # Check if new name already exists (if changing name)
+        if new_name and new_name != current_name:
+            if wallet_name_exists(new_name):
+                raise Exception(f"Wallet name '{new_name}' already exists")
+
+        # Determine password
+        if remove_password:
+            final_password = None
+        elif new_password:
+            final_password = new_password
+        else:
+            # Keep current password (will be handled by save function)
+            final_password = None
+
+        # Save with new properties
+        save_coldkey(final_name, keypair, final_password)
+
+        # Delete old file if name changed
+        if new_name and new_name != current_name:
+            delete_keypair(current_name)
+
+        return {
+            "old_name": current_name,
+            "new_name": final_name,
+            "key_type": wallet_info["key_type"],
+            "ss58_address": wallet_info["ss58_address"],
+            "password_updated": new_password is not None or remove_password,
+            "name_updated": new_name is not None and new_name != current_name,
+        }
+
+    except Exception as e:
+        raise Exception(f"Failed to update coldkey: {str(e)}") from e
+
+
+def update_hotkey(
+    current_name: str,
+    new_name: Optional[str] = None,
+    new_password: Optional[str] = None,
+    remove_password: bool = False,
+    new_owner_name: Optional[str] = None,
+) -> dict:
+    """Update a hotkey's properties."""
+    try:
+        # Load the current keypair
+        keypair = load_keypair(current_name)
+
+        # Get current wallet info
+        wallet_info = get_wallet_info_by_name(current_name)
+
+        # Verify it's a hotkey
+        if not wallet_info.get("is_hotkey", False):
+            raise Exception(f"'{current_name}' is a coldkey, not a hotkey")
+
+        # Determine new name
+        final_name = new_name if new_name else current_name
+
+        # Check if new name already exists (if changing name)
+        if new_name and new_name != current_name:
+            if wallet_name_exists(new_name):
+                raise Exception(f"Wallet name '{new_name}' already exists")
+
+        # Determine owner address
+        owner_address = wallet_info["owner_address"]
+        if new_owner_name:
+            # Validate new owner exists and is a coldkey
+            try:
+                new_owner_info = get_wallet_info_by_name(new_owner_name)
+                if new_owner_info.get("is_hotkey", False):
+                    raise Exception(
+                        f"'{new_owner_name}' is a hotkey. Please provide a coldkey wallet name as the owner."
+                    )
+                owner_address = new_owner_info["ss58_address"]
+            except FileNotFoundError as e:
+                raise Exception(
+                    f"Owner wallet '{new_owner_name}' not found. Please provide an existing coldkey wallet name."
+                ) from e
+
+        # Determine password
+        if remove_password:
+            final_password = None
+        elif new_password:
+            final_password = new_password
+        else:
+            # Keep current password (will be handled by save function)
+            final_password = None
+
+        # Save with new properties
+        save_hotkey(final_name, keypair, owner_address, final_password)
+
+        # Delete old file if name changed
+        if new_name and new_name != current_name:
+            delete_keypair(current_name)
+
+        return {
+            "old_name": current_name,
+            "new_name": final_name,
+            "key_type": wallet_info["key_type"],
+            "ss58_address": wallet_info["ss58_address"],
+            "old_owner_address": wallet_info["owner_address"],
+            "new_owner_address": owner_address,
+            "password_updated": new_password is not None or remove_password,
+            "name_updated": new_name is not None and new_name != current_name,
+            "owner_updated": new_owner_name is not None,
+        }
+
+    except Exception as e:
+        raise Exception(f"Failed to update hotkey: {str(e)}") from e