cartha-cli 1.0.0__py3-none-any.whl

cartha_cli/__init__.py

@@ -0,0 +1,34 @@
+"""Cartha CLI package."""
+
+
+def main() -> None:  # pragma: no cover
+    import sys
+
+    argv = sys.argv[1:]
+
+    if not argv:
+        sys.argv = [sys.argv[0]]
+        from .commands.help import print_root_help
+
+        print_root_help()
+        raise SystemExit(0)
+
+    if argv[0] in {"-h", "--help"}:
+        original = sys.argv[:]
+        sys.argv = [sys.argv[0]]
+        from .commands.help import print_root_help
+
+        print_root_help()
+        sys.argv = original
+        raise SystemExit(0)
+
+    original = sys.argv[:]
+    sanitized = [original[0]] + [arg for arg in argv if arg not in {"-h", "--help"}]
+    sys.argv = sanitized
+    from .main import app
+
+    sys.argv = original
+    app()
+
+
+__all__ = ["main"]

cartha_cli/bt.py

@@ -0,0 +1,206 @@
+"""Bittensor convenience wrappers."""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass
+
+try:
+    import bittensor as bt
+except ImportError:  # pragma: no cover - surfaced at call time
+    bt = None
+
+
+def get_subtensor(network: str) -> bt.Subtensor:
+    if bt is None:  # pragma: no cover - safeguarded for tests
+        raise RuntimeError("bittensor is not installed")
+    return bt.subtensor(network=network)
+
+
+def get_wallet(name: str, hotkey: str) -> bt.wallet:
+    if bt is None:  # pragma: no cover
+        raise RuntimeError("bittensor is not installed")
+    return bt.wallet(name=name, hotkey=hotkey)
+
+
+@dataclass(frozen=True)
+class RegistrationResult:
+    status: str
+    success: bool
+    uid: int | None
+    hotkey: str
+    extrinsic: str | None = None  # Extrinsic hash (e.g., "5759123-5")
+    balance_before: float | None = None  # Balance before registration
+    balance_after: float | None = None  # Balance after registration
+
+
+def register_hotkey(
+    *,
+    network: str,
+    wallet_name: str,
+    hotkey_name: str,
+    netuid: int,
+    burned: bool = True,
+    cuda: bool = False,
+    wait_for_finalization: bool = True,
+    wait_for_inclusion: bool = False,
+    dev_id: int | list[int] | None = 0,
+    tpb: int = 256,
+    num_processes: int | None = None,
+) -> RegistrationResult:
+    """Register a hotkey on the target subnet and return the resulting UID."""
+
+    subtensor = get_subtensor(network)
+    wallet = get_wallet(wallet_name, hotkey_name)
+    hotkey_ss58 = wallet.hotkey.ss58_address
+
+    if subtensor.is_hotkey_registered(hotkey_ss58, netuid=netuid):
+        neuron = subtensor.get_neuron_for_pubkey_and_subnet(hotkey_ss58, netuid)
+        uid = None if getattr(neuron, "is_null", False) else getattr(neuron, "uid", None)
+        return RegistrationResult(status="already", success=True, uid=uid, hotkey=hotkey_ss58)
+
+    # Get balance before registration
+    balance_before = None
+    balance_after = None
+    extrinsic = None
+
+    try:
+        balance_obj = subtensor.get_balance(wallet.coldkeypub.ss58_address)
+        # Convert Balance object to float using .tao property
+        balance_before = balance_obj.tao if hasattr(balance_obj, "tao") else float(balance_obj)
+    except Exception:
+        pass  # Balance may not be available, continue anyway
+
+    if burned:
+        # burned_register returns (success, block_info) or just success
+        registration_result = subtensor.burned_register(
+            wallet=wallet,
+            netuid=netuid,
+            wait_for_finalization=wait_for_finalization,
+        )
+
+        # Handle both return types: bool or (bool, message)
+        if isinstance(registration_result, tuple):
+            ok, message = registration_result
+            if isinstance(message, str) and message:
+                extrinsic = message
+        else:
+            ok = registration_result
+
+        status = "burned"
+    else:
+        ok = subtensor.register(
+            wallet=wallet,
+            netuid=netuid,
+            wait_for_finalization=wait_for_finalization,
+            wait_for_inclusion=wait_for_inclusion,
+            cuda=cuda,
+            dev_id=dev_id,
+            tpb=tpb,
+            num_processes=num_processes,
+            log_verbose=False,
+        )
+        status = "pow"
+        if isinstance(ok, tuple) and len(ok) == 2:
+            ok, message = ok
+            if isinstance(message, str):
+                extrinsic = message
+
+    if not ok:
+        return RegistrationResult(
+            status=status,
+            success=False,
+            uid=None,
+            hotkey=hotkey_ss58,
+            balance_before=balance_before,
+            balance_after=balance_after,
+            extrinsic=extrinsic,
+        )
+
+    # Get balance after registration
+    try:
+        balance_obj = subtensor.get_balance(wallet.coldkeypub.ss58_address)
+        # Convert Balance object to float using .tao property
+        balance_after = balance_obj.tao if hasattr(balance_obj, "tao") else float(balance_obj)
+    except Exception:
+        pass
+
+    neuron = subtensor.get_neuron_for_pubkey_and_subnet(hotkey_ss58, netuid)
+    uid = None if getattr(neuron, "is_null", False) else getattr(neuron, "uid", None)
+
+    return RegistrationResult(
+        status=status,
+        success=True,
+        uid=uid,
+        hotkey=hotkey_ss58,
+        balance_before=balance_before,
+        balance_after=balance_after,
+        extrinsic=extrinsic,
+    )
+
+
+def get_burn_cost(network: str, netuid: int) -> float | None:
+    """Get the burn cost (registration cost) for a subnet.
+
+    Args:
+        network: Bittensor network name (e.g., "test", "finney")
+        netuid: Subnet netuid
+
+    Returns:
+        Burn cost in TAO as a float, or None if unavailable
+    """
+    # Try async SubtensorInterface method (most reliable)
+    try:
+        from bittensor_cli.src.bittensor.balances import Balance  # type: ignore[import-not-found]
+        from bittensor_cli.src.bittensor.subtensor_interface import (  # type: ignore[import-not-found]
+            SubtensorInterface,
+        )
+
+        async def _fetch_burn_cost() -> float:
+            async with SubtensorInterface(network=network) as subtensor_async:
+                block_hash = await subtensor_async.substrate.get_chain_head()
+                burn_raw = await subtensor_async.get_hyperparameter(
+                    param_name="Burn",
+                    netuid=netuid,
+                    block_hash=block_hash,
+                )
+                register_cost = (
+                    Balance.from_rao(int(burn_raw)) if burn_raw is not None else Balance(0)
+                )
+                tao_value = (
+                    register_cost.tao if hasattr(register_cost, "tao") else float(register_cost)
+                )
+                return float(tao_value)
+
+        return asyncio.run(_fetch_burn_cost())
+    except ImportError:
+        # bittensor-cli not available, try fallback synchronous method
+        try:
+            subtensor = get_subtensor(network)
+            # Use get_hyperparameter("Burn", netuid) - this works synchronously
+            if hasattr(subtensor, "get_hyperparameter"):
+                burn_raw = subtensor.get_hyperparameter("Burn", netuid=netuid)
+                if burn_raw is not None:
+                    # Convert from rao to TAO
+                    from bittensor import Balance
+
+                    balance_obj = Balance.from_rao(int(burn_raw))
+                    return balance_obj.tao if hasattr(balance_obj, "tao") else float(balance_obj)
+        except Exception:
+            pass
+    except Exception as exc:
+        # Log other exceptions but don't show warnings in normal operation
+        import warnings
+
+        warnings.warn(f"Failed to fetch burn cost: {exc}", UserWarning, stacklevel=2)
+
+    return None
+
+
+__all__ = [
+    "get_subtensor",
+    "get_wallet",
+    "register_hotkey",
+    "get_burn_cost",
+    "RegistrationResult",
+]

