149 lines
6 KiB
Markdown
149 lines
6 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Build Commands
|
|
|
|
```bash
|
|
# Standard build
|
|
mkdir build && cd build
|
|
cmake ..
|
|
cmake --build . --config Release
|
|
|
|
# Build with specific features
|
|
cmake .. -DCMAKE_BUILD_TYPE=Release \
|
|
-DWITH_HWLOC=ON \
|
|
-DWITH_OPENCL=ON \
|
|
-DWITH_CUDA=ON \
|
|
-DWITH_HTTP=ON \
|
|
-DWITH_TLS=ON
|
|
|
|
# Debug build
|
|
cmake .. -DCMAKE_BUILD_TYPE=Debug -DWITH_DEBUG_LOG=ON
|
|
|
|
# Disable specific algorithms to reduce binary size
|
|
cmake .. -DWITH_RANDOMX=OFF -DWITH_ARGON2=OFF -DWITH_KAWPOW=OFF
|
|
|
|
# Static build
|
|
cmake .. -DBUILD_STATIC=ON
|
|
```
|
|
|
|
## Key CMake Options
|
|
|
|
| Option | Default | Description |
|
|
|--------|---------|-------------|
|
|
| `WITH_HWLOC` | ON | Hardware topology support (recommended) |
|
|
| `WITH_RANDOMX` | ON | RandomX algorithms (Monero) |
|
|
| `WITH_ARGON2` | ON | Argon2 algorithms |
|
|
| `WITH_KAWPOW` | ON | KawPow algorithm (GPU only) |
|
|
| `WITH_ETCHASH` | ON | ETChash/Ethash algorithms (GPU only) |
|
|
| `WITH_PROGPOWZ` | ON | ProgPowZ algorithm (Zano, GPU only) |
|
|
| `WITH_BLAKE3DCR` | ON | Blake3DCR algorithm (Decred) |
|
|
| `WITH_GHOSTRIDER` | ON | GhostRider algorithm |
|
|
| `WITH_OPENCL` | ON | AMD GPU backend |
|
|
| `WITH_CUDA` | ON | NVIDIA GPU backend (requires external plugin) |
|
|
| `WITH_HTTP` | ON | HTTP API and solo mining |
|
|
| `WITH_TLS` | ON | SSL/TLS encrypted connections |
|
|
| `WITH_ASM` | ON | Assembly optimizations |
|
|
| `WITH_MSR` | ON | MSR mod for CPU tuning |
|
|
| `WITH_BENCHMARK` | ON | Built-in RandomX benchmark |
|
|
|
|
## Architecture Overview
|
|
|
|
C++ cryptocurrency miner (XMRig-based) supporting RandomX, KawPow, CryptoNight, GhostRider, ETChash, and ProgPowZ algorithms across CPU, OpenCL (AMD), and CUDA (NVIDIA) backends.
|
|
|
|
### Startup Flow
|
|
|
|
`main()` in `xmrig.cpp` creates `Process` (command line parsing), checks for special `Entry` points (benchmark, version), then runs `App::exec()` which initializes `Controller`. Controller inherits from `Base` and owns `Miner` (backend management) and `Network` (pool connections).
|
|
|
|
### Source Structure (`src/`)
|
|
|
|
```
|
|
src/
|
|
├── xmrig.cpp # Entry point: main() -> Process -> Entry -> App
|
|
├── App.h/cpp # Application lifecycle, signal/console handling
|
|
├── donate.h # Donation configuration (dev fee percentage)
|
|
├── core/
|
|
│ ├── Controller.h/cpp # Main controller: manages backends, network, config
|
|
│ ├── Miner.h/cpp # Mining orchestration, job distribution to backends
|
|
│ └── config/ # JSON configuration parsing and validation
|
|
├── backend/
|
|
│ ├── cpu/ # CPU mining: threads, workers, platform-specific code
|
|
│ ├── opencl/ # AMD GPU: kernels, runners, OpenCL wrappers
|
|
│ └── cuda/ # NVIDIA GPU: runners, CUDA wrappers
|
|
├── crypto/
|
|
│ ├── cn/ # CryptoNight variants (x86/ARM/RISC-V implementations)
|
|
│ ├── randomx/ # RandomX with JIT compiler
|
|
│ ├── kawpow/ # KawPow (GPU-optimized)
|
|
│ ├── etchash/ # ETChash/Ethash (GPU-optimized)
|
|
│ ├── progpowz/ # ProgPowZ for Zano
|
|
│ ├── blake3dcr/ # Blake3DCR for Decred
|
|
│ ├── ghostrider/ # GhostRider algorithm
|
|
│ ├── argon2/ # Argon2 variants
|
|
│ └── common/ # Huge pages, NUMA memory pools, virtual memory
|
|
├── base/
|
|
│ ├── api/ # HTTP REST API server
|
|
│ ├── net/
|
|
│ │ ├── stratum/ # Pool protocol: Client, Job, strategies
|
|
│ │ └── http/ # HTTP client/server
|
|
│ ├── kernel/ # Process, signals, entry points
|
|
│ └── io/ # Logging, JSON utilities
|
|
├── net/
|
|
│ ├── Network.h/cpp # Pool connection management
|
|
│ ├── JobResults.h/cpp # Share submission queue
|
|
│ └── strategies/ # Donation strategy
|
|
└── hw/ # Hardware: MSR access, DMI reading
|
|
```
|
|
|
|
### Key Interfaces
|
|
|
|
- **`IBackend`** - Mining backend abstraction (CPU, OpenCL, CUDA). Methods: `isEnabled()`, `tick()`, `hashrate()`, `setJob()`, `start()`, `stop()`
|
|
- **`IConsoleListener`** - Interactive console commands (h=hashrate, p=pause, r=resume)
|
|
- **`ISignalListener`** - SIGTERM/SIGINT handling for graceful shutdown
|
|
- **`IRxListener`** - RandomX dataset initialization events
|
|
|
|
### Configuration
|
|
|
|
JSON config file is the primary configuration method. Key sections:
|
|
- `pools[]` - Mining pool connections with algorithm/coin settings
|
|
- `cpu` - Thread configuration, huge pages, affinity
|
|
- `opencl`/`cuda` - GPU backend settings
|
|
- `randomx` - Dataset mode, NUMA, MSR tuning
|
|
- `http` - API server settings
|
|
|
|
Runtime config changes via HTTP API: `PUT /1/config`
|
|
|
|
### Memory Management
|
|
|
|
- **Huge pages**: 2MB and 1GB page support for RandomX performance
|
|
- **NUMA-aware**: Allocates memory on correct NUMA node via hwloc
|
|
- **Memory pools**: Reusable scratchpad memory for mining threads
|
|
|
|
### Build Dependencies
|
|
|
|
- **Required**: CMake 3.10+, C++11 compiler, libuv
|
|
- **Recommended**: hwloc (hardware topology), OpenSSL (TLS)
|
|
- **GPU**: OpenCL SDK (AMD), CUDA plugin (NVIDIA - external)
|
|
|
|
Build scripts in `scripts/`:
|
|
- `build_deps.sh` - Compile all dependencies
|
|
- `build.hwloc.sh`, `build.openssl.sh` - Individual dependency builds
|
|
- `randomx_boost.sh` - CPU-specific RandomX tuning
|
|
- `enable_1gb_pages.sh` - Linux huge page setup
|
|
|
|
### Platform-Specific Code
|
|
|
|
Platform variants use suffix naming:
|
|
- `*_unix.cpp` / `*_win.cpp` - OS-specific implementations
|
|
- `CryptoNight_x86.h` / `CryptoNight_arm.h` - Architecture-specific crypto
|
|
|
|
Supported: Linux, Windows, macOS, FreeBSD, OpenBSD, Haiku, Android, iOS
|
|
Architectures: x86-64, x86, ARMv7, ARMv8, RISC-V
|
|
|
|
## HTTP API
|
|
|
|
When built with `-DWITH_HTTP=ON`:
|
|
- `GET /1/summary` - Miner statistics
|
|
- `GET /1/threads` - Per-thread details
|
|
- `GET /1/config` - Current configuration (requires access token)
|
|
- `PUT /1/config` - Update configuration at runtime
|