cartha-cli 1.0.0__tar.gz

cartha_cli-1.0.0/.github/workflows/README.md

@@ -0,0 +1,43 @@
+# GitHub Actions Workflows
+
+This directory contains GitHub Actions workflows for the Cartha CLI.
+
+## Workflows
+
+### `ci.yml`
+
+Runs on every push and pull request to `main` and `demo-verifier` branches.
+
+**Jobs:**
+- **test**: Runs the test suite using `pytest`
+- **lint**: Runs `ruff check` and `ruff format --check` to ensure code quality
+- **type-check**: Runs `mypy` for type checking (non-blocking)
+
+**Status Checks:**
+- For pull requests, the test job sets a commit status that appears in the PR checks
+
+## Local Development
+
+You can run the same checks locally:
+
+```bash
+# Run tests
+uv run pytest
+
+# Run linting
+uv run ruff check cartha_cli tests
+uv run ruff format --check cartha_cli tests
+
+# Run type checking
+uv run mypy cartha_cli
+```
+
+Or use the Makefile:
+
+```bash
+make test      # Runs lint, typecheck, and tests
+make lint      # Runs ruff check
+make format    # Formats code with ruff
+make typecheck # Runs mypy
+```
+

cartha_cli-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,61 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+  workflow_dispatch: # Allow manual triggers
+
+jobs:
+  test:
+    name: Run Tests
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      statuses: write
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Run tests
+        id: test
+        run: uv run pytest
+        env:
+          # Set test environment variables if needed
+          CARTHA_VERIFIER_URL: "https://cartha-verifier-826542474079.us-central1.run.app"
+
+      - name: Set Test Status
+        if: always() && github.event_name == 'pull_request'
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            const testStatus = '${{ steps.test.outcome }}';
+            const prSha = context.payload.pull_request.head.sha;
+
+            github.rest.repos.createCommitStatus({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              sha: prSha,
+              state: testStatus === 'success' ? 'success' : 'failure',
+              target_url: `${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`,
+              description: testStatus === 'success' ? 'All tests passed' : 'Tests failed',
+              context: 'ci/tests'
+            });

cartha_cli-1.0.0/.gitignore

@@ -0,0 +1,22 @@
+__pycache__/
+*.py[cod]
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.venv/
+.env
+.DS_Store
+
+# Build artifacts
+dist/
+build/
+*.egg-info/
+
+# Ignore testnet output files (contains sensitive payloads, signatures, and keys)
+testnet/outputs/
+**/lock_proof_payload.json
+**/evm_key.json
+**/demo_outputs/
+**/outputs/
+test-payload.json
+cartha_eip712_outputs/

cartha_cli-1.0.0/.ruff.toml

@@ -0,0 +1,9 @@
+target-version = "py311"
+line-length = 100
+
+[lint]
+select = ["E", "F", "I", "B", "UP", "N"]
+ignore = ["E501"]
+
+[lint.isort]
+known-first-party = ["cartha_cli"]