cartha_cli/commands/__init__.py

@@ -0,0 +1,25 @@
+"""CLI command modules."""
+
+from . import (
+    config,
+    health,
+    miner_password,
+    miner_status,
+    pair_status,
+    pools,
+    prove_lock,
+    register,
+    version,
+)
+
+__all__ = [
+    "config",
+    "health",
+    "miner_password",
+    "miner_status",
+    "pair_status",
+    "pools",
+    "prove_lock",
+    "register",
+    "version",
+]

cartha_cli/commands/common.py

@@ -0,0 +1,76 @@
+"""Common utilities and helpers for CLI commands."""
+
+from __future__ import annotations
+
+from typing import NoReturn
+
+import bittensor as bt
+import typer
+from rich.console import Console
+
+from ..config import settings
+
+console = Console()
+
+_TRACE_ENABLED = False
+
+
+def set_trace_enabled(enabled: bool) -> None:
+    """Set whether trace mode is enabled."""
+    global _TRACE_ENABLED
+    _TRACE_ENABLED = enabled
+
+
+def trace_enabled() -> bool:
+    """Check if trace mode is enabled."""
+    return _TRACE_ENABLED
+
+
+def exit_with_error(message: str, code: int = 1) -> NoReturn:
+    """Exit with an error message."""
+    console.print(f"[bold red]{message}[/]")
+    raise typer.Exit(code=code)
+
+
+def handle_wallet_exception(
+    *,
+    wallet_name: str | None,
+    wallet_hotkey: str | None,
+    exc: Exception,
+) -> None:
+    """Handle wallet-related exceptions."""
+    detail = str(exc).strip()
+    name = wallet_name or "<unknown>"
+    hotkey = wallet_hotkey or "<unknown>"
+    message = (
+        f"Unable to open coldkey '{name}' hotkey '{hotkey}'. "
+        "Ensure the wallet exists, hotkey files are present, and the key is unlocked."
+    )
+    if detail:
+        message += f" ({detail})"
+    exit_with_error(message)
+
+
+def handle_unexpected_exception(context: str, exc: Exception) -> None:
+    """Handle unexpected exceptions."""
+    if trace_enabled():
+        raise
+    detail = str(exc).strip()
+    message = context
+    if detail:
+        message += f" ({detail})"
+    exit_with_error(message)
+
+
+def log_endpoint_banner() -> None:
+    """Log the endpoint banner based on verifier URL."""
+    verifier_url = settings.verifier_url.lower()
+    if verifier_url.startswith("http://127.0.0.1"):
+        console.print("[bold cyan]Using local verifier endpoint[/]")
+    elif "pr-" in verifier_url:
+        console.print("[bold cyan]Using Cartha DEV network verifier[/]")
+    elif "cartha-verifier-826542474079.us-central1.run.app" in verifier_url:
+        console.print("[bold cyan]Using Cartha Testnet Verifier[/]")
+    else:
+        console.print("[bold cyan]Using Cartha network verifier[/]")
+

