130 lines
4.9 KiB
Markdown
130 lines
4.9 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 (out-of-source recommended)
|
|
mkdir build && cd build
|
|
cmake ..
|
|
make -j$(nproc)
|
|
|
|
# Build with specific options
|
|
cmake .. -DWITH_TLS=ON -DWITH_HTTP=ON
|
|
cmake .. -DWITH_DEBUG_LOG=ON # Enable debug logging
|
|
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 (enables `APP_DEBUG` define)
|
|
- `WITH_ENV_VARS` (ON) - Environment variables in config
|
|
- `WITH_GOOGLE_BREAKPAD` (OFF) - Crash reporting
|
|
|
|
**Dependencies**: CMake 3.10+, libuv, OpenSSL, C++11 compiler
|
|
|
|
## Architecture Overview
|
|
|
|
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. 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
|
|
- `extra_nonce/` - Solo mining support
|
|
- `donate/` - Donation traffic redirection
|
|
|
|
Each splitter has: Mapper (nonce transformation), Storage (state), Splitter (orchestration)
|
|
|
|
**Configuration** (`src/core/`):
|
|
- `Config.h/cpp` - JSON config parsing via RapidJSON
|
|
- `Controller.h/cpp` - Application lifecycle
|
|
- `ConfigTransform.cpp` - Config migration
|
|
|
|
**Base Infrastructure** (`src/base/`):
|
|
- `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: `connect()`, `tick()`, `gc()`, `upstreams()`
|
|
- `IEventListener` - Event handling for connection lifecycle
|
|
- `IBaseListener` - Configuration change callbacks via `onConfigChanged()`
|
|
- `IClient` / `IClientListener` - Pool client abstraction
|
|
|
|
### Stratum Protocol
|
|
|
|
Protocol implementation follows `doc/STRATUM.md`:
|
|
- `login` - Miner authorization (returns session ID + first job)
|
|
- `job` - Pool pushes new work
|
|
- `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 (signal handling)
|
|
- `App_win.cpp` - Windows initialization (console, service support)
|
|
- Platform libs: IOKit (macOS), ws2_32/psapi (Windows), pthread/rt (Linux)
|
|
|
|
### Key Defines
|
|
|
|
```cpp
|
|
XMRIG_PROXY_PROJECT // Proxy-specific code paths
|
|
XMRIG_FORCE_TLS // TLS enforcement
|
|
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
|
|
|
|
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 (`"watch": true`).
|