htcli 1.1.0__py3-none-any.whl

src/htcli/commands/wallet/handlers.py

@@ -0,0 +1,3040 @@
+"""
+Wallet command execution handlers.
+
+Contains the core business logic for wallet operations using the client system.
+Follows the 3-step pattern: prompts → handlers → display.
+"""
+
+import traceback
+import threading
+import time
+from typing import Optional
+
+# Removed direct utils import - use client layer instead
+# Use client layer instead of direct utils imports
+from ...client.offchain.wallet import WalletManager
+from ...errors.base import AmbiguousWalletError
+from ...errors.handlers import handle_substrate_error
+from .error_handling import handle_wallet_extrinsic_error
+from ...models.responses import (
+    WalletCreateResponse,
+    WalletDeleteResponse,
+    WalletListResponse,
+    WalletStatusResponse,
+    WalletTransferResponse,
+    WalletUpdateResponse,
+)
+from ...ui.colors import address, info, success, warning
+from ...ui.components import HTCLISpinner
+from ...ui.display import HTCLIConsole
+from ...utils.logging import get_logger
+from ...utils.wallet.crypto import get_wallet_info_by_name, list_keys
+
+# All utils functions now accessed through client layer - no direct imports needed
+from .display import (
+    display_all_wallet_balances,
+    display_single_wallet_balance,
+    display_wallet_creation_result,
+    display_wallet_deletion_result,
+    display_wallet_describe_result,
+    display_wallet_generation_result,
+    display_wallet_list,
+    display_wallet_restoration_result,
+    display_wallet_status,
+    display_wallet_transfer_result,
+    display_wallet_update_result,
+    display_identity_update_result,
+)
+from .prompts import (
+    prompt_preseeded_wallet,
+    prompt_wallet_balance,
+    prompt_wallet_creation,
+    prompt_wallet_deletion,
+    prompt_wallet_restoration,
+    prompt_wallet_transfer,
+    prompt_wallet_update,
+    prompt_identity_update,
+    select_prompt,
+)
+
+console = HTCLIConsole()
+logger = get_logger(__name__)
+
+
+def _get_network_name(client) -> str:
+    """Best-effort fetch of the connected network name."""
+    try:
+        if client and client.substrate and getattr(client.substrate, "chain", None):
+            return client.substrate.chain
+    except Exception:
+        logger.debug("Unable to determine network name from substrate connection.")
+    return "Hypertensor"
+
+
+def _get_staking_breakdown(client, address: Optional[str]) -> dict:
+    """Fetch staking breakdown (in wei) for a coldkey address.
+
+    Returns:
+        dict with keys: direct_stake, delegate_stake, node_delegate_stake, overwatch_stake, unbonding, total
+    """
+    result = {
+        "direct_stake": 0,
+        "delegate_stake": 0,
+        "node_delegate_stake": 0,
+        "overwatch_stake": 0,
+        "unbonding": 0,
+        "total": 0,
+    }
+
+    if not address or not client or not getattr(client, "rpc", None):
+        return result
+
+    try:
+        # 1. Get direct stakes from nodes owned by this coldkey
+        stake_response = client.rpc.wallet.network_get_coldkey_stakes(address)
+        if stake_response and stake_response.success and stake_response.data:
+            for stake in stake_response.data:
+                if isinstance(stake, dict):
+                    result["direct_stake"] += int(stake.get("balance", 0))
+                else:
+                    result["direct_stake"] += int(getattr(stake, "balance", 0))
+    except Exception as exc:
+        logger.debug(f"Failed to fetch direct stakes for {address}: {exc}")
+
+    try:
+        # 2. Get delegate stakes (subnet delegate stakes)
+        delegate_response = client.rpc.wallet.network_get_delegate_stakes(address)
+        if delegate_response and delegate_response.success and delegate_response.data:
+            for stake in delegate_response.data:
+                if isinstance(stake, dict):
+                    result["delegate_stake"] += int(stake.get("balance", 0))
+                else:
+                    result["delegate_stake"] += int(getattr(stake, "balance", 0))
+    except Exception as exc:
+        logger.debug(f"Failed to fetch delegate stakes for {address}: {exc}")
+
+    try:
+        # 3. Get node delegate stakes
+        node_delegate_response = client.rpc.wallet.network_get_node_delegate_stakes(
+            address
+        )
+        if (
+            node_delegate_response
+            and node_delegate_response.success
+            and node_delegate_response.data
+        ):
+            for stake in node_delegate_response.data:
+                if isinstance(stake, dict):
+                    result["node_delegate_stake"] += int(stake.get("balance", 0))
+                else:
+                    result["node_delegate_stake"] += int(getattr(stake, "balance", 0))
+    except Exception as exc:
+        logger.debug(f"Failed to fetch node delegate stakes for {address}: {exc}")
+
+    try:
+        # 4. Get overwatch stakes for this coldkey
+        # Overwatch stake is stored per hotkey in AccountOverwatchStake
+        # We need to find overwatch nodes owned by this coldkey
+        overwatch_nodes = client.rpc.overwatch.list_overwatch_nodes()
+        if overwatch_nodes:
+            # Normalize address for comparison
+            normalized_address = address.lower() if address else ""
+            for node in overwatch_nodes:
+                node_coldkey = getattr(node, "coldkey", None) or (
+                    node.get("coldkey") if isinstance(node, dict) else None
+                )
+                if node_coldkey:
+                    if node_coldkey.lower() == normalized_address:
+                        stake_balance = getattr(node, "stake_balance", 0) or (
+                            node.get("stake_balance", 0)
+                            if isinstance(node, dict)
+                            else 0
+                        )
+                        result["overwatch_stake"] += int(stake_balance)
+    except Exception as exc:
+        logger.debug(f"Failed to fetch overwatch stakes for {address}: {exc}")
+
+    try:
+        # 5. Get unbonding balance (tokens in unbonding waiting period)
+        unbonding_info = client.rpc.wallet.get_unbonding_info(address)
+        if (
+            unbonding_info
+            and unbonding_info.get("success")
+            and unbonding_info.get("data")
+        ):
+            unbondings = unbonding_info["data"].get("unbondings", [])
+            if unbondings:
+                # Sum all unbonding amounts
+                for unbonding in unbondings:
+                    if isinstance(unbonding, dict):
+                        result["unbonding"] += int(unbonding.get("amount", 0))
+                    elif isinstance(unbonding, (list, tuple)) and len(unbonding) >= 2:
+                        # Could be (amount, block) tuple format
+                        result["unbonding"] += int(unbonding[0])
+                    else:
+                        # Try to get value directly
+                        result["unbonding"] += int(getattr(unbonding, "amount", 0) or 0)
+    except Exception as exc:
+        logger.debug(f"Failed to fetch unbonding info for {address}: {exc}")
+
+    result["total"] = (
+        result["direct_stake"]
+        + result["delegate_stake"]
+        + result["node_delegate_stake"]
+        + result["overwatch_stake"]
+        + result["unbonding"]
+    )
+    return result
+
+
+def _get_total_staked_balance(client, address: Optional[str]) -> int:
+    """Fetch total staked balance (in wei) for a coldkey address.
+
+    This is a backward-compatible wrapper around _get_staking_breakdown.
+    """
+    breakdown = _get_staking_breakdown(client, address)
+    return breakdown["total"]
+
+
+def generate_coldkey_handler(
+    name: Optional[str] = None,
+    key_type: Optional[str] = None,
+    password: Optional[str] = None,
+    copy_mnemonic: bool = False,
+):
+    """Handle coldkey generation command."""
+    try:
+        # Early check: if name is provided via CLI, check existence before prompting for password
+        from ...ui.display import print_error
+        from ...utils.wallet.crypto import get_wallet_info_by_name
+
+        if name:
+            try:
+                get_wallet_info_by_name(name, is_hotkey=False)
+                # If we get here, wallet exists
+                print_error(
+                    f"Wallet '{name}' already exists! Please choose a different name or use the existing wallet."
+                )
+                return
+            except FileNotFoundError:
+                # Good - wallet doesn't exist, can proceed
+                pass
+
+        # STEP 1: Collect input parameters
+        request = prompt_wallet_creation(
+            name=name, key_type=key_type, wallet_type="coldkey", password=password
+        )
+
+        # STEP 2: Execute via client layer
+        wallet_manager = WalletManager()
+        result = wallet_manager.create_coldkey_wallet(
+            name=request.name, password=request.password
+        )
+
+        # Create response model
+        response = WalletCreateResponse(
+            name=result["data"]["name"],
+            address=result["data"]["ss58_address"],
+            public_key=result["data"]["public_key"],
+            key_type=result["data"]["key_type"],
+            wallet_type="coldkey",
+            mnemonic=result["data"]["mnemonic"],
+            encrypted=result["data"]["is_encrypted"],
+        )
+
+        # STEP 3: Display results
+        display_wallet_creation_result(response, copy_mnemonic=copy_mnemonic)
+
+    except Exception as e:
+        from ...errors.handlers import handle_wallet_error
+        from ...ui.display import print_error
+
+        error = handle_wallet_error(e, "update")
+        print_error(error.message, suggestions=error.suggestions)
+
+
+def generate_hotkey_handler(
+    name: Optional[str] = None,
+    coldkey_name: Optional[str] = None,
+    key_type: Optional[str] = None,
+    password: Optional[str] = None,
+    copy_mnemonic: bool = False,
+):
+    """Handle hotkey generation command."""
+    try:
+        # STEP 1: Collect input parameters
+        request = prompt_wallet_creation(
+            name=name,
+            key_type=key_type,
+            wallet_type="hotkey",
+            coldkey_name=coldkey_name,
+            password=password,
+        )
+
+        # Resolve coldkey name if provided to address
+        wallet_manager = WalletManager()
+        if request.owner_address:
+            coldkey_info = wallet_manager.get_wallet_info(
+                request.owner_address, is_hotkey=False
+            )
+            if coldkey_info["data"].get("is_hotkey", False):
+                raise ValueError(
+                    f"'{request.owner_address}' is a hotkey. Please provide a coldkey name."
+                )
+            coldkey_address = coldkey_info["data"]["ss58_address"]
+        else:
+            raise ValueError("Coldkey name is required for hotkey creation")
+
+        # Check if this specific coldkey already has a hotkey with this name
+        from ...ui.display import print_error
+        from ...utils.wallet.crypto import coldkey_has_hotkey
+
+        if coldkey_has_hotkey(coldkey_address, request.name):
+            print_error(
+                f"Coldkey '{request.owner_address}' already has a hotkey named '{request.name}'. "
+                "Please choose a different name for this hotkey."
+            )
+            return
+
+        # STEP 2: Execute via client layer
+        result = wallet_manager.create_hotkey_wallet(
+            name=request.name,
+            owner_address=coldkey_address,
+            password=request.password,
+            owner_coldkey_name=request.owner_address,
+        )
+
+        # Create response model
+        response = WalletCreateResponse(
+            name=result["data"]["name"],
+            address=result["data"]["ss58_address"],
+            public_key=result["data"]["public_key"],
+            key_type=result["data"]["key_type"],
+            wallet_type="hotkey",
+            mnemonic=result["data"]["mnemonic"],
+            encrypted=result["data"]["is_encrypted"],
+        )
+
+        # STEP 3: Display results
+        display_wallet_creation_result(
+            response,
+            copy_mnemonic=copy_mnemonic,
+            owner_name=request.owner_address,
+            owner_address=coldkey_address,
+        )
+
+    except Exception as e:
+        from ...errors.handlers import handle_wallet_error
+        from ...ui.display import print_error
+
+        error = handle_wallet_error(e, "update")
+        print_error(error.message, suggestions=error.suggestions)
+
+
+def generate_handler(
+    coldkey_name: Optional[str] = None,
+    hotkey_name: Optional[str] = None,
+    key_type: Optional[str] = None,
+    password: Optional[str] = None,
+    copy_mnemonic: bool = False,
+):
+    """Handle wallet generation command - creates both coldkey and hotkey at once.
+
+    Provides comprehensive error handling with clear feedback on what succeeded and what failed.
+    """
+    from ...ui.display import print_error, print_info, print_warning
+    from ...utils.wallet.crypto import get_wallet_info_by_name, coldkey_has_hotkey
+    from ...ui.prompts import confirm_prompt
+
+    # Track creation state
+    creation_state = {
+        "coldkey_created": False,
+        "hotkey_created": False,
+        "coldkey_name": None,
+        "hotkey_name": None,
+        "coldkey_address": None,
+    }
+
+    try:
+        # STEP 0: Pre-validation - check for conflicts before starting
+        console.print("[bold cyan]Creating new wallet (coldkey + hotkey)[/bold cyan]\n")
+
+        # Collect input parameters for coldkey (this will prompt if not provided)
+        coldkey_request = prompt_wallet_creation(
+            name=coldkey_name,
+            key_type=key_type,
+            wallet_type="coldkey",
+            password=password,
+        )
+        creation_state["coldkey_name"] = coldkey_request.name
+
+        # Validate coldkey doesn't exist
+        try:
+            existing_coldkey = get_wallet_info_by_name(
+                coldkey_request.name, is_hotkey=False
+            )
+            print_error(
+                f"Coldkey '{coldkey_request.name}' already exists!",
+                suggestions=[
+                    f"Use a different name for the coldkey",
+                    f"Use the existing coldkey: htcli wallet list",
+                    f"Delete the existing coldkey first: htcli wallet delete --coldkey {coldkey_request.name}",
+                ],
+            )
+            return
+        except FileNotFoundError:
+            # Good - coldkey doesn't exist, can proceed
+            pass
+
+        # If hotkey name is already known, check for conflicts early
+        if hotkey_name:
+            # We need the coldkey address to check, but we haven't created it yet
+            # So we'll check after coldkey creation but before hotkey creation
+            pass
+
+        # STEP 1: Create coldkey first
+        console.print(info("📝 Step 1/2: Creating coldkey..."))
+        wallet_manager = WalletManager()
+
+        try:
+            coldkey_result = wallet_manager.create_coldkey_wallet(
+                name=coldkey_request.name, password=coldkey_request.password
+            )
+            creation_state["coldkey_created"] = True
+            creation_state["coldkey_address"] = coldkey_result["data"]["ss58_address"]
+            console.print(
+                success(f"✅ Coldkey '{coldkey_request.name}' created successfully")
+            )
+        except Exception as e:
+            print_error(
+                f"❌ Failed to create coldkey '{coldkey_request.name}': {str(e)}",
+                suggestions=[
+                    "• Check that the wallet name is valid",
+                    "• Ensure you have write permissions to the wallet directory",
+                    "• Try a different wallet name",
+                ],
+            )
+            return
+
+        coldkey_address = creation_state["coldkey_address"]
+        coldkey_response = WalletCreateResponse(
+            name=coldkey_result["data"]["name"],
+            address=coldkey_result["data"]["ss58_address"],
+            public_key=coldkey_result["data"]["public_key"],
+            key_type=coldkey_result["data"]["key_type"],
+            wallet_type="coldkey",
+            mnemonic=coldkey_result["data"]["mnemonic"],
+            encrypted=coldkey_result["data"]["is_encrypted"],
+        )
+
+        # STEP 2: Collect input parameters for hotkey and validate
+        console.print(info("\n📝 Step 2/2: Creating hotkey..."))
+
+        # Check if this specific coldkey already has a hotkey with the provided name
+        if hotkey_name and coldkey_has_hotkey(coldkey_address, hotkey_name):
+            print_error(
+                f"Hotkey '{hotkey_name}' already exists for coldkey '{coldkey_request.name}'",
+                suggestions=[
+                    f"Choose a different hotkey name",
+                    f"Delete the existing hotkey first: htcli wallet delete --coldkey {coldkey_request.name} --hotkey {hotkey_name}",
+                    f"Use 'htcli wallet list' to see existing hotkeys",
+                ],
+            )
+            # Offer cleanup option
+            console.print()
+            print_warning(
+                f"⚠️  Coldkey '{coldkey_request.name}' was created successfully, but hotkey creation failed."
+            )
+            if confirm_prompt(
+                f"Would you like to delete the coldkey '{coldkey_request.name}' that was just created?",
+                default=False,
+            ):
+                try:
+                    wallet_manager.delete_wallet(coldkey_request.name, is_hotkey=False)
+                    console.print(
+                        success(f"✅ Coldkey '{coldkey_request.name}' has been deleted")
+                    )
+                except Exception as cleanup_error:
+                    print_error(
+                        f"❌ Failed to delete coldkey during cleanup: {str(cleanup_error)}",
+                        suggestions=[
+                            f"• Manually delete the coldkey: htcli wallet delete --coldkey {coldkey_request.name}",
+                        ],
+                    )
+            return
+
+        hotkey_request = prompt_wallet_creation(
+            name=hotkey_name,
+            key_type=key_type,
+            wallet_type="hotkey",
+            coldkey_name=coldkey_request.name,
+            password=password,  # Hotkeys typically don't use passwords, but allow it
+        )
+        creation_state["hotkey_name"] = hotkey_request.name
+
+        # STEP 3: Create hotkey
+        try:
+            hotkey_result = wallet_manager.create_hotkey_wallet(
+                name=hotkey_request.name,
+                owner_address=coldkey_address,
+                password=hotkey_request.password,
+                owner_coldkey_name=coldkey_request.name,
+            )
+            creation_state["hotkey_created"] = True
+            console.print(
+                success(f"✅ Hotkey '{hotkey_request.name}' created successfully")
+            )
+        except Exception as e:
+            print_error(
+                f"❌ Failed to create hotkey '{hotkey_request.name}': {str(e)}",
+                suggestions=[
+                    f"• Check that the hotkey name is valid",
+                    f"• Ensure the coldkey '{coldkey_request.name}' is valid",
+                    f"• Try a different hotkey name",
+                ],
+            )
+            # Offer cleanup option
+            console.print()
+            print_warning(
+                f"⚠️  Coldkey '{coldkey_request.name}' was created successfully, but hotkey creation failed."
+            )
+            if confirm_prompt(
+                f"Would you like to delete the coldkey '{coldkey_request.name}' that was just created?",
+                default=False,
+            ):
+                try:
+                    wallet_manager.delete_wallet(coldkey_request.name, is_hotkey=False)
+                    console.print(
+                        success(f"✅ Coldkey '{coldkey_request.name}' has been deleted")
+                    )
+                except Exception as cleanup_error:
+                    print_error(
+                        f"❌ Failed to delete coldkey during cleanup: {str(cleanup_error)}",
+                        suggestions=[
+                            f"• Manually delete the coldkey: htcli wallet delete --coldkey {coldkey_request.name}",
+                        ],
+                    )
+            return
+
+        hotkey_response = WalletCreateResponse(
+            name=hotkey_result["data"]["name"],
+            address=hotkey_result["data"]["ss58_address"],
+            public_key=hotkey_result["data"]["public_key"],
+            key_type=hotkey_result["data"]["key_type"],
+            wallet_type="hotkey",
+            mnemonic=hotkey_result["data"]["mnemonic"],
+            encrypted=hotkey_result["data"]["is_encrypted"],
+        )
+
+        # STEP 4: Display unified results
+        console.print()
+        display_wallet_generation_result(
+            coldkey_response,
+            hotkey_response,
+            copy_mnemonic=copy_mnemonic,
+        )
+
+    except KeyboardInterrupt:
+        # User cancelled - provide cleanup option if partial creation occurred
+        console.print()
+        print_warning("Operation cancelled")
+
+        if creation_state["coldkey_created"] and not creation_state["hotkey_created"]:
+            print_warning(
+                f"⚠️  Coldkey '{creation_state['coldkey_name']}' was created before cancellation."
+            )
+            if confirm_prompt(
+                f"Would you like to delete the coldkey '{creation_state['coldkey_name']}'?",
+                default=False,
+            ):
+                try:
+                    wallet_manager = WalletManager()
+                    wallet_manager.delete_wallet(
+                        creation_state["coldkey_name"], is_hotkey=False
+                    )
+                    console.print(
+                        success(
+                            f"✅ Coldkey '{creation_state['coldkey_name']}' has been deleted"
+                        )
+                    )
+                except Exception as cleanup_error:
+                    print_error(
+                        f"❌ Failed to delete coldkey during cleanup: {str(cleanup_error)}",
+                        suggestions=[
+                            f"• Manually delete the coldkey: htcli wallet delete --coldkey {creation_state['coldkey_name']}",
+                        ],
+                    )
+        return
+
+    except Exception as e:
+        from ...errors.handlers import handle_wallet_error
+
+        # Provide detailed error information based on what was created
+        error = handle_wallet_error(e, "generate")
+
+        console.print()
+        if creation_state["coldkey_created"] and not creation_state["hotkey_created"]:
+            print_error(
+                f"❌ {error.message}",
+                suggestions=error.suggestions
+                + [
+                    f"⚠️  Note: Coldkey '{creation_state['coldkey_name']}' was created successfully",
+                    f"• You can delete it: htcli wallet delete --coldkey {creation_state['coldkey_name']}",
+                    f"• Or use it with a different hotkey name",
+                ],
+            )
+            # Offer cleanup
+            if confirm_prompt(
+                f"Would you like to delete the coldkey '{creation_state['coldkey_name']}' that was created?",
+                default=False,
+            ):
+                try:
+                    wallet_manager = WalletManager()
+                    wallet_manager.delete_wallet(
+                        creation_state["coldkey_name"], is_hotkey=False
+                    )
+                    console.print(
+                        success(
+                            f"✅ Coldkey '{creation_state['coldkey_name']}' has been deleted"
+                        )
+                    )
+                except Exception as cleanup_error:
+                    print_error(
+                        f"❌ Failed to delete coldkey during cleanup: {str(cleanup_error)}",
+                        suggestions=[
+                            f"• Manually delete the coldkey: htcli wallet delete --coldkey {creation_state['coldkey_name']}",
+                        ],
+                    )
+        elif creation_state["coldkey_created"] and creation_state["hotkey_created"]:
+            # Both created but something else failed - unlikely but handle it
+            print_error(
+                f"❌ {error.message}",
+                suggestions=error.suggestions
+                + [
+                    "⚠️  Note: Both coldkey and hotkey were created successfully",
+                    "• The wallets should be available in your wallet list",
+                ],
+            )
+        else:
+            # Nothing was created
+            print_error(error.message, suggestions=error.suggestions)
+
+
+def restore_coldkey_handler(
+    name: Optional[str] = None,
+    private_key: Optional[str] = None,
+    mnemonic: Optional[str] = None,
+    key_type: Optional[str] = None,
+    password: Optional[str] = None,
+):
+    """Handle coldkey restoration command."""
+    try:
+        # Early check: if name is provided via CLI, check existence before prompting
+        from ...ui.display import print_error
+        from ...utils.wallet.crypto import get_wallet_info_by_name
+
+        if name:
+            try:
+                get_wallet_info_by_name(name, is_hotkey=False)
+                # If we get here, wallet exists
+                print_error(
+                    f"Wallet '{name}' already exists! Please choose a different name or delete the existing wallet first."
+                )
+                return
+            except FileNotFoundError:
+                # Good - wallet doesn't exist, can proceed
+                pass
+
+        # STEP 1: Collect input parameters
+        request = prompt_wallet_restoration(
+            name=name,
+            private_key=private_key,
+            mnemonic=mnemonic,
+            key_type=key_type,
+            wallet_type="coldkey",
+            password=password,
+        )
+
+        # STEP 2: Execute via client layer
+        wallet_manager = WalletManager()
+        if request.private_key:
+            result = wallet_manager.import_coldkey_from_private_key(
+                name=request.name,
+                private_key=request.private_key,
+                key_type=request.key_type,
+                password=request.password,
+            )
+            keypair_info = type(
+                "KeypairInfo", (), result["data"]
+            )()  # Convert dict to object
+            import_method = "private key"
+        else:
+            result = wallet_manager.import_coldkey_from_mnemonic(
+                name=request.name,
+                mnemonic=request.mnemonic,
+                key_type=request.key_type,
+                password=request.password,
+            )
+            keypair_info = type(
+                "KeypairInfo", (), result["data"]
+            )()  # Convert dict to object
+            import_method = "mnemonic phrase"
+        response = WalletCreateResponse(
+            name=keypair_info.name,
+            address=keypair_info.ss58_address,
+            public_key=keypair_info.public_key,
+            key_type=keypair_info.key_type,
+            wallet_type="coldkey",
+            mnemonic=getattr(
+                keypair_info, "mnemonic", None
+            ),  # Include mnemonic if available
+            encrypted=(request.password is not None),
+        )
+
+        # Check if there are any existing hotkeys that might be associated with this coldkey
+        # (This can happen if hotkey files weren't fully deleted)
+        from ...utils.wallet.crypto import list_keys, coldkey_has_hotkey
+
+        coldkey_address = keypair_info.ss58_address
+        all_keys = list_keys()
+        existing_hotkeys = [
+            k
+            for k in all_keys
+            if k.get("is_hotkey", False)
+            and (
+                k.get("owner_address") == coldkey_address
+                or k.get("owner_coldkey_name") == keypair_info.name
+            )
+        ]
+
+        if existing_hotkeys:
+            console.print()
+            console.print(
+                warning(
+                    f"⚠️  Found {len(existing_hotkeys)} existing hotkey(s) that may be associated with this coldkey:"
+                )
+            )
+            for hk in existing_hotkeys:
+                console.print(f"  • {hk.get('name')} ({hk.get('ss58_address', 'N/A')})")
+            console.print(
+                info(
+                    "Note: Restoring a coldkey does NOT automatically create hotkeys. "
+                    "These hotkeys were already present. Use 'htcli wallet restore-hotkey' to restore hotkeys separately."
+                )
+            )
+            console.print()
+
+        # STEP 3: Display results
+        display_wallet_restoration_result(response, import_method)
+
+    except Exception as e:
+        from ...errors.handlers import handle_wallet_error
+        from ...ui.display import print_error
+
+        error = handle_wallet_error(e, "update")
+        print_error(error.message, suggestions=error.suggestions)
+
+
+def restore_hotkey_handler(
+    name: Optional[str] = None,
+    private_key: Optional[str] = None,
+    mnemonic: Optional[str] = None,
+    owner_name: Optional[
+        str
+    ] = None,  # Keep for backward compatibility, maps to coldkey_name
+    key_type: Optional[str] = None,
+    password: Optional[str] = None,
+):
+    """Handle hotkey restoration command."""
+    try:
+        # STEP 1: Collect input parameters
+        request = prompt_wallet_restoration(
+            name=name,
+            private_key=private_key,
+            mnemonic=mnemonic,
+            key_type=key_type,
+            wallet_type="hotkey",
+            coldkey_name=owner_name,  # Map owner_name to coldkey_name
+            password=password,
+        )
+
+        # Resolve coldkey name to address
+        coldkey_info = get_wallet_info_by_name(request.owner_address, is_hotkey=False)
+        if coldkey_info.get("is_hotkey", False):
+            raise ValueError(
+                f"'{request.owner_address}' is a hotkey. Please provide a coldkey name."
+            )
+
+        # Check if this specific coldkey already has a hotkey with this name
+        from ...ui.display import print_error
+        from ...utils.wallet.crypto import coldkey_has_hotkey
+
+        coldkey_address = coldkey_info.get("ss58_address") or coldkey_info.get(
+            "address"
+        )
+        if not coldkey_address:
+            raise ValueError(
+                f"Could not determine address for coldkey '{request.owner_address}'"
+            )
+
+        if coldkey_has_hotkey(coldkey_address, request.name):
+            print_error(
+                f"Coldkey '{request.owner_address}' already has a hotkey named '{request.name}'. "
+                "Please choose a different name for this hotkey."
+            )
+            return
+
+        # STEP 2: Execute via client layer
+        wallet_manager = WalletManager()
+        if request.private_key:
+            result = wallet_manager.import_hotkey_from_private_key(
+                name=request.name,
+                private_key=request.private_key,
+                owner_address=coldkey_address,
+                key_type=request.key_type,
+                password=request.password,
+            )
+            keypair_info = type(
+                "KeypairInfo", (), result["data"]
+            )()  # Convert dict to object
+            import_method = "private key"
+        else:
+            result = wallet_manager.import_hotkey_from_mnemonic(
+                name=request.name,
+                mnemonic=request.mnemonic,
+                owner_address=coldkey_address,
+                key_type=request.key_type,
+                password=request.password,
+            )
+            keypair_info = type(
+                "KeypairInfo", (), result["data"]
+            )()  # Convert dict to object
+            import_method = "mnemonic phrase"
+
+        # Create response model - use evm_address if available, otherwise ss58_address
+        address = (
+            getattr(keypair_info, "evm_address", None) or keypair_info.ss58_address
+        )
+        response = WalletCreateResponse(
+            name=keypair_info.name,
+            address=address,
+            public_key=keypair_info.public_key,
+            key_type=keypair_info.key_type,
+            wallet_type="hotkey",
+            mnemonic=getattr(
+                keypair_info, "mnemonic", None
+            ),  # Include mnemonic if available
+            encrypted=(request.password is not None),
+        )
+
+        # STEP 3: Display results
+        display_wallet_restoration_result(
+            response,
+            import_method,
+            owner_name=request.owner_address,
+            owner_address=coldkey_address,
+        )
+
+    except Exception as e:
+        from ...errors.handlers import handle_wallet_error
+        from ...ui.display import print_error
+
+        error = handle_wallet_error(e, "restore")
+        print_error(error.message, suggestions=error.suggestions)
+
+
+def import_preseeded_handler(
+    preseeded_name: str,
+    custom_name: Optional[str] = None,
+    key_type: Optional[str] = None,
+):
+    """Handle preseeded wallet import command."""
+    try:
+        # STEP 1: Collect input parameters
+        request = prompt_preseeded_wallet(
+            preseeded_name=preseeded_name, custom_name=custom_name, key_type=key_type
+        )
+
+        # STEP 2: Execute via client layer
+        wallet_manager = WalletManager()
+        result = wallet_manager.import_preseeded_wallet(
+            preseeded_name=request.preseeded_name,
+            wallet_name=request.custom_name or request.preseeded_name,
+            password=request.password,
+        )
+        keypair_info = type(
+            "KeypairInfo", (), result["data"]
+        )()  # Convert dict to object
+
+        # Create response model
+        response = WalletCreateResponse(
+            name=keypair_info.name,
+            address=keypair_info.ss58_address,
+            public_key=keypair_info.public_key,
+            key_type=keypair_info.key_type,
+            wallet_type="coldkey",
+            mnemonic=getattr(
+                keypair_info, "mnemonic", None
+            ),  # Include mnemonic if available
+            encrypted=(request.password is not None),
+        )
+
+        # STEP 3: Display results
+        display_wallet_creation_result(response, preseeded_name=preseeded_name)
+
+    except Exception as e:
+        from ...errors.handlers import handle_wallet_error
+        from ...ui.display import print_error
+
+        error = handle_wallet_error(e, "update")
+        print_error(error.message, suggestions=error.suggestions)
+
+
+def list_wallets_handler(
+    format_type: str = "tree",
+    show_balances: bool = False,
+):
+    """Handle wallet listing command."""
+    try:
+        # STEP 1: No input needed for listing
+
+        # STEP 2: Execute via client layer
+        wallet_manager = WalletManager()
+        result = wallet_manager.list_wallets()
+        wallets = result["data"]
+
+        # Count wallet types
+        coldkeys = sum(1 for w in wallets if not w.get("is_hotkey", False))
+        hotkeys = sum(1 for w in wallets if w.get("is_hotkey", False))
+
+        # Create response model
+        response = WalletListResponse(
+            wallets=wallets,
+            total_count=len(wallets),
+            coldkeys=coldkeys,
+            hotkeys=hotkeys,
+        )
+
+        # STEP 3: Display results
+        display_wallet_list(response, format_type=format_type)
+
+    except Exception as e:
+        from ...errors.handlers import handle_wallet_error
+        from ...ui.display import print_error
+
+        error = handle_wallet_error(e, "update")
+        print_error(error.message, suggestions=error.suggestions)
+
+
+def status_handler(
+    format_type: str = "table",
+    check_balances: bool = False,
+):
+    """Handle wallet status command."""
+    try:
+        # STEP 1: No input needed for status
+
+        # STEP 2: Execute via client layer
+        wallet_manager = WalletManager()
+        result = wallet_manager.list_wallets()
+        wallets = result["data"]
+
+        # Create response model
+        response = WalletStatusResponse(
+            wallets=wallets, total_keys=len(wallets), total_addresses=len(wallets)
+        )
+
+        # STEP 3: Display results
+        display_wallet_status(response, format_type=format_type)
+
+    except Exception as e:
+        from ...errors.handlers import handle_wallet_error
+        from ...ui.display import print_error
+
+        error = handle_wallet_error(e, "update")
+        print_error(error.message, suggestions=error.suggestions)
+
+
+def delete_handler(
+    coldkey: Optional[str] = None,
+    hotkey: Optional[str] = None,
+    force: bool = False,
+):
+    """Handle wallet deletion command.
+
+    Args:
+        coldkey: Coldkey name to delete (required for coldkey deletion)
+        hotkey: Hotkey name to delete (requires coldkey to specify owner)
+        force: Skip confirmation prompts
+    """
+    try:
+        # Validate parameters
+        if not coldkey and not hotkey:
+            from ...ui.display import print_error
+
+            print_error(
+                "Either --coldkey or both --coldkey and --hotkey must be provided",
+                suggestions=[
+                    "To delete a coldkey: htcli wallet delete --coldkey <name>",
+                    "To delete a hotkey: htcli wallet delete --coldkey <owner_name> --hotkey <name>",
+                ],
+            )
+            return
+
+        if hotkey and not coldkey:
+            # Check if this is an orphaned hotkey (owner doesn't exist)
+            wallet_manager = WalletManager()
+            all_keys = list_keys()
+
+            # Find all hotkeys with this name
+            matching_hotkeys = [
+                k
+                for k in all_keys
+                if k.get("is_hotkey", False) and k.get("name") == hotkey
+            ]
+
+            if not matching_hotkeys:
+                from ...ui.display import print_error
+
+                print_error(
+                    f"Hotkey '{hotkey}' not found",
+                    suggestions=[
+                        "Use: htcli wallet list to see all wallets",
+                    ],
+                )
+                return
+
+            # Check if any of the matching hotkeys are orphaned
+            orphaned_hotkeys = []
+            valid_hotkeys = []
+
+            # Get all coldkey addresses for comparison
+            coldkey_addresses = {
+                k.get("evm_address") or k.get("ss58_address") or k.get("address")
+                for k in all_keys
+                if not k.get("is_hotkey", False)
+            }
+            coldkey_names = {
+                k.get("name") for k in all_keys if not k.get("is_hotkey", False)
+            }
+
+            for hk in matching_hotkeys:
+                owner_address = hk.get("owner_address")
+                owner_coldkey_name = hk.get("owner_coldkey_name")
+
+                # Check if owner exists
+                owner_found = False
+                if owner_address and owner_address in coldkey_addresses:
+                    owner_found = True
+                elif owner_coldkey_name and owner_coldkey_name in coldkey_names:
+                    owner_found = True
+
+                if owner_found:
+                    valid_hotkeys.append(hk)
+                else:
+                    orphaned_hotkeys.append(hk)
+
+            if orphaned_hotkeys and not valid_hotkeys:
+                # All matching hotkeys are orphaned - allow deletion without coldkey
+                # We'll handle this in the deletion logic below
+                pass
+            elif valid_hotkeys:
+                # At least one hotkey has a valid owner - require coldkey for disambiguation
+                from ...ui.display import print_error
+
+                if len(valid_hotkeys) > 1:
+                    print_error(
+                        f"Found {len(valid_hotkeys)} hotkeys named '{hotkey}' with valid owners. Please specify --coldkey to disambiguate.",
+                        suggestions=[
+                            "Use: htcli wallet delete --coldkey <owner_name> --hotkey <name>",
+                            "Or use: htcli wallet list to see all wallets",
+                        ],
+                    )
+                else:
+                    print_error(
+                        f"Hotkey '{hotkey}' has a valid owner. Please specify --coldkey to delete it.",
+                        suggestions=[
+                            f"Use: htcli wallet delete --coldkey <owner_name> --hotkey {hotkey}",
+                        ],
+                    )
+                return
+            # If we get here, all matching hotkeys are orphaned - continue with deletion
+
+        # STEP 1: Collect input parameters
+        # If coldkey is provided but doesn't exist, check if hotkey is orphaned
+        if hotkey and coldkey:
+            try:
+                # Try to verify coldkey exists
+                wallet_manager_temp = WalletManager()
+                wallet_manager_temp.get_wallet_info(coldkey, is_hotkey=False)
+            except (ValueError, FileNotFoundError):
+                # Coldkey doesn't exist - check if hotkey is orphaned
+                all_keys = list_keys()
+                matching_hotkeys = [
+                    k
+                    for k in all_keys
+                    if k.get("is_hotkey", False) and k.get("name") == hotkey
+                ]
+
+                if matching_hotkeys:
+                    # Get all coldkey addresses and names for comparison
+                    coldkey_addresses = {
+                        k.get("evm_address")
+                        or k.get("ss58_address")
+                        or k.get("address")
+                        for k in all_keys
+                        if not k.get("is_hotkey", False)
+                    }
+                    coldkey_names = {
+                        k.get("name") for k in all_keys if not k.get("is_hotkey", False)
+                    }
+
+                    # Check if any matching hotkey is orphaned
+                    is_orphaned = True
+                    for hk in matching_hotkeys:
+                        owner_address = hk.get("owner_address")
+                        owner_coldkey_name = hk.get("owner_coldkey_name")
+
+                        if owner_address and owner_address in coldkey_addresses:
+                            is_orphaned = False
+                            break
+                        elif owner_coldkey_name and owner_coldkey_name in coldkey_names:
+                            is_orphaned = False
+                            break
+
+                    if is_orphaned:
+                        # Hotkey is orphaned - treat as if no coldkey was provided
+                        from ...ui.display import print_warning
+
+                        console.print()
+                        print_warning(
+                            f"Coldkey '{coldkey}' does not exist, but hotkey '{hotkey}' appears to be orphaned. "
+                            "Proceeding with orphaned hotkey deletion."
+                        )
+                        console.print()
+                        coldkey = None  # Clear coldkey so it's treated as orphaned
+
+        try:
+            request = prompt_wallet_deletion(
+                coldkey=coldkey, hotkey=hotkey, force=force
+            )
+        except KeyboardInterrupt:
+            # User cancelled the deletion
+            from ...ui.display import print_info
+
+            console.print()
+            print_info("✋ Deletion cancelled - no wallets were deleted")
+            return
+
+        # STEP 2: Execute via client layer
+        wallet_manager = WalletManager()
+        total_deleted = 0
+        coldkeys_deleted = 0
+        hotkeys_deleted = 0
+        associated_hotkeys_deleted = 0
+        associated_hotkey_details = []  # List of dicts with name and owner
+        successfully_deleted = []
+
+        try:
+            # Determine what we're deleting
+            if hotkey:
+                # Deleting a hotkey
+                wallet_name = hotkey
+
+                if coldkey:
+                    # Owner specified - use it for disambiguation
+                    owner_coldkey_name = coldkey
+
+                    # Get owner address from coldkey name
+                    try:
+                        coldkey_info_result = wallet_manager.get_wallet_info(
+                            coldkey,
+                            is_hotkey=False,
+                        )
+                        owner_address = (
+                            coldkey_info_result["data"].get("evm_address")
+                            or coldkey_info_result["data"].get("ss58_address")
+                            or coldkey_info_result["data"].get("address")
+                        )
+                    except (ValueError, FileNotFoundError) as e:
+                        console.print(
+                            warning(f"❌ Coldkey '{coldkey}' does not exist.")
+                        )
+                        return
+
+                    # Check if hotkey exists
+                    try:
+                        wallet_info_result = wallet_manager.get_wallet_info(
+                            wallet_name,
+                            is_hotkey=True,
+                            owner_address=owner_address,
+                            owner_coldkey_name=owner_coldkey_name,
+                        )
+                    except (ValueError, FileNotFoundError) as e:
+                        console.print(
+                            warning(
+                                f"❌ Hotkey '{hotkey}' owned by '{coldkey}' does not exist."
+                            )
+                        )
+                        return
+
+                    # Delete hotkey
+                    result = wallet_manager.delete_wallet(
+                        wallet_name,
+                        is_hotkey=True,
+                        owner_address=owner_address,
+                        owner_coldkey_name=owner_coldkey_name,
+                    )
+                else:
+                    # No owner specified - this is an orphaned hotkey
+                    # Find the hotkey without owner context
+                    try:
+                        # Try to get wallet info - this will work for orphaned hotkeys
+                        # since they don't have a valid owner to disambiguate
+                        all_keys = list_keys()
+                        matching_hotkeys = [
+                            k
+                            for k in all_keys
+                            if k.get("is_hotkey", False) and k.get("name") == hotkey
+                        ]
+
+                        if not matching_hotkeys:
+                            console.print(warning(f"❌ Hotkey '{hotkey}' not found."))
+                            return
+
+                        # For orphaned hotkeys, use the owner_address from the file itself
+                        # (even though the owner doesn't exist)
+                        hotkey_info = matching_hotkeys[0]  # Use first match
+                        owner_address = hotkey_info.get("owner_address")
+                        owner_coldkey_name = hotkey_info.get("owner_coldkey_name")
+
+                        # Get wallet info using the owner_address from the file
+                        wallet_info_result = wallet_manager.get_wallet_info(
+                            wallet_name,
+                            is_hotkey=True,
+                            owner_address=owner_address,
+                            owner_coldkey_name=owner_coldkey_name,
+                        )
+
+                        # Delete orphaned hotkey
+                        result = wallet_manager.delete_wallet(
+                            wallet_name,
+                            is_hotkey=True,
+                            owner_address=owner_address,
+                            owner_coldkey_name=owner_coldkey_name,
+                        )
+                    except (ValueError, FileNotFoundError) as e:
+                        console.print(warning(f"❌ Hotkey '{hotkey}' not found."))
+                        return
+
+                hotkeys_deleted += 1
+                total_deleted += 1
+                successfully_deleted.append(wallet_name)
+            else:
+                # Deleting a coldkey
+                wallet_name = coldkey
+
+                # Check if coldkey exists
+                try:
+                    wallet_info_result = wallet_manager.get_wallet_info(
+                        wallet_name,
+                        is_hotkey=False,
+                    )
+                except (ValueError, FileNotFoundError) as e:
+                    console.print(warning(f"❌ Coldkey '{coldkey}' does not exist."))
+                    return
+
+                # Use deletion plan if available
+                if request.deletion_plan and wallet_name in request.deletion_plan:
+                    plan = request.deletion_plan[wallet_name]
+                    if plan["delete_hotkeys"]:
+                        result = wallet_manager.delete_coldkey_and_hotkeys(wallet_name)
+                        hotkeys_count = len(plan["associated_hotkeys"])
+                        associated_hotkeys_deleted += hotkeys_count
+                        # Collect hotkey details
+                        for hotkey_info in plan["associated_hotkeys"]:
+                            associated_hotkey_details.append(
+                                {"name": hotkey_info["name"], "owner": wallet_name}
+                            )
+                    else:
+                        # Delete only coldkey, leave hotkeys orphaned
+                        result = wallet_manager.delete_wallet(
+                            wallet_name, is_hotkey=False
+                        )
+                    coldkeys_deleted += 1
+                else:
+                    # Default: delete coldkey and all associated hotkeys
+                    result = wallet_manager.delete_coldkey_and_hotkeys(wallet_name)
+                    coldkeys_deleted += 1
+                    total_hotkeys = result["data"].get("total_hotkeys_deleted", 0)
+                    associated_hotkeys_deleted += total_hotkeys
+                    # Try to get hotkey details from result if available
+                    if "hotkeys_deleted" in result["data"]:
+                        for hotkey_name in result["data"]["hotkeys_deleted"]:
+                            associated_hotkey_details.append(
+                                {"name": hotkey_name, "owner": wallet_name}
+                            )
+                total_deleted += 1
+                successfully_deleted.append(wallet_name)
+
+        except FileNotFoundError as e:
+            # Wallet doesn't exist
+            console.print(warning(f"❌ Wallet does not exist: {str(e)}"))
+        except Exception as e:
+            # If deletion fails
+            error_msg = str(e) if str(e) else repr(e)
+            tb_str = traceback.format_exc()
+            console.print(warning(f"❌ Failed to delete wallet: {error_msg}"))
+            console.print(f"[dim]Traceback:[/dim]\n{tb_str}")
+            logger.error(f"Delete error: {tb_str}")
+
+        # Create response model
+        response = WalletDeleteResponse(
+            deleted_wallets=successfully_deleted,
+            total_deleted=total_deleted,
+            coldkeys_deleted=coldkeys_deleted,
+            hotkeys_deleted=hotkeys_deleted,
+            associated_hotkeys_deleted=associated_hotkeys_deleted,
+            associated_hotkey_details=associated_hotkey_details,
+        )
+
+        # STEP 3: Display results
+        if total_deleted > 0:
+            display_wallet_deletion_result(response)
+        else:
+            console.print(warning("❌ No wallets were deleted."))
+
+    except Exception as e:
+        from ...errors.handlers import handle_wallet_error
+        from ...ui.display import print_error
+
+        # Show full traceback for debugging
+        tb_str = traceback.format_exc()
+        logger.error(f"Delete handler error: {tb_str}")
+        console.print(f"[red]Full traceback:[/red]\n{tb_str}")
+        error = handle_wallet_error(e, "delete")
+        print_error(error.message, suggestions=error.suggestions)
+
+
+def _update_spinner_messages(spinner: HTCLISpinner, stop_event: threading.Event):
+    """Update spinner messages every 2 seconds."""
+    messages = [
+        "Checking wallet balance...",
+        "Connecting to blockchain...",
+        "Fetching balance data...",
+        "Processing wallet information...",
+        "Retrieving account details...",
+        "Verifying wallet status...",
+    ]
+
+    message_index = 0
+    while not stop_event.is_set():
+        try:
+            spinner.update(messages[message_index])
+            message_index = (message_index + 1) % len(messages)
+            time.sleep(2)
+        except Exception:
+            break
+
+
+def balance_handler(
+    wallet_name: Optional[str] = None,
+    address: Optional[str] = None,
+    show_all: bool = False,
+    format_type: str = "table",
+    show_guidance: Optional[bool] = None,
+):
+    """Handle wallet balance command."""
+    try:
+        from ...dependencies import get_client
+        from ...ui.display import print_error
+        from ...utils.wallet.auth import get_wallet_with_retry
+
+        # STEP 1: Collect input parameters
+        wallet_name, address, show_all, format_type, show_guidance = (
+            prompt_wallet_balance(
+                wallet_name, address, show_all, format_type, show_guidance
+            )
+        )
+
+        # STEP 2: Get client and ensure connection
+        client = get_client()
+
+        # Ensure connection is established
+        if not client.substrate:
+            if not client.connect():
+                print_error("Failed to connect to blockchain. Cannot fetch balances.")
+                return
+
+        # Verify RPC layer is initialized
+        if not client.rpc or not client.rpc.wallet:
+            print_error("RPC client not initialized. Cannot fetch balances.")
+            return
+
+        # STEP 3: Execute
+        network_name = _get_network_name(client)
+        if show_all:
+            wallets = [w for w in list_keys() if not w.get("is_hotkey")]
+            if not wallets:
+                console.print(warning("No coldkeys found."))
+                return
+
+            # Iterate through all wallets and get balances with spinner
+            wallet_balances = []
+            total_free_balance = 0
+            total_direct_stake = 0
+            total_delegate_stake = 0
+            total_node_delegate_stake = 0
+            total_overwatch_stake = 0
+            total_unbonding = 0
+            total_staked_balance = 0
+
+            from ...ui.components import HTCLILoadingContext
+
+            # Use a single spinner that updates in place
+            loading = HTCLILoadingContext("Checking wallet balances...", transient=True)
+            loading.__enter__()
+
+            try:
+                for idx, wallet in enumerate(wallets):
+                    wallet_name = wallet["name"]
+                    wallet_info = get_wallet_info_by_name(wallet_name)
+
+                    # Update spinner message to show current wallet
+                    loading.update_message(
+                        f"Checking wallet '{wallet_name}' ({idx + 1}/{len(wallets)})..."
+                    )
+
+                    # Check if wallet is encrypted
+                    is_encrypted = wallet_info.get(
+                        "is_encrypted", False
+                    ) or wallet_info.get("encrypted", False)
+
+                    display_address = wallet_info.get(
+                        "ss58_address"
+                    ) or wallet_info.get("address")
+                    query_address = wallet_info.get("address") or display_address
+
+                    # Debug print to show what address is being queried
+                    from ...utils.logging import get_logger
+
+                    logger = get_logger(__name__)
+                    logger.debug(
+                        f"[show_all] Wallet '{wallet_name}' - query_address: {query_address}, display_address: {display_address}"
+                    )
+
+                    # Get address - for encrypted wallets, unlock them first
+                    try:
+                        if is_encrypted:
+                            # Stop spinner before password prompt to avoid mixing output
+                            loading.__exit__(None, None, None)
+                            # Prompt for password (this will print normally)
+                            # Use silent=True to suppress intermediate error messages
+                            _keypair, _ = get_wallet_with_retry(
+                                wallet_name, silent=True
+                            )
+                            # Restart spinner after password entry
+                            loading.__enter__()
+                            loading.update_message(
+                                f"Fetching balance for '{wallet_name}'..."
+                            )
+                        else:
+                            loading.update_message(
+                                f"Fetching balance for '{wallet_name}'..."
+                            )
+
+                        # Get balance from blockchain
+                        response = client.rpc.wallet.get_balance(query_address)
+
+                        # Ensure displayed address matches wallet list output
+                        if response and display_address:
+                            try:
+                                response.address = display_address
+                            except Exception:
+                                pass
+
+                        if response and response.success:
+                            free_balance = response.balance or 0
+                            staking_breakdown = _get_staking_breakdown(
+                                client, query_address
+                            )
+                            staked_balance = staking_breakdown["total"]
+                            wallet_balances.append(
+                                {
+                                    "name": wallet_name,
+                                    "address": display_address or query_address,
+                                    "free_balance": free_balance,
+                                    "direct_stake": staking_breakdown["direct_stake"],
+                                    "delegate_stake": staking_breakdown[
+                                        "delegate_stake"
+                                    ],
+                                    "node_delegate_stake": staking_breakdown[
+                                        "node_delegate_stake"
+                                    ],
+                                    "overwatch_stake": staking_breakdown[
+                                        "overwatch_stake"
+                                    ],
+                                    "unbonding": staking_breakdown["unbonding"],
+                                    "staked_balance": staked_balance,
+                                    "total_balance": free_balance + staked_balance,
+                                }
+                            )
+                            total_free_balance += free_balance
+                            total_direct_stake += staking_breakdown["direct_stake"]
+                            total_delegate_stake += staking_breakdown["delegate_stake"]
+                            total_node_delegate_stake += staking_breakdown[
+                                "node_delegate_stake"
+                            ]
+                            total_overwatch_stake += staking_breakdown[
+                                "overwatch_stake"
+                            ]
+                            total_unbonding += staking_breakdown["unbonding"]
+                            total_staked_balance += staked_balance
+                        else:
+                            error_msg = response.error if response else "Unknown Error"
+                            wallet_balances.append(
+                                {
+                                    "name": wallet_name,
+                                    "address": display_address or query_address,
+                                    "free_balance": 0,
+                                    "staked_balance": 0,
+                                    "total_balance": 0,
+                                    "display_free": f"[red]{error_msg}[/red]",
+                                    "display_staked": "[red]--[/red]",
+                                    "display_total": "[red]--[/red]",
+                                    "error": error_msg,
+                                }
+                            )
+                    except Exception as e:
+                        # Stop spinner before printing error
+                        if (
+                            loading.spinner
+                            and hasattr(loading.spinner, "_running")
+                            and loading.spinner._running
+                        ):
+                            loading.__exit__(None, None, None)
+                        # Skip wallet if it can't be unlocked or balance can't be fetched
+                        console.print(warning(f"Skipping '{wallet_name}': {str(e)}"))
+                        # Restart spinner for next wallet
+                        if idx < len(wallets) - 1:
+                            loading.__enter__()
+                        continue
+            finally:
+                # Ensure spinner is stopped
+                if (
+                    loading.spinner
+                    and hasattr(loading.spinner, "_running")
+                    and loading.spinner._running
+                ):
+                    loading.__exit__(None, None, None)
+
+            # Display results
+            display_all_wallet_balances(
+                wallet_balances,
+                {
+                    "free": total_free_balance,
+                    "direct_stake": total_direct_stake,
+                    "delegate_stake": total_delegate_stake,
+                    "node_delegate_stake": total_node_delegate_stake,
+                    "overwatch_stake": total_overwatch_stake,
+                    "unbonding": total_unbonding,
+                    "staked": total_staked_balance,
+                    "total": total_free_balance + total_staked_balance,
+                },
+                format_type,
+                network_name=network_name,
+            )
+        else:
+            # Single wallet balance check
+            from ...ui.components import HTCLILoadingContext
+            from ...ui.display import print_error
+
+            wallet_type = "External Address"
+            if wallet_name:
+                wallet_info = get_wallet_info_by_name(wallet_name)
+
+                # Check encryption status explicitly
+                is_encrypted = wallet_info.get(
+                    "is_encrypted", False
+                ) or wallet_info.get("encrypted", False)
+
+                # Use spinner for single wallet check too
+                loading = HTCLILoadingContext(
+                    f"Checking wallet '{wallet_name}'...", transient=True
+                )
+                loading.__enter__()
+
+                try:
+                    display_address = wallet_info.get(
+                        "ss58_address"
+                    ) or wallet_info.get("address")
+                    query_address = wallet_info.get("address") or display_address
+
+                    # Debug print to show what address is being queried
+                    from ...utils.logging import get_logger
+
+                    logger = get_logger(__name__)
+                    logger.debug(
+                        f"[single wallet] Wallet '{wallet_name}' - query_address: {query_address}, display_address: {display_address}"
+                    )
+                    logger.debug(f"[single wallet] Wallet info: {wallet_info}")
+
+                    if is_encrypted:
+                        try:
+                            # Stop spinner before password prompt
+                            loading.__exit__(None, None, None)
+                            # Use silent=True to suppress intermediate error messages
+                            _keypair, _ = get_wallet_with_retry(
+                                wallet_name, silent=True
+                            )
+                            # Restart spinner after password entry
+                            loading.__enter__()
+                            loading.update_message(
+                                f"Fetching balance for '{wallet_name}'..."
+                            )
+                        except Exception as e:
+                            print_error(
+                                f"Failed to unlock wallet '{wallet_name}': {str(e)}"
+                            )
+                            return
+                    else:
+                        loading.update_message(
+                            f"Fetching balance for '{wallet_name}'..."
+                        )
+
+                    wallet_type = (
+                        "Hotkey" if wallet_info.get("is_hotkey", False) else "Coldkey"
+                    )
+
+                    # Get balance for single wallet
+                    response = None
+                    try:
+                        # Ensure client is connected
+                        if not client.substrate:
+                            if not client.connect():
+                                loading.__exit__(None, None, None)
+                                print_error("Failed to connect to blockchain")
+                                return
+
+                        # Get balance from blockchain
+                        response = client.rpc.wallet.get_balance(query_address)
+                    except TimeoutError as e:
+                        loading.__exit__(None, None, None)
+                        print_error(f"Balance query timed out: {str(e)}")
+                        print_error(
+                            "The blockchain RPC endpoint may be slow or unavailable"
+                        )
+                        return
+                    except Exception as e:
+                        loading.__exit__(None, None, None)
+                        print_error(f"Balance query failed: {str(e)}")
+                        raise
+
+                    if response is None:
+                        loading.__exit__(None, None, None)
+                        print_error("Balance query returned no response")
+                        return
+
+                    if response and display_address:
+                        try:
+                            response.address = display_address
+                        except Exception:
+                            pass
+
+                    loading.__exit__(None, None, None)
+                    if response.success:
+                        staking_breakdown = _get_staking_breakdown(
+                            client, query_address
+                        )
+                        staking_balance = staking_breakdown["total"]
+                        display_single_wallet_balance(
+                            response,
+                            wallet_name,
+                            wallet_type,
+                            format_type,
+                            show_guidance,
+                            staking_balance=staking_balance,
+                            staking_breakdown=staking_breakdown,
+                            network_name=network_name,
+                        )
+                    else:
+                        error_msg = response.error or "Unknown Error"
+                        print_error(f"Balance query failed: {error_msg}")
+                        raise Exception(error_msg)
+                finally:
+                    # Ensure spinner is stopped
+                    if (
+                        loading.spinner
+                        and hasattr(loading.spinner, "_running")
+                        and loading.spinner._running
+                    ):
+                        loading.__exit__(None, None, None)
+            else:
+                # External address check (no wallet name)
+                response = None
+                with HTCLILoadingContext(
+                    "Fetching balance for address...", transient=True
+                ):
+                    try:
+                        if not client.substrate:
+                            if not client.connect():
+                                print_error("Failed to connect to blockchain")
+                                return
+
+                        response = client.rpc.wallet.get_balance(address)
+                    except TimeoutError as e:
+                        print_error(f"Balance query timed out: {str(e)}")
+                        print_error(
+                            "The blockchain RPC endpoint may be slow or unavailable"
+                        )
+                        return
+                    except Exception as e:
+                        print_error(f"Balance query failed: {str(e)}")
+                        raise
+
+                    if response is None:
+                        print_error("Balance query returned no response")
+                        return
+
+                # Display results after spinner has stopped
+                if response.success:
+                    staking_breakdown = _get_staking_breakdown(client, address)
+                    staking_balance = staking_breakdown["total"]
+                    display_single_wallet_balance(
+                        response,
+                        None,  # No wallet name for external address
+                        wallet_type,  # "External Address"
+                        format_type,
+                        show_guidance,
+                        staking_balance=staking_balance,
+                        staking_breakdown=staking_breakdown,
+                        network_name=network_name,
+                    )
+                else:
+                    error_msg = response.error or "Unknown Error"
+                    print_error(f"Balance query failed: {error_msg}")
+                    raise Exception(error_msg)
+
+    except RuntimeError as e:
+        # Handle connection errors specifically
+        from ...ui.display import print_error
+
+        error_str = str(e).lower()
+        if "connect" in error_str or "blockchain" in error_str:
+            print_error(f"Blockchain Connection Error: {str(e)}")
+        else:
+            print_error(f"Error: {str(e)}")
+    except Exception as e:
+        from ...errors.handlers import handle_wallet_error
+        from ...ui.display import print_error
+
+        error = handle_wallet_error(e, "update")
+        print_error(error.message, suggestions=error.suggestions)
+
+
+def transfer_handler(
+    from_wallet: Optional[str] = None,
+    to_address: Optional[str] = None,
+    amount: Optional[float] = None,
+    password: Optional[str] = None,
+    dry_run: bool = False,
+):
+    """Handle wallet transfer command."""
+    try:
+        # Convert amount to string if provided
+        amount_str = str(amount) if amount is not None else None
+
+        # STEP 1: Collect input parameters
+        # Create request directly to avoid hanging in prompts
+        from ...models.requests import WalletTransferRequest
+        from ...ui.display import print_error
+
+        # Handle None values - use prompts if any required field is missing
+        if not from_wallet or not to_address or not amount_str:
+            request = prompt_wallet_transfer(
+                from_wallet=from_wallet,
+                to_address=to_address,
+                amount=amount_str,
+                password=password,
+            )
+        else:
+            # Validate CLI-provided amount before creating request
+            try:
+                amount_float = float(amount_str)
+                if amount_float <= 0:
+                    print_error("Amount must be positive")
+                    return
+                if amount_float > 1_000_000_000:  # 1 billion TENSOR
+                    print_error(f"Amount too large: {amount_float:,.2f} TENSOR")
+                    print_error("Maximum allowed: 1,000,000,000 TENSOR")
+                    print_error("This prevents blockchain runtime errors")
+                    return
+                if amount_float < 0.000001:
+                    print_error("Amount too small. Minimum: 0.000001 TENSOR")
+                    return
+            except ValueError:
+                print_error(f"Invalid amount format: {amount_str}")
+                return
+
+            request = WalletTransferRequest(
+                from_wallet=from_wallet,
+                to_address=to_address,
+                amount=amount_str,
+                password=password,
+            )
+
+        # STEP 2: Execute
+        wallet_info = get_wallet_info_by_name(request.from_wallet, is_hotkey=False)
+
+        # Resolve destination address if it's a wallet name
+        to_address = request.to_address
+        if request.from_wallet == to_address:
+            print_error("Source and destination cannot be the same wallet")
+            return
+
+        # Try to resolve as wallet name first (simpler approach)
+        if not to_address.startswith("0x") and len(to_address) < 50:
+            # Likely a wallet name, try to resolve it
+            try:
+                dest_wallet_info = get_wallet_info_by_name(to_address, is_hotkey=False)
+                to_address = dest_wallet_info["ss58_address"]
+            except FileNotFoundError:
+                pass
+
+        if (
+            wallet_info.get("address") == to_address
+            or wallet_info.get("ss58_address") == to_address
+        ):
+            print_error("Source and destination cannot be the same address")
+            return
+
+        # Always load keypair for transfers (needed to sign transaction)
+        # Transfers must use coldkeys (only coldkeys have balances)
+        from ...ui.display import print_error
+        from ...utils.wallet.crypto import load_keypair
+
+        # Get password from request if it exists, otherwise None
+        wallet_password = getattr(request, "password", None)
+
+        try:
+            # Explicitly specify is_hotkey=False to disambiguate when both coldkey and hotkey exist with same name
+            keypair = load_keypair(
+                request.from_wallet, wallet_password, is_hotkey=False
+            )
+        except Exception as e:
+            print_error(f"Failed to load keypair: {str(e)}")
+            raise
+
+        # Call transfer client with loading context
+        from ...dependencies import get_client
+        from ...ui.components import HTCLILoadingContext
+
+        client = get_client()
+
+        try:
+            with HTCLILoadingContext(f"Transferring {request.amount} TENSOR..."):
+                response = client.extrinsics.wallet.transfer_funds(
+                    from_address=wallet_info["address"],
+                    to_address=to_address,
+                    amount=request.amount,
+                    keypair=keypair,
+                )
+        except Exception as e:
+            # Let the outer handler display the error
+            raise
+
+        if not response["success"]:
+            error_msg = response.get("message") or response.get(
+                "error", "Unknown error"
+            )
+            # Let the outer handler display the error
+            raise Exception(error_msg)
+
+        # Create response model from dict with proper field mapping
+        transfer_response = WalletTransferResponse(
+            success=response["success"],
+            from_address=response["data"]["from_address"],
+            to_address=response["data"]["to_address"],
+            amount=str(response["data"]["amount"]),  # Convert to string
+            unit="TENSOR",  # Add required unit field
+            transaction_hash=response.get("transaction_hash"),  # Correct field name
+            block_hash=response.get("block_hash"),
+        )
+
+        # STEP 3: Display results
+        console.print()  # Add blank line after spinner
+        display_wallet_transfer_result(transfer_response, dry_run=dry_run)
+
+    except KeyboardInterrupt:
+        from ...ui.display import print_warning
+
+        console.print()
+        print_warning("Operation cancelled")
+        raise
+    except RuntimeError as e:
+        # Handle connection errors specifically
+        from ...ui.display import print_error
+
+        console.print()
+        error_str = str(e).lower()
+        if "connect" in error_str or "blockchain" in error_str:
+            print_error(f"Blockchain Connection Error: {str(e)}")
+        else:
+            print_error(f"Error: {str(e)}")
+    except Exception as e:
+        # Use centralized error handling
+        from ...errors import handle_and_display_error
+
+        console.print()
+
+        # Check specific wallet/transfer error handlers first
+        error_msg = str(e)
+        if not handle_wallet_extrinsic_error(
+            error_msg, "transfer", client if "client" in locals() else None
+        ):
+            handle_and_display_error(e, "transfer")
+
+
+def rotate_coldkey_handler(name: str, password: Optional[str] = None):
+    """Handle coldkey rotation command."""
+    try:
+        from substrateinterface import Keypair
+
+        from ...dependencies import get_client
+        from ...models.requests.identity import IdentityUpdateColdkeyRequest
+        from ...ui.display import print_error, print_success, print_warning
+        from ...ui.prompts import confirm_prompt
+        from ...utils.wallet.core import _get_keypair_with_password_retry
+
+        # STEP 1: Connect to blockchain
+        client = get_client()
+        if not client.substrate:
+            if not client.connect():
+                print_error("Failed to connect to blockchain. Cannot rotate key.")
+                return
+
+        wallet_manager = WalletManager()
+
+        # STEP 2: Load current wallet (verify password)
+        console.print(info(f"🔐 Unlocking coldkey '{name}'..."))
+        wallet_info = wallet_manager.get_wallet_info(name, is_hotkey=False)
+        _, current_keypair = _get_keypair_with_password_retry(
+            client, name, wallet_info["data"], 3, password
+        )
+
+        # STEP 3: Generate new keypair
+        console.print(info("🎲 Generating new keypair..."))
+        mnemonic = Keypair.generate_mnemonic()
+        new_keypair = Keypair.create_from_mnemonic(mnemonic, crypto_type=2)  # ECDSA
+        new_address = new_keypair.ss58_address  # Same as EVM address for ECDSA
+
+        console.print()
+        print_warning("⚠️  CRITICAL: BACKUP YOUR NEW MNEMONIC")
+        console.print(
+            "If the rotation succeeds but the file save fails, this is your ONLY way to access the wallet."
+        )
+        console.print(f"[bold green]{mnemonic}[/bold green]")
+        console.print()
+
+        if not confirm_prompt("Have you backed up this mnemonic?", default=False):
+            print_error("Rotation cancelled. Please backup the mnemonic first.")
+            return
+
+        # STEP 4: Submit rotation extrinsic
+        console.print()
+        with HTCLISpinner(f"Rotating coldkey to {new_address}..."):
+            request = IdentityUpdateColdkeyRequest(new_coldkey=new_address)
+            response = client.extrinsics.identity.update_coldkey(
+                request, current_keypair
+            )
+
+        if not response["success"]:
+            print_error(f"Rotation failed: {response.get('error')}")
+            return
+
+        # STEP 5: Update local wallet file
+        console.print(print_success("✅ On-chain rotation successful!"))
+        console.print(info("💾 Updating local wallet file..."))
+
+        # Backup old wallet first
+        try:
+            backup_path = (
+                wallet_manager.wallet_dir / "backups" / f"{name}.coldkey.bak.json"
+            )
+            wallet_manager.backup_wallet(name, str(backup_path), password or "")
+            console.print(f"  • Old wallet backed up to: {backup_path}")
+        except Exception as e:
+            print_warning(f"  • Backup failed: {e}")
+
+        # Save new wallet (using same password)
+        # We need to temporarily delete the old file to allow saving the new one with the same name
+        wallet_manager.delete_wallet(name, is_hotkey=False)
+        wallet_manager.save_coldkey(name, new_keypair, password)
+
+        console.print(print_success(f"✅ Local wallet '{name}' updated successfully!"))
+        console.print(f"  • New Address: {new_address}")
+        console.print(f"  • Old Address: {current_keypair.ss58_address}")
+
+    except Exception as e:
+        from ...errors.handlers import handle_wallet_error
+        from ...ui.display import print_error
+
+        error = handle_wallet_error(e, "rotate")
+        print_error(error.message, suggestions=error.suggestions)
+
+
+def rotate_hotkey_handler(
+    name: str,
+    owner_name: Optional[str] = None,
+    password: Optional[str] = None,
+):
+    """Handle hotkey rotation command."""
+    try:
+        from substrateinterface import Keypair
+
+        from ...dependencies import get_client
+        from ...models.requests.identity import IdentityUpdateHotkeyRequest
+        from ...ui.display import print_error, print_success, print_warning
+        from ...ui.prompts import confirm_prompt
+        from ...utils.wallet.core import _get_keypair_with_password_retry
+
+        # STEP 1: Connect to blockchain
+        client = get_client()
+        if not client.substrate:
+            if not client.connect():
+                print_error("Failed to connect to blockchain. Cannot rotate key.")
+                return
+
+        wallet_manager = WalletManager()
+
+        # Resolve owner if not provided
+        if not owner_name:
+            # Try to infer owner from hotkey file
+            hotkey_info = wallet_manager.get_wallet_info(name, is_hotkey=True)
+            owner_name = hotkey_info["data"].get("owner_coldkey_name")
+            if not owner_name:
+                print_error(
+                    "Could not determine owner coldkey. Please specify --owner <coldkey_name>"
+                )
+                return
+
+        # STEP 2: Load wallets
+        # For hotkey rotation, we need:
+        # 1. The coldkey (owner) to sign the transaction
+        # 2. The hotkey wallet info to get the file path/name
+
+        console.print(info(f"🔐 Unlocking owner coldkey '{owner_name}'..."))
+        owner_info = wallet_manager.get_wallet_info(owner_name, is_hotkey=False)
+        owner_address = (
+            owner_info["data"].get("evm_address")
+            or owner_info["data"].get("ss58_address")
+            or owner_info["data"].get("address")
+        )
+
+        # Get owner keypair (may prompt for password)
+        _, owner_keypair = _get_keypair_with_password_retry(
+            client, owner_name, owner_info["data"], 3
+        )
+
+        # STEP 3: Generate new keypair
+        console.print(info("🎲 Generating new hotkey pair..."))
+        mnemonic = Keypair.generate_mnemonic()
+        new_keypair = Keypair.create_from_mnemonic(mnemonic, crypto_type=2)  # ECDSA
+        new_address = new_keypair.ss58_address
+
+        console.print()
+        print_warning("⚠️  CRITICAL: BACKUP YOUR NEW MNEMONIC")
+        console.print(f"[bold green]{mnemonic}[/bold green]")
+        console.print()
+
+        if not confirm_prompt("Have you backed up this mnemonic?", default=False):
+            print_error("Rotation cancelled. Please backup the mnemonic first.")
+            return
+
+        # STEP 4: Submit rotation extrinsic
+        console.print()
+        with HTCLISpinner(f"Rotating hotkey to {new_address}..."):
+            request = IdentityUpdateHotkeyRequest(new_hotkey=new_address)
+            # Sign with OWNER (coldkey)
+            response = client.extrinsics.identity.update_hotkey(request, owner_keypair)
+
+        if not response["success"]:
+            print_error(f"Rotation failed: {response.get('error')}")
+            return
+
+        # STEP 5: Update local wallet file
+        console.print(print_success("✅ On-chain rotation successful!"))
+        console.print(info("💾 Updating local wallet file..."))
+
+        # Backup old wallet first
+        try:
+            backup_path = (
+                wallet_manager.wallet_dir / "backups" / f"{name}.hotkey.bak.json"
+            )
+            # Hotkeys usually don't have passwords, but pass empty string if needed
+            wallet_manager.backup_wallet(name, str(backup_path), password or "")
+            console.print(f"  • Old wallet backed up to: {backup_path}")
+        except Exception as e:
+            # If backup fails (e.g. invalid password for old hotkey), just warn
+            print_warning(f"  • Backup failed: {e}")
+
+        # Save new wallet
+        # Delete old file first
+        wallet_manager.delete_wallet(
+            name, is_hotkey=True, owner_coldkey_name=owner_name
+        )
+        wallet_manager.save_hotkey(
+            name, new_keypair, owner_address, password, owner_coldkey_name=owner_name
+        )
+
+        console.print(print_success(f"✅ Local hotkey '{name}' updated successfully!"))
+        console.print(f"  • New Address: {new_address}")
+
+    except Exception as e:
+        from ...errors.handlers import handle_wallet_error
+        from ...ui.display import print_error
+
+        error = handle_wallet_error(e, "rotate")
+        print_error(error.message, suggestions=error.suggestions)
+
+
+def update_coldkey_handler(
+    name: Optional[str] = None,
+    new_name: Optional[str] = None,
+    new_password: Optional[str] = None,
+    current_password: Optional[str] = None,
+):
+    """Handle coldkey update command."""
+    try:
+        # STEP 1: Collect input parameters
+        request = prompt_wallet_update(
+            current_name=name,
+            new_name=new_name,
+            new_password=new_password,
+            is_hotkey=False,
+        )
+
+        # STEP 2: Execute via client layer
+        wallet_manager = WalletManager()
+        result = wallet_manager.update_coldkey(
+            name=request.current_name,
+            new_name=request.new_name,
+            new_password=request.new_password,
+            remove_password=request.remove_password,
+            current_password=request.current_password,
+        )
+        update_data = result["data"]
+
+        # Create response model
+        response = WalletUpdateResponse(
+            old_name=update_data["old_name"],
+            new_name=update_data["new_name"],
+            address=update_data["ss58_address"],
+            key_type=update_data["key_type"],
+            name_updated=update_data["name_updated"],
+            password_updated=update_data["password_updated"],
+        )
+
+        # STEP 3: Display results
+        display_wallet_update_result(response)
+
+    except Exception as e:
+        from ...errors.handlers import handle_wallet_error
+        from ...ui.display import print_error
+
+        # Print full traceback for debugging
+        # console.print("\n[yellow]Full Traceback:[/yellow]")
+        # console.console.print_exception(show_locals=True, width=120)
+        # console.print()
+
+        error = handle_wallet_error(e, "update")
+        print_error(error.message, suggestions=error.suggestions)
+
+
+def update_hotkey_handler(
+    name: Optional[str] = None,
+    new_password: Optional[str] = None,
+    current_password: Optional[str] = None,
+    new_owner: Optional[str] = None,
+    owner_name: Optional[str] = None,
+    new_name: Optional[str] = None,
+):
+    """Handle hotkey update command."""
+    try:
+        # STEP 1: Collect input parameters
+        request = prompt_wallet_update(
+            current_name=name,
+            new_name=new_name,
+            new_password=new_password,
+            new_coldkey=new_owner,
+            is_hotkey=True,
+            coldkey_name=owner_name,
+        )
+    except AmbiguousWalletError as e:
+        # FIX: If prompt didn't handle it, handle it here
+        from ...ui.display import print_warning
+        from ...ui.components import HTCLITable
+        from ...ui.prompts import prompt_for_required
+
+        console.print()
+        print_warning(
+            f"Found {len(e.matches)} hotkeys named '{e.name}'. Please select which one to update:"
+        )
+
+        table = HTCLITable(title="Select Hotkey")
+        table.add_column("Index", style="bold white", width=6)
+        table.add_column("Coldkey", style="bold yellow", width=25)
+        table.add_column("Address", style="white", width=30)
+
+        for i, match in enumerate(e.matches):
+            owner_ck = match.get("owner_coldkey_name", "Unknown")
+            address = (
+                match.get("evm_address")
+                or match.get("ss58_address")
+                or match.get("address", "N/A")
+            )
+            if address != "N/A":
+                from ...ui.colors import format_address_display
+
+                address_display = format_address_display(address)
+            else:
+                address_display = address
+            table.add_row(str(i + 1), owner_ck, address_display)
+
+        console.print(table.table)
+        console.print()
+
+        choice = prompt_for_required(
+            f"Select hotkey to update (1-{len(e.matches)})",
+            int,
+            f"Enter a number from 1 to {len(e.matches)}",
+        )
+
+        if not (1 <= choice <= len(e.matches)):
+            raise ValueError(
+                f"Invalid selection. Please choose between 1 and {len(e.matches)}"
+            )
+
+        selected_match = e.matches[choice - 1]
+
+        # Retry with selected owner
+        owner_coldkey_name = selected_match.get("owner_coldkey_name")
+        try:
+            request = prompt_wallet_update(
+                current_name=e.name,
+                new_name=new_name,
+                new_password=new_password,
+                new_coldkey=new_owner,
+                is_hotkey=True,
+                coldkey_name=owner_coldkey_name,
+            )
+        except Exception as e:
+            from ...errors.handlers import handle_wallet_error
+            from ...ui.display import print_error
+
+            error = handle_wallet_error(e, "update")
+            print_error(error.message, suggestions=error.suggestions)
+            return
+
+    except Exception as e:
+        from ...errors.handlers import handle_wallet_error
+        from ...ui.display import print_error
+
+        error = handle_wallet_error(e, "update")
+        print_error(error.message, suggestions=error.suggestions)
+        return
+
+    try:
+        # STEP 2: Execute via client layer
+        wallet_manager = WalletManager()
+
+        # Get owner address for disambiguation if needed
+        owner_address = None
+        if request.owner_name:
+            try:
+                owner_info = wallet_manager.get_wallet_info(
+                    request.owner_name, is_hotkey=False
+                )
+                owner_address = (
+                    owner_info["data"].get("evm_address")
+                    or owner_info["data"].get("ss58_address")
+                    or owner_info["data"].get("address")
+                )
+            except Exception:
+                pass
+
+        # STEP 2a: Handle on-chain owner update if owner is being changed
+        on_chain_update_result = None
+        if request.new_owner:
+            # Owner is being changed - need to update on-chain if hotkey is registered
+            from ...dependencies import get_client
+            from ...ui.display import print_warning, print_info
+            from ...ui.prompts import confirm_prompt
+
+            # Get hotkey address first (before updating off-chain)
+            hotkey_info = wallet_manager.get_wallet_info(
+                request.current_name,
+                is_hotkey=True,
+                owner_address=owner_address,
+                owner_coldkey_name=request.owner_name,
+            )
+            hotkey_address = (
+                hotkey_info["data"].get("evm_address")
+                or hotkey_info["data"].get("ss58_address")
+                or hotkey_info["data"].get("address")
+            )
+
+            # Get new owner address
+            new_owner_info = wallet_manager.get_wallet_info(
+                request.new_owner, is_hotkey=False
+            )
+            new_owner_address = (
+                new_owner_info["data"].get("evm_address")
+                or new_owner_info["data"].get("ss58_address")
+                or new_owner_info["data"].get("address")
+            )
+
+            # Get old owner address and keypair for signing
+            old_owner_address = hotkey_info["data"].get("owner_address")
+            old_owner_name = hotkey_info["data"].get("owner_coldkey_name")
+
+            if not old_owner_name:
+                # Try to find old owner name from address
+                all_keys = list_keys()
+                for key in all_keys:
+                    if not key.get("is_hotkey", False):
+                        key_addr = (
+                            key.get("evm_address")
+                            or key.get("ss58_address")
+                            or key.get("address")
+                        )
+                        if key_addr and key_addr.lower() == old_owner_address.lower():
+                            old_owner_name = key.get("name")
+                            break
+
+            # Check if hotkey is registered on-chain
+            client = get_client()
+            if not client.substrate:
+                if not client.connect():
+                    console.print()
+                    print_warning(
+                        "Could not connect to blockchain to check on-chain owner"
+                    )
+                    console.print()
+                    if not confirm_prompt(
+                        "Continue with file-only update? (on-chain owner will NOT be updated)",
+                        default=False,
+                    ):
+                        console.print()
+                        print_info("Owner change cancelled")
+                        return
+                else:
+                    # Connection successful, continue
+                    pass
+
+            # Query on-chain owner
+            on_chain_owner = None
+            console.print()  # Add blank line before spinner
+            with HTCLISpinner("Checking if hotkey is registered on-chain..."):
+                try:
+                    import time
+
+                    time.sleep(0.1)  # Small delay to ensure spinner is visible
+                    owner_result = client.substrate.query(
+                        "Network", "HotkeyOwner", [hotkey_address]
+                    )
+                    if owner_result and owner_result.value:
+                        owner_value = owner_result.value
+                        # Check if owner is the zero address (means no owner registered)
+                        if isinstance(owner_value, str):
+                            owner_hex = owner_value.lower().replace("0x", "")
+                            if owner_hex and not all(c == "0" for c in owner_hex):
+                                on_chain_owner = owner_value
+                        elif isinstance(owner_value, (bytes, list)):
+                            owner_bytes = (
+                                bytes(owner_value)
+                                if isinstance(owner_value, list)
+                                else owner_value
+                            )
+                            if owner_bytes and not all(b == 0 for b in owner_bytes):
+                                from ...utils.blockchain.formatting import (
+                                    to_checksum_address,
+                                )
+
+                                on_chain_owner = to_checksum_address(
+                                    "0x" + owner_bytes.hex()
+                                )
+                        else:
+                            owner_str = str(owner_value)
+                            if (
+                                owner_str
+                                != "0x0000000000000000000000000000000000000000"
+                            ):
+                                on_chain_owner = owner_str
+                except Exception as e:
+                    logger.warning(f"Failed to query on-chain owner: {e}")
+                    on_chain_owner = None
+
+            if on_chain_owner:
+                # Hotkey is registered on-chain - need to update on-chain owner
+                console.print()
+                console.print(
+                    info("🔗 Hotkey is registered on-chain. Updating on-chain owner...")
+                )
+                console.print()
+
+                # Verify old owner matches on-chain owner
+                if on_chain_owner.lower() != old_owner_address.lower():
+                    console.print()
+                    print_warning(
+                        f"On-chain owner ({on_chain_owner}) does not match local owner ({old_owner_address})"
+                    )
+                    console.print()
+                    if not confirm_prompt(
+                        "Continue anyway? This may fail if you don't own the hotkey on-chain.",
+                        default=False,
+                    ):
+                        console.print()
+                        print_info("Owner change cancelled")
+                        return
+
+                # Get old owner keypair for signing
+                if not old_owner_name:
+                    console.print()
+                    print_warning(
+                        "Could not determine old owner name. Cannot update on-chain owner."
+                    )
+                    console.print()
+                    if not confirm_prompt(
+                        "Continue with file-only update? (on-chain owner will NOT be updated)",
+                        default=False,
+                    ):
+                        console.print()
+                        print_info("Owner change cancelled")
+                        return
+                    old_owner_keypair = None
+                else:
+                    # Load old owner keypair
+                    try:
+                        old_owner_wallet_info = wallet_manager.get_wallet_info(
+                            old_owner_name, is_hotkey=False
+                        )
+                        # Get keypair - this will prompt for password if needed
+                        from ...utils.wallet.core import (
+                            _get_keypair_with_password_retry,
+                        )
+
+                        old_owner_name_resolved, old_owner_keypair = (
+                            _get_keypair_with_password_retry(
+                                client, old_owner_name, old_owner_wallet_info["data"], 3
+                            )
+                        )
+                        # Verify the keypair matches the old owner address
+                        old_keypair_address = old_owner_keypair.ss58_address
+                        if old_keypair_address.lower() != old_owner_address.lower():
+                            console.print()
+                            print_warning(
+                                f"⚠️  Loaded keypair address ({old_keypair_address}) does not match expected owner ({old_owner_address})"
+                            )
+                            console.print()
+                            if not confirm_prompt(
+                                "Continue anyway? This may fail if you don't own the hotkey on-chain.",
+                                default=False,
+                            ):
+                                console.print()
+                                print_info("Owner change cancelled")
+                                return
+                    except Exception as e:
+                        console.print()
+                        print_warning(f"Could not load old owner keypair: {str(e)}")
+                        console.print()
+                        if not confirm_prompt(
+                            "Continue with file-only update? (on-chain owner will NOT be updated)",
+                            default=False,
+                        ):
+                            console.print()
+                            print_info("Owner change cancelled")
+                            return
+                        old_owner_keypair = None
+
+                    if old_owner_keypair:
+                        # Update on-chain owner
+                        try:
+                            with HTCLISpinner("Updating on-chain owner..."):
+                                on_chain_update_result = (
+                                    client.extrinsics.wallet.update_coldkey(
+                                        hotkey=hotkey_address,
+                                        new_coldkey=new_owner_address,
+                                        keypair=old_owner_keypair,
+                                    )
+                                )
+
+                            # Check for errors in result
+                            if isinstance(
+                                on_chain_update_result, dict
+                            ) and not on_chain_update_result.get("success", False):
+                                error_msg = on_chain_update_result.get(
+                                    "message"
+                                ) or on_chain_update_result.get(
+                                    "error", "Update failed"
+                                )
+                                if handle_wallet_extrinsic_error(
+                                    error_msg, "update coldkey", client
+                                ):
+                                    # Error was handled, ask if user wants to continue with file-only update
+                                    console.print()
+                                    if not confirm_prompt(
+                                        "Continue with file-only update? (on-chain owner will remain unchanged)",
+                                        default=False,
+                                    ):
+                                        console.print()
+                                        print_info("Owner change cancelled")
+                                        return
+                                    on_chain_update_result = None  # Mark as failed
+                                else:
+                                    # Error not handled, show warning and ask
+                                    console.print()
+                                    print_warning(
+                                        f"On-chain update failed: {error_msg}"
+                                    )
+                                    console.print()
+                                    if not confirm_prompt(
+                                        "Continue with file-only update? (on-chain owner will NOT be updated)",
+                                        default=False,
+                                    ):
+                                        console.print()
+                                        print_info("Owner change cancelled")
+                                        return
+                                    on_chain_update_result = None  # Mark as failed
+                            else:
+                                # Success
+                                console.print()
+                                console.print(
+                                    success(f"✅ On-chain owner updated successfully!")
+                                )
+                                console.print(
+                                    info(
+                                        f"   Transaction: {on_chain_update_result.get('transaction_hash', 'N/A')}"
+                                    )
+                                )
+                                if on_chain_update_result.get("block_hash"):
+                                    console.print(
+                                        info(
+                                            f"   Block Hash: {on_chain_update_result.get('block_hash')}"
+                                        )
+                                    )
+                                if on_chain_update_result.get("block_number"):
+                                    console.print(
+                                        info(
+                                            f"   Block Number: {on_chain_update_result.get('block_number')}"
+                                        )
+                                    )
+                                console.print()
+                        except Exception as e:
+                            error_str = str(e)
+                            if not handle_wallet_extrinsic_error(
+                                error_str, "update coldkey", client
+                            ):
+                                # Error not handled by our handler, show generic warning
+                                console.print()
+                                print_warning(f"On-chain update failed: {error_str}")
+                                console.print()
+
+                            # Ask if user wants to continue with file-only update
+                            if not confirm_prompt(
+                                "Continue with file-only update? (on-chain owner will remain unchanged)",
+                                default=False,
+                            ):
+                                console.print()
+                                print_info("Owner change cancelled")
+                                return
+                            on_chain_update_result = None  # Mark as failed
+            else:
+                # Hotkey is not registered on-chain - cannot change owner
+
+                print_warning("Hotkey is not registered on-chain. Cannot change owner.")
+                console.print()
+                print_info(
+                    "💡 To change the owner, the hotkey must first be registered on-chain (e.g., by registering a node)."
+                )
+                console.print()
+                print_info("Owner change cancelled - no changes were made.")
+                return
+
+        # STEP 2b: Update off-chain wallet file (only if on-chain update succeeded or owner not changed)
+        result = wallet_manager.update_hotkey(
+            name=request.current_name,
+            new_name=request.new_name,
+            new_password=request.new_password,
+            remove_password=request.remove_password,
+            new_owner=request.new_owner,
+            current_password=request.current_password,
+            owner_address=owner_address,
+        )
+        update_data = result["data"]
+
+        # Create response model
+        response = WalletUpdateResponse(
+            old_name=update_data["old_name"],
+            new_name=update_data["new_name"],
+            address=update_data.get("ss58_address")
+            or update_data.get("evm_address")
+            or update_data.get("address"),
+            key_type=update_data["key_type"],
+            name_updated=update_data["name_updated"],
+            password_updated=update_data["password_updated"],
+            owner_updated=update_data.get("owner_updated"),
+            old_owner_address=update_data.get("old_owner_address"),
+            new_owner_address=update_data.get("new_owner_address"),
+            transaction_hash=(
+                on_chain_update_result.get("transaction_hash")
+                if on_chain_update_result
+                else None
+            ),
+            block_hash=(
+                on_chain_update_result.get("block_hash")
+                if on_chain_update_result
+                else None
+            ),
+            block_number=(
+                on_chain_update_result.get("block_number")
+                if on_chain_update_result
+                else None
+            ),
+        )
+
+        # STEP 3: Display results
+        display_wallet_update_result(response)
+
+    except Exception as e:
+        from ...errors.handlers import handle_wallet_error
+        from ...ui.display import print_error
+
+        error = handle_wallet_error(e, "update")
+        print_error(error.message, suggestions=error.suggestions)
+
+
+def describe_handler(name: Optional[str] = None):
+    """Handle wallet describe command."""
+    try:
+        # STEP 1: Collect input parameters
+        if not name:
+            from .prompts import prompt_wallet_selection
+
+            name = prompt_wallet_selection("Select wallet to describe")
+
+        # STEP 2: Get wallet information
+        wallet_info = get_wallet_info_by_name(name)
+
+        # STEP 3: Get balance if it's a coldkey
+        balance_info = None
+        if not wallet_info.get("is_hotkey", False):
+            try:
+                from ...dependencies import get_client
+
+                client = get_client()
+                # Ensure connection is established
+                if not client.substrate:
+                    if not client.connect():
+                        balance_info = {"error": "Failed to connect to blockchain"}
+                    else:
+                        response = client.rpc.wallet.get_balance(wallet_info["address"])
+                else:
+                    response = client.rpc.wallet.get_balance(wallet_info["address"])
+                if response.success:
+                    # BalanceResponse has fields directly, not in data object
+                    balance_info = {
+                        "address": response.address,
+                        "balance": response.balance or 0,
+                        "available_balance": response.available_balance or 0,
+                        "locked_balance": response.locked_balance or 0,
+                        "reserved_balance": response.reserved_balance or 0,
+                    }
+                else:
+                    raise Exception(response.message)
+            except Exception as e:
+                balance_info = {"error": f"Unable to fetch balance: {str(e)}"}
+
+        # STEP 4: Display results
+        display_wallet_describe_result(wallet_info, balance_info)
+
+    except FileNotFoundError:
+        from ...ui.colors import error
+        from ...ui.display import HTCLIConsole
+
+        console = HTCLIConsole()
+        console.print(error(f"Wallet '{name}' does not exist."))
+    except Exception as e:
+        from ...errors.handlers import handle_wallet_error
+        from ...ui.display import print_error
+
+        error = handle_wallet_error(e, "update")
+        print_error(error.message, suggestions=error.suggestions)
+
+
+def check_hotkey_owner_handler(
+    hotkey_name: Optional[str] = None,
+    hotkey_address: Optional[str] = None,
+    coldkey_name: Optional[str] = None,
+):
+    """Check the on-chain owner of a hotkey."""
+    try:
+        from ...dependencies import get_client
+        from ...ui.display import print_error
+
+        # STEP 1: Get hotkey address
+        if not hotkey_address:
+            if not hotkey_name:
+                # Show list of hotkeys for user to select
+                all_keys = list_keys()
+                hotkeys = [k for k in all_keys if k.get("is_hotkey", False)]
+                if not hotkeys:
+                    console.print(warning("No hotkeys found."))
+                    return
+
+                from ...ui.components import HTCLITable
+                from ...ui.prompts import prompt_for_required
+
+                table = HTCLITable(
+                    title="Available Hotkeys",
+                    border_style="blue",
+                    header_style="bold cyan",
+                )
+                table.add_column("Index", style="bold white", width=6)
+                table.add_column("Name", style="bold cyan", width=25)
+                table.add_column("Coldkey", style="bold yellow", width=25)
+                table.add_column("Address", style="white", width=30)
+
+                for i, hotkey in enumerate(hotkeys):
+                    coldkey_name_display = "Unknown"
+                    coldkey_address = hotkey.get("owner_address")
+                    if coldkey_address:
+                        for key in all_keys:
+                            if key.get(
+                                "ss58_address"
+                            ) == coldkey_address and not key.get("is_hotkey", False):
+                                coldkey_name_display = key.get(
+                                    "name", coldkey_address[:20] + "..."
+                                )
+                                break
+                        else:
+                            coldkey_name_display = coldkey_address[:20] + "..."
+
+                    address_display = (
+                        hotkey.get("evm_address")
+                        or hotkey.get("ss58_address")
+                        or hotkey.get("address", "N/A")
+                    )
+                    if address_display != "N/A":
+                        from ...ui.colors import format_address_display
+
+                        address_display = format_address_display(address_display)
+
+                    table.add_row(
+                        str(i + 1),
+                        hotkey.get("name", "N/A"),
+                        coldkey_name_display,
+                        address_display,
+                    )
+
+                console.print(table.table)
+                console.print()
+
+                choice = prompt_for_required(
+                    f"Select hotkey to check owner (1-{len(hotkeys)})",
+                    int,
+                    f"Enter a number from 1 to {len(hotkeys)}",
+                )
+
+                if not (1 <= choice <= len(hotkeys)):
+                    raise ValueError(
+                        f"Invalid selection. Please choose between 1 and {len(hotkeys)}"
+                    )
+
+                selected_hotkey = hotkeys[choice - 1]
+                hotkey_name = selected_hotkey["name"]
+                coldkey_name = None
+                # Try to find coldkey name
+                coldkey_address = selected_hotkey.get("owner_address")
+                if coldkey_address:
+                    for key in all_keys:
+                        if key.get("ss58_address") == coldkey_address and not key.get(
+                            "is_hotkey", False
+                        ):
+                            coldkey_name = key.get("name")
+                            break
+
+            # Get hotkey info
+            if coldkey_name:
+                # Use coldkey to disambiguate
+                wallet_manager = WalletManager()
+                try:
+                    coldkey_info_result = wallet_manager.get_wallet_info(
+                        coldkey_name, is_hotkey=False
+                    )
+                    coldkey_info = coldkey_info_result["data"]
+                    owner_address = coldkey_info.get(
+                        "ss58_address"
+                    ) or coldkey_info.get("address")
+                except (ValueError, FileNotFoundError) as e:
+                    console.print(
+                        warning(f"❌ Coldkey '{coldkey_name}' does not exist.")
+                    )
+                    return
+
+                # Get hotkey info
+                try:
+                    hotkey_info_result = wallet_manager.get_wallet_info(
+                        hotkey_name,
+                        is_hotkey=True,
+                        owner_address=owner_address,
+                        owner_coldkey_name=coldkey_name,
+                    )
+                    hotkey_info = hotkey_info_result["data"]
+                    hotkey_address = (
+                        hotkey_info.get("evm_address")
+                        or hotkey_info.get("ss58_address")
+                        or hotkey_info.get("address")
+                    )
+                except (ValueError, FileNotFoundError) as e:
+                    console.print(
+                        warning(
+                            f"❌ Hotkey '{hotkey_name}' owned by '{coldkey_name}' does not exist."
+                        )
+                    )
+                    return
+            else:
+                # Get hotkey info without owner context
+                wallet_info = get_wallet_info_by_name(hotkey_name, is_hotkey=True)
+                if not wallet_info.get("is_hotkey", False):
+                    console.print(warning(f"❌ '{hotkey_name}' is not a hotkey."))
+                    return
+                hotkey_address = (
+                    wallet_info.get("evm_address")
+                    or wallet_info.get("ss58_address")
+                    or wallet_info.get("address")
+                )
+
+        # STEP 2: Connect to blockchain and query
+        client = get_client()
+        if not client.substrate:
+            if not client.connect():
+                print_error(
+                    "Failed to connect to blockchain. Cannot check hotkey owner."
+                )
+                return
+
+        # STEP 3: Query on-chain owner
+        console.print()
+        console.print(
+            info(f"🔍 Checking on-chain owner for hotkey: {address(hotkey_address)}")
+        )
+        console.print()
+
+        on_chain_owner = None
+        try:
+            owner_result = client.substrate.query(
+                "Network", "HotkeyOwner", [hotkey_address]
+            )
+            if owner_result and owner_result.value:
+                owner_value = owner_result.value
+                # Check if owner is the zero address (means no owner registered)
+                if isinstance(owner_value, str):
+                    owner_hex = owner_value.lower().replace("0x", "")
+                    if owner_hex and not all(c == "0" for c in owner_hex):
+                        on_chain_owner = owner_value
+                elif isinstance(owner_value, (bytes, list)):
+                    owner_bytes = (
+                        bytes(owner_value)
+                        if isinstance(owner_value, list)
+                        else owner_value
+                    )
+                    if owner_bytes and not all(b == 0 for b in owner_bytes):
+                        from ...utils.blockchain.formatting import to_checksum_address
+
+                        on_chain_owner = to_checksum_address("0x" + owner_bytes.hex())
+                else:
+                    owner_str = str(owner_value)
+                    if owner_str != "0x0000000000000000000000000000000000000000":
+                        on_chain_owner = owner_str
+        except Exception as e:
+            logger.error(f"Failed to query on-chain owner: {e}")
+            console.print(warning(f"Could not query on-chain owner: {str(e)}"))
+            return
+
+        # STEP 4: Display results
+        console.print()
+        if on_chain_owner:
+            console.print(success("✅ Hotkey has an on-chain owner"))
+            console.print()
+            console.print(f"[bold]Hotkey Address:[/bold] {address(hotkey_address)}")
+            console.print(f"[bold]On-Chain Owner:[/bold] {address(on_chain_owner)}")
+
+            # Try to find if this owner is a known coldkey
+            all_keys = list_keys()
+            owner_name = None
+            for key in all_keys:
+                key_address = (
+                    key.get("evm_address")
+                    or key.get("ss58_address")
+                    or key.get("address")
+                )
+                if (
+                    key_address
+                    and key_address.lower() == on_chain_owner.lower()
+                    and not key.get("is_hotkey", False)
+                ):
+                    owner_name = key.get("name")
+                    break
+
+            if owner_name:
+                console.print(f"[bold]Owner Name:[/bold] {owner_name}")
+        else:
+            console.print(warning("Hotkey is not registered on-chain"))
+            console.print()
+            console.print(f"[bold]Hotkey Address:[/bold] {address(hotkey_address)}")
+            console.print("[bold]On-Chain Owner:[/bold] None (not registered)")
+            console.print()
+            console.print(
+                info(
+                    "💡 This hotkey can be registered on-chain when registering a node."
+                )
+            )
+
+        console.print()
+
+    except Exception as e:
+        from ...errors.handlers import handle_wallet_error
+        from ...ui.display import print_error
+
+        error = handle_wallet_error(e, "check-hotkey-owner")
+        print_error(error.message, suggestions=error.suggestions)
+
+
+def upgrade_wallet_layout_handler(
+    *,
+    dry_run: bool = False,
+    force: bool = False,
+    backup: bool = True,
+    wallet_names: Optional[list[str]] = None,
+):
+    """Handle wallet layout upgrade command."""
+    try:
+        wallet_manager = WalletManager()
+        result = wallet_manager.upgrade_wallet_layout(
+            dry_run=dry_run,
+            force=force,
+            backup=backup,
+            wallets=wallet_names,
+            log=console.print,
+        )
+        summary = result.get("data", {})
+        migrated = len(summary.get("migrated", []))
+        skipped = len(summary.get("skipped", []))
+        warnings_list = summary.get("warnings", [])
+
+        console.print(
+            "[success]Wallet layout upgrade complete[/success] "
+            f"(migrated={migrated}, skipped={skipped}, warnings={len(warnings_list)})"
+        )
+        if warnings_list:
+            console.print()
+            console.print("[warning]Warnings:[/warning]")
+            for warning_msg in warnings_list:
+                console.print(f"[warning]- {warning_msg}[/warning]")
+    except Exception as e:
+        from ...errors.handlers import handle_wallet_error
+
+        error = handle_wallet_error(e, "update")
+        console.print(f"[error]{error.message}[/error]")
+        if error.suggestions:
+            for suggestion in error.suggestions:
+                console.print(f"[info]- {suggestion}[/info]")
+
+
+def update_identity_handler(
+    hotkey_name: Optional[str] = None,
+    name: Optional[str] = None,
+    url: Optional[str] = None,
+    image: Optional[str] = None,
+    discord: Optional[str] = None,
+    x: Optional[str] = None,
+    telegram: Optional[str] = None,
+    github: Optional[str] = None,
+    hugging_face: Optional[str] = None,
+    description: Optional[str] = None,
+    misc: Optional[str] = None,
+    password: Optional[str] = None,
+):
+    """Handle identity update/registration command."""
+    try:
+        from ...dependencies import get_client
+        from ...ui.display import print_error, print_success
+        from ...utils.wallet.core import _get_keypair_with_password_retry
+
+        # STEP 1: Collect input parameters
+        hotkey_name, password, request = prompt_identity_update(
+            hotkey_name=hotkey_name,
+            name=name,
+            url=url,
+            image=image,
+            discord=discord,
+            x=x,
+            telegram=telegram,
+            github=github,
+            hugging_face=hugging_face,
+            description=description,
+            misc=misc,
+            password=password,
+        )
+
+        # STEP 2: Connect to blockchain
+        client = get_client()
+        if not client.substrate:
+            if not client.connect():
+                print_error("Failed to connect to blockchain. Cannot update identity.")
+                return
+
+        # STEP 3: Load wallet
+        wallet_manager = WalletManager()
+        console.print(info(f"🔐 Unlocking hotkey '{hotkey_name}'..."))
+
+        try:
+            wallet_info = wallet_manager.get_wallet_info(hotkey_name, is_hotkey=True)
+        except Exception:
+            print_error(f"Wallet '{hotkey_name}' not found.")
+            return
+
+        # Update request with address
+        address = wallet_info["data"].get("ss58_address") or wallet_info["data"].get(
+            "address"
+        )
+        request.hotkey = address
+
+        # Get keypair
+        _, keypair = _get_keypair_with_password_retry(
+            client, hotkey_name, wallet_info["data"], 3, password
+        )
+
+        # STEP 4: Submit extrinsic
+        console.print()
+        with HTCLISpinner("Updating identity on-chain..."):
+            response = client.extrinsics.identity.register_or_update_identity(
+                request, keypair
+            )
+
+        # STEP 5: Display result
+        if response["success"]:
+            display_identity_update_result(response, address)
+        else:
+            error_msg = response.get("message") or response.get(
+                "error", "Unknown error"
+            )
+            print_error(f"Identity update failed: {error_msg}")
+
+    except Exception as e:
+        from ...errors.handlers import handle_wallet_error
+        from ...ui.display import print_error
+
+        error = handle_wallet_error(e, "identity")
+        print_error(error.message, suggestions=error.suggestions)