CLAUDE.md

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

Build Commands

# 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

6 KiB Raw Permalink Blame History