From 473c72814fdaf5ee84c91fe7e543bc8f4e217c96 Mon Sep 17 00:00:00 2001 From: snider Date: Wed, 31 Dec 2025 01:53:53 +0000 Subject: [PATCH] fix: Update documentation for miner-cuda plugin and improve build instructions --- miner/core/CLAUDE.md | 17 +++++++++++--- miner/proxy/CLAUDE.md | 52 ++++++++++++++++++++++++++++++++----------- 2 files changed, 53 insertions(+), 16 deletions(-) diff --git a/miner/core/CLAUDE.md b/miner/core/CLAUDE.md index dc61617..bd770f2 100644 --- a/miner/core/CLAUDE.md +++ b/miner/core/CLAUDE.md @@ -36,6 +36,9 @@ cmake .. -DBUILD_STATIC=ON | `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) | @@ -47,7 +50,11 @@ cmake .. -DBUILD_STATIC=ON ## Architecture Overview -XMRig is a C++ cryptocurrency miner supporting RandomX, KawPow, CryptoNight, and GhostRider algorithms across CPU, OpenCL (AMD), and CUDA (NVIDIA) backends. +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/`) @@ -55,9 +62,10 @@ XMRig is a C++ cryptocurrency miner supporting RandomX, KawPow, CryptoNight, and 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 +│ ├── Miner.h/cpp # Mining orchestration, job distribution to backends │ └── config/ # JSON configuration parsing and validation ├── backend/ │ ├── cpu/ # CPU mining: threads, workers, platform-specific code @@ -67,6 +75,9 @@ src/ │ ├── 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 @@ -86,7 +97,7 @@ src/ ### Key Interfaces -- **`IBackend`** - Mining backend abstraction (CPU, OpenCL, CUDA) +- **`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 diff --git a/miner/proxy/CLAUDE.md b/miner/proxy/CLAUDE.md index 481af1a..6805bf4 100644 --- a/miner/proxy/CLAUDE.md +++ b/miner/proxy/CLAUDE.md @@ -17,12 +17,17 @@ cmake .. -DWITH_GOOGLE_BREAKPAD=ON # Enable crash reporting # Clean rebuild rm -rf build && mkdir build && cd build && cmake .. && make -j$(nproc) + +# Run the proxy (after build) +./miner-proxy -c config.json +./miner-proxy --help # Show all CLI options +./miner-proxy --dry-run # Test configuration and exit ``` **Build options** (CMakeLists.txt): - `WITH_TLS` (ON) - OpenSSL/TLS support - `WITH_HTTP` (ON) - HTTP API support -- `WITH_DEBUG_LOG` (OFF) - Debug logging +- `WITH_DEBUG_LOG` (OFF) - Debug logging (enables `APP_DEBUG` define) - `WITH_ENV_VARS` (ON) - Environment variables in config - `WITH_GOOGLE_BREAKPAD` (OFF) - Crash reporting @@ -32,16 +37,32 @@ rm -rf build && mkdir build && cd build && cmake .. && make -j$(nproc) XMRig Proxy is a high-performance CryptoNote stratum protocol proxy that can handle 100K+ miner connections while maintaining minimal pool-side connections through nonce splitting. +### Data Flow + +``` +Miners (100K+) → [Server] → [Login] → [Miner] → [Splitter] → Pool (few connections) + ↑ ↓ + [TlsContext] [NonceMapper] + ↓ + [Events] → [Stats/Workers] +``` + ### Core Components (`src/`) **Proxy Module** (`src/proxy/`): -- `Proxy.h/cpp` - Main orchestrator; manages servers, splitters, stats, workers +- `Proxy.h/cpp` - Main orchestrator; manages servers, splitters, stats, workers. Runs main tick loop (1s interval), handles garbage collection every 60s - `Server.h/cpp` - TCP server accepting miner connections (binds to configured addresses) - `Miner.h/cpp` - Individual miner connection state and protocol handling - `Miners.h/cpp` - Miner pool management - `Login.h/cpp` - Stratum authentication - `Stats.h/cpp`, `StatsData.h` - Performance metrics aggregation +**Event System** (`src/proxy/events/`): +- Events propagate connection lifecycle changes through the proxy +- Event types: `LoginEvent`, `AcceptEvent`, `SubmitEvent`, `CloseEvent`, `ConnectionEvent` +- `IEventListener` interface for subscribing to events +- `Events.cpp` dispatches events to registered listeners + **Splitter System** (`src/proxy/splitters/`) - Handles nonce space partitioning: - `nicehash/` - Default mode with full nonce splitting (NonceMapper, NonceStorage, NonceSplitter) - `simple/` - Direct pool connection sharing @@ -56,33 +77,35 @@ Each splitter has: Mapper (nonce transformation), Storage (state), Splitter (orc - `ConfigTransform.cpp` - Config migration **Base Infrastructure** (`src/base/`): -- Network I/O layer built on libuv -- HTTP client/server -- Crypto utilities -- Logging (file, syslog) +- `net/` - Network I/O layer built on libuv (stratum clients, DNS, HTTP) +- `io/` - Console, signals, file watchers, JSON parsing +- `crypto/` - Algorithm definitions, keccak, SHA3 +- `io/log/` - Logging backends (ConsoleLog, FileLog, SysLog) +- `kernel/` - Platform abstraction, process management, interfaces **API** (`src/api/v1/`): - `ApiRouter.h/cpp` - REST API for monitoring (when `WITH_HTTP=ON`) ### Key Interfaces -- `ISplitter` (`src/proxy/interfaces/`) - Splitter abstraction +- `ISplitter` (`src/proxy/interfaces/`) - Splitter abstraction: `connect()`, `tick()`, `gc()`, `upstreams()` - `IEventListener` - Event handling for connection lifecycle -- `IBaseListener` - Configuration change callbacks +- `IBaseListener` - Configuration change callbacks via `onConfigChanged()` +- `IClient` / `IClientListener` - Pool client abstraction ### Stratum Protocol Protocol implementation follows `doc/STRATUM.md`: -- `login` - Miner authorization +- `login` - Miner authorization (returns session ID + first job) - `job` - Pool pushes new work -- `submit` - Miner submits shares +- `submit` - Miner submits shares (with nonce transformation in proxy) - `keepalived` - Connection keepalive Extensions in `doc/STRATUM_EXT.md`: algorithm negotiation, rig identifiers, NiceHash compatibility. ### Platform-Specific Code -- `App_unix.cpp` - Linux/macOS initialization +- `App_unix.cpp` - Linux/macOS initialization (signal handling) - `App_win.cpp` - Windows initialization (console, service support) - Platform libs: IOKit (macOS), ws2_32/psapi (Windows), pthread/rt (Linux) @@ -91,8 +114,11 @@ Extensions in `doc/STRATUM_EXT.md`: algorithm negotiation, rig identifiers, Nice ```cpp XMRIG_PROXY_PROJECT // Proxy-specific code paths XMRIG_FORCE_TLS // TLS enforcement -APP_DEVEL // Development features +APP_DEVEL // Development features (enables printState()) +APP_DEBUG // Debug logging (set via WITH_DEBUG_LOG) XMRIG_ALGO_RANDOMX // Algorithm support flags +XMRIG_FEATURE_HTTP // HTTP API enabled +XMRIG_FEATURE_API // REST API enabled ``` ## Configuration @@ -101,4 +127,4 @@ Default config template: `src/config.json` Key sections: pools, bind addresses, proxy mode (nicehash/simple/extra_nonce), TLS certificates, HTTP API settings, logging. -Config hot-reload is enabled by default. +Config hot-reload is enabled by default (`"watch": true`).