cartha_cli-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,281 @@
+# Contributing to Cartha CLI
+
+Thank you for your interest in contributing to the Cartha CLI! This guide will help you get started.
+
+## Getting Started
+
+### Prerequisites
+
+- Python 3.11
+- [`uv`](https://github.com/astral-sh/uv) package manager or `pip`
+- Git
+- Basic understanding of Bittensor and EIP-712 signatures
+
+### Development Setup
+
+1. **Fork and clone the repository**
+
+   ```bash
+   git clone https://github.com/your-username/cartha-cli.git
+   cd cartha-cli
+   ```
+
+2. **Install dependencies**
+
+   ```bash
+   uv sync
+   # or
+   pip install -e .
+   ```
+
+3. **Run tests**
+
+   ```bash
+   uv run pytest
+   # or
+   make test
+   ```
+
+## Development Workflow
+
+### 1. Find Something to Work On
+
+- Check [open issues](https://github.com/your-org/cartha-cli/issues)
+- Look for `good first issue` labels
+- Discuss major changes before starting (open an issue first)
+
+### 2. Create a Branch
+
+```bash
+git checkout -b feature/your-feature-name
+# or
+git checkout -b fix/your-bug-fix
+```
+
+### 3. Make Your Changes
+
+- Write clean, readable code
+- Follow existing code style
+- Add tests for new functionality
+- Update documentation as needed
+
+### 4. Test Your Changes
+
+```bash
+# Run tests
+uv run pytest
+
+# Test CLI commands locally
+uv run cartha --help
+uv run cartha pair status --help
+```
+
+### 5. Commit Your Changes
+
+- Write clear, descriptive commit messages
+- Keep commits focused and atomic
+- Reference issue numbers when applicable
+
+Example:
+
+```bash
+git commit -m "feat: add --dry-run flag to prove-lock command
+
+- Allow users to test lock proof without submitting
+- Add validation for dry-run mode
+- Fixes #123"
+```
+
+### 6. Push and Create Pull Request
+
+```bash
+git push origin feature/your-feature-name
+```
+
+Then create a pull request on GitHub.
+
+## Code Style
+
+### Python Style
+
+- Follow PEP 8
+- Use type hints
+- Run linters before committing
+- Use `typer` for CLI commands
+
+### Code Organization
+
+- Keep commands focused and small
+- Add docstrings for public functions
+- Use meaningful variable names
+- Comment complex logic
+
+### Testing
+
+- Write tests for new commands
+- Test both success and failure cases
+- Use fixtures for common test data
+- Test with both testnet and mainnet configs
+
+## Pull Request Guidelines
+
+### Before Submitting
+
+- [ ] Code follows the project's style guidelines
+- [ ] Tests pass locally
+- [ ] Documentation is updated
+- [ ] Commit messages are clear
+- [ ] PR description explains the changes
+- [ ] CLI commands work as expected
+
+### PR Description Template
+
+```markdown
+## Description
+Brief description of changes
+
+## Type of Change
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Documentation update
+- [ ] Performance improvement
+- [ ] Refactoring
+
+## Testing
+How was this tested?
+
+## CLI Changes
+- [ ] New command added
+- [ ] Existing command modified
+- [ ] Breaking change (document migration path)
+
+## Related Issues
+Closes #123
+```
+
+### Review Process
+
+- Maintainers will review your PR
+- Address feedback promptly
+- Be open to suggestions
+- Keep discussions constructive
+
+## Project Structure
+
+```text
+cartha-cli/
+├── cartha_cli/          # Main CLI code
+│   ├── main.py         # CLI entry point (Typer app)
+│   ├── bt.py           # Bittensor helpers
+│   ├── eth712.py       # EIP-712 signature helpers
+│   ├── verifier.py     # Verifier API client
+│   └── config.py       # Configuration
+├── testnet/            # Testnet-specific helpers
+│   └── pool_ids.py     # Pool ID conversion helpers
+├── tests/              # Test suite
+└── pyproject.toml      # Project config
+```
+
+## Areas for Contribution
+
+### Code Contributions
+
+- Bug fixes
+- New CLI commands
+- Performance improvements
+- Code refactoring
+- Test coverage improvements
+
+### Documentation
+
+- Improve existing docs
+- Add command examples
+- Fix typos
+- Add tutorials
+- Improve error messages
+
+### Test
+
+- Add test cases
+- Improve test coverage
+- Add integration tests
+- Test edge cases
+
+## CLI-Specific Guidelines
+
+### Command Design
+
+- Use clear, intuitive command names
+- Provide helpful error messages
+- Include examples in help text
+- Support both testnet and mainnet
+
+### User Experience
+
+- Make commands easy to use
+- Provide sensible defaults
+- Validate inputs early
+- Give clear feedback
+
+### Security
+
+- Never log private keys or mnemonics
+- Never commit secrets
+- Validate all inputs
+- Use secure defaults
+
+### Error Handling
+
+- Provide helpful error messages
+- Suggest solutions when possible
+- Log errors appropriately
+- Handle edge cases gracefully
+
+## Adding New Commands
+
+When adding a new command:
+
+1. Add the command function to `cartha_cli/main.py`
+2. Use `@app.command()` decorator
+3. Add type hints
+4. Add docstring
+5. Add tests
+6. Update documentation
+
+Example:
+
+```python
+@app.command()
+def new_command(
+    arg: str = typer.Option(..., help="Description"),
+) -> None:
+    """Brief description of the command."""
+    # Implementation
+    pass
+```
+
+## Questions?
+
+- Check the [README](README.md) for general information
+- Review the [testnet guide](testnet/README.md) for testnet-specific info
+- Open an issue for questions
+- Ask in discussions
+
+## Code of Conduct
+
+All contributors are expected to:
+
+- Be respectful and inclusive
+- Provide constructive feedback
+- Help others learn
+- Follow project guidelines
+
+## Recognition
+
+Contributors are recognized in:
+
+- Release notes
+- Project documentation
+- GitHub contributors list
+
+Thank you for contributing to Cartha CLI! 🎉

cartha_cli-1.0.0/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.

cartha_cli-1.0.0/Makefile

@@ -0,0 +1,9 @@
+UV ?= uv
+
+.PHONY: sync test
+
+sync:
+	$(UV) sync
+
+test:
+	PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 $(UV) run pytest

cartha_cli-1.0.0/PKG-INFO

@@ -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**