Mining/miner/proxy/CLAUDE.md

CLAUDE.md

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

Build Commands

# 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

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).