cartha-cli 1.0.0__py3-none-any.whl

cartha_cli/verifier.py

@@ -0,0 +1,342 @@
+"""HTTP helpers for interacting with the Cartha verifier service."""
+
+from __future__ import annotations
+
+import time
+from typing import Any
+
+import requests  # type: ignore[import-untyped]
+
+from .config import settings
+
+
+class VerifierError(RuntimeError):
+    """Raised when the verifier cannot be reached or returns an error."""
+
+    def __init__(self, message: str, status_code: int | None = None) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+
+
+def _build_url(path: str) -> str:
+    base = settings.verifier_url.rstrip("/")
+    return f"{base}{path}"
+
+
+def _request(
+    method: str,
+    path: str,
+    *,
+    params: dict[str, Any] | None = None,
+    json_data: dict[str, Any] | None = None,
+    headers: dict[str, str] | None = None,
+    retry: bool = True,
+) -> dict[str, Any]:
+    """Make HTTP request with automatic retry logic.
+    
+    Args:
+        method: HTTP method (GET, POST, etc.)
+        path: API path
+        params: Query parameters
+        json_data: JSON body for POST requests
+        headers: Additional headers
+        retry: Whether to retry on transient failures (default: True)
+        
+    Returns:
+        Response JSON data as dict
+        
+    Raises:
+        VerifierError: If request fails after retries
+    """
+    request_headers: dict[str, str] = {"Accept": "application/json"}
+    if headers:
+        request_headers.update(headers)
+    url = _build_url(path)
+
+    max_attempts = settings.retry_max_attempts if retry else 1
+    backoff_factor = settings.retry_backoff_factor
+    retry_statuses = settings.retry_on_status
+
+    last_exception: Exception | None = None
+    response: requests.Response | None = None
+    
+    for attempt in range(max_attempts):
+        try:
+            # Use separate connection and read timeouts
+            # Connection timeout: 5s (fast fail if can't connect)
+            # Read timeout: 60s (allow time for response to arrive after connection established)
+            # This helps when verifier processes quickly but response transmission is slow
+            response = requests.request(
+                method,
+                url,
+                params=params,
+                json=json_data,
+                headers=request_headers,
+                timeout=(5, 60),  # (connect_timeout, read_timeout) in seconds
+            )
+            
+            # Check if we should retry based on status code
+            if retry and attempt < max_attempts - 1 and response.status_code in retry_statuses:
+                wait_time = backoff_factor ** attempt
+                time.sleep(wait_time)
+                continue  # Retry the request
+            
+            # If we get here, either success or non-retryable error - break and process
+            break
+            
+        except requests.Timeout as exc:
+            last_exception = exc
+            # Retry timeouts if we have attempts left
+            if retry and attempt < max_attempts - 1:
+                wait_time = backoff_factor ** attempt
+                time.sleep(wait_time)
+                continue
+            
+            # Explicitly handle timeout - request took longer than allowed
+            # This could be connection timeout (5s) or read timeout (60s)
+            error_msg = (
+                f"Request to verifier timed out after {max_attempts} attempt(s): {url}\n"
+                "This is a CLI-side timeout.\n"
+                "If verifier logs show request completed, this is likely slow network response transmission.\n"
+                "Possible causes: network latency, large response size, or slow connection.\n"
+                "Tip: Try again in a moment or check verifier logs to confirm request was processed."
+            )
+            raise VerifierError(error_msg) from exc
+        except requests.RequestException as exc:  # pragma: no cover - network failure
+            last_exception = exc
+            # Retry network errors if we have attempts left
+            if retry and attempt < max_attempts - 1:
+                wait_time = backoff_factor ** attempt
+                time.sleep(wait_time)
+                continue
+            
+            # Provide more context about the failed URL
+            error_msg = f"Failed to reach verifier at {url} after {max_attempts} attempt(s): {exc}"
+            raise VerifierError(error_msg) from exc
+    
+    # If we exhausted retries without getting a response, raise the last exception
+    if response is None and last_exception:
+        raise VerifierError(f"Request failed after {max_attempts} attempts: {last_exception}") from last_exception
+    
+    # Process the response (response should be set at this point)
+    assert response is not None  # nosec - response should be set if we got here
+
+    try:
+        data = response.json()
+    except ValueError:
+        data = None
+
+    if response.status_code >= 400:
+        if isinstance(data, dict):
+            detail = data.get("detail") or data.get("error") or response.text
+        else:
+            detail = response.text or "Unknown verifier error"
+
+        # Handle FastAPI validation errors which return detail as a list
+        if isinstance(detail, list):
+            # Format list of validation errors into a readable string
+            formatted_errors = []
+            for item in detail:
+                if isinstance(item, dict):
+                    # Extract field location and message
+                    loc = item.get("loc", [])
+                    msg = item.get("msg", "Validation error")
+                    field = " -> ".join(str(x) for x in loc) if loc else "unknown"
+                    formatted_errors.append(f"{field}: {msg}")
+                else:
+                    formatted_errors.append(str(item))
+            detail = "; ".join(formatted_errors)
+        elif isinstance(detail, str):
+            detail = detail.strip()
+        else:
+            detail = str(detail)
+
+        # Log error details for debugging (only in debug mode or for 500 errors)
+        if response.status_code >= 500:
+            import logging
+
+            logger = logging.getLogger(__name__)
+            logger.debug(f"Verifier error - URL: {url}")
+            logger.debug(f"Verifier error - Status: {response.status_code}")
+            logger.debug(f"Verifier error - Response: {response.text[:500]}")
+
+        raise VerifierError(detail, status_code=response.status_code)
+
+    if not isinstance(data, dict):
+        raise VerifierError("Unexpected verifier response payload.")
+    return data
+
+
+def fetch_miner_status(
+    *,
+    hotkey: str,
+    slot: str,
+) -> dict[str, Any]:
+    """Return miner status without authentication (public endpoint)."""
+    return _request(
+        "GET",
+        "/v1/miner/status",
+        params={"hotkey": hotkey, "slot": slot},
+    )
+
+
+def fetch_pair_status(
+    *,
+    hotkey: str,
+    slot: str,
+    network: str,
+    netuid: int,
+    message: str,
+    signature: str,
+) -> dict[str, Any]:
+    """Return the status for a (hotkey, slotUID) pair after verifying ownership."""
+    payload = {
+        "hotkey": hotkey,
+        "slot": slot,
+        "network": network,
+        "netuid": netuid,
+        "message": message,
+        "signature": signature,
+    }
+    return _request(
+        "POST",
+        "/v1/pair/status",
+        json_data=payload,
+    )
+
+
+# REMOVED: fetch_pair_password and register_pair_password
+# These functions are no longer needed - the new lock flow uses session tokens instead of passwords.
+# The verifier endpoints /v1/pair/password/* have been removed.
+
+
+def check_registration(
+    *,
+    hotkey: str,
+    miner_slot: str | None = None,
+    uid: str | None = None,
+) -> dict[str, Any]:
+    """Check if a hotkey is registered on subnet 35.
+    
+    Returns: {registered: bool, uid: int | None}
+    """
+    params: dict[str, Any] = {"hotkey": hotkey}
+    if miner_slot is not None:
+        params["minerSlot"] = miner_slot
+    if uid is not None:
+        params["uid"] = uid
+    return _request(
+        "GET",
+        "/subnet/check-registration",
+        params=params,
+    )
+
+
+def verify_hotkey(
+    *,
+    hotkey: str,
+    signature: str,
+    message: str,
+) -> dict[str, Any]:
+    """Verify Bittensor hotkey signature and get session token.
+    
+    Returns: {verified: bool, session_token: str, expires_at: int}
+    """
+    payload = {
+        "hotkey": hotkey,
+        "signature": signature,
+        "message": message,
+    }
+    return _request(
+        "POST",
+        "/auth/verify-hotkey",
+        json_data=payload,
+    )
+
+
+def request_lock_signature(
+    *,
+    session_token: str,
+    pool_id: str,
+    amount: int,
+    lock_days: int,
+    hotkey: str,
+    miner_slot: str | None,
+    uid: str | None,
+    owner: str,
+    chain_id: int,
+    vault_address: str,
+) -> dict[str, Any]:
+    """Request EIP-712 LockRequest signature from verifier.
+    
+    Returns: {signature, timestamp, nonce, expiresAt, approveTx, lockTx}
+    """
+    payload = {
+        "poolId": pool_id,
+        "amount": amount,
+        "lockDays": lock_days,
+        "hotkey": hotkey,
+        "owner": owner,
+        "chainId": chain_id,
+        "vaultAddress": vault_address,
+    }
+    if miner_slot is not None:
+        payload["minerSlot"] = miner_slot
+    if uid is not None:
+        payload["uid"] = uid
+    
+    headers = {"Authorization": f"Bearer {session_token}"}
+    return _request(
+        "POST",
+        "/lock/request-signature",
+        json_data=payload,
+        headers=headers,
+    )
+
+
+def get_lock_status(
+    *,
+    tx_hash: str,
+) -> dict[str, Any]:
+    """Check status of a lock transaction.
+    
+    Returns: {verified: bool, lockId: str | None, addedToEpoch: str | None, message: str | None}
+    """
+    return _request(
+        "GET",
+        "/lock/status",
+        params={"tx_hash": tx_hash},  # Match endpoint parameter name (snake_case)
+    )
+
+
+def process_lock_transaction(
+    *,
+    tx_hash: str,
+) -> dict[str, Any]:
+    """Trigger immediate processing of a lock transaction.
+    
+    Returns: {success: bool, action: str, hotkey: str, slot: str, ...}
+    """
+    return _request(
+        "POST",
+        "/lock/process",
+        json_data={"tx_hash": tx_hash},
+    )
+
+
+# REMOVED: Old endpoints - replaced by new lock flow
+# fetch_pair_password, register_pair_password, submit_lock_proof removed
+
+
+__all__ = [
+    "VerifierError",
+    "_build_url",
+    "_request",
+    "fetch_pair_status",
+    "fetch_miner_status",
+    "check_registration",
+    "verify_hotkey",
+    "request_lock_signature",
+    "get_lock_status",
+    "process_lock_transaction",
+]

