Skip to content

CLAUDE.md

Latest commit

 

History

History
114 lines (91 loc) · 3.66 KB

CLAUDE.md

File metadata and controls

114 lines (91 loc) · 3.66 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

Running the application

# Basic usage
python cmswitcher.py --cpuminer <path_to_cpuminer_binary>

# With options
python cmswitcher.py --cpuminer cpuminer --log-level DEBUG --log-file cmswitcher.log

# Benchmark only
python cmswitcher.py --cpuminer cpuminer --benchmark-only

# Force re-benchmark
python cmswitcher.py --cpuminer cpuminer --force-benchmark

Installation

pip install -r requirements.txt
# or for development
pip install -e .

Dependencies

  • Python 3.7+ with packages: requests, tabulate
  • cpuminer binary (cpuminer-opt or cpuminer-multi)

Architecture

Package Structure

cmswitcher/
├── __init__.py          # Package initialization
├── config.py            # Configuration management
├── models.py            # Data models (Miner, Pool, BenchmarkResult)
├── api_client.py        # cpuminer API communication
├── pool_api.py          # Pool API interaction
├── benchmark.py         # Benchmarking logic
├── profit.py            # Profitability calculations
├── mining_session.py    # Mining process management
├── logger.py            # Logging configuration
└── main.py              # Main application and CLI

Key Classes and Components

  1. Config (config.py): Manages all configuration loading with type-safe property access
  2. Miner (models.py): Represents a mining software configuration with benchmark results
  3. Pool (models.py): Represents a mining pool with API integration
  4. MinerAPIClient (api_client.py): Handles communication with cpuminer's API (port 40101)
  5. Benchmarker (benchmark.py): Manages algorithm benchmarking process
  6. ProfitabilityCalculator (profit.py): Calculates profits and fetches Bitcoin prices
  7. MiningSession (mining_session.py): Manages mining process lifecycle
  8. CMSwitcher (main.py): Main application class that orchestrates everything

Data Flow

  1. Initialization:

    • Load configuration files from data/ directory
    • Create Miner and Pool instances
    • Fetch pool API data to discover supported algorithms

  2. Benchmarking:

    • Find common algorithms between miners and pools
    • Skip blacklisted algorithms
    • Run benchmarks and save results to benchmark-<miner>.json

  3. Mining Loop:

    • Calculate profitability for all algorithm combinations
    • Filter out blacklisted algorithms
    • Start mining with most profitable algorithm
    • Monitor performance via cpuminer API
    • Switch when better algorithm becomes available

Important Constants

  • API_PORT: 40101 (cpuminer API)
  • Default session timeout: 600 seconds
  • Default minimum profitability: $0.05/day

Error Handling

  • Retry logic for API connections
  • Graceful handling of miner crashes
  • Fallback Bitcoin price if APIs fail
  • Comprehensive logging throughout

Testing

To test changes:

  1. Ensure data/ directory has all required JSON files
  2. Run with valid cpuminer binary path
  3. Check benchmarking completes successfully
  4. Verify profit switching behavior
  5. Monitor logs for any errors

Common Development Tasks

Adding a new pool

  1. Add pool configuration to data/pools.json
  2. Ensure API endpoint returns compatible format
  3. Test algorithm name matching

Adding a new miner

  1. Add miner configuration to data/miners.json
  2. Define launch pattern and supported algorithms
  3. Test API communication on port 40101

Debugging

  • Use --log-level DEBUG for detailed logging
  • Check --log-file output for full trace
  • Monitor cpuminer output if crashes occur