cartha_cli/commands/config.py

@@ -0,0 +1,294 @@
+"""Configuration command - view and set environment variables."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any
+
+import typer
+from rich.table import Table
+
+from ..config import Settings
+from .common import console
+
+
+# Environment variable documentation
+ENV_VAR_DOCS: dict[str, dict[str, Any]] = {
+    "CARTHA_VERIFIER_URL": {
+        "description": "URL of the Cartha verifier service",
+        "default": "https://cartha-verifier-826542474079.us-central1.run.app",
+        "required": False,
+    },
+    "CARTHA_NETWORK": {
+        "description": "Bittensor network name (e.g., 'finney', 'test')",
+        "default": "finney",
+        "required": False,
+    },
+    "CARTHA_NETUID": {
+        "description": "Subnet UID (netuid) for the Cartha subnet",
+        "default": "35",
+        "required": False,
+    },
+    "CARTHA_EVM_PK": {
+        "description": "EVM private key for signing transactions (sensitive)",
+        "default": None,
+        "required": False,
+        "sensitive": True,
+    },
+    "CARTHA_RETRY_MAX_ATTEMPTS": {
+        "description": "Maximum number of retry attempts for failed requests",
+        "default": "3",
+        "required": False,
+    },
+    "CARTHA_RETRY_BACKOFF_FACTOR": {
+        "description": "Backoff factor for exponential retry delays",
+        "default": "1.5",
+        "required": False,
+    },
+    "CARTHA_LOCK_UI_URL": {
+        "description": "URL of the Cartha Lock UI frontend",
+        "default": "https://cartha.finance",
+        "required": False,
+    },
+}
+
+
+def _get_env_file_path() -> Path:
+    """Get the path to the .env file in the current directory."""
+    return Path.cwd() / ".env"
+
+
+def _read_env_file() -> dict[str, str]:
+    """Read existing .env file and return as dict."""
+    env_file = _get_env_file_path()
+    env_vars: dict[str, str] = {}
+    
+    if env_file.exists():
+        try:
+            with open(env_file, "r", encoding="utf-8") as f:
+                for line in f:
+                    line = line.strip()
+                    # Skip empty lines and comments
+                    if not line or line.startswith("#"):
+                        continue
+                    # Parse KEY=VALUE format
+                    if "=" in line:
+                        key, value = line.split("=", 1)
+                        env_vars[key.strip()] = value.strip().strip('"').strip("'")
+        except Exception:
+            pass
+    
+    return env_vars
+
+
+def _write_env_file(env_vars: dict[str, str], remove_vars: set[str] | None = None) -> None:
+    """Write environment variables to .env file.
+    
+    Args:
+        env_vars: Dictionary of variables to set/update
+        remove_vars: Optional set of variable names to remove from file
+    """
+    env_file = _get_env_file_path()
+    remove_vars = remove_vars or set()
+    
+    # Read existing file to preserve comments and other vars
+    existing_lines: list[str] = []
+    existing_vars: set[str] = set()
+    
+    if env_file.exists():
+        with open(env_file, "r", encoding="utf-8") as f:
+            for line in f:
+                stripped = line.strip()
+                if stripped and not stripped.startswith("#") and "=" in stripped:
+                    key = stripped.split("=", 1)[0].strip()
+                    existing_vars.add(key)
+                    # Skip lines for variables we want to remove
+                    if key in remove_vars:
+                        continue
+                existing_lines.append(line.rstrip())
+    
+    # Update or add new vars
+    for key, value in env_vars.items():
+        if key in existing_vars and key not in remove_vars:
+            # Update existing line
+            for i, line in enumerate(existing_lines):
+                if line.strip() and not line.strip().startswith("#") and line.startswith(f"{key}="):
+                    existing_lines[i] = f"{key}={value}"
+                    break
+        elif key not in remove_vars:
+            # Add new line
+            existing_lines.append(f"{key}={value}")
+    
+    # Write back to file
+    with open(env_file, "w", encoding="utf-8") as f:
+        for line in existing_lines:
+            f.write(line + "\n")
+
+
+def config_list() -> None:
+    """List all available environment variables and their current values."""
+    console.print("\n[bold cyan]━━━ Configuration ━━━[/]")
+    console.print()
+    
+    # Get default values
+    default_settings = Settings()
+    
+    # Get current values from environment
+    current_values: dict[str, str | None] = {}
+    for env_var in ENV_VAR_DOCS.keys():
+        current_values[env_var] = os.getenv(env_var)
+    
+    # Create table
+    table = Table(show_header=True, header_style="bold cyan")
+    table.add_column("Variable", style="cyan", no_wrap=True)
+    table.add_column("Description", style="dim")
+    table.add_column("Current Value", style="green")
+    table.add_column("Default", style="dim")
+    table.add_column("Source", justify="center")
+    
+    for env_var, doc in ENV_VAR_DOCS.items():
+        current_val = current_values.get(env_var)
+        default_val = doc.get("default")
+        is_sensitive = doc.get("sensitive", False)
+        
+        # Format current value
+        if current_val is not None:
+            if is_sensitive:
+                display_current = "[REDACTED]"
+            else:
+                display_current = current_val
+            source = "[green]●[/] env"
+        else:
+            display_current = default_val or "-"
+            source = "[dim]○[/] default"
+        
+        # Format default value
+        display_default = default_val or "-"
+        
+        table.add_row(
+            env_var,
+            doc["description"],
+            display_current,
+            display_default,
+            source,
+        )
+    
+    console.print(table)
+    console.print()
+    console.print("[dim]● = Set via environment variable[/]")
+    console.print("[dim]○ = Using default value[/]")
+    console.print()
+    console.print(f"[dim]Environment file: {_get_env_file_path()}[/]")
+    console.print("[dim]Use 'cartha config set <VAR> <VALUE>' to set a value[/]")
+
+
+def config_set(
+    variable: str = typer.Argument(..., help="Environment variable name (e.g., CARTHA_VERIFIER_URL)"),
+    value: str = typer.Argument(..., help="Value to set"),
+    env_file: bool = typer.Option(
+        True,
+        "--env-file/--no-env-file",
+        help="Write to .env file (default: True). If False, only sets in current session.",
+    ),
+) -> None:
+    """Set an environment variable value.
+    
+    By default, writes to .env file in the current directory. Use --no-env-file
+    to only set for the current session (doesn't persist).
+    """
+    # Validate variable name
+    if variable not in ENV_VAR_DOCS:
+        console.print(f"[bold red]✗ Unknown variable: {variable}[/]")
+        console.print(f"\nAvailable variables:")
+        for var_name in ENV_VAR_DOCS.keys():
+            console.print(f"  • {var_name}")
+        raise typer.Exit(code=1)
+    
+    doc = ENV_VAR_DOCS[variable]
+    is_sensitive = doc.get("sensitive", False)
+    
+    if env_file:
+        # Read existing .env file
+        env_vars = _read_env_file()
+        
+        # Update the variable
+        env_vars[variable] = value
+        
+        # Write back
+        try:
+            _write_env_file(env_vars)
+            display_value = "[REDACTED]" if is_sensitive else value
+            console.print(f"[bold green]✓ Set {variable}={display_value}[/]")
+            console.print(f"[dim]Written to: {_get_env_file_path()}[/]")
+            console.print("[yellow]Note: Restart your terminal or run 'source .env' to apply changes[/]")
+        except Exception as exc:
+            console.print(f"[bold red]✗ Failed to write to .env file: {exc}[/]")
+            raise typer.Exit(code=1)
+    else:
+        # Only set for current session
+        os.environ[variable] = value
+        display_value = "[REDACTED]" if is_sensitive else value
+        console.print(f"[bold green]✓ Set {variable}={display_value}[/] (current session only)")
+        console.print("[yellow]Note: This will not persist after the terminal session ends[/]")
+
+
+def config_get(
+    variable: str = typer.Argument(..., help="Environment variable name (e.g., CARTHA_VERIFIER_URL)"),
+) -> None:
+    """Get the current value of an environment variable."""
+    if variable not in ENV_VAR_DOCS:
+        console.print(f"[bold red]✗ Unknown variable: {variable}[/]")
+        console.print(f"\nAvailable variables:")
+        for var_name in ENV_VAR_DOCS.keys():
+            console.print(f"  • {var_name}")
+        raise typer.Exit(code=1)
+    
+    doc = ENV_VAR_DOCS[variable]
+    is_sensitive = doc.get("sensitive", False)
+    
+    # Get current value
+    current_val = os.getenv(variable)
+    default_val = doc.get("default")
+    
+    console.print(f"\n[bold cyan]{variable}[/]")
+    console.print(f"Description: {doc['description']}")
+    console.print(f"Default: {default_val or 'None'}")
+    
+    if current_val is not None:
+        display_value = "[REDACTED]" if is_sensitive else current_val
+        console.print(f"Current Value: [green]{display_value}[/] (from environment)")
+    else:
+        console.print(f"Current Value: [dim]{default_val or 'None'}[/] (using default)")
+
+
+def config_unset(
+    variable: str = typer.Argument(..., help="Environment variable name to unset"),
+    env_file: bool = typer.Option(
+        True,
+        "--env-file/--no-env-file",
+        help="Remove from .env file (default: True). If False, only unsets in current session.",
+    ),
+) -> None:
+    """Unset an environment variable (remove from .env file or current session)."""
+    if variable not in ENV_VAR_DOCS:
+        console.print(f"[bold red]✗ Unknown variable: {variable}[/]")
+        raise typer.Exit(code=1)
+    
+    if env_file:
+        # Read existing .env file to check if it exists
+        env_vars = _read_env_file()
+        
+        if variable in env_vars:
+            # Remove from file
+            _write_env_file({}, remove_vars={variable})
+            console.print(f"[bold green]✓ Removed {variable} from .env file[/]")
+        else:
+            console.print(f"[yellow]⚠ {variable} not found in .env file[/]")
+    else:
+        # Remove from current session
+        if variable in os.environ:
+            del os.environ[variable]
+            console.print(f"[bold green]✓ Removed {variable} from current session[/]")
+        else:
+            console.print(f"[yellow]⚠ {variable} not set in current session[/]")