cartha-cli 1.0.2__py3-none-any.whl → 1.0.3__py3-none-any.whl

cartha_cli/commands/pair_status.py

@@ -50,7 +50,7 @@ def _fallback_pool_id_to_name(pool_id: str) -> str | None:
 
 # Try to import from testnet module, fallback to default if not available
 try:
-    from ...testnet.pool_ids import pool_id_to_name
+    from ..testnet.pool_ids import pool_id_to_name
 except (ImportError, ModuleNotFoundError):
     # Use fallback function
     pool_id_to_name = _fallback_pool_id_to_name

cartha_cli/commands/pools.py

@@ -22,36 +22,16 @@ def _fallback_pool_id_to_chain_id(pool_id: str) -> int | None:
 
 # Try to import from testnet module, fallback to defaults if not available
 try:
-    from ...testnet.pool_ids import (
+    from ..testnet.pool_ids import (
         list_pools,
         pool_id_to_chain_id,
         pool_id_to_vault_address,
     )
 except (ImportError, ModuleNotFoundError):
-    # Fallback if running from different context
-    import sys
-    from pathlib import Path
-
-    # Try adding parent directory to path
-    testnet_dir = Path(__file__).parent.parent.parent / "testnet"
-    if testnet_dir.exists():
-        sys.path.insert(0, str(testnet_dir.parent))
-        try:
-            from testnet.pool_ids import (
-                list_pools,
-                pool_id_to_chain_id,
-                pool_id_to_vault_address,
-            )
-        except (ImportError, ModuleNotFoundError):
-            # Use fallback functions
-            list_pools = _fallback_list_pools
-            pool_id_to_vault_address = _fallback_pool_id_to_vault_address
-            pool_id_to_chain_id = _fallback_pool_id_to_chain_id
-    else:
-        # Use fallback functions if testnet directory doesn't exist
-        list_pools = _fallback_list_pools
-        pool_id_to_vault_address = _fallback_pool_id_to_vault_address
-        pool_id_to_chain_id = _fallback_pool_id_to_chain_id
+    # Use fallback functions if import failed
+    list_pools = _fallback_list_pools
+    pool_id_to_vault_address = _fallback_pool_id_to_vault_address
+    pool_id_to_chain_id = _fallback_pool_id_to_chain_id
 
 
 def pools(

cartha_cli/commands/prove_lock.py

@@ -86,7 +86,8 @@ def _fallback_vault_address_to_chain_id(vault_address: str) -> int | None:
 
 # Try to import from testnet module, fallback to defaults if not available
 try:
-    from ...testnet.pool_ids import (
+    # Import from cartha_cli.testnet (works both in development and when installed)
+    from ..testnet.pool_ids import (
         format_pool_id,
         list_pools,
         pool_id_to_chain_id,
@@ -97,45 +98,15 @@ try:
         vault_address_to_pool_id,
     )
 except (ImportError, ModuleNotFoundError):
-    # Fallback if running from different context
-    import sys
-    from pathlib import Path
-
-    # Try adding parent directory to path
-    testnet_dir = Path(__file__).parent.parent.parent / "testnet"
-    if testnet_dir.exists():
-        sys.path.insert(0, str(testnet_dir.parent))
-        try:
-            from testnet.pool_ids import (
-                format_pool_id,
-                list_pools,
-                pool_id_to_chain_id,
-                pool_id_to_name,
-                pool_id_to_vault_address,
-                pool_name_to_id,
-                vault_address_to_chain_id,
-                vault_address_to_pool_id,
-            )
-        except (ImportError, ModuleNotFoundError):
-            # Use fallback functions
-            pool_name_to_id = _fallback_pool_name_to_id
-            pool_id_to_name = _fallback_pool_id_to_name
-            format_pool_id = _fallback_format_pool_id
-            list_pools = _fallback_list_pools
-            pool_id_to_vault_address = _fallback_pool_id_to_vault_address
-            vault_address_to_pool_id = _fallback_vault_address_to_pool_id
-            pool_id_to_chain_id = _fallback_pool_id_to_chain_id
-            vault_address_to_chain_id = _fallback_vault_address_to_chain_id
-    else:
-        # Use fallback functions if testnet directory doesn't exist
-        pool_name_to_id = _fallback_pool_name_to_id
-        pool_id_to_name = _fallback_pool_id_to_name
-        format_pool_id = _fallback_format_pool_id
-        list_pools = _fallback_list_pools
-        pool_id_to_vault_address = _fallback_pool_id_to_vault_address
-        vault_address_to_pool_id = _fallback_vault_address_to_pool_id
-        pool_id_to_chain_id = _fallback_pool_id_to_chain_id
-        vault_address_to_chain_id = _fallback_vault_address_to_chain_id
+    # Use fallback functions if import failed
+    pool_name_to_id = _fallback_pool_name_to_id
+    pool_id_to_name = _fallback_pool_id_to_name
+    format_pool_id = _fallback_format_pool_id
+    list_pools = _fallback_list_pools
+    pool_id_to_vault_address = _fallback_pool_id_to_vault_address
+    vault_address_to_pool_id = _fallback_vault_address_to_pool_id
+    pool_id_to_chain_id = _fallback_pool_id_to_chain_id
+    vault_address_to_chain_id = _fallback_vault_address_to_chain_id
 
 
 def prove_lock(

cartha_cli/testnet/README.md

@@ -0,0 +1,446 @@
+# Cartha CLI - Testnet Setup Guide
+
+This guide will help you set up and use the Cartha CLI on the public testnet with real vault contracts.
+
+## Prerequisites
+
+- Python 3.11
+- Bittensor wallet (for subnet registration)
+- Access to the testnet verifier URL
+- Testnet TAO (required for subnet registration)
+- EVM wallet (MetaMask or similar) with testnet USDC for locking
+
+## Step 0: Set Up Your EVM Wallet for Base Sepolia Testnet
+
+Before you can lock funds, you need to configure your EVM wallet (MetaMask, Coinbase Wallet, etc.) to connect to Base Sepolia Testnet and get testnet tokens.
+
+### 0.1: Add Base Sepolia Testnet to Your Wallet
+
+**For MetaMask:**
+
+1. Open MetaMask and click the network dropdown (usually shows "Ethereum Mainnet")
+2. Click "Add Network" or "Add a network manually"
+3. Enter the following network details:
+
+   ```
+   Network Name: Base Sepolia
+   RPC URL: https://sepolia.base.org
+   Chain ID: 84532
+   Currency Symbol: ETH
+   Block Explorer URL: https://sepolia.basescan.org
+   ```
+
+4. Click "Save" to add the network
+5. Switch to the "Base Sepolia" network
+
+**For Other Wallets:**
+
+- **Coinbase Wallet**: Go to Settings → Networks → Add Network, then enter the details above
+- **WalletConnect-compatible wallets**: Use the same network details when connecting
+
+**Quick Add (MetaMask):**
+
+You can also use the [Chainlist](https://chainlist.org/) website:
+1. Visit https://chainlist.org/
+2. Search for "Base Sepolia"
+3. Click "Connect Wallet" and approve the connection
+4. Click "Add to MetaMask" and confirm
+
+### 0.2: Get Testnet ETH for Gas Fees
+
+You'll need testnet ETH on Base Sepolia to pay for transaction gas fees. Get it from the official Optimism Superchain faucet:
+
+1. **Visit the Optimism Superchain Faucet**: https://console.optimism.io/faucet
+2. **Connect your wallet** (MetaMask or WalletConnect)
+3. **Select "Base Sepolia"** from the network dropdown
+4. **Enter your wallet address** (or it will auto-detect from your connected wallet)
+5. **Click "Request Tokens"** or similar button
+6. **Wait for confirmation** - You should receive testnet ETH within a few minutes
+
+**Note**: The faucet may have rate limits (e.g., once per 24 hours per address). If you need more testnet ETH, you may need to wait or use a different address.
+
+**Alternative Faucets** (if the main faucet is unavailable):
+- Check Base Sepolia documentation for additional faucet options
+- Join the Cartha Discord/Telegram for community faucet links
+
+### 0.3: Get Testnet USDC Tokens
+
+Testnet USDC is required to lock funds in the Cartha vaults. You can claim testnet USDC from the Cartha faucet.
+
+**To Get Testnet USDC:**
+
+1. **Visit the Cartha Faucet**: https://cartha.finance/faucet
+2. **Connect your wallet** (MetaMask, Coinbase Wallet, Talisman, or WalletConnect)
+3. **Make sure you're on Base Sepolia network** (Chain ID: 84532)
+4. **Click "Claim USDC"** button
+5. **Approve the transaction** in your wallet
+6. **Wait for confirmation** - You should receive 1,000,000 testnet USDC within a few minutes
+
+**Faucet Details**:
+- **Claim Amount**: 1,000,000 USDC per claim
+- **Cooldown**: 24 hours between claims (per wallet address)
+- **Network**: Base Sepolia (Chain ID: 84532)
+
+**Note**: The faucet has a 24-hour cooldown period. After claiming, you'll need to wait 24 hours before you can claim again from the same wallet address.
+
+**Testnet USDC Contract Address** (for reference):
+- Base Sepolia: `0x2340D09c348930A76c8c2783EDa8610F699A51A8`
+
+You can verify you received USDC by:
+- Checking your wallet balance (should show USDC)
+- Viewing your address on [BaseScan Sepolia](https://sepolia.basescan.org/)
+
+### Getting Testnet TAO
+
+You'll need testnet TAO to register your hotkey to the subnet. Get testnet TAO from the faucet:
+
+🔗 **Testnet TAO Faucet**: <https://app.minersunion.ai/testnet-faucet>
+
+Simply visit the faucet and request testnet TAO to your wallet address. You'll need TAO in your wallet to pay for subnet registration.
+
+## Installation
+
+Install the Cartha CLI from PyPI:
+
+```bash
+pip install cartha-cli
+```
+
+Verify the installation:
+
+```bash
+cartha --help
+```
+
+## Testnet Configuration
+
+### Environment Variables
+
+Set the following environment variables:
+
+```bash
+# Required: Testnet verifier URL
+export CARTHA_VERIFIER_URL="https://cartha-verifier-826542474079.us-central1.run.app"
+
+# Required: Bittensor network configuration
+export CARTHA_NETWORK="test"  # Use "test" for testnet
+export CARTHA_NETUID=78       # Testnet subnet UID
+
+# Optional: Custom wallet path
+export BITTENSOR_WALLET_PATH="/path/to/wallet"
+```
+
+### Verify Configuration
+
+```bash
+# Check CLI can access verifier
+cartha --help
+
+# Test verifier connectivity
+curl "${CARTHA_VERIFIER_URL}/health"
+```
+
+## Testnet Workflow
+
+### Step 1: Verify Your EVM Wallet Setup
+
+Before proceeding, make sure you have:
+
+- ✅ Base Sepolia network added to your wallet
+- ✅ Testnet ETH in your wallet (for gas fees)
+- ✅ Testnet USDC in your wallet (contact team if needed)
+
+You can verify your balances:
+- Check ETH balance in your wallet
+- Check USDC balance (should show as a token in your wallet)
+- View on [BaseScan Sepolia](https://sepolia.basescan.org/address/YOUR_ADDRESS) to see all tokens
+
+### Step 2: Register Your Hotkey
+
+Register your hotkey to the testnet subnet:
+
+```bash
+cartha miner register \
+  --wallet-name <your-wallet-name> \
+  --wallet-hotkey <your-hotkey-name> \
+  --network test \
+  --netuid 78
+```
+
+This will:
+
+- Register your hotkey to subnet 78 (testnet)
+- Fetch your slot UID
+- Display your registration details
+
+**Save the output** - you'll need your slot UID.
+
+### Step 3: Lock Funds Using Cartha Lock UI
+
+Use the streamlined lock flow with the Cartha Lock UI:
+
+```bash
+cartha vault lock \
+  --coldkey <your-coldkey-name> \
+  --hotkey <your-hotkey-name> \
+  --pool-id BTCUSD \
+  --amount 100.0 \
+  --lock-days 30 \
+  --owner-evm 0xYourEVMAddress
+
+# Note: --chain-id and --vault-address are optional - CLI auto-matches them from pool-id!
+```
+
+This command will:
+
+1. **Check Registration**: Verify your hotkey is registered on the subnet
+2. **Authenticate**: Sign a challenge message with your Bittensor hotkey to get a session token
+3. **Request Signature**: Get an EIP-712 LockRequest signature from the verifier
+4. **Open Cartha Lock UI**: Automatically opens the web interface in your browser with all parameters pre-filled
+5. **Phase 1 - Approve USDC**: Connect your wallet and approve USDC spending through the frontend. The CLI automatically detects when approval completes
+6. **Phase 2 - Lock Position**: Lock your USDC in the vault contract through the frontend
+7. **Auto-Detection**: The verifier automatically detects your `LockCreated` event and adds you to the upcoming epoch
+
+**Important Notes**:
+- Make sure you're connected to **Base Sepolia** network in your wallet (not Mainnet!)
+- You'll need testnet USDC in your EVM wallet (contact team if you don't have any)
+- The frontend supports MetaMask, Coinbase Wallet, Talisman, and WalletConnect
+- Make sure the wallet you connect matches the `--owner-evm` address specified in the CLI
+- The frontend includes wallet validation to prevent using the wrong address
+
+**Transaction Flow**:
+1. **Approve USDC**: First transaction approves the vault to spend your USDC (handled in frontend)
+2. **Lock Position**: Second transaction locks your USDC in the vault (handled in frontend)
+3. Both transactions require gas fees (paid in testnet ETH)
+
+**Managing Existing Positions**:
+- Visit https://cartha.finance/manage to view all your locks
+- Use "Extend" or "Top Up" buttons to modify existing positions
+
+### Step 4: Check Miner Status
+
+Verify your miner status (no authentication required):
+
+```bash
+cartha miner status \
+  --wallet-name <your-wallet-name> \
+  --wallet-hotkey <your-hotkey-name>
+
+# Or with explicit slot UID
+cartha miner status \
+  --wallet-name <your-wallet-name> \
+  --wallet-hotkey <your-hotkey-name> \
+  --slot <your-slot-uid>
+```
+
+This will show:
+
+- Miner state and pool information
+- All active pools with amounts and expiration dates
+- Days remaining countdown (with warnings for expiring pools)
+
+## Pool IDs and Vault Addresses
+
+Pool IDs can be specified as either:
+- **Human-readable names**: `BTCUSD`, `EUR/USD`, `ETH/USD`, etc.
+- **Hex strings**: `0x...` (32 bytes)
+
+The CLI automatically converts readable names to hex format and matches them to the correct vault address.
+
+### Available Testnet Pools (Base Sepolia)
+
+| Pool Name | Pool ID (hex) | Vault Address |
+|-----------|---------------|---------------|
+| BTCUSD | `0xee62665949c883f9e0f6f002eac32e00bd59dfe6c34e92a91c37d6a8322d6489` | `0x471D86764B7F99b894ee38FcD3cEFF6EAB321b69` |
+| ETH/USD | `0x0b43555ace6b39aae1b894097d0a9fc17f504c62fea598fa206cc6f5088e6e45` | `0xdB74B44957A71c95406C316f8d3c5571FA588248` |
+| EUR/USD | `0xa9226449042e36bf6865099eec57482aa55e3ad026c315a0e4a692b776c318ca` | `0x3C4dAfAC827140B8a031d994b7e06A25B9f27BAD` |
+
+**Note**: When using `cartha vault lock`, you can simply specify `--pool-id BTCUSD` and the CLI will automatically:
+- Match the correct vault address for that pool
+- Match the correct chain ID (Base Sepolia: 84532)
+
+You don't need to manually specify `--vault-address` or `--chain-id` unless you want to override them.
+
+See `testnet/pool_ids.py` for the complete pool mappings and helper functions.
+
+## Common Commands
+
+### Check CLI Version
+
+```bash
+cartha version
+```
+
+### View Help
+
+```bash
+cartha --help
+cartha miner register --help
+cartha vault lock --help
+cartha miner status --help
+```
+
+### Register (Burned Registration)
+
+```bash
+cartha miner register \
+  --wallet-name <name> \
+  --wallet-hotkey <hotkey> \
+  --network test \
+  --netuid 78 \
+  --burned
+```
+
+## Troubleshooting
+
+### "Verifier URL not found"
+
+**Problem**: CLI can't connect to verifier
+
+**Solution**:
+
+```bash
+# Verify environment variable is set
+echo $CARTHA_VERIFIER_URL
+
+# Test verifier connectivity
+curl "${CARTHA_VERIFIER_URL}/health"
+
+# If using a different URL, update it
+export CARTHA_VERIFIER_URL="https://cartha-verifier-826542474079.us-central1.run.app"
+```
+
+### "Hotkey not registered"
+
+**Problem**: Hotkey is not registered on the subnet
+
+**Solution**:
+
+- Register your hotkey first using `cartha miner register`
+- Verify you're using the correct network (`test`) and netuid (`78`)
+- Check that you have testnet TAO in your wallet
+
+### "Wallet not found"
+
+**Problem**: CLI can't find your Bittensor wallet
+
+**Solution**:
+
+```bash
+# Check default wallet location
+ls ~/.bittensor/wallets/
+
+# Or set custom path
+export BITTENSOR_WALLET_PATH="/path/to/wallet"
+```
+
+### "Network error"
+
+**Problem**: Can't connect to Bittensor network
+
+**Solution**:
+
+- Verify `CARTHA_NETWORK` is set to `"test"` for testnet
+- Check your internet connection
+- Try using a VPN if network is blocked
+
+### "Transaction failed"
+
+**Problem**: MetaMask transaction failed
+
+**Solution**:
+
+- **Check Network**: Make sure you're on **Base Sepolia** network (not Mainnet or other networks)
+- **Check Gas**: Ensure you have enough testnet ETH for gas fees
+- **Check USDC**: Ensure you have enough testnet USDC in your wallet
+- **Check Approval**: Make sure you've approved the vault to spend USDC (first transaction)
+- **Verify Transaction Data**: Check that the transaction data matches what the CLI displayed
+- **Check Network Congestion**: Base Sepolia may be slower than mainnet - wait a bit and retry
+
+### "Insufficient funds" or "Not enough ETH"
+
+**Problem**: Don't have enough testnet ETH for gas
+
+**Solution**:
+
+- Visit https://console.optimism.io/faucet
+- Select "Base Sepolia" network
+- Request testnet ETH to your wallet address
+- Wait a few minutes for the transaction to complete
+- Retry your transaction
+
+### "USDC balance is zero" or "No USDC found"
+
+**Problem**: Don't have testnet USDC tokens
+
+**Solution**:
+
+- Visit the Cartha faucet at https://cartha.finance/faucet
+- Connect your wallet and claim 1,000,000 testnet USDC
+- Note: There's a 24-hour cooldown between claims
+- Verify receipt on [BaseScan Sepolia](https://sepolia.basescan.org/)
+
+### "Wrong wallet connected" or "Wallet address mismatch"
+
+**Problem**: The frontend shows a warning that the connected wallet doesn't match the required owner address
+
+**Solution**:
+
+1. **Disconnect your current wallet** using the "Disconnect" button in the frontend
+2. **Connect the correct wallet** that matches the `--owner-evm` address you specified in the CLI
+3. **Verify the address** - The frontend will show "Required Owner" vs "Connected Wallet" to help you identify the mismatch
+4. If you need to use a different address, restart the CLI command with the correct `--owner-evm` address
+
+**Note**: The frontend includes automatic wallet validation to prevent this issue. Always ensure you connect the wallet that matches the address specified in the CLI command.
+
+## Testing Your Setup
+
+### Complete Testnet Checklist
+
+Before starting, make sure you have:
+
+- [ ] Python 3.11 installed
+- [ ] `uv` package manager installed
+- [ ] Bittensor wallet set up
+- [ ] MetaMask (or other EVM wallet) installed
+- [ ] Base Sepolia network added to MetaMask
+- [ ] Testnet ETH in your wallet (from faucet)
+- [ ] Testnet USDC in your wallet (from team)
+- [ ] Testnet TAO in your Bittensor wallet (for registration)
+
+### Quick Test
+
+```bash
+# 1. Register your hotkey
+cartha miner register --wallet-name test --wallet-hotkey test --network test --netuid 78
+
+# 2. Check miner status (no authentication needed)
+cartha miner status --wallet-name test --wallet-hotkey test
+
+# 3. Lock funds (interactive flow)
+# Note: Make sure you're on Base Sepolia network in MetaMask!
+# Chain ID and vault address are auto-detected from pool-id - no need to specify!
+cartha vault lock \
+  --coldkey test \
+  --hotkey test \
+  --pool-id BTCUSD \
+  --amount 100.0 \
+  --lock-days 30 \
+  --owner-evm 0xYourEVMAddress
+```
+
+**Important**: 
+- Chain ID (84532 for Base Sepolia) and vault address are **automatically detected** from the pool ID
+- You only need to specify `--pool-id BTCUSD` (or `ETH/USD`, `EUR/USD`)
+- The CLI will show you the auto-matched values before proceeding
+
+## Next Steps
+
+- Check the [Main README](../README.md) for advanced usage
+- Review [Validator Setup](../../cartha-validator/docs/TESTNET_SETUP.md) if running a validator
+- Provide feedback via [GitHub Issues](https://github.com/your-org/cartha-cli/issues)
+
+## Additional Resources
+
+- [CLI README](../README.md) - Full CLI documentation
+- `testnet/pool_ids.py` - Pool ID helper functions for converting between readable names and hex format

cartha_cli/testnet/__init__.py

@@ -0,0 +1,2 @@
+"""Testnet utilities for Cartha CLI."""
+

cartha_cli/testnet/pool_ids.py

@@ -0,0 +1,208 @@
+"""Helper functions for generating and displaying human-readable pool IDs.
+
+Pool IDs are bytes32 (32 bytes = 64 hex chars), so we can encode readable text
+in hex format. This module provides helpers to convert between readable names
+and hex pool IDs.
+"""
+
+from __future__ import annotations
+
+# Predefined pool mappings (readable name -> hex pool ID)
+# Base Sepolia testnet pool IDs from vault contracts (keccak256 hashes)
+# Pool IDs are bytes32 (keccak256 hashes: 32 bytes = 64 hex chars + 0x prefix = 66 chars)
+POOL_MAPPINGS: dict[str, str] = {
+    "BTCUSD": "0xee62665949c883f9e0f6f002eac32e00bd59dfe6c34e92a91c37d6a8322d6489",  # BTC/USD (keccak256("BTC/USD"))
+    "ETHUSD": "0x0b43555ace6b39aae1b894097d0a9fc17f504c62fea598fa206cc6f5088e6e45",  # ETH/USD (keccak256("ETH/USD"))
+    "EURUSD": "0xa9226449042e36bf6865099eec57482aa55e3ad026c315a0e4a692b776c318ca",  # EUR/USD (keccak256("EUR/USD"))
+}
+
+# Reverse mapping (hex -> readable name)
+POOL_NAMES: dict[str, str] = {v.lower(): k for k, v in POOL_MAPPINGS.items()}
+
+# Pool ID to Vault Address mapping (Base Sepolia testnet)
+# Each pool ID has its own dedicated vault address
+VAULT_ADDRESSES: dict[str, str] = {
+    "BTCUSD": "0x471D86764B7F99b894ee38FcD3cEFF6EAB321b69",  # BTC/USD Vault
+    "ETHUSD": "0xdB74B44957A71c95406C316f8d3c5571FA588248",  # ETH/USD Vault
+    "EURUSD": "0x3C4dAfAC827140B8a031d994b7e06A25B9f27BAD",  # EUR/USD Vault
+}
+
+# Pool ID (hex) to Vault Address mapping
+POOL_ID_TO_VAULT: dict[str, str] = {
+    POOL_MAPPINGS["BTCUSD"].lower(): VAULT_ADDRESSES["BTCUSD"],
+    POOL_MAPPINGS["ETHUSD"].lower(): VAULT_ADDRESSES["ETHUSD"],
+    POOL_MAPPINGS["EURUSD"].lower(): VAULT_ADDRESSES["EURUSD"],
+}
+
+# Vault Address to Chain ID mapping (Base Sepolia testnet)
+# All testnet vaults are on Base Sepolia (chain ID 84532)
+VAULT_TO_CHAIN_ID: dict[str, int] = {
+    VAULT_ADDRESSES["BTCUSD"].lower(): 84532,  # Base Sepolia
+    VAULT_ADDRESSES["ETHUSD"].lower(): 84532,  # Base Sepolia
+    VAULT_ADDRESSES["EURUSD"].lower(): 84532,  # Base Sepolia
+}
+
+# Pool ID (hex) to Chain ID mapping
+POOL_ID_TO_CHAIN_ID: dict[str, int] = {
+    POOL_MAPPINGS["BTCUSD"].lower(): 84532,  # Base Sepolia
+    POOL_MAPPINGS["ETHUSD"].lower(): 84532,  # Base Sepolia
+    POOL_MAPPINGS["EURUSD"].lower(): 84532,  # Base Sepolia
+}
+
+
+def pool_id_to_vault_address(pool_id: str) -> str | None:
+    """Get vault address for a given pool ID.
+    
+    Args:
+        pool_id: Pool ID in hex format (bytes32)
+        
+    Returns:
+        Vault address if found, None otherwise
+    """
+    pool_id_lower = pool_id.lower().strip()
+    if not pool_id_lower.startswith("0x"):
+        pool_id_lower = "0x" + pool_id_lower
+    
+    return POOL_ID_TO_VAULT.get(pool_id_lower)
+
+
+def vault_address_to_pool_id(vault_address: str) -> str | None:
+    """Get pool ID for a given vault address.
+    
+    Args:
+        vault_address: Vault contract address
+        
+    Returns:
+        Pool ID if found, None otherwise
+    """
+    vault_lower = vault_address.lower().strip()
+    if not vault_lower.startswith("0x"):
+        vault_lower = "0x" + vault_lower
+    
+    # Reverse lookup
+    for pool_id, vault in POOL_ID_TO_VAULT.items():
+        if vault.lower() == vault_lower:
+            return pool_id
+    return None
+
+
+def pool_id_to_chain_id(pool_id: str) -> int | None:
+    """Get chain ID for a given pool ID.
+    
+    Args:
+        pool_id: Pool ID in hex format (bytes32)
+        
+    Returns:
+        Chain ID if found, None otherwise
+    """
+    pool_id_lower = pool_id.lower().strip()
+    if not pool_id_lower.startswith("0x"):
+        pool_id_lower = "0x" + pool_id_lower
+    
+    return POOL_ID_TO_CHAIN_ID.get(pool_id_lower)
+
+
+def vault_address_to_chain_id(vault_address: str) -> int | None:
+    """Get chain ID for a given vault address.
+    
+    Args:
+        vault_address: Vault contract address
+        
+    Returns:
+        Chain ID if found, None otherwise
+    """
+    vault_lower = vault_address.lower().strip()
+    if not vault_lower.startswith("0x"):
+        vault_lower = "0x" + vault_lower
+    
+    return VAULT_TO_CHAIN_ID.get(vault_lower)
+
+
+def pool_name_to_id(pool_name: str) -> str:
+    """Convert a readable pool name to hex pool ID.
+    
+    Args:
+        pool_name: Readable name (e.g., "USDEUR", "XAUUSD")
+        
+    Returns:
+        Hex pool ID (bytes32 format)
+        
+    Examples:
+        >>> pool_name_to_id("USDEUR")
+        '0x0000000000000000000000000000000000000000000000000000000000555344455552'
+    """
+    pool_name_upper = pool_name.upper()
+    if pool_name_upper in POOL_MAPPINGS:
+        return POOL_MAPPINGS[pool_name_upper]
+    
+    # If not in predefined mappings, encode the name as hex
+    # Pad to 32 bytes (64 hex chars), right-padded (data at end, zeros at beginning)
+    name_bytes = pool_name.encode("utf-8")
+    if len(name_bytes) > 32:
+        raise ValueError(f"Pool name too long: {pool_name} (max 32 bytes)")
+    
+    # Right-pad with zeros to 32 bytes (data at end, zeros at beginning)
+    padded = name_bytes.rjust(32, b"\x00")
+    hex_id = "0x" + padded.hex()
+    # Validate length
+    if len(hex_id) != 66:  # 0x + 64 hex chars
+        raise ValueError(f"Generated pool_id has incorrect length: {len(hex_id)} (expected 66)")
+    return hex_id
+
+
+def pool_id_to_name(pool_id: str) -> str | None:
+    """Convert a hex pool ID to readable name if available.
+    
+    Args:
+        pool_id: Hex pool ID (bytes32 format)
+        
+    Returns:
+        Readable name if found, None otherwise
+        
+    Examples:
+        >>> pool_id_to_name("0x0000000000000000000000000000000000000000000000000000000000555344455552")
+        'USDEUR'
+    """
+    pool_id_lower = pool_id.lower()
+    if pool_id_lower in POOL_NAMES:
+        return POOL_NAMES[pool_id_lower]
+    
+    # Try to decode from hex
+    try:
+        # Remove 0x prefix
+        hex_str = pool_id_lower.removeprefix("0x")
+        # Convert to bytes
+        pool_bytes = bytes.fromhex(hex_str)
+        # Try to decode as UTF-8 (remove trailing zeros)
+        name = pool_bytes.rstrip(b"\x00").decode("utf-8", errors="ignore")
+        if name and name.isprintable():
+            return name
+    except Exception:
+        pass
+    
+    return None
+
+
+def format_pool_id(pool_id: str) -> str:
+    """Format a pool ID for display (shows readable name if available).
+    
+    Args:
+        pool_id: Hex pool ID
+        
+    Returns:
+        Formatted string: "USDEUR (0x...)" or just "0x..." if no name found
+    """
+    name = pool_id_to_name(pool_id)
+    if name:
+        return f"{name} ({pool_id})"
+    return pool_id
+
+
+def list_pools() -> dict[str, str]:
+    """List all predefined pools.
+    
+    Returns:
+        Dictionary mapping readable names to hex pool IDs
+    """
+    return POOL_MAPPINGS.copy()
+

{cartha_cli-1.0.2.dist-info → cartha_cli-1.0.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cartha-cli
-Version: 1.0.2
+Version: 1.0.3
 Summary: CLI utilities for Cartha subnet miners.
 Project-URL: Homepage, https://cartha.finance
 Project-URL: Repository, https://github.com/General-Tao-Ventures/cartha-cli

{cartha_cli-1.0.2.dist-info → cartha_cli-1.0.3.dist-info}/RECORD

@@ -15,14 +15,17 @@ cartha_cli/commands/health.py,sha256=NRwmIultxUzAe7udOOBIdkcdGG5KsE_kuCs43LZObGk
 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=Q_CTi-7vrvpe0XYiuf_RFdFNXiBcs84xLcTYguxb4ho,19979
-cartha_cli/commands/pools.py,sha256=hXtqRmBLfcMe_FJiW_rcVcttyt7jMX37n0mZAXSnmOU,4661
-cartha_cli/commands/prove_lock.py,sha256=A5AZkfqCLbDio4idud4XV-ktYRhYVOA22WhqPojyFc8,61480
+cartha_cli/commands/pair_status.py,sha256=LoU-fA1MXuWZGHNmeKPMjwvNw30Yn094ZD1EC0-WXVc,19978
+cartha_cli/commands/pools.py,sha256=P02SEp23a7OdrgNj6AaiJTnQ9K_QrI300DzucA6HH8A,3884
+cartha_cli/commands/prove_lock.py,sha256=ihcZLrYcc9Pr4X75K9cgaDEod0Sjjyj58sAUPAhRQEo,60268
 cartha_cli/commands/register.py,sha256=sxbYO0V4NucOKLZpaFoVnhFDHLSLDHREoMtN9DjyLsM,10227
 cartha_cli/commands/shared_options.py,sha256=itHzJSgxuKQxUVOh1_jVTcMQXjI3PPzexQyhqIbabxc,5874
 cartha_cli/commands/version.py,sha256=u5oeccQzK0LLcCbgZm0U8-Vslk5vB_lVvW3xT5HPeTg,456
-cartha_cli-1.0.2.dist-info/METADATA,sha256=oCfBEiLZfg8QSFW-Ml9smIh0WNPG-vQ2QKbC4oKZG6c,5794
-cartha_cli-1.0.2.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-cartha_cli-1.0.2.dist-info/entry_points.txt,sha256=sTYVMgb9l0fuJibUtWpGnIoDmgHinne97G4Y_cCwC-U,43
-cartha_cli-1.0.2.dist-info/licenses/LICENSE,sha256=B4UCiDn13m4xYwIl4TMKfbuKw7kh9pg4c81rJecxHSo,1076
-cartha_cli-1.0.2.dist-info/RECORD,,
+cartha_cli/testnet/README.md,sha256=kWKaLtq6t_46W-mvXkSaLi2fjXDELLk5ntVGkogiUY0,14511
+cartha_cli/testnet/__init__.py,sha256=xreJMXs-ZKTkPtUQBR5xdY7ImOyUiF7WKG6bv9J9aBM,41
+cartha_cli/testnet/pool_ids.py,sha256=0jvQ6tvc6sL0aGKkl31KXM6ngVpUboYiABY5SDMaRCQ,6747
+cartha_cli-1.0.3.dist-info/METADATA,sha256=5c0z7KdAKD3ZejILXjQF9GI6WvIUcqxUdmgv-qhm1eY,5794
+cartha_cli-1.0.3.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+cartha_cli-1.0.3.dist-info/entry_points.txt,sha256=sTYVMgb9l0fuJibUtWpGnIoDmgHinne97G4Y_cCwC-U,43
+cartha_cli-1.0.3.dist-info/licenses/LICENSE,sha256=B4UCiDn13m4xYwIl4TMKfbuKw7kh9pg4c81rJecxHSo,1076
+cartha_cli-1.0.3.dist-info/RECORD,,