cartha_cli/wallet.py

@@ -0,0 +1,59 @@
+"""Wallet handling utilities for the Cartha CLI."""
+
+from __future__ import annotations
+
+import bittensor as bt
+import typer
+from rich.console import Console
+
+from .bt import get_wallet
+from .utils import format_timestamp
+
+console = Console()
+
+CHALLENGE_PREFIX = "cartha-pair-auth"
+CHALLENGE_TTL_SECONDS = 120
+
+
+def load_wallet(
+    wallet_name: str, wallet_hotkey: str, expected_hotkey: str | None = None
+) -> bt.wallet:
+    """Load a Bittensor wallet.
+
+    Args:
+        wallet_name: Coldkey wallet name
+        wallet_hotkey: Hotkey name
+        expected_hotkey: Optional expected hotkey SS58 address to validate
+
+    Returns:
+        Loaded wallet object
+
+    Raises:
+        typer.Exit: If wallet cannot be loaded or hotkey mismatch
+    """
+    try:
+        wallet = get_wallet(wallet_name, wallet_hotkey)
+    except bt.KeyFileError as exc:
+        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})"
+        console.print(f"[bold red]{message}[/]")
+        raise typer.Exit(code=1) from exc
+    except Exception as exc:  # pragma: no cover - defensive
+        console.print(f"[bold red]Failed to load wallet '{wallet_name}/{wallet_hotkey}': {exc}[/]")
+        raise typer.Exit(code=1) from exc
+
+    if expected_hotkey and wallet.hotkey.ss58_address != expected_hotkey:
+        console.print(
+            "[bold red]Hotkey mismatch: loaded wallet hotkey does not match the supplied address.[/]"
+        )
+        raise typer.Exit(code=1)
+
+    return wallet
+

