htcli 1.1.0__py3-none-any.whl

src/htcli/client/offchain/wallet.py

@@ -0,0 +1,839 @@
+"""
+Off-chain wallet management operations.
+Thin client layer that delegates to utility functions.
+"""
+
+import json
+from pathlib import Path
+from typing import Callable, Iterable, Optional
+
+from substrateinterface.keypair import Keypair
+
+from src.htcli.utils.wallet.core import decrypt_data, encrypt_data
+from src.htcli.utils.wallet.crypto import (
+    build_wallet_file_path,
+    public_key_to_evm_address,
+    resolve_wallet_file_path,
+)
+
+from ...utils.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+class WalletManager:
+    """Manager for off-chain wallet operations - thin client layer."""
+
+    def __init__(self, wallet_dir: Optional[str] = None):
+        """Initialize WalletManager with wallet directory.
+
+        Args:
+            wallet_dir: Optional wallet directory path. If None, will read from config.
+        """
+        if wallet_dir:
+            self.wallet_dir = Path(wallet_dir).expanduser()
+        else:
+            # Fall back to config or default
+            try:
+                from ...utils.wallet.crypto import get_wallet_directory
+
+                self.wallet_dir = get_wallet_directory()
+            except Exception:
+                # Final fallback to default
+                self.wallet_dir = Path.home() / ".htcli" / "wallets"
+
+    def create_coldkey_wallet(
+        self, name: str, password: Optional[str] = None, mnemonic: Optional[str] = None
+    ) -> dict:
+        """Create a new wallet - delegates to utility functions."""
+        from ...utils.wallet.crypto import generate_coldkey_pair
+
+        try:
+            # Delegate to utility function
+            result = generate_coldkey_pair(
+                name=name, key_type="ecdsa", password=password
+            )
+
+            return {
+                "success": True,
+                "message": f"Wallet '{name}' created successfully",
+                "data": {
+                    "name": result.name,
+                    "ss58_address": result.ss58_address,
+                    "evm_address": result.ss58_address,  # Same for ECDSA
+                    "public_key": result.public_key,
+                    "mnemonic": result.mnemonic,  # Return for user to backup
+                    "is_encrypted": bool(password),
+                    "key_type": result.key_type,
+                },
+            }
+        except Exception as e:
+            logger.error(f"Failed to create wallet: {str(e)}")
+            raise
+
+    def create_hotkey_wallet(
+        self,
+        name: str,
+        owner_address: str,
+        password: Optional[str] = None,
+        mnemonic: Optional[str] = None,
+        owner_coldkey_name: Optional[str] = None,
+    ) -> dict:
+        """Create a new hotkey wallet - delegates to utility functions."""
+        from ...utils.wallet.crypto import generate_hotkey_pair
+
+        try:
+            # Delegate to utility function
+            result = generate_hotkey_pair(
+                name=name,
+                owner_address=owner_address,
+                key_type="ecdsa",
+                password=password,
+                owner_coldkey_name=owner_coldkey_name,
+            )
+
+            return {
+                "success": True,
+                "message": f"Hotkey wallet '{name}' created successfully",
+                "data": {
+                    "name": result.name,
+                    "ss58_address": result.ss58_address,
+                    "evm_address": result.ss58_address,  # Same for ECDSA
+                    "public_key": result.public_key,
+                    "mnemonic": result.mnemonic,  # Return for user to backup
+                    "is_encrypted": bool(password),
+                    "key_type": result.key_type,
+                    "owner_address": result.owner_address,
+                    "owner_coldkey_name": result.owner_coldkey_name
+                    or owner_coldkey_name,
+                },
+            }
+        except Exception as e:
+            logger.error(f"Failed to create hotkey wallet: {str(e)}")
+            raise
+
+    def load_wallet(
+        self,
+        name: str,
+        password: str,
+        is_hotkey: Optional[bool] = None,
+        owner_address: Optional[str] = None,
+    ) -> dict:
+        """Load an existing wallet - delegates to utility functions.
+
+        Args:
+            name: Wallet name
+            password: Password for encrypted wallets
+            is_hotkey: Optional hint to specify if this is a hotkey (True) or coldkey (False)
+            owner_address: Optional coldkey address for hotkey disambiguation
+        """
+        from ...utils.wallet.crypto import load_keypair
+
+        try:
+            # Delegate to utility function with disambiguation parameters
+            keypair = load_keypair(
+                name, password, is_hotkey=is_hotkey, owner_address=owner_address
+            )
+
+            return {
+                "success": True,
+                "message": f"Wallet '{name}' loaded successfully",
+                "data": {
+                    "name": name,
+                    "address": keypair.ss58_address,
+                    "public_key": keypair.public_key.hex(),
+                    "keypair": keypair,
+                },
+            }
+        except Exception as e:
+            logger.error(f"Failed to load wallet: {str(e)}")
+            raise
+
+    def list_wallets(self) -> dict:
+        """List all available wallets - delegates to utility functions."""
+        from ...utils.wallet.crypto import list_keys
+
+        try:
+            # Delegate to utility function
+            wallets = list_keys()
+
+            return {
+                "success": True,
+                "message": f"Found {len(wallets)} wallet(s)",
+                "data": wallets,
+            }
+        except Exception as e:
+            logger.error(f"Failed to list wallets: {str(e)}")
+            raise
+
+    def delete_wallet(
+        self,
+        name: str,
+        is_hotkey: Optional[bool] = None,
+        owner_address: Optional[str] = None,
+        owner_coldkey_name: Optional[str] = None,
+    ) -> dict:
+        """Delete a wallet - delegates to utility functions.
+
+        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
+        """
+        from ...utils.wallet.crypto import delete_keypair
+
+        try:
+            # Delegate to utility function (confirmation handled by handler)
+            deleted = delete_keypair(
+                name,
+                is_hotkey=is_hotkey,
+                owner_address=owner_address,
+                owner_coldkey_name=owner_coldkey_name,
+            )
+
+            if not deleted:
+                raise FileNotFoundError(f"Wallet '{name}' not found")
+
+            return {
+                "success": True,
+                "message": f"Wallet '{name}' deleted successfully",
+                "data": {"name": name},
+            }
+        except Exception as e:
+            logger.error(f"Failed to delete wallet: {str(e)}")
+            raise
+
+    def get_wallet_info(
+        self,
+        name: str,
+        is_hotkey: Optional[bool] = None,
+        owner_address: Optional[str] = None,
+        owner_coldkey_name: Optional[str] = None,
+    ) -> dict:
+        """Get wallet information - delegates to utility functions.
+
+        Args:
+            name: Wallet name
+            is_hotkey: Optional hint to specify if this is a hotkey (True) or coldkey (False)
+            owner_address: Optional coldkey address for hotkey disambiguation
+        """
+        from ...utils.wallet.crypto import get_wallet_info_by_name
+
+        try:
+            # Delegate to utility function
+            wallet_info = get_wallet_info_by_name(
+                name,
+                is_hotkey=is_hotkey,
+                owner_address=owner_address,
+                owner_coldkey_name=owner_coldkey_name,
+            )
+
+            if not wallet_info:
+                raise ValueError(f"Wallet '{name}' not found")
+
+            return {
+                "success": True,
+                "message": f"Wallet '{name}' information retrieved",
+                "data": wallet_info,
+            }
+        except Exception as e:
+            logger.error(f"Failed to get wallet info: {str(e)}")
+            raise
+
+    def backup_wallet(self, name: str, backup_path: str, password: str) -> dict:
+        """Create a backup of a wallet."""
+        from ...utils.wallet.crypto import get_wallet_info_by_name
+
+        try:
+            # First get wallet info to handle ambiguity
+            wallet_info = get_wallet_info_by_name(name)
+            is_hotkey = wallet_info.get("is_hotkey", False)
+            owner_address = wallet_info.get("owner_address")
+
+            # Use wallet_dir from config
+            wallet_path = resolve_wallet_file_path(
+                name, is_hotkey=is_hotkey, owner_address=owner_address
+            )
+
+            # Load wallet to verify password
+            wallet_result = self.load_wallet(
+                name, password, is_hotkey=is_hotkey, owner_address=owner_address
+            )
+            if not wallet_result["success"]:
+                raise ValueError("Invalid password")
+
+            # Copy wallet file to backup location
+            backup_file = Path(backup_path)
+            backup_file.parent.mkdir(parents=True, exist_ok=True)
+
+            with open(wallet_path) as src, open(backup_file, "w") as dst:
+                dst.write(src.read())
+
+            return {
+                "success": True,
+                "message": f"Wallet '{name}' backed up successfully",
+                "data": {
+                    "name": name,
+                    "backup_path": str(backup_file),
+                    "original_path": str(wallet_path),
+                },
+            }
+        except Exception as e:
+            logger.error(f"Failed to backup wallet: {str(e)}")
+            raise
+
+    def restore_wallet(self, backup_path: str, name: Optional[str] = None) -> dict:
+        """Restore a wallet from backup."""
+        try:
+            backup_file = Path(backup_path)
+
+            if not backup_file.exists():
+                raise ValueError(f"Backup file '{backup_path}' not found")
+
+            with open(backup_file) as f:
+                wallet_data = json.load(f)
+
+            # Use provided name or original name
+            wallet_name = name or wallet_data.get("name", backup_file.stem)
+            # Use wallet_dir from config
+            wallet_path = build_wallet_file_path(
+                wallet_name,
+                wallet_data.get("is_hotkey", False),
+                wallet_dir=self.wallet_dir,
+                owner_address=wallet_data.get("owner_address"),
+            )
+
+            if wallet_path.exists():
+                raise ValueError(f"Wallet '{wallet_name}' already exists")
+
+            # Update wallet data with new name if different
+            if name and name != wallet_data.get("name"):
+                wallet_data["name"] = name
+
+            # Save restored wallet
+            with open(wallet_path, "w") as f:
+                json.dump(wallet_data, f, indent=2)
+
+            return {
+                "success": True,
+                "message": f"Wallet '{wallet_name}' restored successfully",
+                "data": {
+                    "name": wallet_name,
+                    "address": wallet_data.get("address"),
+                    "path": str(wallet_path),
+                    "backup_path": backup_path,
+                },
+            }
+        except Exception as e:
+            logger.error(f"Failed to restore wallet: {str(e)}")
+            raise
+
+    def change_wallet_password(
+        self, name: str, old_password: str, new_password: str
+    ) -> dict:
+        """Change wallet password."""
+        from ...utils.wallet.crypto import get_wallet_info_by_name
+
+        try:
+            # First get wallet info to handle ambiguity
+            wallet_info = get_wallet_info_by_name(name)
+            is_hotkey = wallet_info.get("is_hotkey", False)
+            owner_address = wallet_info.get("owner_address")
+
+            # Load wallet with old password
+            wallet_result = self.load_wallet(
+                name, old_password, is_hotkey=is_hotkey, owner_address=owner_address
+            )
+            if not wallet_result["success"]:
+                raise ValueError("Invalid old password")
+
+            wallet_data = wallet_result["data"]["wallet_data"]
+
+            # Decrypt with old password and re-encrypt with new password
+            encrypted_mnemonic = wallet_data.get("encrypted_mnemonic")
+            mnemonic = decrypt_data(encrypted_mnemonic, old_password)
+            new_encrypted_mnemonic = encrypt_data(mnemonic, new_password)
+
+            # Update wallet data
+            wallet_data["encrypted_mnemonic"] = new_encrypted_mnemonic
+
+            # Save updated wallet
+            wallet_path = resolve_wallet_file_path(
+                name, is_hotkey=is_hotkey, owner_address=owner_address
+            )
+            with open(wallet_path, "w") as f:
+                json.dump(wallet_data, f, indent=2)
+
+            return {
+                "success": True,
+                "message": f"Password for wallet '{name}' changed successfully",
+                "data": {"name": name},
+            }
+        except Exception as e:
+            logger.error(f"Failed to change wallet password: {str(e)}")
+            raise
+
+    def export_mnemonic(self, name: str, password: str) -> dict:
+        """Export wallet mnemonic (use with caution)."""
+        from ...utils.wallet.crypto import get_wallet_info_by_name
+
+        try:
+            # First get wallet info to handle ambiguity
+            wallet_info = get_wallet_info_by_name(name)
+            is_hotkey = wallet_info.get("is_hotkey", False)
+            owner_address = wallet_info.get("owner_address")
+
+            wallet_result = self.load_wallet(
+                name, password, is_hotkey=is_hotkey, owner_address=owner_address
+            )
+            if not wallet_result["success"]:
+                raise ValueError("Invalid password")
+
+            wallet_data = wallet_result["data"]["wallet_data"]
+            encrypted_mnemonic = wallet_data.get("encrypted_mnemonic")
+            mnemonic = decrypt_data(encrypted_mnemonic, password)
+
+            return {
+                "success": True,
+                "message": f"Mnemonic for wallet '{name}' exported",
+                "data": {
+                    "name": name,
+                    "mnemonic": mnemonic,
+                    "warning": "Keep this mnemonic secure and private!",
+                },
+            }
+        except Exception as e:
+            logger.error(f"Failed to export mnemonic: {str(e)}")
+            raise
+
+    def upgrade_wallet_layout(
+        self,
+        *,
+        dry_run: bool = False,
+        force: bool = False,
+        backup: bool = True,
+        wallets: Optional[Iterable[str]] = None,
+        log: Optional[Callable[[str], None]] = None,
+    ) -> dict:
+        """Upgrade the wallet directory to the hierarchical layout."""
+        from ...utils.wallet.migration import migrate_wallet_layout
+
+        try:
+            report = migrate_wallet_layout(
+                wallet_dir=self.wallet_dir,
+                dry_run=dry_run,
+                force=force,
+                backup=backup,
+                only_wallets=wallets,
+                log=log,
+            )
+            return {
+                "success": True,
+                "message": "Wallet layout upgrade completed",
+                "data": report.as_dict(),
+            }
+        except Exception as e:
+            logger.error(f"Failed to upgrade wallet layout: {str(e)}")
+            raise
+
+    def get_keypair(
+        self,
+        name: str,
+        password: str,
+        is_hotkey: Optional[bool] = None,
+        owner_address: Optional[str] = None,
+    ) -> Keypair:
+        """Get keypair for a wallet (for transaction signing).
+
+        Args:
+            name: Wallet name
+            password: Password for encrypted wallets (None for unencrypted)
+            is_hotkey: Optional hint to specify if this is a hotkey (True) or coldkey (False)
+            owner_address: Optional coldkey address for hotkey disambiguation
+        """
+        try:
+            wallet_result = self.load_wallet(
+                name, password, is_hotkey=is_hotkey, owner_address=owner_address
+            )
+            if not wallet_result["success"]:
+                raise ValueError("Invalid password")
+
+            return wallet_result["data"]["keypair"]
+        except Exception as e:
+            logger.error(f"Failed to get keypair: {str(e)}")
+            raise
+
+    def resolve_hotkey_address(
+        self,
+        hotkey_input: str,
+        owner_coldkey_name: Optional[str] = None,
+        owner_address: Optional[str] = None,
+    ) -> str:
+        """
+        Resolve hotkey input to a valid Bytes20 address.
+        Handles both direct addresses and wallet names.
+
+        Args:
+            hotkey_input: Either a Bytes20 address (0x...) or wallet name
+            owner_coldkey_name: Optional coldkey name for disambiguating hotkeys with the same name
+            owner_address: Optional coldkey address for disambiguating hotkeys with the same name
+
+        Returns:
+            str: Valid Bytes20 address
+
+        Raises:
+            ValueError: If hotkey cannot be resolved or is invalid format
+        """
+        hotkey_input = hotkey_input.strip()
+
+        # Check if it's already a valid Ethereum address
+        if self.validate_ethereum_address(hotkey_input):
+            return hotkey_input
+
+        # Check if it's a wallet name
+        try:
+            # Use get_wallet_info_by_name with owner context for proper disambiguation
+            from ...utils.wallet.crypto import get_wallet_info_by_name
+
+            wallet_info = get_wallet_info_by_name(
+                hotkey_input,
+                is_hotkey=True,
+                owner_address=owner_address,
+                owner_coldkey_name=owner_coldkey_name,
+            )
+
+            if wallet_info:
+                resolved_address = (
+                    wallet_info.get("evm_address")
+                    or wallet_info.get("address")
+                    or wallet_info.get("ss58_address")
+                )
+                if resolved_address and self.validate_ethereum_address(
+                    resolved_address
+                ):
+                    return resolved_address
+
+                public_key_hex = wallet_info.get("public_key")
+                if public_key_hex:
+                    try:
+                        derived_address = public_key_to_evm_address(
+                            bytes.fromhex(public_key_hex)
+                        )
+                        if self.validate_ethereum_address(derived_address):
+                            return derived_address
+                    except Exception:
+                        pass
+
+                raise ValueError(
+                    f"Wallet '{hotkey_input}' does not have a valid EVM address on disk. "
+                    "Please regenerate or restore this wallet to continue."
+                )
+            else:
+                raise ValueError(f"Wallet '{hotkey_input}' not found")
+        except FileNotFoundError:
+            raise ValueError(f"Wallet '{hotkey_input}' not found")
+        except Exception as e:
+            raise ValueError(
+                f"Failed to resolve hotkey '{hotkey_input}': {str(e)}"
+            ) from e
+
+    def validate_ethereum_address(self, address: str) -> bool:
+        """Validate if address is a valid Ethereum/Bytes20 format."""
+        return (
+            address.startswith("0x")
+            and len(address) == 42
+            and all(c in "0123456789abcdefABCDEF" for c in address[2:])
+        )
+
+    # ============================================================================
+    # MIGRATION METHODS: Methods that wrap utils functions for proper architecture
+    # ============================================================================
+
+    def import_coldkey_from_private_key(
+        self,
+        name: str,
+        private_key: str,
+        key_type: str = "ecdsa",
+        password: Optional[str] = None,
+    ) -> dict:
+        """Import coldkey from private key - delegates to utility functions."""
+        from ...utils.wallet.crypto import import_keypair
+
+        try:
+            # Delegate to utility function
+            keypair_info = import_keypair(
+                name=name,
+                private_key=private_key,
+                key_type=key_type,
+                password=password,
+            )
+
+            return {
+                "success": True,
+                "message": f"Coldkey '{name}' imported from private key successfully",
+                "data": {
+                    "name": keypair_info.name,
+                    "ss58_address": keypair_info.ss58_address,
+                    "public_key": keypair_info.public_key,
+                    "key_type": keypair_info.key_type,
+                    "mnemonic": None,  # Private key import doesn't have mnemonic
+                    "import_method": "private key",
+                },
+            }
+        except Exception as e:
+            logger.error(f"Failed to import coldkey from private key: {str(e)}")
+            raise
+
+    def import_coldkey_from_mnemonic(
+        self,
+        name: str,
+        mnemonic: str,
+        key_type: str = "ecdsa",
+        password: Optional[str] = None,
+    ) -> dict:
+        """Import coldkey from mnemonic - delegates to utility functions."""
+        from ...utils.wallet.crypto import import_keypair_from_mnemonic
+
+        try:
+            # Delegate to utility function
+            keypair_info = import_keypair_from_mnemonic(
+                name=name,
+                mnemonic=mnemonic,
+                key_type=key_type,
+                password=password,
+            )
+
+            return {
+                "success": True,
+                "message": f"Coldkey '{name}' imported from mnemonic successfully",
+                "data": {
+                    "name": keypair_info.name,
+                    "ss58_address": keypair_info.ss58_address,
+                    "public_key": keypair_info.public_key,
+                    "key_type": keypair_info.key_type,
+                    "mnemonic": mnemonic,  # Include the mnemonic used for restoration
+                    "import_method": "mnemonic",
+                },
+            }
+        except Exception as e:
+            logger.error(f"Failed to import coldkey from mnemonic: {str(e)}")
+            raise
+
+    def import_hotkey_from_private_key(
+        self,
+        name: str,
+        private_key: str,
+        owner_address: str,
+        key_type: str = "ecdsa",
+        password: Optional[str] = None,
+    ) -> dict:
+        """Import hotkey from private key - delegates to utility functions."""
+        from ...utils.wallet.crypto import import_hotkey_from_private_key
+
+        try:
+            # Delegate to utility function
+            keypair_info = import_hotkey_from_private_key(
+                name=name,
+                private_key=private_key,
+                owner_address=owner_address,
+                key_type=key_type,
+                password=password,
+            )
+
+            return {
+                "success": True,
+                "message": f"Hotkey '{name}' imported from private key successfully",
+                "data": {
+                    "name": keypair_info.name,
+                    "ss58_address": keypair_info.ss58_address,
+                    "public_key": keypair_info.public_key,
+                    "key_type": keypair_info.key_type,
+                    "owner_address": keypair_info.owner_address,
+                    "mnemonic": None,  # Private key import doesn't have mnemonic
+                    "import_method": "private key",
+                },
+            }
+        except Exception as e:
+            logger.error(f"Failed to import hotkey from private key: {str(e)}")
+            raise
+
+    def import_hotkey_from_mnemonic(
+        self,
+        name: str,
+        mnemonic: str,
+        owner_address: str,
+        key_type: str = "ecdsa",
+        password: Optional[str] = None,
+    ) -> dict:
+        """Import hotkey from mnemonic - delegates to utility functions."""
+        from ...utils.wallet.crypto import import_hotkey_from_mnemonic
+
+        try:
+            # Delegate to utility function
+            keypair_info = import_hotkey_from_mnemonic(
+                name=name,
+                mnemonic=mnemonic,
+                owner_address=owner_address,
+                key_type=key_type,
+                password=password,
+            )
+
+            return {
+                "success": True,
+                "message": f"Hotkey '{name}' imported from mnemonic successfully",
+                "data": {
+                    "name": keypair_info.name,
+                    "ss58_address": keypair_info.ss58_address,
+                    "public_key": keypair_info.public_key,
+                    "key_type": keypair_info.key_type,
+                    "owner_address": keypair_info.owner_address,
+                    "mnemonic": mnemonic,  # Include the mnemonic used for restoration
+                    "import_method": "mnemonic",
+                },
+            }
+        except Exception as e:
+            logger.error(f"Failed to import hotkey from mnemonic: {str(e)}")
+            raise
+
+    def import_preseeded_wallet(
+        self, preseeded_name: str, wallet_name: str, password: Optional[str] = None
+    ) -> dict:
+        """Import preseeded wallet - delegates to utility functions."""
+        from ...utils.wallet.crypto import import_preseeded_wallet
+
+        try:
+            # Delegate to utility function
+            keypair_info = import_preseeded_wallet(
+                preseeded_name=preseeded_name,
+                wallet_name=wallet_name,
+                password=password,
+            )
+
+            return {
+                "success": True,
+                "message": f"Preseeded wallet '{preseeded_name}' imported as '{wallet_name}' successfully",
+                "data": {
+                    "name": keypair_info.name,
+                    "ss58_address": keypair_info.ss58_address,
+                    "public_key": keypair_info.public_key,
+                    "key_type": keypair_info.key_type,
+                    "mnemonic": None,  # Preseeded wallets use private keys, no mnemonic
+                    "preseeded_name": preseeded_name,
+                },
+            }
+        except Exception as e:
+            logger.error(f"Failed to import preseeded wallet: {str(e)}")
+            raise
+
+    def delete_coldkey_and_hotkeys(self, name: str) -> dict:
+        """Delete coldkey and associated hotkeys - delegates to utility functions."""
+        from ...utils.wallet.crypto import delete_coldkey_and_hotkeys
+
+        try:
+            # Delegate to utility function (confirmation handled by handler)
+            result = delete_coldkey_and_hotkeys(name)
+
+            return {
+                "success": True,
+                "message": f"Coldkey '{name}' and associated hotkeys deleted successfully",
+                "data": result,
+            }
+        except Exception as e:
+            logger.error(f"Failed to delete coldkey and hotkeys: {str(e)}")
+            raise
+
+    def update_coldkey(
+        self,
+        name: str,
+        new_name: Optional[str] = None,
+        new_password: Optional[str] = None,
+        remove_password: bool = False,
+        current_password: Optional[str] = None,
+    ) -> dict:
+        """Update coldkey - delegates to utility functions."""
+        from ...utils.wallet.crypto import update_coldkey
+
+        try:
+            # Delegate to utility function
+            update_data = update_coldkey(
+                current_name=name,
+                new_name=new_name,
+                new_password=new_password,
+                remove_password=remove_password,
+                current_password=current_password,
+            )
+
+            return {
+                "success": True,
+                "message": f"Coldkey '{name}' updated successfully",
+                "data": update_data,
+            }
+        except Exception as e:
+            # Let the error bubble up to handler for beautiful error display
+            raise
+
+    def update_hotkey(
+        self,
+        name: str,
+        new_name: Optional[str] = None,
+        new_password: Optional[str] = None,
+        remove_password: bool = False,
+        new_owner: Optional[str] = None,
+        current_password: Optional[str] = None,
+        owner_address: Optional[str] = None,
+    ) -> dict:
+        """Update hotkey - delegates to utility functions."""
+        from ...utils.wallet.crypto import update_hotkey
+
+        try:
+            # Delegate to utility function
+            # update_hotkey expects new_owner_name as a wallet name, not address
+            update_data = update_hotkey(
+                current_name=name,
+                new_name=new_name,
+                new_password=new_password,
+                remove_password=remove_password,
+                new_owner_name=new_owner,  # This will be the wallet name
+                current_password=current_password,
+                owner_address=owner_address,  # Pass owner address for disambiguation
+            )
+
+            return {
+                "success": True,
+                "message": f"Hotkey '{name}' updated successfully",
+                "data": update_data,
+            }
+        except Exception as e:
+            # Let the error bubble up to handler for beautiful error display
+            raise
+
+    def save_coldkey(
+        self, name: str, keypair: Keypair, password: Optional[str] = None
+    ) -> dict:
+        """Save a coldkey to disk (used for rotation/restoration)."""
+        from ...utils.wallet.crypto import save_coldkey
+
+        try:
+            save_coldkey(name, keypair, password)
+            return {"success": True, "message": f"Coldkey '{name}' saved successfully"}
+        except Exception as e:
+            logger.error(f"Failed to save coldkey: {str(e)}")
+            raise
+
+    def save_hotkey(
+        self,
+        name: str,
+        keypair: Keypair,
+        owner_address: str,
+        password: Optional[str] = None,
+        owner_coldkey_name: Optional[str] = None,
+    ) -> dict:
+        """Save a hotkey to disk (used for rotation/restoration)."""
+        from ...utils.wallet.crypto import save_hotkey
+
+        try:
+            save_hotkey(name, keypair, owner_address, password, owner_coldkey_name)
+            return {"success": True, "message": f"Hotkey '{name}' saved successfully"}
+        except Exception as e:
+            logger.error(f"Failed to save hotkey: {str(e)}")
+            raise