cartha-cli 1.0.0__py3-none-any.whl

cartha_cli/main.py

@@ -0,0 +1,237 @@
+"""Primary Typer application for the Cartha CLI."""
+
+from __future__ import annotations
+
+import typer
+
+from .commands import (
+    config,
+    health,
+    miner_status,
+    pair_status,
+    pools,
+    prove_lock,
+    register,
+    version,
+)
+from .commands.common import log_endpoint_banner, set_trace_enabled
+from .commands.help import print_root_help
+
+app = typer.Typer(
+    help="Miner-facing tooling for registering on the Cartha subnet and managing lock positions. Cartha is the Liquidity Provider for 0xMarkets DEX.",
+    add_completion=False,
+)
+
+# Create command groups
+miner_app = typer.Typer(
+    help="Miner management commands: register, check status, and manage passwords.",
+    name="miner",
+    invoke_without_command=True,
+)
+miner_app_alias = typer.Typer(
+    help="Miner management commands: register, check status, and manage passwords.",
+    name="m",
+    invoke_without_command=True,
+)
+vault_app = typer.Typer(
+    help="Vault management commands: lock funds and claim deposits.",
+    name="vault",
+    invoke_without_command=True,
+)
+vault_app_alias = typer.Typer(
+    help="Vault management commands: lock funds and claim deposits.",
+    name="v",
+    invoke_without_command=True,
+)
+
+
+# Define callbacks for groups (show help when invoked without subcommand)
+def miner_group_callback(
+    ctx: typer.Context,
+    help_option: bool = typer.Option(
+        False,
+        "--help",
+        "-h",
+        help="Show this message and exit.",
+        is_eager=True,
+    ),
+) -> None:
+    """Miner management commands."""
+    if ctx.invoked_subcommand is None or help_option:
+        ctx.get_help()
+        raise typer.Exit()
+
+
+def vault_group_callback(
+    ctx: typer.Context,
+    help_option: bool = typer.Option(
+        False,
+        "--help",
+        "-h",
+        help="Show this message and exit.",
+        is_eager=True,
+    ),
+) -> None:
+    """Vault management commands."""
+    if ctx.invoked_subcommand is None or help_option:
+        ctx.get_help()
+        raise typer.Exit()
+
+
+# Register callbacks for both miner apps (main and alias)
+miner_app.callback(invoke_without_command=True)(miner_group_callback)
+miner_app_alias.callback(invoke_without_command=True)(miner_group_callback)
+
+# Register callbacks for both vault apps (main and alias)
+vault_app.callback(invoke_without_command=True)(vault_group_callback)
+vault_app_alias.callback(invoke_without_command=True)(vault_group_callback)
+
+# Register commands in both miner apps (main and alias)
+for miner_group in [miner_app, miner_app_alias]:
+    miner_group.command("status")(miner_status.miner_status)
+    miner_group.command("register")(register.register)
+
+# Register commands in both vault apps (main and alias)
+for vault_group in [vault_app, vault_app_alias]:
+    vault_group.command("lock")(prove_lock.prove_lock)
+    vault_group.command("pools")(pools.pools)
+
+# Add groups with short aliases (after callbacks and commands are registered)
+app.add_typer(miner_app, name="miner")
+app.add_typer(miner_app_alias, name="m")  # Short alias
+app.add_typer(vault_app, name="vault")
+app.add_typer(vault_app_alias, name="v")  # Short alias
+
+# Keep pair_app for backward compatibility (deprecated)
+pair_app = typer.Typer(
+    help="Pair status commands (deprecated - use 'cartha miner status')."
+)
+app.add_typer(pair_app, name="pair")
+
+
+@app.callback(invoke_without_command=True)
+def cli_root(
+    ctx: typer.Context,
+    help_option: bool = typer.Option(
+        False,
+        "--help",
+        "-h",
+        help="Show this message and exit.",
+        is_eager=True,
+    ),
+    trace: bool = typer.Option(
+        False,
+        "--trace",
+        help="Show full stack traces when errors occur.",
+    ),
+) -> None:
+    """Top-level callback to provide rich help and endpoint banner."""
+    set_trace_enabled(trace)
+    if ctx.obj is None:
+        ctx.obj = {}
+    ctx.obj["trace"] = trace
+
+    if help_option:
+        print_root_help()
+        raise typer.Exit()
+
+    if ctx.invoked_subcommand is None:
+        print_root_help()
+        raise typer.Exit()
+
+    log_endpoint_banner()
+
+
+# Register top-level commands
+app.command("version")(version.version_command)
+
+# Create utils command group
+utils_app = typer.Typer(
+    help="Utility commands: health checks and configuration management.",
+    name="utils",
+    invoke_without_command=True,
+)
+utils_app_alias = typer.Typer(
+    help="Utility commands: health checks and configuration management.",
+    name="u",
+    invoke_without_command=True,
+)
+
+def utils_group_callback(
+    ctx: typer.Context,
+    help_option: bool = typer.Option(
+        False,
+        "--help",
+        "-h",
+        help="Show this message and exit.",
+        is_eager=True,
+    ),
+) -> None:
+    """Utility commands."""
+    if ctx.invoked_subcommand is None or help_option:
+        ctx.get_help()
+        raise typer.Exit()
+
+# Register callbacks for both utils apps (main and alias)
+utils_app.callback(invoke_without_command=True)(utils_group_callback)
+utils_app_alias.callback(invoke_without_command=True)(utils_group_callback)
+
+# Register commands in both utils apps (main and alias)
+for utils_group in [utils_app, utils_app_alias]:
+    utils_group.command("health")(health.health_check)
+
+# Create config subcommand group under utils
+config_app = typer.Typer(
+    help="Configuration commands: view and set environment variables.",
+    name="config",
+    invoke_without_command=True,
+)
+
+def config_group_callback(
+    ctx: typer.Context,
+    help_option: bool = typer.Option(
+        False,
+        "--help",
+        "-h",
+        help="Show this message and exit.",
+        is_eager=True,
+    ),
+) -> None:
+    """Configuration commands."""
+    if ctx.invoked_subcommand is None or help_option:
+        if ctx.invoked_subcommand is None:
+            # Show list by default
+            config.config_list()
+        else:
+            ctx.get_help()
+        raise typer.Exit()
+
+config_app.callback(invoke_without_command=True)(config_group_callback)
+config_app.command("list")(config.config_list)
+config_app.command("set")(config.config_set)
+config_app.command("get")(config.config_get)
+config_app.command("unset")(config.config_unset)
+
+# Add config to both utils apps (main and alias)
+for utils_group in [utils_app, utils_app_alias]:
+    utils_group.add_typer(config_app)
+
+# Add groups with short aliases (after callbacks and commands are registered)
+app.add_typer(utils_app, name="utils")
+app.add_typer(utils_app_alias, name="u")  # Short alias
+
+
+def help_command() -> None:
+    """Show help message."""
+    print_root_help()
+    raise typer.Exit()
+
+
+app.command("help")(help_command)
+
+# Keep deprecated commands for backward compatibility
+pair_app.command("status")(pair_status.pair_status)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    app()

