htcli 1.1.0__py3-none-any.whl

src/htcli/errors/handlers.py

@@ -0,0 +1,710 @@
+"""
+Improved error handling functions for htcli using SubstrateInterface built-in error parsing.
+"""
+
+import os
+import traceback
+from typing import Any
+
+from pydantic import ValidationError
+from substrateinterface.exceptions import (
+    BlockNotFound,
+    ConfigurationError,
+    ExtrinsicFailedException,
+    StorageFunctionNotFound,
+    SubstrateRequestException,
+)
+
+from .base import (
+    AddressValidationError,
+    BalanceError,
+    DelegateStakeError,
+    HTCLIError,
+    InvalidPasswordError,
+    KeyDeletionError,
+    KeyGenerationError,
+    NodeError,
+    NodeOperationError,
+    NodeRegistrationError,
+    StakeError,
+    SubnetActivationError,
+    SubnetError,
+    SubnetRegistrationError,
+    TransferError,
+    WalletError,
+)
+
+DEBUG_ERRORS = os.environ.get("HTCLI_DEBUG", "").lower() in {"1", "true", "yes"}
+
+
+def _print_debug_traceback(error: Exception) -> None:
+    """Print the exception traceback when HTCLI_DEBUG is enabled."""
+    if not DEBUG_ERRORS:
+        return
+    traceback.print_exception(type(error), error, error.__traceback__)
+
+
+def handle_substrate_error(error: Exception) -> HTCLIError:
+    """
+    Convert SubstrateInterface errors to user-friendly HTCLI errors.
+    Uses SubstrateInterface's built-in error parsing with pattern matching.
+    """
+    _print_debug_traceback(error)
+    error_str = str(error).lower()
+
+    # Handle SubstrateInterface specific exceptions
+    if isinstance(error, ExtrinsicFailedException):
+        return _handle_extrinsic_error(error)
+    elif isinstance(error, SubstrateRequestException):
+        return _handle_request_error(error)
+    elif isinstance(error, ConfigurationError):
+        return _handle_config_error(error)
+    elif isinstance(error, StorageFunctionNotFound):
+        return _handle_storage_error(error)
+    elif isinstance(error, BlockNotFound):
+        return _handle_block_error(error)
+
+    # Pattern matching for common error types - ORDER MATTERS!
+    # Check for config errors first (before "invalid" pattern catches them)
+    if "setting" in error_str and (
+        "not found" in error_str or "setting '" in error_str
+    ):
+        return HTCLIError(
+            str(error),
+            [
+                "Check that the configuration key exists",
+                "Use 'htcli config show' to view all settings",
+                "Use 'htcli config --help' for usage",
+            ],
+        )
+    # Check for stake/delegate errors BEFORE subnet errors (stake errors may mention subnet ID)
+    stake_error_patterns = [
+        "delegatestake", "delegatestake", "nodedelegatestake", "stake", "staking",
+        "minstake", "maxstake", "stakenot", "invalidstake", "stakeamount"
+    ]
+    if any(pattern in error_str for pattern in stake_error_patterns):
+        return _create_stake_error(str(error))
+    # Check for specific subnet errors BEFORE generic balance errors
+    # This prevents misclassification (e.g., NotSubnetOwner shouldn't become "Insufficient balance")
+    # Check for common subnet error patterns (case-insensitive via error_str which is already lowercased)
+    subnet_error_patterns = [
+        "notsubnetowner", "notpending", "invalidsubnet", "subnetmustbe",
+        "subnetnameexist", "subnetrepoexist", "subnetis", "subnetnot",
+        "badorigin", "notowner"
+    ]
+    if any(pattern in error_str for pattern in subnet_error_patterns):
+        return _create_subnet_error(str(error))
+    # Only match balance errors if they don't contain subnet/owner context
+    elif any(pattern in error_str for pattern in ["insufficient", "balance", "funds"]) and not any(pattern in error_str for pattern in ["subnet", "node", "owner", "pending"]):
+        return _create_balance_error(str(error))
+    elif any(pattern in error_str for pattern in ["wallet", "key", "signature"]):
+        return _create_wallet_error(str(error))
+    elif any(pattern in error_str for pattern in ["invalid", "address", "account"]) and "typeerror" not in error_str:
+        return _create_address_error(str(error))
+
+    # Generic fallback
+    return HTCLIError(
+        f"Operation failed: {str(error)}",
+        ["Please check your parameters and try again", "Use --help for command usage"],
+    )
+
+
+def _handle_extrinsic_error(error: ExtrinsicFailedException) -> HTCLIError:
+    """Handle failed extrinsic errors with specific patterns."""
+    error_msg = str(error)
+    error_details = getattr(error, "error_message", {})
+
+    # Parse module errors if available
+    if isinstance(error_details, dict) and "Module" in error_details:
+        module_info = error_details["Module"]
+        return _parse_module_error(module_info, error_msg)
+
+    # Pattern matching for common extrinsic failures
+    if "insufficientbalance" in error_msg.lower():
+        return TransferError(
+            "Insufficient balance to complete the transaction",
+            [
+                "Check your balance: htcli wallet balance --wallet <wallet-name>",
+                "Ensure you have enough funds for both transfer and fees",
+                "Transaction fees are typically 0.001-0.01 TENSOR",
+                "Try a smaller amount",
+            ],
+        )
+
+    if "invalidaddress" in error_msg.lower():
+        return AddressValidationError(
+            "Invalid destination address provided",
+            [
+                "Verify the address format is correct",
+                "Ensure the address is for the correct network",
+                "Check for any typos in the address",
+            ],
+        )
+
+    return HTCLIError(f"Transaction failed: {error_msg}")
+
+
+def _handle_request_error(error: SubstrateRequestException) -> HTCLIError:
+    """Handle RPC request errors."""
+    return HTCLIError(
+        f"Network request failed: {str(error)}",
+        [
+            "Check your network connection",
+            "Verify the RPC endpoint is accessible",
+            "Try again in a moment",
+        ],
+    )
+
+
+def _handle_config_error(error: ConfigurationError) -> HTCLIError:
+    """Handle configuration errors."""
+    return HTCLIError(
+        f"Configuration error: {str(error)}",
+        [
+            "Check your configuration file",
+            "Verify network settings",
+            "Use htcli config --help for configuration options",
+        ],
+    )
+
+
+def _handle_storage_error(error: StorageFunctionNotFound) -> HTCLIError:
+    """Handle storage function not found errors."""
+    return HTCLIError(
+        f"Storage function not found: {str(error)}",
+        [
+            "This might be a version compatibility issue",
+            "Check if you're connected to the correct network",
+            "Verify the blockchain runtime version",
+        ],
+    )
+
+
+def _handle_block_error(error: BlockNotFound) -> HTCLIError:
+    """Handle block not found errors."""
+    return HTCLIError(
+        f"Block not found: {str(error)}",
+        [
+            "The requested block may not exist yet",
+            "Check if the block number/hash is correct",
+            "Try with a different block or use latest",
+        ],
+    )
+
+
+def _parse_module_error(module_info: dict, full_error: str) -> HTCLIError:
+    """Parse module-specific errors from substrate."""
+    error_index = module_info.get("error", 0)
+    module_index = module_info.get("index", 0)
+
+    # Common substrate module error patterns
+    balance_errors = [0, 1, 2, 5]  # InsufficientBalance, LiquidityRestrictions, etc.
+    if error_index in balance_errors:
+        return TransferError(
+            "Insufficient balance or liquidity restrictions",
+            [
+                "Check your balance: htcli wallet balance --wallet <wallet-name>",
+                "Ensure funds are not locked or reserved",
+                "Try a smaller amount",
+                "Wait for any pending transactions to complete",
+            ],
+        )
+
+    # Generic module error
+    return HTCLIError(
+        f"Module error (index: {module_index}, error: {error_index}): {full_error}",
+        [
+            "This is a blockchain-specific error",
+            "Check the blockchain documentation for error details",
+            "Verify your transaction parameters",
+        ],
+    )
+
+
+def _create_balance_error(error_msg: str) -> BalanceError:
+    """Create user-friendly balance error."""
+    return BalanceError(
+        "Insufficient balance to complete the operation",
+        [
+            "Check your current balance: htcli wallet balance --wallet <wallet-name>",
+            "Ensure you have enough funds for the operation plus fees",
+            "Transaction fees are typically 0.001-0.01 TENSOR",
+            "Try with a smaller amount",
+        ],
+    )
+
+
+def _create_address_error(error_msg: str) -> AddressValidationError:
+    """Create user-friendly address validation error."""
+    return AddressValidationError(
+        "Invalid address format or address not found",
+        [
+            "Verify the address format is correct",
+            "Ensure you're using the right network address format",
+            "Check for typos in the address",
+            "For EVM addresses, use format: 0x1234567890123456789012345678901234567890",
+        ],
+    )
+
+
+def _create_subnet_error(error_msg: str) -> SubnetError:
+    """Create user-friendly subnet error."""
+    if "registration" in error_msg.lower():
+        return SubnetRegistrationError(
+            "Subnet registration failed",
+            [
+                "Check if you have sufficient stake for registration",
+                "Verify subnet parameters are valid",
+                "Ensure you have permission to register subnets",
+                "Check subnet requirements: htcli subnet requirements",
+            ],
+        )
+    elif "activation" in error_msg.lower():
+        return SubnetActivationError(
+            "Subnet activation failed",
+            [
+                "Check if the subnet meets activation requirements",
+                "Verify you own the subnet or have permission",
+                "Ensure all activation criteria are met",
+                "Check subnet status: htcli subnet list",
+            ],
+        )
+    else:
+        return SubnetError(
+            "Subnet operation failed",
+            [
+                "Check subnet status: htcli subnet list",
+                "Verify your permissions and balance",
+                "Review command help: htcli subnet <command> --help",
+            ],
+        )
+
+
+def _create_stake_error(error_msg: str) -> StakeError:
+    """Create user-friendly stake error."""
+    if "delegate" in error_msg.lower():
+        return DelegateStakeError(
+            "Delegate stake operation failed",
+            [
+                "Check your balance: htcli wallet balance --wallet <wallet-name>",
+                "Verify subnet ID is valid: htcli subnet info --subnet-id <id>",
+                "Ensure you have sufficient funds for the stake amount plus fees",
+                "Check stake requirements: htcli stake delegate-add --help",
+            ],
+        )
+    else:
+        return StakeError(
+            "Stake operation failed",
+            [
+                "Check your balance: htcli wallet balance --wallet <wallet-name>",
+                "Verify subnet/node ID is valid",
+                "Ensure you have sufficient funds for the stake amount plus fees",
+                "Review command help: htcli stake <command> --help",
+            ],
+        )
+
+
+def _create_node_error(error_msg: str) -> NodeError:
+    """Create user-friendly node error."""
+    error_lower = error_msg.lower()
+    
+    if "registration" in error_lower:
+        return NodeRegistrationError(
+            "Node registration failed",
+            [
+                "Check if you have sufficient stake for node registration",
+                "Verify node parameters are valid (peer IDs, delegate rate, etc.)",
+                "Ensure the subnet exists and is accepting registrations",
+                "Check node requirements: htcli node register --help",
+                "Verify subnet info: htcli subnet info --subnet-id <id>",
+            ],
+        )
+    elif "overwatch" in error_lower:
+        # Handle overwatch-specific errors with appropriate suggestions
+        if any(pattern in error_lower for pattern in ["register", "register_overwatch", "qualified", "stake"]):
+            return NodeOperationError(
+                "Overwatch registration failed",
+                [
+                    "Check qualification status: htcli overwatch check-qualification --coldkey <name>",
+                    "Ensure you have sufficient balance for minimum stake",
+                    "Verify the hotkey is not already registered elsewhere",
+                    "The hotkey must be different from the coldkey",
+                    "Review command help: htcli overwatch register --help",
+                ],
+            )
+        elif any(pattern in error_lower for pattern in ["commit", "reveal", "epoch"]):
+            return NodeOperationError(
+                "Overwatch commit/reveal operation failed",
+                [
+                    "Verify the node exists: htcli overwatch list",
+                    "Check if the epoch number is valid",
+                    "Ensure the node has overwatch data for the specified epoch",
+                    "Try: htcli overwatch info --node-id <id>",
+                ],
+            )
+        else:
+            return NodeOperationError(
+                "Overwatch node operation failed",
+                [
+                    "Check your overwatch node status: htcli overwatch list",
+                    "Verify you have the correct permissions",
+                    "Check qualification: htcli overwatch check-qualification --coldkey <name>",
+                    "Review command help: htcli overwatch --help",
+                ],
+            )
+    elif "not found" in error_lower or "does not exist" in error_lower:
+        return NodeOperationError(
+            "Node not found",
+            [
+                "Verify the node ID exists in the specified subnet",
+                "Check available nodes: htcli node list --subnet-id <id>",
+                "Ensure the subnet ID is correct",
+                "Verify subnet exists: htcli subnet list",
+            ],
+        )
+    else:
+        return NodeError(
+            "Node operation failed",
+            [
+                "Check node status: htcli node info --subnet-id <id> --node-id <id>",
+                "Verify node exists: htcli node list --subnet-id <id>",
+                "Ensure you have the correct permissions",
+                "Review command help: htcli node <command> --help",
+            ],
+        )
+
+
+
+def _create_wallet_error(error_msg: str) -> WalletError:
+    """Create user-friendly wallet error."""
+    if "key" in error_msg.lower():
+        if "generation" in error_msg.lower() or "create" in error_msg.lower():
+            return KeyGenerationError(
+                "Failed to generate wallet keys",
+                [
+                    "Ensure you have write permissions to the wallet directory",
+                    "Check available disk space",
+                    "Try with a different wallet name",
+                    "Verify the key type is supported",
+                ],
+            )
+        elif "deletion" in error_msg.lower() or "remove" in error_msg.lower():
+            return KeyDeletionError(
+                "Failed to delete wallet keys",
+                [
+                    "Verify the wallet exists: htcli wallet list",
+                    "Ensure you have write permissions",
+                    "Check if the wallet is currently in use",
+                    "Try again with --force flag if appropriate",
+                ],
+            )
+
+    # Include the actual error message so users can see what went wrong
+    # Only use generic message if error_msg is too generic
+    if error_msg.lower() in ["wallet operation failed", "wallet error", "wallet"]:
+        display_msg = "Wallet operation failed"
+    else:
+        display_msg = f"Wallet operation failed: {error_msg}"
+
+    return WalletError(
+        display_msg,
+        [
+            "Verify the wallet exists: htcli wallet list",
+            "Check wallet permissions and password",
+            "Ensure wallet files are not corrupted",
+            "Try reloading the wallet",
+        ],
+    )
+
+
+# Legacy function aliases for backward compatibility
+def handle_blockchain_error(error_msg: str) -> HTCLIError:
+    """Legacy function - redirects to new substrate error handler."""
+    return handle_substrate_error(Exception(error_msg))
+
+
+def handle_wallet_error(error: Exception, operation: str = "wallet") -> WalletError:
+    """Handle wallet-specific errors."""
+    error_str = str(error).lower()
+    
+    # Handle InvalidPasswordError specifically with helpful suggestions
+    if isinstance(error, InvalidPasswordError):
+        if operation == "update":
+            return WalletError(
+                "Invalid password provided",
+                [
+                    "The password you entered is incorrect",
+                    "Double-check that you're using the correct password for this wallet",
+                    "If you've forgotten your password, you'll need to restore from your mnemonic",
+                    "Make sure Caps Lock is off and you're entering the password correctly",
+                ],
+            )
+        else:
+            return WalletError(
+                "Invalid password provided",
+                [
+                    "The password you entered is incorrect",
+                    "Double-check that you're using the correct password for this wallet",
+                    "If you've forgotten your password, you'll need to restore from your mnemonic",
+                ],
+            )
+    
+    # Handle wallet name conflicts specifically
+    if ("already exists" in error_str or "already has" in error_str) and ("wallet" in error_str or "name" in error_str or "hotkey" in error_str or "coldkey" in error_str):
+        return WalletError(
+            str(error),
+            [
+                "Choose a different wallet name",
+                "Use 'htcli wallet list' to see existing wallet names",
+                "For hotkeys: each coldkey can only have one hotkey with a given name",
+            ],
+        )
+
+    substrate_error = handle_substrate_error(error)
+
+    if isinstance(substrate_error, WalletError):
+        return substrate_error
+    else:
+        return WalletError(
+            f"Wallet {operation} failed: {str(error)}",
+            [
+                "Verify wallet exists: htcli wallet list",
+                "Check wallet permissions and password",
+                "Ensure wallet files are accessible",
+                f"Review command help: htcli wallet {operation} --help",
+            ],
+        )
+
+
+def handle_subnet_error(error_msg: str, operation: str = "subnet") -> SubnetError:
+    """Handle subnet-specific errors."""
+    error = Exception(error_msg)
+    substrate_error = handle_substrate_error(error)
+
+    if isinstance(substrate_error, SubnetError):
+        return substrate_error
+    else:
+        return SubnetError(
+            f"Subnet {operation} failed: {error_msg}",
+            [
+                "Check subnet status: htcli subnet list",
+                "Verify permissions and wallet balance",
+                f"Review command help: htcli subnet {operation} --help",
+            ],
+        )
+
+
+def format_pydantic_validation_error(error: ValidationError, model_name: str = "Request") -> str:
+    """
+    Format a Pydantic ValidationError into a user-friendly message.
+
+    Args:
+        error: The Pydantic ValidationError
+        model_name: Name of the model that failed validation (e.g., "SubnetRegisterRequest")
+
+    Returns:
+        Formatted error message string
+    """
+    errors = error.errors()
+    if not errors:
+        return f"Validation failed for {model_name}"
+
+    error_lines = [f"[htcli.error]❌ Validation Error in {model_name}[/htcli.error]\n"]
+    error_lines.append("[htcli.subtitle]The following fields have invalid values:[/htcli.subtitle]\n")
+
+    for err in errors:
+        field_path = " -> ".join(str(loc) for loc in err["loc"])
+        field_name = field_path if field_path != "root" else "request"
+        error_type = err["type"]
+        error_msg = err.get("msg", "Invalid value")
+        input_value = err.get("input")
+
+        # Format the error message
+        error_lines.append(f"[htcli.value]• {field_name}[/htcli.value]")
+
+        # Extract the actual error message from the context
+        if "ctx" in err and "error" in err["ctx"]:
+            actual_error = err["ctx"]["error"]
+            error_lines.append(f"  [htcli.error]{actual_error}[/htcli.error]")
+        else:
+            # Try to extract meaningful message from error_msg
+            if "Value error" in error_msg:
+                # Extract the actual error message after "Value error, "
+                parts = error_msg.split(", ", 1)
+                if len(parts) > 1:
+                    error_lines.append(f"  [htcli.error]{parts[1]}[/htcli.error]")
+                else:
+                    error_lines.append(f"  [htcli.error]{error_msg}[/htcli.error]")
+            else:
+                error_lines.append(f"  [htcli.error]{error_msg}[/htcli.error]")
+
+        # Show the invalid input value if available
+        if input_value is not None:
+            if isinstance(input_value, (int, float)) and input_value > 1e15:
+                # Format large numbers (likely wei values) in a readable way
+                formatted_value = f"{input_value / 1e18:.2f} TENSOR (raw: {input_value})"
+            else:
+                formatted_value = str(input_value)
+            error_lines.append(f"  [htcli.info]Invalid value: {formatted_value}[/htcli.info]")
+
+        error_lines.append("")  # Empty line between errors
+
+    return "\n".join(error_lines)
+
+
+def get_validation_suggestions(error: ValidationError) -> list[str]:
+    """
+    Generate helpful suggestions based on the validation errors.
+
+    Args:
+        error: The Pydantic ValidationError
+
+    Returns:
+        List of suggestion strings
+    """
+    suggestions = []
+    errors = error.errors()
+
+    for err in errors:
+        field_path = " -> ".join(str(loc) for loc in err["loc"])
+        error_type = err["type"]
+        error_msg = err.get("msg", "")
+
+        # Generate suggestions based on field and error type
+        if "min_stake" in field_path.lower():
+            suggestions.append("min_stake must be between 100 and 250 TENSOR")
+        elif "max_stake" in field_path.lower():
+            suggestions.append("max_stake must be <= 1000 TENSOR and >= min_stake")
+        elif "max_registered_nodes" in field_path.lower():
+            suggestions.append("max_registered_nodes must be between 1 and 64")
+        elif "delegate_stake_percentage" in field_path.lower():
+            suggestions.append("delegate_stake_percentage must be between 5% and 95%")
+        elif "required" in error_type.lower() or "missing" in error_msg.lower():
+            suggestions.append(f"Field '{field_path}' is required and must be provided")
+        elif "greater_than" in error_type.lower() or "less_than" in error_type.lower():
+            suggestions.append(f"Check that '{field_path}' is within the allowed range")
+
+    # Remove duplicates while preserving order
+    seen = set()
+    unique_suggestions = []
+    for suggestion in suggestions:
+        if suggestion not in seen:
+            seen.add(suggestion)
+            unique_suggestions.append(suggestion)
+
+    return unique_suggestions if unique_suggestions else None
+
+
+def display_pydantic_validation_error(
+    error: ValidationError,
+    model_name: str = "Request",
+    suggestions: list[str] = None,
+) -> None:
+    """
+    Display a Pydantic ValidationError in a user-friendly format.
+
+    Args:
+        error: The Pydantic ValidationError
+        model_name: Name of the model that failed validation
+        suggestions: Optional list of helpful suggestions
+    """
+    from ..ui.components import HTCLIPanel
+    from ..ui.display import HTCLIConsole
+
+    console = HTCLIConsole()
+
+    # Format the error message
+    error_content = format_pydantic_validation_error(error, model_name)
+
+    # Add suggestions if provided
+    if suggestions:
+        error_content += "\n[htcli.info]💡 How to fix this:[/htcli.info]\n"
+        for suggestion in suggestions:
+            error_content += f"  • {suggestion}\n"
+    else:
+        # Generate default suggestions based on common validation errors
+        error_content += "\n[htcli.info]💡 Tips:[/htcli.info]\n"
+        error_content += "  • Check that all numeric values are within the allowed ranges\n"
+        error_content += "  • Ensure required fields are provided\n"
+        error_content += "  • Verify that string fields meet length requirements\n"
+
+    # Create and display the error panel
+    error_panel = HTCLIPanel(
+        error_content,
+        title="⚠️  Validation Error",
+        border_style="htcli.error",
+        highlight=True,
+    )
+    error_panel.render(console.console)
+    console.print("")
+
+
+def handle_and_display_error(error: Exception, operation: str = "operation") -> None:
+    """Handle and display any error with appropriate formatting."""
+    # Handle KeyboardInterrupt cleanly
+    if isinstance(error, KeyboardInterrupt):
+        from ..ui.display import get_console, print_warning
+
+        get_console().print()
+        print_warning("Operation cancelled")
+        import sys
+        sys.exit(130)  # Standard exit code for SIGINT (Ctrl+C)
+        return
+    
+    # Handle RuntimeError specifically (connection errors from get_client())
+    if isinstance(error, RuntimeError):
+        from ..ui.display import print_error
+        error_str = str(error).lower()
+        if "connect" in error_str or "blockchain" in error_str:
+            print_error(f"Blockchain Connection Error: {str(error)}")
+        else:
+            print_error(f"Error: {str(error)}")
+        raise SystemExit(1)
+    
+    # Handle Pydantic ValidationError specifically
+    if isinstance(error, ValidationError):
+        suggestions = get_validation_suggestions(error)
+        display_pydantic_validation_error(
+            error,
+            model_name=operation.replace("_", " ").title(),
+            suggestions=suggestions,
+        )
+        raise SystemExit(1)
+
+    # Handle other errors using substrate error handler
+    htcli_error = handle_substrate_error(error)
+    htcli_error.display()
+    raise SystemExit(1)
+
+
+def handle_and_display_subnet_error(
+    error: Exception, operation: str = "subnet"
+) -> None:
+    """Handle and display subnet errors with appropriate formatting."""
+    subnet_error = handle_subnet_error(str(error), operation)
+    subnet_error.display()
+
+
+def handle_node_error(error_msg: str, operation: str = "node") -> NodeError:
+    """Handle node-specific errors."""
+    error = Exception(error_msg)
+    substrate_error = handle_substrate_error(error)
+
+    if isinstance(substrate_error, NodeError):
+        return substrate_error
+    else:
+        return NodeError(
+            f"Node {operation} failed: {error_msg}",
+            [
+                "Check node status: htcli node info --subnet-id <id> --node-id <id>",
+                "Verify node exists: htcli node list --subnet-id <id>",
+                "Ensure you have the correct permissions",
+                f"Review command help: htcli node {operation} --help",
+            ],
+        )
+
+
+def handle_and_display_node_error(error: Exception, operation: str = "node") -> None:
+    """Handle and display node errors with appropriate formatting."""
+    node_error = handle_node_error(str(error), operation)
+    node_error.display()