htcli 1.1.0__py3-none-any.whl

src/htcli/utils/wallet/crypto.py

@@ -0,0 +1,1615 @@
+"""
+Cryptographic utility functions for the Hypertensor CLI.
+EVM-compatible wallet operations with Byte20 addresses.
+"""
+
+import base64
+import hmac
+import json
+import os
+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 eth_utils import keccak
+from substrateinterface import Keypair
+
+HOTKEY_FILE_SUFFIX = ".hotkey.json"
+COLDKEY_FILE_SUFFIX = ".coldkey.json"
+LEGACY_FILE_SUFFIX = ".json"
+HOTKEYS_SUBDIR = "hotkeys"
+
+
+def _wallet_layout_mode() -> str:
+    """Return configured wallet layout preference."""
+    return os.getenv("HTCLI_WALLET_LAYOUT", "hierarchical").lower()
+
+
+def _hierarchical_layout_enabled() -> bool:
+    """Whether the hierarchical wallet layout should be used for new writes."""
+    return _wallet_layout_mode() not in {"legacy", "flat", "old", "0", "false"}
+
+
+def _wallet_base_dir(wallet_dir: Optional[Path] = None) -> Path:
+    return (wallet_dir or get_wallet_directory()).expanduser()
+
+
+def _legacy_coldkey_path(name: str, wallet_dir: Optional[Path] = None) -> Path:
+    return _wallet_base_dir(wallet_dir) / f"{name}{COLDKEY_FILE_SUFFIX}"
+
+
+def _legacy_hotkey_path(
+    name: str, owner_address: Optional[str] = None, wallet_dir: Optional[Path] = None
+) -> Path:
+    base_dir = _wallet_base_dir(wallet_dir)
+    owner_fragment = ""
+    if owner_address:
+        owner_fragment = f".{owner_address.lower()[:8]}"
+    return base_dir / f"{name}{owner_fragment}{HOTKEY_FILE_SUFFIX}"
+
+
+def _coldkey_dir(name: str, wallet_dir: Optional[Path] = None) -> Path:
+    return _wallet_base_dir(wallet_dir) / name
+
+
+def _hierarchical_coldkey_path(name: str, wallet_dir: Optional[Path] = None) -> Path:
+    return _coldkey_dir(name, wallet_dir) / f"{name}{COLDKEY_FILE_SUFFIX}"
+
+
+def _hotkeys_dir(coldkey_name: str, wallet_dir: Optional[Path] = None) -> Path:
+    return _coldkey_dir(coldkey_name, wallet_dir) / HOTKEYS_SUBDIR
+
+
+def _hierarchical_hotkey_path(
+    coldkey_name: str,
+    hotkey_name: str,
+    wallet_dir: Optional[Path] = None,
+) -> Path:
+    return _hotkeys_dir(coldkey_name, wallet_dir) / f"{hotkey_name}{HOTKEY_FILE_SUFFIX}"
+
+
+def _load_hierarchical_wallet_entries(wallet_dir: Path, add_entry) -> None:
+    """Load entries stored inside the hierarchical directory layout."""
+    for coldkey_dir in sorted(wallet_dir.iterdir()):
+        if not coldkey_dir.is_dir():
+            continue
+        coldkey_name = coldkey_dir.name
+        # Try to find coldkey file - check both new format (.coldkey.json) and legacy format (.json)
+        coldkey_file = next(coldkey_dir.glob(f"*{COLDKEY_FILE_SUFFIX}"), None)
+        # If not found, check for legacy format coldkey file
+        if not coldkey_file or not coldkey_file.is_file():
+            legacy_coldkey_file = coldkey_dir / f"{coldkey_name}{LEGACY_FILE_SUFFIX}"
+            if legacy_coldkey_file.exists() and legacy_coldkey_file.is_file():
+                coldkey_file = legacy_coldkey_file
+            else:
+                # Also check root directory for legacy coldkey file
+                root_legacy_file = wallet_dir / f"{coldkey_name}{LEGACY_FILE_SUFFIX}"
+                if root_legacy_file.exists() and root_legacy_file.is_file():
+                    try:
+                        with open(root_legacy_file) as f:
+                            test_data = json.load(f)
+                        # Only use if it's actually a coldkey (not a misclassified hotkey)
+                        if not test_data.get("is_hotkey", False) and not test_data.get(
+                            "owner_address"
+                        ):
+                            coldkey_file = root_legacy_file
+                    except Exception:
+                        pass
+
+        coldkey_data = None
+        coldkey_address = None
+
+        # Load coldkey data if file exists
+        if coldkey_file and coldkey_file.is_file():
+            try:
+                with open(coldkey_file) as f:
+                    coldkey_data = json.load(f)
+                # Validate this is actually a coldkey (not a misclassified hotkey)
+                is_hotkey = coldkey_data.get("is_hotkey", False)
+                owner_address = coldkey_data.get("owner_address")
+                # Coldkeys should not have is_hotkey=True or owner_address set
+                if is_hotkey or owner_address:
+                    # This is likely a misclassified hotkey file, skip it
+                    coldkey_data = None
+                else:
+                    coldkey_data["file_path"] = str(coldkey_file)
+                    # For coldkeys, owner_coldkey_name should be None (coldkeys don't have owners)
+                    # The directory name is just for organization, not ownership
+                    coldkey_data["owner_coldkey_name"] = None
+                    coldkey_data["is_hotkey"] = False
+                    # Ensure owner_address is None for coldkeys
+                    if "owner_address" in coldkey_data:
+                        del coldkey_data["owner_address"]
+                    add_entry(coldkey_data)
+                    # Get coldkey address for matching hotkeys (use ss58_address, evm_address, or address in that order)
+                    coldkey_address = (
+                        coldkey_data.get("ss58_address")
+                        or coldkey_data.get("evm_address")
+                        or coldkey_data.get("address")
+                    )
+            except Exception:
+                coldkey_data = None
+
+        # Scan hotkeys directory even if no coldkey file was found
+        # (hotkeys can exist in hierarchical structure even if coldkey is in legacy location)
+        hotkeys_dir = coldkey_dir / HOTKEYS_SUBDIR
+        if not hotkeys_dir.exists():
+            continue
+
+        for hotkey_file in sorted(hotkeys_dir.glob(f"*{HOTKEY_FILE_SUFFIX}")):
+            if not hotkey_file.is_file():
+                continue
+            try:
+                with open(hotkey_file) as f:
+                    hotkey_data = json.load(f)
+                hotkey_data["file_path"] = str(hotkey_file)
+                hotkey_data["owner_coldkey_name"] = coldkey_name
+                hotkey_data["is_hotkey"] = True
+                # Use coldkey address from coldkey file if available, otherwise use owner_address from hotkey file
+                if coldkey_address:
+                    hotkey_data["owner_address"] = coldkey_address
+                else:
+                    # Fallback to what's in the hotkey file if coldkey file wasn't found
+                    hotkey_data.setdefault(
+                        "owner_address", hotkey_data.get("owner_address")
+                    )
+                add_entry(hotkey_data)
+            except Exception:
+                continue
+    return None
+
+
+def get_wallet_directory() -> Path:
+    """Get the wallet directory from config or use default."""
+    try:
+        from ...dependencies import get_config
+
+        config = get_config()
+        if config and config.wallet and config.wallet.path:
+            # Expand ~ and other path variables
+            wallet_path = Path(config.wallet.path).expanduser()
+            return wallet_path
+    except Exception:
+        # Fallback to default if config is not available
+        pass
+
+    # Default fallback
+    return Path.home() / ".htcli" / "wallets"
+
+
+def build_wallet_file_path(
+    name: str,
+    is_hotkey: bool,
+    wallet_dir: Optional[Path] = None,
+    owner_address: Optional[str] = None,
+    owner_coldkey_name: Optional[str] = None,
+    prefer_hierarchical: Optional[bool] = None,
+) -> Path:
+    """Return the canonical wallet file path for the given wallet name/type."""
+    use_hierarchical = (
+        prefer_hierarchical
+        if prefer_hierarchical is not None
+        else _hierarchical_layout_enabled()
+    )
+
+    if is_hotkey:
+        if use_hierarchical and owner_coldkey_name:
+            return _hierarchical_hotkey_path(
+                owner_coldkey_name, name, wallet_dir=wallet_dir
+            )
+        return _legacy_hotkey_path(name, owner_address, wallet_dir=wallet_dir)
+
+    # coldkey path
+    if use_hierarchical:
+        return _hierarchical_coldkey_path(name, wallet_dir=wallet_dir)
+    return _legacy_coldkey_path(name, wallet_dir=wallet_dir)
+
+
+def _load_wallet_entries() -> list[dict]:
+    """Load all wallet key metadata entries from disk.
+
+    Handles both new format (.hotkey.json, .coldkey.json) and legacy format (.json).
+    Prefers new format files when both exist for the same wallet.
+    """
+    wallet_dir = get_wallet_directory()
+    if not wallet_dir.exists():
+        return []
+
+    entries: list[dict] = []
+    seen_wallets: dict[
+        tuple, dict
+    ] = {}  # (name, is_hotkey, owner_address, owner_ck) -> entry
+
+    def _add_entry(entry: dict):
+        key = (
+            entry.get("name"),
+            entry.get("is_hotkey", False),
+            entry.get("owner_address"),
+            entry.get("owner_coldkey_name"),
+        )
+        if key not in seen_wallets:
+            seen_wallets[key] = entry
+            entries.append(entry)
+
+    # Load hierarchical layout first so it takes precedence.
+    _load_hierarchical_wallet_entries(wallet_dir, _add_entry)
+
+    # First pass: load all files
+    all_files = sorted(wallet_dir.glob("*.json"))
+
+    # Separate new format and legacy format files
+    new_format_files = []
+    legacy_files = []
+
+    for keypair_file in all_files:
+        filename = keypair_file.name
+        if filename.endswith(HOTKEY_FILE_SUFFIX) or filename.endswith(
+            COLDKEY_FILE_SUFFIX
+        ):
+            new_format_files.append(keypair_file)
+        else:
+            legacy_files.append(keypair_file)
+
+    # Load new format files first (they take precedence)
+    for keypair_file in new_format_files:
+        try:
+            with open(keypair_file) as f:
+                keypair_data = json.load(f)
+
+            # Validate coldkey files don't have owner_address (coldkeys don't have owners)
+            is_hotkey = keypair_data.get("is_hotkey", False)
+            owner_address = keypair_data.get("owner_address")
+            if not is_hotkey and owner_address:
+                # This is a misclassified coldkey file, skip it
+                continue
+
+            keypair_data["file_path"] = str(keypair_file)
+
+            # Create unique key for deduplication
+            name = keypair_data.get("name", "")
+            key = (name, is_hotkey, owner_address)
+
+            # Only add if we haven't seen this wallet yet
+            if key + (None,) not in seen_wallets:
+                keypair_data.setdefault("owner_coldkey_name", None)
+                _add_entry(keypair_data)
+        except Exception:
+            continue
+
+    # Load legacy files, but skip if we already have a new format version
+    for keypair_file in legacy_files:
+        try:
+            with open(keypair_file) as f:
+                keypair_data = json.load(f)
+
+            name = keypair_data.get("name", "")
+            is_hotkey = keypair_data.get("is_hotkey", False)
+            owner_address = keypair_data.get("owner_address")
+
+            # Validate coldkey files don't have owner_address (coldkeys don't have owners)
+            if not is_hotkey and owner_address:
+                # This is a misclassified coldkey file, skip it
+                continue
+
+            key = (name, is_hotkey, owner_address)
+
+            # Skip if we already have this wallet in new format
+            if key + (None,) in seen_wallets:
+                continue
+
+            keypair_data["file_path"] = str(keypair_file)
+            keypair_data.setdefault("owner_coldkey_name", None)
+            _add_entry(keypair_data)
+        except Exception:
+            continue
+
+    return entries
+
+
+def _find_wallet_entries(
+    name: str,
+    is_hotkey: Optional[bool] = None,
+    owner_address: Optional[str] = None,
+    owner_coldkey_name: Optional[str] = None,
+) -> list[dict]:
+    """Find wallet metadata entries that match the provided criteria."""
+
+    def normalize_address(addr):
+        """Normalize address for comparison (lowercase, remove 0x prefix differences)."""
+        if not addr:
+            return None
+        addr_str = str(addr).strip()
+        # Remove 0x prefix if present, then normalize
+        if addr_str.startswith("0x") or addr_str.startswith("0X"):
+            addr_str = addr_str[2:]
+        # Lowercase and ensure consistent format
+        addr_str = addr_str.lower()
+        # Add 0x prefix back for consistency (if it's a hex address)
+        if len(addr_str) == 40 and all(c in "0123456789abcdef" for c in addr_str):
+            return f"0x{addr_str}"
+        # Return as-is if not a standard hex address
+        return addr_str
+
+    matches = []
+    normalized_owner_address = (
+        normalize_address(owner_address) if owner_address else None
+    )
+
+    for entry in _load_wallet_entries():
+        if entry.get("name") != name:
+            continue
+        if is_hotkey is not None and entry.get("is_hotkey", False) != is_hotkey:
+            continue
+
+        # If disambiguation parameters are provided, entry must match
+        # If owner_coldkey_name is provided, ONLY match on name (strict name-based disambiguation)
+        # If only owner_address is provided, match on address
+        # If both provided, use OR logic: match if EITHER name OR address matches
+        if normalized_owner_address or owner_coldkey_name:
+            matched = False
+
+            # If owner_coldkey_name is provided, check name match first
+            if owner_coldkey_name:
+                entry_owner_name = entry.get("owner_coldkey_name")
+                # Check if name matches (handle None/empty cases)
+                if entry_owner_name:
+                    entry_owner_name_clean = str(entry_owner_name).strip()
+                    owner_coldkey_name_clean = str(owner_coldkey_name).strip()
+                    if entry_owner_name_clean == owner_coldkey_name_clean:
+                        matched = True
+
+            # Check address if matched is not yet True
+            # This handles two cases:
+            # 1. owner_coldkey_name was NOT provided (so we must check address)
+            # 2. owner_coldkey_name WAS provided but didn't match (e.g. entry has None/stale name)
+            #    In this case, we trust the address if it matches, as address is the source of truth
+            if normalized_owner_address and not matched:
+                entry_owner_addr_raw = entry.get("owner_address")
+                if entry_owner_addr_raw:
+                    entry_owner_addr = normalize_address(entry_owner_addr_raw)
+                    # Only compare the owner_address field, not the hotkey's own addresses
+                    if (
+                        entry_owner_addr
+                        and entry_owner_addr == normalized_owner_address
+                    ):
+                        matched = True
+
+            # If we have disambiguation params but no match, skip this entry
+            if not matched:
+                continue
+
+        matches.append(entry)
+    return matches
+
+
+def resolve_wallet_file_path(
+    name: str,
+    is_hotkey: Optional[bool] = None,
+    owner_address: Optional[str] = None,
+    owner_coldkey_name: Optional[str] = None,
+) -> Path:
+    """Resolve the on-disk file path for a wallet.
+
+    Args:
+        name: Wallet name
+        is_hotkey: Specify True for hotkey, False for coldkey to disambiguate
+        owner_address: For hotkeys, specify the coldkey owner address to disambiguate
+
+    Raises:
+        ValueError: If wallet name is ambiguous and disambiguation parameters are missing
+    """
+    matches = _find_wallet_entries(
+        name,
+        is_hotkey=is_hotkey,
+        owner_address=owner_address,
+        owner_coldkey_name=owner_coldkey_name,
+    )
+    if not matches:
+        raise FileNotFoundError(f"Wallet '{name}' not found")
+    if len(matches) > 1:
+        # Provide helpful error message with suggestions
+        hotkey_matches = [m for m in matches if m.get("is_hotkey", False)]
+        coldkey_matches = [m for m in matches if not m.get("is_hotkey", False)]
+
+        error_msg = f"Wallet '{name}' is ambiguous. Found {len(matches)} wallet(s) with this name:\n"
+        if coldkey_matches:
+            error_msg += f"  - {len(coldkey_matches)} coldkey wallet(s)\n"
+        if hotkey_matches:
+            error_msg += f"  - {len(hotkey_matches)} hotkey wallet(s)\n"
+        error_msg += "\nTo resolve this, specify:\n"
+        error_msg += "  - is_hotkey=True for hotkey, is_hotkey=False for coldkey\n"
+        if hotkey_matches:
+            error_msg += "  - owner_address=<coldkey_address> or owner_coldkey_name=<coldkey_name> for hotkeys\n"
+        raise ValueError(error_msg)
+    file_path = matches[0].get("file_path")
+    if not file_path:
+        raise FileNotFoundError(f"Could not resolve file path for wallet '{name}'")
+    return Path(file_path)
+
+
+def public_key_to_evm_address(public_key: bytes) -> str:
+    """Convert a public key to EVM address (Byte20 format)."""
+    hash_bytes = keccak(public_key)
+    address_bytes = hash_bytes[-20:]
+    return "0x" + address_bytes.hex()
+
+
+def get_network_appropriate_key_type() -> str:
+    """For Hypertensor EVM chain, always return ECDSA."""
+    return "ecdsa"
+
+
+def validate_key_type_for_network(key_type: str) -> tuple[bool, str]:
+    """For Hypertensor EVM chain, only ECDSA is supported."""
+    if key_type != "ecdsa":
+        return (
+            False,
+            f"Hypertensor chain requires ECDSA keys for EVM compatibility. You specified '{key_type}'.",
+        )
+    return True, ""
+
+
+def detect_address_type(address: str) -> tuple[str, str, bool]:
+    """Detect the type and format of an address."""
+    if not address:
+        return "unknown", "Invalid", False
+    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,
+            )
+    elif len(address) > 40 and address[0].isdigit():
+        return "legacy_ss58", "Legacy SS58/Substrate (unsupported)", False
+    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, truncate: bool = True
+) -> str:
+    """Format address display in MetaMask style (0x + first 5 + last 5 characters)."""
+    if not address or address == "N/A":
+        return "N/A"
+
+    from ..blockchain.formatting import to_checksum_address
+    # Apply EIP-55 checksum first
+    checksummed = to_checksum_address(address) or address
+
+    # MetaMask style: 0x + first 5 characters + ... + last 5 characters
+    if truncate and len(checksummed) > 10:
+        # Remove 0x prefix if present for calculation
+        clean_address = checksummed[2:] if checksummed.startswith("0x") else checksummed
+
+        if len(clean_address) > 10:
+            display_address = f"0x{clean_address[:5]}...{clean_address[-5:]}"
+        else:
+            display_address = checksummed
+    else:
+        display_address = checksummed
+
+    return display_address
+
+
+def generate_password_hash(password: str, salt: bytes) -> bytes:
+    """Generate a secure password hash using PBKDF2."""
+    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."""
+    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."""
+    password_salt = secrets.token_bytes(16)
+    password_hash = generate_password_hash(password, password_salt)
+    encryption_salt = secrets.token_bytes(16)
+    encryption_key = generate_password_hash(password, encryption_salt)
+    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."""
+    if not verify_password(password, password_hash, password_salt):
+        raise ValueError("Invalid password")
+    encryption_key = generate_password_hash(password, encryption_salt)
+    cipher = Fernet(base64.urlsafe_b64encode(encryption_key))
+    return cipher.decrypt(encrypted_key)
+
+
+@dataclass
+class KeypairInfo:
+    """Information about a keypair."""
+
+    name: str
+    key_type: str
+    public_key: str
+    ss58_address: str
+    evm_address: str
+    mnemonic: Optional[str] = None
+    owner_address: Optional[str] = None
+    owner_coldkey_name: Optional[str] = None
+
+    def __post_init__(self):
+        if not self.ss58_address.startswith("0x"):
+            self.ss58_address = self.evm_address
+
+
+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}")
+
+        # For ECDSA keys, keypair.ss58_address already contains the correct EVM address
+        if key_type == "ecdsa":
+            evm_address = keypair.ss58_address
+            ss58_address = evm_address
+        else:
+            # For other key types, use the keypair's ss58_address
+            ss58_address = keypair.ss58_address
+            evm_address = ss58_address
+
+        # Create keypair info
+        keypair_info = KeypairInfo(
+            name=name,
+            key_type=key_type,
+            public_key=keypair.public_key.hex(),
+            ss58_address=ss58_address,
+            evm_address=evm_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,
+    owner_coldkey_name: 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}")
+
+        # For ECDSA keys, compute EVM address from public key (same as save_hotkey does)
+        if key_type == "ecdsa":
+            evm_address = public_key_to_evm_address(keypair.public_key)
+            ss58_address = evm_address
+        else:
+            # For other key types, use the keypair's ss58_address
+            ss58_address = keypair.ss58_address
+            evm_address = ss58_address
+
+        # Create keypair info
+        keypair_info = KeypairInfo(
+            name=name,
+            key_type=key_type,
+            public_key=keypair.public_key.hex(),
+            ss58_address=ss58_address,
+            evm_address=evm_address,
+            mnemonic=mnemonic,  # Include the recovery phrase
+            owner_address=owner_address,  # Hotkeys have owners
+            owner_coldkey_name=owner_coldkey_name,
+        )
+
+        # Use the password directly from the CLI function
+        # The CLI function already handles the password prompting
+        save_hotkey(
+            name,
+            keypair,
+            owner_address,
+            password,
+            owner_coldkey_name=owner_coldkey_name,
+        )
+
+        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."""
+    if key_type != "ecdsa":
+        raise ValueError("Hypertensor chain requires ECDSA keys for EVM compatibility")
+    if private_key.startswith("0x"):
+        private_key = private_key[2:]
+    if len(private_key) != 64:
+        raise ValueError("ECDSA private key must be 64 characters (32 bytes)")
+    keypair = Keypair.create_from_private_key(private_key, crypto_type=2)
+    # For ECDSA keys, keypair.ss58_address already contains the correct EVM address
+    evm_address = keypair.ss58_address
+    keypair_info = KeypairInfo(
+        name=name,
+        key_type="ecdsa",
+        public_key=keypair.public_key.hex(),
+        ss58_address=evm_address,
+        evm_address=evm_address,
+    )
+    save_coldkey(name, keypair, password)
+    return keypair_info
+
+
+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."""
+    if key_type != "ecdsa":
+        raise ValueError("Hypertensor chain requires ECDSA keys for EVM compatibility")
+    keypair = Keypair.create_from_mnemonic(mnemonic, crypto_type=2)
+    # For ECDSA keys, keypair.ss58_address already contains the correct EVM address
+    evm_address = keypair.ss58_address
+    keypair_info = KeypairInfo(
+        name=name,
+        key_type="ecdsa",
+        public_key=keypair.public_key.hex(),
+        ss58_address=evm_address,
+        evm_address=evm_address,
+    )
+    save_coldkey(name, keypair, password)
+    return keypair_info
+
+
+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."""
+    if key_type != "ecdsa":
+        raise ValueError("Hypertensor chain requires ECDSA keys for EVM compatibility")
+    keypair = Keypair.create_from_private_key(private_key, crypto_type=2)
+    # For ECDSA keys, compute EVM address from public key
+    evm_address = public_key_to_evm_address(keypair.public_key)
+    keypair_info = KeypairInfo(
+        name=name,
+        key_type="ecdsa",
+        public_key=keypair.public_key.hex(),
+        ss58_address=evm_address,
+        evm_address=evm_address,
+        owner_address=owner_address,
+        owner_coldkey_name=get_coldkey_name_for_address(owner_address),
+    )
+    save_hotkey(name, keypair, owner_address, password)
+    return keypair_info
+
+
+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."""
+    if key_type != "ecdsa":
+        raise ValueError("Hypertensor chain requires ECDSA keys for EVM compatibility")
+    keypair = Keypair.create_from_mnemonic(mnemonic, crypto_type=2)
+    evm_address = public_key_to_evm_address(keypair.public_key)
+    keypair_info = KeypairInfo(
+        name=name,
+        key_type="ecdsa",
+        public_key=keypair.public_key.hex(),
+        ss58_address=evm_address,
+        evm_address=evm_address,
+        owner_address=owner_address,
+        owner_coldkey_name=get_coldkey_name_for_address(owner_address),
+    )
+    save_hotkey(name, keypair, owner_address, password)
+    return keypair_info
+
+
+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",
+        },
+        "baltathar": {
+            "name": "Baltathar",
+            "private_key": PRESEEDED_WALLETS["baltathar"],
+            "address": "0x3Cd0A705a2DC65e5b1E1205896BaA2be8A07c6e0",
+            "description": "Second development account",
+        },
+    }
+
+
+def import_preseeded_wallet(
+    preseeded_name: str,
+    wallet_name: Optional[str] = None,
+    password: Optional[str] = None,
+) -> KeypairInfo:
+    """Import a preseeded development wallet."""
+    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]
+    wallet_name = wallet_name or preseeded_name
+    return import_keypair(
+        name=wallet_name, private_key=private_key, key_type="ecdsa", password=password
+    )
+
+
+def save_coldkey(name: str, keypair: Keypair, password: Optional[str]):
+    """Save a coldkey to disk with encryption and EVM address."""
+    wallet_dir = get_wallet_directory()
+    wallet_dir.mkdir(parents=True, exist_ok=True)
+    evm_address = keypair.ss58_address
+    wallet_data = {
+        "name": name,
+        "key_type": "ecdsa",
+        "public_key": keypair.public_key.hex(),
+        "ss58_address": evm_address,
+        "evm_address": evm_address,
+        "is_hotkey": False,
+        "owner_address": None,
+        "is_encrypted": password is not None,
+        "owner_coldkey_name": name,
+    }
+    if password:
+        encrypted_key, password_hash, password_salt, encryption_salt = (
+            encrypt_private_key(keypair.private_key, password)
+        )
+        wallet_data.update(
+            {
+                "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(),
+            }
+        )
+    else:
+        wallet_data["private_key"] = keypair.private_key.hex()
+
+    target_file = build_wallet_file_path(
+        name,
+        is_hotkey=False,
+        wallet_dir=wallet_dir,
+        prefer_hierarchical=True,
+    )
+    legacy_file = _legacy_coldkey_path(name, wallet_dir=wallet_dir)
+    if target_file.exists() or legacy_file.exists():
+        raise ValueError(
+            f"Wallet '{name}' already exists. Please choose another name or delete the existing coldkey."
+        )
+    target_file.parent.mkdir(parents=True, exist_ok=True)
+    with open(target_file, "w") as f:
+        json.dump(wallet_data, f, indent=2)
+    target_file.chmod(0o600)
+
+
+def save_hotkey(
+    name: str,
+    keypair: Keypair,
+    owner_address: str,
+    password: Optional[str],
+    owner_coldkey_name: Optional[str] = None,
+):
+    """Save a hotkey to disk with encryption and EVM address."""
+    wallet_dir = get_wallet_directory()
+    wallet_dir.mkdir(parents=True, exist_ok=True)
+    # For ECDSA keys, compute EVM address from public key
+    if keypair.crypto_type == 2:  # ECDSA
+        evm_address = public_key_to_evm_address(keypair.public_key)
+    else:
+        # For other key types, use ss58_address
+        evm_address = keypair.ss58_address
+    resolved_coldkey_name = owner_coldkey_name or get_coldkey_name_for_address(
+        owner_address
+    )
+    wallet_data = {
+        "name": name,
+        "key_type": "ecdsa",
+        "public_key": keypair.public_key.hex(),
+        "ss58_address": evm_address,
+        "evm_address": evm_address,
+        "is_hotkey": True,
+        "owner_address": owner_address,
+        "is_encrypted": password is not None,
+        "owner_coldkey_name": resolved_coldkey_name,
+    }
+    if password:
+        encrypted_key, password_hash, password_salt, encryption_salt = (
+            encrypt_private_key(keypair.private_key, password)
+        )
+        wallet_data.update(
+            {
+                "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(),
+            }
+        )
+    else:
+        wallet_data["private_key"] = keypair.private_key.hex()
+
+    prefer_hierarchical = bool(resolved_coldkey_name) and _hierarchical_layout_enabled()
+    wallet_file = build_wallet_file_path(
+        name,
+        is_hotkey=True,
+        owner_address=owner_address,
+        owner_coldkey_name=resolved_coldkey_name,
+        prefer_hierarchical=prefer_hierarchical,
+    )
+    legacy_file = _legacy_hotkey_path(name, owner_address, wallet_dir=wallet_dir)
+    if wallet_file.exists() or legacy_file.exists():
+        raise ValueError(
+            f"Hotkey '{name}' already exists for this coldkey. Choose another name."
+        )
+
+    wallet_file.parent.mkdir(parents=True, exist_ok=True)
+    with open(wallet_file, "w") as f:
+        json.dump(wallet_data, f, indent=2)
+    wallet_file.chmod(0o600)
+
+
+def load_keypair(
+    name: str,
+    password: Optional[str] = None,
+    file_path: Optional[Path] = None,
+    is_hotkey: Optional[bool] = None,
+    owner_address: Optional[str] = None,
+) -> Keypair:
+    """Load a keypair from disk.
+
+    Args:
+        name: Wallet name
+        password: Optional password for encrypted wallets
+        file_path: Optional direct file path (bypasses name resolution)
+        is_hotkey: Optional hint to disambiguate when name resolution is needed
+        owner_address: Optional owner address for hotkey disambiguation
+    """
+    if file_path:
+        keypair_file = Path(file_path)
+    else:
+        keypair_file = resolve_wallet_file_path(
+            name, is_hotkey=is_hotkey, owner_address=owner_address
+        )
+    with open(keypair_file) as f:
+        keypair_data = json.load(f)
+    is_encrypted = keypair_data.get("is_encrypted", True)
+    if is_encrypted:
+        from ...errors.base import InvalidPasswordError
+        from .auth import get_unlock_password
+
+        decrypt_password = password or get_unlock_password(
+            name, "Enter password to unlock this keypair"
+        )
+        if "password_hash" in keypair_data and "password_salt" in keypair_data:
+            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"])
+            try:
+                private_key_bytes = decrypt_private_key(
+                    encrypted_private_key,
+                    decrypt_password,
+                    password_hash,
+                    password_salt,
+                    encryption_salt,
+                )
+            except ValueError as e:
+                raise InvalidPasswordError("Invalid password") from e
+        else:
+            salt = base64.b64decode(keypair_data["salt"])
+            encrypted_private_key = base64.b64decode(
+                keypair_data["encrypted_private_key"]
+            )
+            try:
+                cipher = Fernet(salt)
+                private_key_bytes = cipher.decrypt(encrypted_private_key)
+            except Exception as e:
+                raise InvalidPasswordError(
+                    "Invalid password or corrupted wallet file"
+                ) from e
+    else:
+        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")
+    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":
+        # Match mesh-template pattern - no ss58_format specified for ECDSA
+        keypair = Keypair.create_from_private_key(
+            private_key_bytes.hex(), crypto_type=2
+        )
+    else:
+        keypair = Keypair.create_from_private_key(
+            private_key_bytes.hex(), crypto_type=0
+        )
+    return keypair
+
+
+def list_keys() -> list[dict]:
+    """List all available keys."""
+    entries = _load_wallet_entries()
+    keys: list[dict] = []
+    for entry in entries:
+        public_key_hex = entry.get("public_key")
+        evm_address = entry.get("evm_address")
+        if not evm_address and public_key_hex:
+            try:
+                evm_address = public_key_to_evm_address(bytes.fromhex(public_key_hex))
+            except Exception:
+                evm_address = None
+
+        ss58_address = entry.get("ss58_address")
+        preferred_address = evm_address or ss58_address
+
+        key_info = {
+            "name": entry.get("name"),
+            "key_type": entry.get("key_type"),
+            "public_key": public_key_hex,
+            "ss58_address": ss58_address,
+            "evm_address": evm_address,
+            "address": preferred_address,
+            "is_hotkey": entry.get("is_hotkey", False),
+            "owner_address": entry.get("owner_address"),
+            "is_encrypted": entry.get("is_encrypted", True),
+            "file_path": entry.get("file_path"),
+            "owner_coldkey_name": entry.get("owner_coldkey_name"),
+        }
+        keys.append(key_info)
+    return keys
+
+
+def get_wallet_info_by_name(
+    name: str,
+    is_hotkey: Optional[bool] = None,
+    owner_address: Optional[str] = None,
+    owner_coldkey_name: Optional[str] = None,
+) -> dict:
+    """Get wallet information by name without loading the private key.
+
+    Args:
+        name: Wallet display name
+        is_hotkey: Optional filter to require hotkey/coldkey
+        owner_address: Optional coldkey address for hotkey disambiguation
+        owner_coldkey_name: Optional coldkey name for hotkey disambiguation
+    """
+    matches = _find_wallet_entries(
+        name,
+        is_hotkey=is_hotkey,
+        owner_address=owner_address,
+        owner_coldkey_name=owner_coldkey_name,
+    )
+    if not matches:
+        raise FileNotFoundError(f"Wallet '{name}' not found")
+    if len(matches) > 1:
+        if is_hotkey is None:
+            # Prefer coldkey if ambiguous, but warn user
+            preferred = next(
+                (entry for entry in matches if not entry.get("is_hotkey", False)),
+                matches[0],
+            )
+            matches = [preferred]
+        else:
+            # is_hotkey specified but still ambiguous - need owner_address for hotkeys
+            hotkey_matches = [
+                m for m in matches if m.get("is_hotkey", False) == is_hotkey
+            ]
+            if len(hotkey_matches) > 1 and is_hotkey:
+                # FIX: Raise custom exception with matches for better handling
+                from ...errors.base import AmbiguousWalletError
+                raise AmbiguousWalletError(name, hotkey_matches, is_hotkey=True)
+            elif len(hotkey_matches) > 0:
+                matches = hotkey_matches
+            else:
+                # Wrong type specified
+                raise ValueError(
+                    f"Wallet '{name}' found but doesn't match specified type "
+                    f"(is_hotkey={is_hotkey}). Found: {[m.get('is_hotkey') for m in matches]}"
+                )
+    keypair_data = matches[0]
+
+    public_key_hex = keypair_data.get("public_key")
+    evm_address = keypair_data.get("evm_address")
+    if not evm_address and public_key_hex:
+        try:
+            evm_address = public_key_to_evm_address(bytes.fromhex(public_key_hex))
+        except Exception:
+            evm_address = None
+
+    ss58_address = keypair_data.get("ss58_address")
+    preferred_address = evm_address or ss58_address
+
+    wallet_info = {
+        "name": keypair_data.get("name"),
+        "key_type": keypair_data.get("key_type"),
+        "public_key": public_key_hex,
+        "ss58_address": ss58_address,
+        "evm_address": evm_address,
+        "address": preferred_address,
+        "is_hotkey": keypair_data.get("is_hotkey", False),
+        "owner_address": keypair_data.get("owner_address"),
+        "owner_coldkey_name": keypair_data.get("owner_coldkey_name"),
+        "is_encrypted": keypair_data.get("is_encrypted", True),
+        "file_path": keypair_data.get("file_path"),
+    }
+    return wallet_info
+
+
+def wallet_name_exists(name: str) -> bool:
+    """Check if a wallet name already exists."""
+    return bool(_find_wallet_entries(name))
+
+
+def get_coldkey_name_for_address(address: str) -> Optional[str]:
+    """Resolve the coldkey name that owns a given address."""
+    if not address:
+        return None
+    for entry in _load_wallet_entries():
+        if entry.get("is_hotkey", False):
+            continue
+        if entry.get("ss58_address") == address or entry.get("evm_address") == address:
+            return entry.get("name")
+    return None
+
+
+def coldkey_has_hotkey(coldkey_address: str, hotkey_name: str) -> bool:
+    """Check if a specific coldkey already has a hotkey with the given name.
+
+    Args:
+        coldkey_address: The SS58 or EVM address of the coldkey
+        hotkey_name: The name of the hotkey to check
+
+    Returns:
+        True if the coldkey already has a hotkey with this name, False otherwise
+    """
+    all_keys = list_keys()
+    for key in all_keys:
+        if (
+            key.get("is_hotkey", False)
+            and key.get("name") == hotkey_name
+            and key.get("owner_address") == coldkey_address
+        ):
+            return True
+    return False
+
+
+def delete_keypair(
+    name: str,
+    is_hotkey: Optional[bool] = None,
+    owner_address: Optional[str] = None,
+    owner_coldkey_name: Optional[str] = None,
+) -> bool:
+    """Delete a keypair from disk.
+
+    This function deletes ALL matching files (both legacy and hierarchical formats)
+    to ensure complete deletion.
+
+    Args:
+        name: Wallet name to delete
+        is_hotkey: Optional hint to specify if this is a hotkey (True) or coldkey (False)
+        owner_address: Optional coldkey address for hotkey disambiguation
+    """
+    # Find ALL matching files (may exist in both legacy and hierarchical locations)
+    try:
+        matches = _find_wallet_entries(
+            name,
+            is_hotkey=is_hotkey,
+            owner_address=owner_address,
+            owner_coldkey_name=owner_coldkey_name,
+        )
+    except Exception:
+        return False
+
+    if not matches:
+        return False
+
+    deleted_any = False
+    deleted_paths = []
+
+    # Delete all matching files
+    for match in matches:
+        file_path = match.get("file_path")
+        if not file_path:
+            continue
+        try:
+            keypair_file = Path(file_path)
+            if keypair_file.exists():
+                keypair_file.unlink()
+                deleted_any = True
+                deleted_paths.append(keypair_file)
+        except Exception:
+            continue
+
+    # Clean up empty directories for hierarchical layout
+    for deleted_path in deleted_paths:
+        try:
+            parent_dir = deleted_path.parent
+            if parent_dir.name == HOTKEYS_SUBDIR and not any(parent_dir.iterdir()):
+                parent_dir.rmdir()
+                coldkey_dir = parent_dir.parent
+                if not any(coldkey_dir.iterdir()):
+                    coldkey_dir.rmdir()
+        except Exception:
+            pass
+
+    return deleted_any
+
+
+def delete_coldkey_and_hotkeys(coldkey_name: str) -> dict:
+    """Delete a coldkey and all its associated hotkeys.
+
+    Finds hotkeys by both owner_address (in all formats) and owner_coldkey_name to ensure
+    all associated hotkeys are found and deleted, even if metadata is inconsistent.
+    """
+    coldkey_info = get_wallet_info_by_name(coldkey_name, is_hotkey=False)
+    if coldkey_info.get("is_hotkey", False):
+        raise Exception(f"'{coldkey_name}' is a hotkey, not a coldkey")
+
+    # Get all possible address formats from coldkey info
+    coldkey_addresses = set()
+    if coldkey_info.get("address"):
+        coldkey_addresses.add(coldkey_info["address"])
+    if coldkey_info.get("ss58_address"):
+        coldkey_addresses.add(coldkey_info["ss58_address"])
+    if coldkey_info.get("evm_address"):
+        coldkey_addresses.add(coldkey_info["evm_address"])
+
+    all_keys = list_keys()
+    # Find hotkeys by matching any address format OR owner_coldkey_name
+    associated_hotkeys = []
+    for k in all_keys:
+        if not k.get("is_hotkey", False):
+            continue
+
+        # Check if owner_address matches any of the coldkey's address formats
+        owner_address = k.get("owner_address")
+        owner_matches = owner_address and owner_address in coldkey_addresses
+
+        # Check if owner_coldkey_name matches
+        owner_name_matches = k.get("owner_coldkey_name") == coldkey_name
+
+        if owner_matches or owner_name_matches:
+            associated_hotkeys.append(k)
+
+    if not delete_keypair(coldkey_name, is_hotkey=False):
+        raise Exception(f"Failed to delete coldkey '{coldkey_name}'")
+
+    # Delete hotkeys - delete_keypair will now delete ALL matching files (legacy + hierarchical)
+    hotkeys_deleted = []
+    for hotkey in associated_hotkeys:
+        hotkey_name = hotkey["name"]
+        # Try multiple deletion strategies to ensure we catch all files
+        deleted = False
+
+        # Strategy 1: Delete with owner_address
+        if hotkey.get("owner_address"):
+            deleted = delete_keypair(
+                hotkey_name,
+                is_hotkey=True,
+                owner_address=hotkey.get("owner_address"),
+            )
+
+        # Strategy 2: Delete with owner_coldkey_name (if not already deleted)
+        if not deleted and (hotkey.get("owner_coldkey_name") or coldkey_name):
+            deleted = delete_keypair(
+                hotkey_name,
+                is_hotkey=True,
+                owner_coldkey_name=hotkey.get("owner_coldkey_name") or coldkey_name,
+            )
+
+        # Strategy 3: Try deleting without owner context (as fallback)
+        if not deleted:
+            deleted = delete_keypair(
+                hotkey_name,
+                is_hotkey=True,
+            )
+
+        if deleted:
+            hotkeys_deleted.append(hotkey_name)
+
+    return {
+        "coldkey_deleted": coldkey_name,
+        "hotkeys_deleted": hotkeys_deleted,
+        "total_hotkeys_deleted": len(hotkeys_deleted),
+    }
+
+
+def update_coldkey(
+    current_name: str,
+    new_name: Optional[str] = None,
+    new_password: Optional[str] = None,
+    remove_password: bool = False,
+    current_password: Optional[str] = None,
+) -> dict:
+    """Update a coldkey's properties.
+
+    Flow:
+    - If keeping password and only changing name: copy encrypted file directly (no password needed)
+    - If keeping password and no changes: do nothing
+    - If changing password: decrypt with current_password, encrypt with new_password
+    - If removing password: decrypt with current_password, save unencrypted
+    - If adding password: load unencrypted, encrypt with new_password
+    """
+    import json
+    from pathlib import Path
+
+    wallet_info = get_wallet_info_by_name(current_name, is_hotkey=False)
+    if wallet_info.get("is_hotkey", False):
+        raise Exception(f"'{current_name}' is a hotkey, not a coldkey")
+
+    is_encrypted = wallet_info.get("is_encrypted", False)
+    final_name = new_name or current_name
+    name_changed = bool(new_name and new_name != current_name)
+
+    # Check if new name already exists (only check for coldkeys, not hotkeys)
+    if name_changed:
+        try:
+            get_wallet_info_by_name(final_name, is_hotkey=False)
+            # If we found a coldkey with this name, it's a conflict
+            raise Exception(f"Wallet name '{final_name}' already exists")
+        except FileNotFoundError:
+            # Good - no coldkey with this name exists
+            pass
+
+    # Special case: only changing name (no password changes) - just copy the file
+    if new_password is None and not remove_password and name_changed:
+        wallet_file = Path.home() / ".htcli" / "wallets" / f"{current_name}.json"
+        new_wallet_file = Path.home() / ".htcli" / "wallets" / f"{final_name}.json"
+        if wallet_file.exists():
+            with open(wallet_file) as f:
+                wallet_data = json.load(f)
+            # Update the name in the file if it's stored there
+            if "name" in wallet_data:
+                wallet_data["name"] = final_name
+            with open(new_wallet_file, "w") as f:
+                json.dump(wallet_data, f, indent=2)
+            new_wallet_file.chmod(0o600)
+            wallet_file.unlink()
+            # Use the original wallet_info since we just copied the file (same address)
+            return {
+                "old_name": current_name,
+                "new_name": final_name,
+                "key_type": wallet_info["key_type"],
+                "ss58_address": wallet_info["evm_address"],
+                "password_updated": False,
+                "name_updated": True,
+            }
+
+    # If nothing to change, return early
+    if not name_changed and new_password is None and not remove_password:
+        return {
+            "old_name": current_name,
+            "new_name": final_name,
+            "key_type": wallet_info["key_type"],
+            "ss58_address": wallet_info["evm_address"],
+            "password_updated": False,
+            "name_updated": False,
+        }
+
+    # Need to load keypair - handle different cases:
+    # 1. Encrypted wallet + changing/removing password: need current password
+    # 2. Encrypted wallet + keeping password + changing name: can copy file (handled above)
+    # 3. Unencrypted wallet + adding password: load directly without password prompt
+    # 4. Unencrypted wallet + keeping unencrypted + changing name: can copy file (handled above)
+    need_password = is_encrypted and (new_password is not None or remove_password)
+    if need_password:
+        # Wallet is encrypted and we're changing/removing password - need current password
+        keypair = load_keypair(current_name, password=current_password, is_hotkey=False)
+    elif not is_encrypted:
+        # Wallet is NOT encrypted - load directly from file to avoid any password prompts
+        # This handles the case where we're adding a password to an unencrypted wallet
+        wallet_file = resolve_wallet_file_path(current_name, is_hotkey=False)
+        with open(wallet_file) as f:
+            keypair_data = json.load(f)
+        # Verify it's actually not encrypted
+        if keypair_data.get("is_encrypted", False):
+            # File says it's encrypted but wallet_info says it's not - use load_keypair
+            keypair = load_keypair(current_name, password=current_password)
+        else:
+            # Load private key directly without any password prompts
+            private_key_hex = keypair_data.get("private_key")
+            if not private_key_hex:
+                raise ValueError("Key file is corrupted: missing private key")
+            private_key_bytes = bytes.fromhex(private_key_hex)
+            key_type = keypair_data.get("key_type", "ecdsa").lower()
+            if key_type == "sr25519":
+                keypair = Keypair.create_from_private_key(private_key_bytes.hex())
+            elif key_type == "ecdsa":
+                keypair = Keypair.create_from_private_key(
+                    private_key_bytes.hex(), crypto_type=2
+                )
+            else:
+                keypair = Keypair.create_from_private_key(
+                    private_key_bytes.hex(), crypto_type=0
+                )
+    else:
+        # Encrypted wallet but keeping password and changing name - should have been handled above
+        # This shouldn't happen, but fall back to load_keypair
+        keypair = load_keypair(current_name, password=current_password, is_hotkey=False)
+
+    # Determine final password for saving
+    if remove_password:
+        final_password = None
+    elif new_password is not None:
+        final_password = new_password
+    else:
+        # Keeping password - but we can't preserve it through save_coldkey
+        # So if we're here and keeping password, we should have handled it above
+        # This means we're keeping password but changing name, which was handled
+        # Or we're adding password to unencrypted wallet
+        final_password = (
+            new_password  # Will be None for keeping, but we shouldn't reach here
+        )
+
+    # Save wallet with new properties
+    save_coldkey(final_name, keypair, final_password)
+
+    if name_changed:
+        delete_keypair(current_name, is_hotkey=False)
+
+    return {
+        "old_name": current_name,
+        "new_name": final_name,
+        "key_type": wallet_info["key_type"],
+        "ss58_address": wallet_info["evm_address"],
+        "password_updated": new_password is not None or remove_password,
+        "name_updated": name_changed,
+    }
+
+
+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,
+    current_password: Optional[str] = None,
+    owner_address: Optional[str] = None,
+) -> dict:
+    """Update a hotkey's properties.
+
+    Flow:
+    - If changing password: decrypt with current_password, encrypt with new_password
+    - If removing password: decrypt with current_password, save unencrypted
+    - If adding password: load unencrypted, encrypt with new_password
+
+    Args:
+        owner_address: Optional owner address to disambiguate when hotkey name is ambiguous
+    """
+    # Load keypair with current password (if encrypted and changing/removing password)
+    wallet_info = get_wallet_info_by_name(
+        current_name, is_hotkey=True, owner_address=owner_address
+    )
+    if not wallet_info.get("is_hotkey", False):
+        raise Exception(f"'{current_name}' is a coldkey, not a hotkey")
+
+    is_encrypted = wallet_info.get("is_encrypted", False)
+    # Use the file path from wallet_info to avoid ambiguity
+    # (since we already know which wallet we're working with)
+    wallet_file_path = wallet_info.get("file_path")
+    if wallet_file_path:
+        from pathlib import Path
+
+        file_path = Path(wallet_file_path)
+    else:
+        file_path = None
+
+    # Use current_password if provided (for changing/removing), otherwise let load_keypair prompt
+    keypair = load_keypair(
+        current_name,
+        password=current_password
+        if (is_encrypted and (new_password or remove_password))
+        else None,
+        file_path=file_path,
+        is_hotkey=True,
+        owner_address=wallet_info.get("owner_address"),
+    )
+
+    # CRITICAL: Verify that the loaded keypair matches the expected address
+    # This prevents accidentally using a different hotkey's keypair
+    expected_address = wallet_info.get("evm_address") or wallet_info.get("ss58_address")
+    if expected_address:
+        # For ECDSA keys, compute EVM address from public key
+        if keypair.crypto_type == 2:  # ECDSA
+            actual_address = public_key_to_evm_address(keypair.public_key)
+        else:
+            actual_address = keypair.ss58_address
+
+        # Normalize addresses for comparison (remove 0x prefix and convert to lowercase)
+        def normalize_address(addr):
+            if not addr:
+                return None
+            addr_str = str(addr).lower().replace("0x", "")
+            return addr_str
+
+        expected_normalized = normalize_address(expected_address)
+        actual_normalized = normalize_address(actual_address)
+
+        if expected_normalized != actual_normalized:
+            raise Exception(
+                f"CRITICAL ERROR: Loaded keypair address ({actual_address}) does not match "
+                f"expected address ({expected_address}). This indicates the wrong wallet file "
+                f"was loaded or the keypair was corrupted. Aborting update to prevent data loss."
+            )
+
+    final_name = new_name or current_name
+    name_changed = bool(new_name and new_name != current_name)
+
+    owner_address = wallet_info["owner_address"]
+    if new_owner_name:
+        new_owner_info = get_wallet_info_by_name(new_owner_name, is_hotkey=False)
+        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["evm_address"]
+
+    # Check if the new name already exists for this coldkey (but not if it's the same hotkey we're updating)
+    if name_changed:
+        # Check if another hotkey with this name already exists for the same coldkey
+        # We need to check all hotkeys to see if there's a different one with the same name
+        all_keys = list_keys()
+        current_hotkey_address = wallet_info.get("ss58_address") or wallet_info.get(
+            "evm_address"
+        )
+
+        for key in all_keys:
+            if (
+                key.get("is_hotkey", False)
+                and key.get("name") == final_name
+                and key.get("owner_address") == owner_address
+                and (
+                    key.get("ss58_address")
+                    or key.get("evm_address")
+                    or key.get("address")
+                )
+                != current_hotkey_address
+            ):
+                # Found a different hotkey with the same name for the same coldkey - conflict!
+                raise Exception(
+                    f"Coldkey already has a hotkey named '{final_name}'. "
+                    "Please choose a different name for this hotkey."
+                )
+
+    # Determine final password: None if removing, new_password if changing/adding, None if keeping
+    final_password = None if remove_password else new_password
+
+    # Get owner_coldkey_name for proper hierarchical layout
+    owner_coldkey_name = wallet_info.get("owner_coldkey_name")
+    if new_owner_name:
+        # Owner is being changed - get the new owner's name
+        new_owner_info = get_wallet_info_by_name(new_owner_name, is_hotkey=False)
+        owner_coldkey_name = new_owner_info.get("name")
+
+    # Check if we're updating the same file (same name and same owner)
+    # If so, we need to delete the old file first before saving the new one
+    final_file_path = build_wallet_file_path(
+        final_name, is_hotkey=True, owner_address=owner_address, owner_coldkey_name=owner_coldkey_name
+    )
+    current_file_path = Path(wallet_info.get("file_path", ""))
+    old_owner_address = wallet_info["owner_address"]
+    owner_changed = new_owner_name is not None and old_owner_address != owner_address
+
+    # If the final file path is the same as the current file path, delete it first
+    # This handles the case where we're updating password/encryption without changing the name or owner
+    if final_file_path == current_file_path and current_file_path.exists():
+        current_file_path.unlink()
+    # If name or owner changed, delete the old file (different path)
+    elif (name_changed or owner_changed) and current_file_path.exists():
+        current_file_path.unlink()
+        # Also check for legacy file path if owner changed
+        if owner_changed:
+            legacy_file = _legacy_hotkey_path(
+                current_name, old_owner_address, wallet_dir=get_wallet_directory()
+            )
+            if legacy_file.exists():
+                legacy_file.unlink()
+
+    # Save wallet with new properties (will encrypt if final_password is provided, otherwise unencrypted)
+    # Pass owner_coldkey_name to ensure proper hierarchical layout
+    save_hotkey(final_name, keypair, owner_address, final_password, owner_coldkey_name=owner_coldkey_name)
+
+    # Get the actual address from the keypair (not from wallet_info which might be stale)
+    # For ECDSA keys, compute EVM address from public key
+    if keypair.crypto_type == 2:  # ECDSA
+        actual_evm_address = public_key_to_evm_address(keypair.public_key)
+    else:
+        actual_evm_address = keypair.ss58_address
+
+    return {
+        "old_name": current_name,
+        "new_name": final_name,
+        "key_type": wallet_info["key_type"],
+        "ss58_address": actual_evm_address,  # Use address from keypair, not wallet_info
+        "evm_address": actual_evm_address,  # Also include evm_address for consistency
+        "old_owner_address": wallet_info["owner_address"],
+        "new_owner_address": owner_address,
+        "password_updated": new_password is not None or remove_password,
+        "name_updated": bool(new_name and new_name != current_name),
+        "owner_updated": new_owner_name is not None,
+    }