cartha_cli/pair.py

@@ -0,0 +1,201 @@
+"""Pair authentication and status utilities for the Cartha CLI."""
+
+from __future__ import annotations
+
+import time
+from typing import Any
+
+import bittensor as bt
+import typer
+from rich.console import Console
+
+from .bt import get_subtensor
+from .utils import format_timestamp
+from .verifier import VerifierError, fetch_pair_status
+from .wallet import CHALLENGE_PREFIX, CHALLENGE_TTL_SECONDS, load_wallet
+
+console = Console()
+
+
+def get_uid_from_hotkey(
+    *,
+    network: str,
+    netuid: int,
+    hotkey: str,
+) -> int | None:
+    """Get the UID for a hotkey on the subnet.
+
+    Args:
+        network: Bittensor network name
+        netuid: Subnet netuid
+        hotkey: Hotkey SS58 address
+
+    Returns:
+        UID if registered, None if not registered or deregistered
+    """
+    subtensor = None
+
+    try:
+        subtensor = get_subtensor(network)
+
+        # Try to get UID directly - if successful, they're registered
+        try:
+            uid = subtensor.get_uid_for_hotkey_on_subnet(
+                hotkey_ss58=hotkey, netuid=netuid
+            )
+            if uid is not None and uid >= 0:
+                return int(uid)
+        except AttributeError:
+            # Method doesn't exist in this bittensor version
+            return None
+        except Exception:
+            # Any other error means not registered or network issue
+            return None
+
+        return None
+    except Exception as exc:
+        error_msg = str(exc)
+        if "nodename" in error_msg.lower() or "servname" in error_msg.lower():
+            console.print(
+                f"[bold red]Network error[/]: Unable to connect to Bittensor {network} network: {error_msg}"
+            )
+            console.print(
+                "[yellow]This might be a DNS/network connectivity issue. Please check your internet connection.[/]"
+            )
+            raise typer.Exit(code=1) from None
+        # Re-raise other exceptions as-is
+        raise
+    finally:
+        # Clean up connections
+        try:
+            if subtensor is not None:
+                if hasattr(subtensor, "close"):
+                    subtensor.close()
+                del subtensor
+        except Exception:
+            pass
+
+
+def ensure_pair_registered(
+    *,
+    network: str,
+    netuid: int,
+    slot: str,
+    hotkey: str,
+) -> None:
+    """Ensure a pair is registered on the subnet.
+
+    Args:
+        network: Bittensor network name
+        netuid: Subnet netuid
+        slot: Slot UID
+        hotkey: Hotkey SS58 address
+
+    Raises:
+        typer.Exit: If pair is not registered or UID mismatch
+    """
+    subtensor = None
+    metagraph = None
+    try:
+        subtensor = get_subtensor(network)
+        metagraph = subtensor.metagraph(netuid)
+        slot_index = int(slot)
+        if slot_index < 0 or slot_index >= len(metagraph.hotkeys):
+            console.print(
+                f"[bold red]UID {slot} not found[/] in the metagraph (netuid {netuid})."
+            )
+            raise typer.Exit(code=1)
+        registered_hotkey = metagraph.hotkeys[slot_index]
+        if registered_hotkey != hotkey:
+            console.print(
+                f"[bold red]UID mismatch[/]: slot {slot} belongs to a different hotkey, not {hotkey}. Please verify your inputs."
+            )
+            raise typer.Exit(code=1)
+    except Exception as exc:
+        error_msg = str(exc)
+        if "nodename" in error_msg.lower() or "servname" in error_msg.lower():
+            console.print(
+                f"[bold red]Network error[/]: Unable to connect to Bittensor {network} network: {error_msg}"
+            )
+            console.print(
+                "[yellow]This might be a DNS/network connectivity issue. Please check your internet connection.[/]"
+            )
+            raise typer.Exit(code=1) from None
+        # Re-raise other exceptions as-is
+        raise
+    finally:
+        # Clean up connections
+        try:
+            if subtensor is not None:
+                if hasattr(subtensor, "close"):
+                    subtensor.close()
+                del subtensor
+            if metagraph is not None:
+                del metagraph
+        except Exception:
+            pass
+
+
+def build_pair_auth_payload(
+    *,
+    network: str,
+    netuid: int,
+    slot: str,
+    hotkey: str,
+    wallet_name: str,
+    wallet_hotkey: str,
+    skip_metagraph_check: bool = False,
+    challenge_prefix: str | None = None,
+) -> dict[str, Any]:
+    """Build authentication payload for pair status/password requests or lock flow.
+
+    Args:
+        network: Bittensor network name
+        netuid: Subnet netuid
+        slot: Slot UID
+        hotkey: Hotkey SS58 address
+        wallet_name: Coldkey wallet name
+        wallet_hotkey: Hotkey name
+        skip_metagraph_check: Skip metagraph validation check
+        challenge_prefix: Challenge prefix (defaults to CHALLENGE_PREFIX, use "cartha-lock" for lock flow)
+
+    Returns:
+        Dictionary with message, signature, and expires_at
+    """
+    wallet = load_wallet(wallet_name, wallet_hotkey, hotkey)
+    if not skip_metagraph_check:
+        ensure_pair_registered(
+            network=network, netuid=netuid, slot=slot, hotkey=hotkey
+        )
+
+    timestamp = int(time.time())
+    prefix = challenge_prefix or CHALLENGE_PREFIX
+    message = (
+        f"{prefix}|network:{network}|netuid:{netuid}|slot:{slot}|"
+        f"hotkey:{hotkey}|ts:{timestamp}"
+    )
+    message_bytes = message.encode("utf-8")
+    signature_bytes = wallet.hotkey.sign(message_bytes)
+
+    verifier_keypair = bt.Keypair(ss58_address=hotkey)
+    if not verifier_keypair.verify(message_bytes, signature_bytes):
+        console.print("[bold red]Unable to verify the ownership signature locally.[/]")
+        raise typer.Exit(code=1)
+
+    expires_at = timestamp + CHALLENGE_TTL_SECONDS
+    expiry_time = format_timestamp(expires_at)
+    console.print(
+        "[bold green]Ownership challenge signed[/] "
+        f"(expires in {CHALLENGE_TTL_SECONDS}s at {expiry_time})."
+    )
+
+    return {
+        "message": message,
+        "signature": "0x" + signature_bytes.hex(),
+        "expires_at": expires_at,
+    }
+
+
+# REMOVED: request_pair_status_or_password - replaced by new lock flow
+# Old function removed as part of new lock flow implementation
+