cartha_cli-1.0.0.dist-info/METADATA

@@ -0,0 +1,180 @@
+Metadata-Version: 2.4
+Name: cartha-cli
+Version: 1.0.0
+Summary: CLI utilities for Cartha subnet miners.
+Project-URL: Homepage, https://cartha.finance
+Project-URL: Repository, https://github.com/General-Tao-Ventures/cartha-cli
+Project-URL: Documentation, https://github.com/General-Tao-Ventures/cartha-cli#readme
+Author: Cartha Contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: 0xmarkets,bittensor,cartha,cli,mining,subnet
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: <3.12,>=3.11
+Requires-Dist: bittensor<10,>=9.12.2
+Requires-Dist: eth-account<0.11,>=0.10
+Requires-Dist: pydantic-settings<3,>=2.6
+Requires-Dist: pydantic<3,>=2.6
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: requests>=2.32
+Requires-Dist: torch<3,>=2.2
+Requires-Dist: typer[all]>=0.12
+Requires-Dist: web3<7,>=6.11
+Provides-Extra: dev
+Requires-Dist: pytest>=8.2; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Cartha CLI
+
+**The official command-line tool for Cartha subnet miners.** Cartha is the Liquidity Provider for 0xMarkets DEX. A simple, powerful way to manage your mining operations—from registration to tracking your locked funds.
+
+## Why Cartha CLI?
+
+Cartha CLI makes mining on the Cartha subnet effortless. As the Liquidity Provider for 0xMarkets DEX, Cartha enables miners to provide liquidity and earn rewards:
+
+- **🔐 One-Click Registration** - Get started mining in minutes
+- **📊 Instant Status Updates** - See all your pools, balances, and expiration dates at a glance
+- **⏰ Smart Expiration Warnings** - Never miss a renewal with color-coded countdowns
+- **💼 Multi-Pool Management** - Track multiple trading pairs in one place
+- **🔑 Secure by Default** - Your password stays hidden until you actually need it
+
+## Quick Start
+
+```bash
+# Install dependencies
+uv sync
+
+# Show available commands
+uv run cartha
+
+# Get started with registration
+uv run cartha miner register --help
+
+# Check your miner status (no authentication needed)
+uv run cartha miner status --help
+
+# Check CLI health and connectivity
+uv run cartha health
+
+# Or use short aliases
+uv run cartha m status
+uv run cartha v lock
+```
+
+## Requirements
+
+- Python 3.11
+- Bittensor wallet
+- [`uv`](https://github.com/astral-sh/uv) package manager (or pip)
+
+## What You Can Do
+
+### Get Started
+
+**Register your miner:**
+```bash
+cartha miner register --wallet-name your-wallet --wallet-hotkey your-hotkey
+```
+
+**Check your status anytime:**
+```bash
+cartha miner status --wallet-name your-wallet --wallet-hotkey your-hotkey
+# Or use the short alias: cartha m status
+```
+
+### Track Your Pools
+
+See all your active trading pairs, balances, and when they expire—all in one command. The CLI shows you:
+- Which pools are active and earning rewards
+- How much you have locked in each pool
+- Days remaining before expiration (with helpful warnings)
+- Which pools are included in the next reward epoch
+
+### View Available Pools
+
+See all available pools with their pool IDs and vault addresses:
+
+```bash
+cartha vault pools
+# Or use: cartha v pools
+```
+
+This shows you which pools are available, their full pool IDs, vault contract addresses, and chain IDs.
+
+### Lock Your Funds
+
+Create a new lock position with the streamlined lock flow:
+```bash
+cartha vault lock \
+  --coldkey your-wallet \
+  --hotkey your-hotkey \
+  --pool-id "BTCUSD" \
+  --amount 1000.0 \
+  --lock-days 30 \
+  --owner-evm 0xYourEVMAddress \
+  --chain 8453 \
+  --vault-address 0xVaultAddress
+# Or use: cartha v lock
+```
+
+**Parameter Notes:**
+- `--owner` and `--owner-evm` are interchangeable (EVM address that will own the lock)
+- `--vault` and `--vault-address` are interchangeable (vault contract address)
+- `--network` accepts `test` (netuid 78) or `finney` (netuid 35, default)
+- `--chain` or `--chain-id` are interchangeable (EVM chain ID: 84532 for Base Sepolia testnet)
+
+The CLI will:
+1. Check your registration on the specified network (subnet 35 for finney, subnet 78 for test)
+2. Authenticate with your Bittensor hotkey
+3. Request a signed LockRequest from the verifier
+4. Automatically open the Cartha Lock UI in your browser with all parameters pre-filled
+5. Guide you through Phase 1 (Approve USDC) and Phase 2 (Lock Position) via the web interface
+6. Automatically detect when approval completes and proceed to Phase 2
+7. The verifier automatically detects your lock and adds you to the upcoming epoch
+
+**Managing Positions**: Visit https://cartha.finance/manage to view all your positions, extend locks, or top up existing positions.
+
+### View Your Password
+
+When you need your password (like for signing transactions):
+```bash
+cartha miner password --wallet-name your-wallet --wallet-hotkey your-hotkey
+```
+
+**Tip:** Use `miner status` for daily checks—it's faster and doesn't require signing. Only use `miner password` when you actually need it.
+
+### Check Your Setup
+
+Verify your CLI is configured correctly and can reach all services:
+
+```bash
+cartha health
+```
+
+This checks:
+- Verifier connectivity and latency
+- Bittensor network connectivity
+- Configuration validation
+
+Use `cartha health --verbose` for detailed troubleshooting information.
+
+## Need Help?
+
+- **[Full Command Reference](docs/COMMANDS.md)** - Complete guide to all commands
+- **[Testnet Guide](testnet/README.md)** - Getting started on testnet
+- **[Feedback & Support](docs/FEEDBACK.md)** - Questions or suggestions?
+
+## Contributing
+
+We welcome contributions! Please see our [Feedback & Support](docs/FEEDBACK.md) page for ways to get involved.
+
+---
+
+**Made with ❤ by GTV**

cartha_cli-1.0.0.dist-info/RECORD

@@ -0,0 +1,28 @@
+cartha_cli/__init__.py,sha256=cSKsPAfHW8_hqJkGMXUh4mFNz9HXsq-UcgRl8G_2KhM,720
+cartha_cli/bt.py,sha256=GGW8QvOgFPFNrIghu7JNygRmTgBeMt2vhEh26ZiPe4Q,6933
+cartha_cli/config.py,sha256=MSHNiRow1tzHUJeMOvQRQsTslntV6DecLTQ-Y_CmB4A,2294
+cartha_cli/display.py,sha256=Krim69DLgiCHSYDuWNjnOep25IAHUebRAceePHfsiRA,2040
+cartha_cli/eth712.py,sha256=5NU0MnvOk89mxWnkDHzoOaSHN8TJGRAHVLGXmCq8jhM,241
+cartha_cli/main.py,sha256=0-G2syhsj2okLblX5WYb5NGqWjOwF5eW2tDn9AF5vaw,6756
+cartha_cli/pair.py,sha256=Y-TAjAK5FeWqKlUK52dHZLdBhDxx1CJbea8mlsQXkqc,6245
+cartha_cli/utils.py,sha256=LWlJXzWNkIpInWclCJ2PObkG--JEN1mIcvVXsHmFllE,8429
+cartha_cli/verifier.py,sha256=JFtDA9bhecsAUCQEp0SBrZ1Z-48EkDT1Q6y7X4eTK60,10548
+cartha_cli/wallet.py,sha256=Jha1pONa4Hy2XsHMTrk60eBqdkwJyzsQYgPuI-cxxFo,1770
+cartha_cli/commands/__init__.py,sha256=8CYMVEWJmg2qjLyE3ZeheQtS-E9doltDSfyyumOsET4,345
+cartha_cli/commands/common.py,sha256=tpxKsdzjFtcb0ae7J-J-zxnh32qVXZd8jwjP-frFoio,2099
+cartha_cli/commands/config.py,sha256=XT1LQo7b9vVm_mgwUTJRLCBCHJhtGclBzh_CTBAd280,10539
+cartha_cli/commands/health.py,sha256=NRwmIultxUzAe7udOOBIdkcdGG5KsE_kuCs43LZObGk,20717
+cartha_cli/commands/help.py,sha256=6ubfWtmjXfCtp6L_PYvn7rR7m5C_pp-iEjtRc6BS0GA,1721
+cartha_cli/commands/miner_password.py,sha256=7cbcyrJ9KzCyJ68_174U_CXjBUt9BaYhgKAycRpv7AE,11078
+cartha_cli/commands/miner_status.py,sha256=tWlCWcuwm9NEd4USuCLp_6qObikX2odc2e7m6Y_vNrU,21873
+cartha_cli/commands/pair_status.py,sha256=Sk6-bIAcgAH3KxGg0Hw3PofLW_4eyonLUmJOkJ8gem0,19821
+cartha_cli/commands/pools.py,sha256=LkFJlur1T5lxV2qz7DeYYj9GbyRiy0wjb1mUNsV1zQg,4104
+cartha_cli/commands/prove_lock.py,sha256=rNxuKupTGyJ-SzKA5Yil6t6fPmLuzbX4jG4D4ZzVo4c,60562
+cartha_cli/commands/register.py,sha256=m7BLTTmiEbeXRrStUSNQbwI79IN4KOBEjU-nN6cSU4k,10109
+cartha_cli/commands/shared_options.py,sha256=itHzJSgxuKQxUVOh1_jVTcMQXjI3PPzexQyhqIbabxc,5874
+cartha_cli/commands/version.py,sha256=u5oeccQzK0LLcCbgZm0U8-Vslk5vB_lVvW3xT5HPeTg,456
+cartha_cli-1.0.0.dist-info/METADATA,sha256=W_n3aBURJG5xcgP-r9HF9grG5stONJLHYRsrUgaOZcg,5875
+cartha_cli-1.0.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+cartha_cli-1.0.0.dist-info/entry_points.txt,sha256=sTYVMgb9l0fuJibUtWpGnIoDmgHinne97G4Y_cCwC-U,43
+cartha_cli-1.0.0.dist-info/licenses/LICENSE,sha256=B4UCiDn13m4xYwIl4TMKfbuKw7kh9pg4c81rJecxHSo,1076
+cartha_cli-1.0.0.dist-info/RECORD,,

cartha_cli-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

cartha_cli-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+cartha = cartha_cli:main

cartha_cli-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Cartha Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.