cartha_cli/utils.py

@@ -0,0 +1,274 @@
+"""Utility functions for the Cartha CLI."""
+
+from __future__ import annotations
+
+import time
+from datetime import UTC, datetime, timedelta
+from decimal import ROUND_DOWN, Decimal, InvalidOperation
+from zoneinfo import ZoneInfo
+
+import typer
+from rich import box
+from rich.table import Table
+
+from .config import settings
+
+console = typer.get_current().console if hasattr(typer, "get_current") else None
+
+
+def normalize_hex(value: str, prefix: str = "0x") -> str:
+    """Normalize hex string to ensure it has the correct prefix.
+    
+    Handles common mistakes like "Ox" (capital O) -> "0x" (zero).
+    """
+    value = value.strip()
+    # Fix common mistake: "Ox" (capital O) -> "0x" (zero)
+    if value.startswith("Ox") or value.startswith("OX"):
+        value = "0x" + value[2:]
+    if not value.startswith(prefix):
+        value = prefix + value
+    return value
+
+
+def format_timestamp(ts: int | float | str | None) -> str:
+    """Format a timestamp showing both UTC and local time.
+
+    Args:
+        ts: Unix timestamp (seconds) as int, float, or string, or None for current time
+
+    Returns:
+        Formatted string like "2024-01-01 12:00:00 UTC (2024-01-01 07:00:00 EST)"
+    """
+    if ts is None:
+        ts = time.time()
+    elif isinstance(ts, str):
+        try:
+            ts = float(ts)
+        except ValueError:
+            return str(ts)  # Return as-is if not parseable
+
+    try:
+        ts_float = float(ts)
+        utc_dt = datetime.fromtimestamp(ts_float, tz=UTC)
+
+        # Get local timezone
+        try:
+            local_tz: ZoneInfo = ZoneInfo("local")
+        except Exception:
+            # Fallback if zoneinfo fails (shouldn't happen on Python 3.11+)
+            fallback_tz = datetime.now().astimezone().tzinfo
+            if fallback_tz is None:
+                # Ultimate fallback to UTC
+                local_tz = ZoneInfo("UTC")
+            else:
+                # Type ignore: mypy doesn't understand that ZoneInfo is compatible with tzinfo
+                local_tz = fallback_tz  # type: ignore[assignment]
+
+        local_dt = utc_dt.astimezone(local_tz)
+
+        # Format both times
+        utc_str = utc_dt.strftime("%Y-%m-%d %H:%M:%S UTC")
+        local_str = local_dt.strftime("%Y-%m-%d %H:%M:%S %Z")
+
+        return f"{utc_str} ({local_str})"
+    except (ValueError, OSError, OverflowError):
+        # Fallback to simple ISO format if anything fails
+        try:
+            return datetime.fromtimestamp(float(ts), tz=UTC).isoformat()
+        except Exception:
+            return str(ts)
+
+
+def format_timestamp_multiline(ts: int | float | str | None) -> str:
+    """Format a timestamp showing UTC and local time on separate lines.
+
+    Args:
+        ts: Unix timestamp (seconds) as int, float, or string, or None for current time
+
+    Returns:
+        Formatted string with UTC on first line, local time on second line (if different from UTC),
+        or just UTC if user is in UTC timezone.
+    """
+    if ts is None:
+        ts = time.time()
+    elif isinstance(ts, str):
+        try:
+            ts = float(ts)
+        except ValueError:
+            return str(ts)  # Return as-is if not parseable
+
+    try:
+        ts_float = float(ts)
+        utc_dt = datetime.fromtimestamp(ts_float, tz=UTC)
+
+        # Get local timezone
+        try:
+            local_tz: ZoneInfo = ZoneInfo("local")
+        except Exception:
+            fallback_tz = datetime.now().astimezone().tzinfo
+            if fallback_tz is None:
+                local_tz = ZoneInfo("UTC")
+            else:
+                local_tz = fallback_tz  # type: ignore[assignment]
+
+        local_dt = utc_dt.astimezone(local_tz)
+
+        # Format UTC time
+        utc_str = utc_dt.strftime("%Y-%m-%d %H:%M:%S UTC")
+
+        # Check if local timezone is UTC (compare timezone objects, not just hours/minutes)
+        # Also check if the offset is zero (handles cases where timezone name differs but offset is UTC)
+        is_utc_timezone = (
+            str(local_tz) == "UTC" 
+            or local_tz.utcoffset(utc_dt) == timedelta(0)
+            or (hasattr(local_tz, 'key') and local_tz.key == 'UTC')
+        )
+        
+        if is_utc_timezone:
+            # User is in UTC timezone, only show UTC
+            return utc_str
+        else:
+            # Show both UTC and local time on separate lines
+            local_str = local_dt.strftime("%Y-%m-%d %H:%M:%S %Z")
+            return f"{utc_str}\n({local_str})"
+    except (ValueError, OSError, OverflowError):
+        try:
+            return datetime.fromtimestamp(float(ts), tz=UTC).isoformat()
+        except Exception:
+            return str(ts)
+
+
+def format_evm_address(address: str) -> str:
+    """Format an EVM address in standard crypto wallet display format.
+
+    Args:
+        address: EVM address (e.g., "0x86997f52073317659B25aA622C5d93ed77444DeE")
+
+    Returns:
+        Formatted address like "0x8699...44DeE" (first 6 chars after 0x + last 4 chars)
+    """
+    if not address or len(address) < 10:
+        return address
+    
+    # Remove 0x prefix if present for processing
+    if address.startswith("0x"):
+        prefix = "0x"
+        addr_without_prefix = address[2:]
+    else:
+        prefix = ""
+        addr_without_prefix = address
+    
+    if len(addr_without_prefix) <= 10:
+        # Address is too short, return as-is
+        return address
+    
+    # Format: 0x + first 4 chars + ... + last 4 chars
+    return f"{prefix}{addr_without_prefix[:4]}...{addr_without_prefix[-4:]}"
+
+
+def usdc_to_base_units(value: str) -> int:
+    """Convert USDC amount string to base units (micro-USDC).
+
+    Args:
+        value: USDC amount as string (e.g., "250.5")
+
+    Returns:
+        Amount in base units (e.g., 250500000)
+
+    Raises:
+        typer.Exit: If value is invalid or non-positive
+    """
+    try:
+        decimal_value = Decimal(value.strip())
+    except (InvalidOperation, AttributeError) as exc:
+        raise typer.Exit(code=1) from exc
+    if decimal_value <= 0:
+        raise typer.Exit(code=1)
+    quantized = decimal_value.quantize(Decimal("0.000001"), rounding=ROUND_DOWN)
+    return int(quantized * Decimal(10**6))
+
+
+def get_current_epoch_start(reference: datetime | None = None) -> datetime:
+    """Calculate the start of the current epoch (Friday 00:00 UTC).
+
+    Args:
+        reference: Reference datetime (defaults to now in UTC)
+
+    Returns:
+        Datetime of the current epoch start (Friday 00:00 UTC)
+    """
+    reference = reference or datetime.now(tz=UTC)
+    weekday = reference.weekday()  # Monday=0, Friday=4
+    days_since_friday = (weekday - 4) % 7
+    candidate = datetime(
+        year=reference.year,
+        month=reference.month,
+        day=reference.day,
+        hour=0,
+        minute=0,
+        second=0,
+        microsecond=0,
+        tzinfo=UTC,
+    )
+    return candidate - timedelta(days=days_since_friday)
+
+
+def get_next_epoch_freeze_time(reference: datetime | None = None) -> datetime:
+    """Calculate the next epoch freeze time (next Friday 00:00 UTC).
+
+    Args:
+        reference: Reference datetime (defaults to now in UTC)
+
+    Returns:
+        Datetime of the next epoch freeze (next Friday 00:00 UTC)
+    """
+    current_start = get_current_epoch_start(reference)
+    # If we're exactly at epoch start, next is in 7 days
+    # Otherwise, next is current + 7 days
+    return current_start + timedelta(days=7)
+
+
+def format_countdown(seconds: float) -> str:
+    """Format seconds into a human-readable countdown string.
+
+    Args:
+        seconds: Number of seconds remaining
+
+    Returns:
+        Formatted string like "2d 5h 30m 15s"
+    """
+    if seconds < 0:
+        return "0s"
+
+    days = int(seconds // 86400)
+    hours = int((seconds % 86400) // 3600)
+    minutes = int((seconds % 3600) // 60)
+    secs = int(seconds % 60)
+
+    parts = []
+    if days > 0:
+        parts.append(f"{days}d")
+    if hours > 0:
+        parts.append(f"{hours}h")
+    if minutes > 0:
+        parts.append(f"{minutes}m")
+    if secs > 0 or not parts:
+        parts.append(f"{secs}s")
+
+    return " ".join(parts)
+
+
+def get_local_timezone() -> ZoneInfo:
+    """Get the local timezone, with fallbacks.
+
+    Returns:
+        ZoneInfo object for local timezone
+    """
+    try:
+        return ZoneInfo("local")
+    except Exception:
+        fallback_tz = datetime.now().astimezone().tzinfo
+        if fallback_tz is None:
+            return ZoneInfo("UTC")
+        return fallback_tz  # type: ignore[return-value]
+