Snider/Mining
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: Add miner suite documentation and release workflow

Browse source 
- Create miner/README.md documenting standalone C++ mining tools
- Update miner/core and miner/proxy READMEs with EUPL-1.2 license
- Add GitHub Actions workflow for multi-platform miner releases
- Add Makefile targets: build-miner, build-miner-core, build-miner-proxy
- Update main README with standalone miner usage instructions

The miner/ directory contains standalone CPU/GPU miner and stratum
proxy that can be used independently without the GUI. Pre-built
binaries will be published alongside Go releases.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
snider 2026-01-13 16:45:44 +00:00
parent 9f1ec97a60
commit bce309b78d
6 changed files with 1010 additions and 150 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

251
.github/workflows/miner-release.yml vendored Normal file
View file

@ -0,0 +1,251 @@
name: Miner Release
on:
push:
tags:
- 'miner-v*'
workflow_dispatch:
inputs:
version:
description: 'Version tag (e.g., 0.1.0)'
required: true
default: '0.1.0'
env:
BUILD_TYPE: Release
jobs:
build-linux:
name: Linux ${{ matrix.arch }}
runs-on: ubuntu-latest
strategy:
matrix:
include:
- arch: x64
cmake_arch: x86_64
- arch: arm64
cmake_arch: aarch64
steps:
- name: Checkout
uses: actions/checkout@v4
with:
submodules: recursive
- name: Install dependencies
run: |
sudo apt-get update
sudo apt-get install -y \
build-essential \
cmake \
libuv1-dev \
libssl-dev \
libhwloc-dev \
git
- name: Build miner core
working-directory: miner/core
run: |
mkdir -p build && cd build
cmake .. \
-DCMAKE_BUILD_TYPE=$BUILD_TYPE \
-DWITH_OPENCL=OFF \
-DWITH_CUDA=OFF
cmake --build . --config $BUILD_TYPE -j$(nproc)
- name: Build miner proxy
working-directory: miner/proxy
run: |
mkdir -p build && cd build
cmake .. -DCMAKE_BUILD_TYPE=$BUILD_TYPE
cmake --build . --config $BUILD_TYPE -j$(nproc)
- name: Package binaries
run: |
mkdir -p dist
cp miner/core/build/miner dist/
cp miner/proxy/build/miner-proxy dist/
chmod +x dist/*
cd dist
tar -czvf ../miner-linux-${{ matrix.arch }}.tar.gz *
- name: Upload artifact
uses: actions/upload-artifact@v4
with:
name: miner-linux-${{ matrix.arch }}
path: miner-linux-${{ matrix.arch }}.tar.gz
build-macos:
name: macOS ${{ matrix.arch }}
runs-on: macos-latest
strategy:
matrix:
include:
- arch: x64
cmake_osx_arch: x86_64
- arch: arm64
cmake_osx_arch: arm64
steps:
- name: Checkout
uses: actions/checkout@v4
with:
submodules: recursive
- name: Install dependencies
run: |
brew install cmake libuv openssl hwloc
- name: Build miner core
working-directory: miner/core
env:
OSX_ARCH: ${{ matrix.cmake_osx_arch }}
run: |
mkdir -p build && cd build
cmake .. \
-DCMAKE_BUILD_TYPE=$BUILD_TYPE \
-DCMAKE_OSX_ARCHITECTURES=$OSX_ARCH \
-DWITH_OPENCL=OFF \
-DWITH_CUDA=OFF \
-DOPENSSL_ROOT_DIR=$(brew --prefix openssl)
cmake --build . --config $BUILD_TYPE -j$(sysctl -n hw.ncpu)
- name: Build miner proxy
working-directory: miner/proxy
env:
OSX_ARCH: ${{ matrix.cmake_osx_arch }}
run: |
mkdir -p build && cd build
cmake .. \
-DCMAKE_BUILD_TYPE=$BUILD_TYPE \
-DCMAKE_OSX_ARCHITECTURES=$OSX_ARCH \
-DOPENSSL_ROOT_DIR=$(brew --prefix openssl)
cmake --build . --config $BUILD_TYPE -j$(sysctl -n hw.ncpu)
- name: Package binaries
run: |
mkdir -p dist
cp miner/core/build/miner dist/
cp miner/proxy/build/miner-proxy dist/
chmod +x dist/*
cd dist
tar -czvf ../miner-macos-${{ matrix.arch }}.tar.gz *
- name: Upload artifact
uses: actions/upload-artifact@v4
with:
name: miner-macos-${{ matrix.arch }}
path: miner-macos-${{ matrix.arch }}.tar.gz
build-windows:
name: Windows x64
runs-on: windows-latest
steps:
- name: Checkout
uses: actions/checkout@v4
with:
submodules: recursive
- name: Setup MSVC
uses: microsoft/setup-msbuild@v2
- name: Install dependencies
run: |
vcpkg install libuv:x64-windows openssl:x64-windows
- name: Build miner core
working-directory: miner/core
run: |
mkdir build
cd build
cmake .. `
-DCMAKE_BUILD_TYPE=$env:BUILD_TYPE `
-DCMAKE_TOOLCHAIN_FILE="$env:VCPKG_INSTALLATION_ROOT/scripts/buildsystems/vcpkg.cmake" `
-DWITH_OPENCL=OFF `
-DWITH_CUDA=OFF
cmake --build . --config $env:BUILD_TYPE
- name: Build miner proxy
working-directory: miner/proxy
run: |
mkdir build
cd build
cmake .. `
-DCMAKE_BUILD_TYPE=$env:BUILD_TYPE `
-DCMAKE_TOOLCHAIN_FILE="$env:VCPKG_INSTALLATION_ROOT/scripts/buildsystems/vcpkg.cmake"
cmake --build . --config $env:BUILD_TYPE
- name: Package binaries
run: |
mkdir dist
Copy-Item miner/core/build/$env:BUILD_TYPE/miner.exe dist/
Copy-Item miner/proxy/build/$env:BUILD_TYPE/miner-proxy.exe dist/
Compress-Archive -Path dist/* -DestinationPath miner-windows-x64.zip
- name: Upload artifact
uses: actions/upload-artifact@v4
with:
name: miner-windows-x64
path: miner-windows-x64.zip
release:
name: Create Release
needs: [build-linux, build-macos, build-windows]
runs-on: ubuntu-latest
if: startsWith(github.ref, 'refs/tags/')
steps:
- name: Download all artifacts
uses: actions/download-artifact@v4
with:
path: artifacts
- name: List artifacts
run: ls -la artifacts/*/
- name: Create Release
uses: softprops/action-gh-release@v1
with:
draft: false
prerelease: false
files: |
artifacts/miner-linux-x64/miner-linux-x64.tar.gz
artifacts/miner-linux-arm64/miner-linux-arm64.tar.gz
artifacts/miner-macos-x64/miner-macos-x64.tar.gz
artifacts/miner-macos-arm64/miner-macos-arm64.tar.gz
artifacts/miner-windows-x64/miner-windows-x64.zip
body: |
## Miner Suite
### Downloads
| Platform | Architecture | Download |
|----------|--------------|----------|
| Linux | x64 | `miner-linux-x64.tar.gz` |
| Linux | ARM64 | `miner-linux-arm64.tar.gz` |
| macOS | Intel | `miner-macos-x64.tar.gz` |
| macOS | Apple Silicon | `miner-macos-arm64.tar.gz` |
| Windows | x64 | `miner-windows-x64.zip` |
### Included Binaries
- `miner` - CPU/GPU cryptocurrency miner
- `miner-proxy` - Stratum proxy for mining farms
### Quick Start
```bash
# Extract
tar -xzf miner-linux-x64.tar.gz
# Run miner
./miner -o pool.example.com:3333 -u YOUR_WALLET -p x
# Run proxy
./miner-proxy -o pool.example.com:3333 -u YOUR_WALLET -b 0.0.0.0:3333
```
See [miner/README.md](miner/README.md) for full documentation.
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

95
Makefile
View file

@ -1,4 +1,4 @@
.PHONY: all build test clean install run demo help lint fmt vet docs install-swag dev package e2e e2e-ui e2e-api test-cpp test-cpp-core test-cpp-proxy build-cpp-tests
.PHONY: all build test clean install run demo help lint fmt vet docs install-swag dev package e2e e2e-ui e2e-api test-cpp test-cpp-core test-cpp-proxy build-cpp-tests build-miner build-miner-core build-miner-proxy build-miner-all
# Variables
BINARY_NAME=miner-ctrl
@ -66,6 +66,34 @@ build-cpp-tests-proxy:
$(CMAKE) -DBUILD_TESTS=ON .. && \
$(CMAKE) --build . --target unit_tests integration_tests --parallel
# Build miner binaries (release builds)
build-miner: build-miner-core build-miner-proxy
@echo "Miner binaries built successfully"
# Build miner core (CPU/GPU miner)
build-miner-core:
@echo "Building miner core..."
@mkdir -p $(MINER_CORE_BUILD_DIR)
@cd $(MINER_CORE_BUILD_DIR) && \
$(CMAKE) -DCMAKE_BUILD_TYPE=Release .. && \
$(CMAKE) --build . --config Release --parallel
# Build miner proxy
build-miner-proxy:
@echo "Building miner proxy..."
@mkdir -p $(MINER_PROXY_BUILD_DIR)
@cd $(MINER_PROXY_BUILD_DIR) && \
$(CMAKE) -DCMAKE_BUILD_TYPE=Release .. && \
$(CMAKE) --build . --config Release --parallel
# Build all miner components and package
build-miner-all: build-miner
@echo "Packaging miner binaries..."
@mkdir -p dist/miner
@cp $(MINER_CORE_BUILD_DIR)/miner dist/miner/ 2>/dev/null || true
@cp $(MINER_PROXY_BUILD_DIR)/miner-proxy dist/miner/ 2>/dev/null || true
@echo "Miner binaries available in dist/miner/"
# Run C++ tests (builds first if needed)
test-cpp: test-cpp-proxy
@echo "All C++ tests completed"
@ -177,30 +205,41 @@ e2e-api: build
# Help
help:
@echo "Available targets:"
@echo " all - Run tests and build"
@echo " build - Build the CLI binary"
@echo " build-all - Build for multiple platforms"
@echo " install - Install the binary"
@echo " test - Run all tests (Go + C++)"
@echo " test-go - Run Go tests only"
@echo " test-cpp - Run C++ tests (core + proxy)"
@echo " test-cpp-core - Run miner/core C++ tests"
@echo " test-cpp-proxy - Run miner/proxy C++ tests"
@echo " build-cpp-tests - Build all C++ tests"
@echo " coverage - Run tests with coverage report"
@echo " demo - Run the demo"
@echo " run - Build and run the CLI"
@echo " clean - Clean build artifacts (including C++ builds)"
@echo " fmt - Format code"
@echo " vet - Run go vet"
@echo " lint - Run linters"
@echo " tidy - Tidy dependencies"
@echo " deps - Download dependencies"
@echo " docs - Generate Swagger documentation"
@echo " install-swag- Install the swag CLI"
@echo " package - Create local distribution packages using GoReleaser"
@echo " dev - Start the development server with docs and build"
@echo " e2e - Run E2E tests with Playwright"
@echo " e2e-ui - Open Playwright UI for interactive testing"
@echo " e2e-api - Run API-only E2E tests"
@echo " help - Show this help message"
@echo ""
@echo "Go Application:"
@echo " all - Run tests and build"
@echo " build - Build the CLI binary"
@echo " build-all - Build for multiple platforms"
@echo " install - Install the binary"
@echo " run - Build and run the CLI"
@echo " dev - Start the development server with docs and build"
@echo ""
@echo "Miner (C++ Binaries):"
@echo " build-miner - Build miner core and proxy"
@echo " build-miner-core - Build miner core only"
@echo " build-miner-proxy - Build miner proxy only"
@echo " build-miner-all - Build and package all miner binaries"
@echo ""
@echo "Testing:"
@echo " test - Run all tests (Go + C++)"
@echo " test-go - Run Go tests only"
@echo " test-cpp - Run C++ tests (proxy)"
@echo " test-cpp-core - Run miner/core C++ tests"
@echo " test-cpp-proxy- Run miner/proxy C++ tests"
@echo " coverage - Run tests with coverage report"
@echo " e2e - Run E2E tests with Playwright"
@echo " e2e-ui - Open Playwright UI for interactive testing"
@echo " e2e-api - Run API-only E2E tests"
@echo ""
@echo "Code Quality:"
@echo " fmt - Format code"
@echo " vet - Run go vet"
@echo " lint - Run linters"
@echo " tidy - Tidy dependencies"
@echo ""
@echo "Other:"
@echo " clean - Clean all build artifacts"
@echo " deps - Download dependencies"
@echo " docs - Generate Swagger documentation"
@echo " package - Create local distribution packages"
@echo " help - Show this help message"

48
README.md
View file

@ -108,25 +108,43 @@ wails3 build
```
Mining/
├── cmd/
│ ├── mining/ # CLI application
│ ├── mining/ # CLI application (miner-ctrl)
│ └── desktop/ # Wails desktop app
├── pkg/mining/ # Core Go package
│ ├── mining.go # Interfaces and types
│ ├── manager.go # Miner lifecycle management
│ ├── service.go # RESTful API (Gin)
│ ├── xmrig.go # XMRig implementation
│ └── profile_manager.go # Profile persistence
├── miner/core/ # Modified XMRig with algorithm support
│ └── src/
│ ├── backend/opencl/ # OpenCL GPU kernels
│ ├── backend/cuda/ # CUDA GPU kernels
│ └── crypto/ # Algorithm implementations
├── miner/ # Standalone C++ mining tools
│ ├── core/ # CPU/GPU miner binary
│ ├── proxy/ # Stratum proxy for farms
│ ├── cuda/ # CUDA plugin for NVIDIA
│ └── README.md # Miner documentation
└── ui/ # Angular 20+ web dashboard
└── src/app/
├── components/ # Reusable UI components
└── pages/ # Route pages
```
## Standalone Miner Tools
The `miner/` directory contains standalone C++ mining programs that can be used independently without the GUI:
```bash
# Build miner binaries
make build-miner
# Or build individually
make build-miner-core # CPU/GPU miner
make build-miner-proxy # Stratum proxy
# Run directly
./miner/core/build/miner -o pool.example.com:3333 -u WALLET -p x
./miner/proxy/build/miner-proxy -o pool.example.com:3333 -b 0.0.0.0:3333
```
Pre-built binaries are available from [Releases](https://github.com/letheanVPN/Mining/releases). See [miner/README.md](miner/README.md) for full documentation.
## API Reference
Base path: `/api/v1/mining`
@ -158,26 +176,24 @@ Swagger UI: `http://localhost:9090/api/v1/mining/swagger/index.html`
### Build Commands
```bash
# Backend
# Go Backend
make build # Build CLI binary
make test # Run tests with coverage
make test # Run all tests (Go + C++)
make dev # Start dev server on :9090
# Miner (C++ Binaries)
make build-miner # Build miner and proxy
make build-miner-all # Build and package to dist/miner/
# Frontend
cd ui
npm install
npm run build # Build web component
npm test # Run unit tests (36 specs)
npm test # Run unit tests
# Desktop
cd cmd/desktop/mining-desktop
wails3 build # Build native app
# Miner Core (GPU support)
cd miner/core
mkdir build && cd build
cmake .. -DWITH_OPENCL=ON -DWITH_CUDA=ON
make -j$(nproc)
```
## Configuration

289
miner/README.md Normal file
View file

@ -0,0 +1,289 @@
# Lethean Miner Suite
[![License: EUPL-1.2](https://img.shields.io/badge/License-EUPL--1.2-blue.svg)](https://opensource.org/license/eupl-1-2)
[![Platform](https://img.shields.io/badge/platform-linux%20%7C%20macos%20%7C%20windows%20%7C%20freebsd-lightgrey.svg)](https://github.com/letheanVPN/Mining/releases)
High-performance cryptocurrency mining tools. These standalone C++ programs can be used independently or managed through the Mining Platform GUI.
## Components
| Component | Description | Binary |
|-----------|-------------|--------|
| [**core**](core/) | CPU/GPU miner with full algorithm support | `miner` |
| [**proxy**](proxy/) | Stratum proxy for mining farms (100K+ connections) | `miner-proxy` |
| [**cuda**](cuda/) | CUDA plugin for NVIDIA GPUs | `libminer-cuda.so` |
| [**config**](config/) | Configuration generator tool | `miner-config` |
| [**workers**](workers/) | Worker management utilities | `miner-workers` |
| [**heatmap**](heatmap/) | Hardware temperature visualization | `miner-heatmap` |
## Supported Algorithms
### CPU Mining
| Algorithm | Coins |
|-----------|-------|
| RandomX | Monero (XMR), Lethean (LTHN), Wownero (WOW) |
| CryptoNight | Various CN variants |
| GhostRider | Raptoreum (RTM) |
| Argon2 | Chukwa, Ninja |
### GPU Mining (OpenCL/CUDA)
| Algorithm | Coins |
|-----------|-------|
| RandomX | Monero, Lethean |
| KawPow | Ravencoin (RVN), Neoxa |
| ETChash | Ethereum Classic (ETC) |
| ProgPowZ | Zano (ZANO) |
| Blake3 | Decred (DCR) |
## Quick Start
### Download Pre-built Binaries
Download from [Releases](https://github.com/letheanVPN/Mining/releases):
- `miner-linux-x64.tar.gz` - Linux x86_64
- `miner-linux-arm64.tar.gz` - Linux ARM64
- `miner-macos-x64.tar.gz` - macOS Intel
- `miner-macos-arm64.tar.gz` - macOS Apple Silicon
- `miner-windows-x64.zip` - Windows x64
### Run the Miner
```bash
# Basic CPU mining
./miner -o pool.example.com:3333 -u YOUR_WALLET -p x
# With config file (recommended)
./miner -c config.json
# CPU + GPU mining
./miner -c config.json --opencl --cuda
# Show help
./miner --help
```
### Run the Proxy
```bash
# Start proxy for mining farm
./miner-proxy -o pool.example.com:3333 -u YOUR_WALLET -b 0.0.0.0:3333
# With config file
./miner-proxy -c proxy-config.json
```
## Building from Source
### Prerequisites
**All Platforms:**
- CMake 3.10+
- C++11 compatible compiler
- libuv
- OpenSSL (for TLS support)
**Linux:**
```bash
sudo apt-get install build-essential cmake libuv1-dev libssl-dev libhwloc-dev
```
**macOS:**
```bash
brew install cmake libuv openssl hwloc
```
**Windows:**
- Visual Studio 2019+ with C++ workload
- vcpkg for dependencies
### Build Miner Core
```bash
cd core
mkdir build && cd build
# Standard build
cmake ..
cmake --build . --config Release -j$(nproc)
# With GPU support
cmake .. -DWITH_OPENCL=ON -DWITH_CUDA=ON
# Static build (portable)
cmake .. -DBUILD_STATIC=ON
# Minimal build (RandomX only)
cmake .. -DWITH_ARGON2=OFF -DWITH_KAWPOW=OFF -DWITH_GHOSTRIDER=OFF
```
### Build Proxy
```bash
cd proxy
mkdir build && cd build
cmake ..
cmake --build . --config Release -j$(nproc)
```
### Build All Components
From the repository root:
```bash
make build-miner # Build miner core
make build-miner-proxy # Build proxy
make build-miner-all # Build all components
```
## Configuration
### Miner Config (config.json)
```json
{
"autosave": true,
"cpu": true,
"opencl": false,
"cuda": false,
"pools": [
{
"url": "stratum+tcp://pool.example.com:3333",
"user": "YOUR_WALLET",
"pass": "x",
"keepalive": true,
"tls": false
}
],
"http": {
"enabled": true,
"host": "127.0.0.1",
"port": 8080,
"access-token": null
}
}
```
### Proxy Config (proxy-config.json)
```json
{
"mode": "nicehash",
"pools": [
{
"url": "stratum+tcp://pool.example.com:3333",
"user": "YOUR_WALLET",
"pass": "x"
}
],
"bind": [
{
"host": "0.0.0.0",
"port": 3333
}
],
"http": {
"enabled": true,
"host": "127.0.0.1",
"port": 8081
}
}
```
## HTTP API
Both miner and proxy expose HTTP APIs for monitoring and control.
### Miner API (default: http://127.0.0.1:8080)
| Endpoint | Description |
|----------|-------------|
| `GET /1/summary` | Mining statistics |
| `GET /1/threads` | Per-thread hashrates |
| `GET /1/config` | Current configuration |
| `PUT /1/config` | Update configuration |
### Proxy API (default: http://127.0.0.1:8081)
| Endpoint | Description |
|----------|-------------|
| `GET /1/summary` | Proxy statistics |
| `GET /1/workers` | Connected workers |
| `GET /1/config` | Current configuration |
## Performance Tuning
### CPU Mining
```bash
# Enable huge pages (Linux)
sudo sysctl -w vm.nr_hugepages=1280
# Or permanent (add to /etc/sysctl.conf)
echo "vm.nr_hugepages=1280" | sudo tee -a /etc/sysctl.conf
# Enable 1GB pages (better performance)
sudo ./scripts/enable_1gb_pages.sh
```
### GPU Mining
```bash
# AMD GPUs - increase virtual memory
# Add to /etc/security/limits.conf:
# * soft memlock unlimited
# * hard memlock unlimited
# NVIDIA GPUs - optimize power
nvidia-smi -pl 120 # Set power limit
```
## Testing
```bash
# Run miner tests
cd core/build
ctest --output-on-failure
# Run proxy tests
cd proxy/build
./tests/unit_tests
./tests/integration_tests
```
## Directory Structure
```
miner/
├── core/ # Main miner (CPU/GPU)
│ ├── src/
│ │ ├── backend/ # CPU, OpenCL, CUDA backends
│ │ ├── crypto/ # Algorithm implementations
│ │ ├── base/ # Network, I/O, utilities
│ │ └── core/ # Configuration, controller
│ ├── scripts/ # Build and setup scripts
│ └── CMakeLists.txt
├── proxy/ # Stratum proxy
│ ├── src/
│ │ ├── proxy/ # Proxy core (splitters, events)
│ │ └── base/ # Shared base code
│ ├── tests/ # Unit and integration tests
│ └── CMakeLists.txt
├── cuda/ # CUDA plugin
├── config/ # Config generator
├── workers/ # Worker utilities
├── heatmap/ # Temperature visualization
├── deps/ # Dependency build scripts
└── README.md # This file
```
## License
Copyright (c) 2025 Lethean <https://lethean.io>
Licensed under the European Union Public License 1.2 (EUPL-1.2).
See [LICENSE](../LICENSE) for details.
## Related Projects
- [Mining Platform](../) - GUI management platform
- [Lethean](https://lethean.io) - Lethean Network

210
miner/core/README.md
View file

@ -1,38 +1,192 @@
# XMRig
# Miner
[![Github All Releases](https://img.shields.io/github/downloads/xmrig/xmrig/total.svg)](https://github.com/xmrig/xmrig/releases)
[![GitHub release](https://img.shields.io/github/release/xmrig/xmrig/all.svg)](https://github.com/xmrig/xmrig/releases)
[![GitHub Release Date](https://img.shields.io/github/release-date/xmrig/xmrig.svg)](https://github.com/xmrig/xmrig/releases)
[![GitHub license](https://img.shields.io/github/license/xmrig/xmrig.svg)](https://github.com/xmrig/xmrig/blob/master/LICENSE)
[![GitHub stars](https://img.shields.io/github/stars/xmrig/xmrig.svg)](https://github.com/xmrig/xmrig/stargazers)
[![GitHub forks](https://img.shields.io/github/forks/xmrig/xmrig.svg)](https://github.com/xmrig/xmrig/network)
High-performance, cross-platform CPU/GPU cryptocurrency miner supporting RandomX, KawPow, CryptoNight, GhostRider, ETChash, ProgPowZ, and Blake3 algorithms.
XMRig is a high performance, open source, cross platform RandomX, KawPow, CryptoNight and [GhostRider](https://github.com/xmrig/xmrig/tree/master/src/crypto/ghostrider#readme) unified CPU/GPU miner and [RandomX benchmark](https://xmrig.com/benchmark). Official binaries are available for Windows, Linux, macOS and FreeBSD.
## Features
## Mining backends
### Mining Backends
- **CPU** (x86/x64/ARMv7/ARMv8/RISC-V)
- **OpenCL** for AMD GPUs.
- **CUDA** for NVIDIA GPUs via external [CUDA plugin](https://github.com/xmrig/xmrig-cuda).
- **OpenCL** for AMD GPUs
- **CUDA** for NVIDIA GPUs via external [CUDA plugin](../cuda/)
## Download
* **[Binary releases](https://github.com/xmrig/xmrig/releases)**
* **[Build from source](https://xmrig.com/docs/miner/build)**
### Supported Algorithms
## Usage
The preferred way to configure the miner is the [JSON config file](https://xmrig.com/docs/miner/config) as it is more flexible and human friendly. The [command line interface](https://xmrig.com/docs/miner/command-line-options) does not cover all features, such as mining profiles for different algorithms. Important options can be changed during runtime without miner restart by editing the config file or executing [API](https://xmrig.com/docs/miner/api) calls.
| Algorithm | Variants | CPU | GPU |
|-----------|----------|-----|-----|
| RandomX | rx/0, rx/wow, rx/arq, rx/graft, rx/sfx, rx/keva | Yes | Yes |
| CryptoNight | cn/0-2, cn-lite, cn-heavy, cn-pico | Yes | Yes |
| GhostRider | gr | Yes | No |
| Argon2 | chukwa, chukwa2, ninja | Yes | No |
| KawPow | kawpow | No | Yes |
| ETChash | etchash, ethash | No | Yes |
| ProgPowZ | progpowz | No | Yes |
| Blake3 | blake3 | Yes | Yes |
* **[Wizard](https://xmrig.com/wizard)** helps you create initial configuration for the miner.
* **[Workers](http://workers.xmrig.info)** helps manage your miners via HTTP API.
## Quick Start
## Donations
* Default donation 1% (1 minute in 100 minutes) can be increased via option `donate-level` or disabled in source code.
* XMR: `48edfHu7V9Z84YzzMa6fUueoELZ9ZRXq9VetWzYGzKt52XU5xvqgzYnDK9URnRoJMk1j8nLwEVsaSWJ4fhdUyZijBGUicoD`
### Download
## Developers
* **[xmrig](https://github.com/xmrig)**
* **[sech1](https://github.com/SChernykh)**
Pre-built binaries are available from [Releases](https://github.com/letheanVPN/Mining/releases).
## Contacts
* support@xmrig.com
* [reddit](https://www.reddit.com/user/XMRig/)
* [twitter](https://twitter.com/xmrig_dev)
### Usage
```bash
# Basic CPU mining to a pool
./miner -o pool.example.com:3333 -u YOUR_WALLET -p x
# With JSON config (recommended)
./miner -c config.json
# Enable GPU mining
./miner -c config.json --opencl --cuda
# Benchmark mode
./miner --bench=1M
# Show all options
./miner --help
```
### Configuration
The recommended way to configure the miner is via JSON config file:
```json
{
"autosave": true,
"cpu": true,
"opencl": false,
"cuda": false,
"pools": [
{
"url": "stratum+tcp://pool.example.com:3333",
"user": "YOUR_WALLET",
"pass": "x",
"keepalive": true
}
]
}
```
## Building from Source
### Dependencies
**Linux (Ubuntu/Debian):**
```bash
sudo apt-get install git build-essential cmake libuv1-dev libssl-dev libhwloc-dev
```
**Linux (Fedora/RHEL):**
```bash
sudo dnf install git cmake gcc gcc-c++ libuv-devel openssl-devel hwloc-devel
```
**macOS:**
```bash
brew install cmake libuv openssl hwloc
```
**Windows:**
- Visual Studio 2019 or later
- CMake 3.10+
- vcpkg for dependencies
### Build Commands
```bash
mkdir build && cd build
# Standard build
cmake ..
cmake --build . --config Release
# With GPU support
cmake .. -DWITH_OPENCL=ON -DWITH_CUDA=ON
# Static binary
cmake .. -DBUILD_STATIC=ON
# Debug build
cmake .. -DCMAKE_BUILD_TYPE=Debug -DWITH_DEBUG_LOG=ON
# Minimal build (reduce binary size)
cmake .. -DWITH_KAWPOW=OFF -DWITH_GHOSTRIDER=OFF -DWITH_ARGON2=OFF
```
### CMake Options
| Option | Default | Description |
|--------|---------|-------------|
| `WITH_HWLOC` | ON | Hardware topology support |
| `WITH_RANDOMX` | ON | RandomX algorithms |
| `WITH_ARGON2` | ON | Argon2 algorithms |
| `WITH_KAWPOW` | ON | KawPow (GPU only) |
| `WITH_ETCHASH` | ON | ETChash/Ethash (GPU only) |
| `WITH_PROGPOWZ` | ON | ProgPowZ (GPU only) |
| `WITH_BLAKE3DCR` | ON | Blake3 for Decred |
| `WITH_GHOSTRIDER` | ON | GhostRider algorithm |
| `WITH_OPENCL` | ON | AMD GPU support |
| `WITH_CUDA` | ON | NVIDIA GPU support |
| `WITH_HTTP` | ON | HTTP API |
| `WITH_TLS` | ON | SSL/TLS support |
| `WITH_ASM` | ON | Assembly optimizations |
| `WITH_MSR` | ON | MSR mod for CPU tuning |
| `BUILD_STATIC` | OFF | Static binary |
| `BUILD_TESTS` | OFF | Build unit tests |
## HTTP API
When built with `-DWITH_HTTP=ON`, the miner exposes a REST API:
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/1/summary` | GET | Mining statistics |
| `/1/threads` | GET | Per-thread details |
| `/1/config` | GET | Current configuration |
| `/1/config` | PUT | Update configuration |
Example:
```bash
curl http://127.0.0.1:8080/1/summary
```
## Performance Optimization
### Huge Pages (Linux)
```bash
# Temporary
sudo sysctl -w vm.nr_hugepages=1280
# Permanent
echo "vm.nr_hugepages=1280" | sudo tee -a /etc/sysctl.conf
# 1GB pages (best performance)
sudo ./scripts/enable_1gb_pages.sh
```
### MSR Mod (Intel/AMD CPUs)
The miner can automatically apply MSR tweaks for better RandomX performance. Requires root/admin privileges.
```bash
sudo ./miner -c config.json
```
## Testing
```bash
# Build with tests
cmake .. -DBUILD_TESTS=ON
cmake --build .
# Run tests
ctest --output-on-failure
```
## License
Copyright (c) 2025 Lethean <https://lethean.io>
Licensed under the European Union Public License 1.2 (EUPL-1.2).

263
miner/proxy/README.md
View file

@ -1,105 +1,216 @@
# XMRig Proxy
[![Github All Releases](https://img.shields.io/github/downloads/xmrig/xmrig-proxy/total.svg)](https://github.com/xmrig/xmrig-proxy/releases)
[![GitHub release](https://img.shields.io/github/release/xmrig/xmrig-proxy/all.svg)](https://github.com/xmrig/xmrig-proxy/releases)
[![GitHub Release Date](https://img.shields.io/github/release-date-pre/xmrig/xmrig-proxy.svg)](https://github.com/xmrig/xmrig-proxy/releases)
[![GitHub license](https://img.shields.io/github/license/xmrig/xmrig-proxy.svg)](https://github.com/xmrig/xmrig-proxy/blob/master/LICENSE)
[![GitHub stars](https://img.shields.io/github/stars/xmrig/xmrig-proxy.svg)](https://github.com/xmrig/xmrig-proxy/stargazers)
[![GitHub forks](https://img.shields.io/github/forks/xmrig/xmrig-proxy.svg)](https://github.com/xmrig/xmrig-proxy/network)
# Miner Proxy
This is an extremely high-performance proxy for the CryptoNote stratum protocol (including Monero and others).
It can efficiently manage over 100K connections on an inexpensive, low-memory virtual machine (with just 1024 MB of RAM).
The proxy significantly reduces the number of connections to the pool, decreasing 100,000 workers down to just 391 on the pool side.
The codebase is shared with the [XMRig](https://github.com/xmrig/xmrig) miner.
High-performance stratum protocol proxy for cryptocurrency mining farms. Efficiently manages 100K+ miner connections while maintaining minimal pool-side connections through nonce splitting.
## Compatibility
Compatible with any pool and any miner that supports NiceHash.
## Features
## Why?
This proxy is designed to handle donation traffic from XMRig. No other solution works well with high connection and disconnection rates.
- Handle 100K+ concurrent miner connections
- Reduce pool connections (100,000 miners → ~400 pool connections)
- NiceHash compatibility mode
- TLS/SSL support for secure connections
- HTTP API for monitoring
- Low memory footprint (~1GB RAM for 100K connections)
## Download
* Binary releases: https://github.com/xmrig/xmrig-proxy/releases
* Git tree: https://github.com/xmrig/xmrig-proxy.git
* Clone with `git clone https://github.com/xmrig/xmrig-proxy.git` :hammer: [Build instructions](https://xmrig.com/docs/proxy).
## Quick Start
## Usage
:boom: If you are using Linux and need to manage over **1000 connections**, you must [increase the limits on open files](https://github.com/xmrig/xmrig-proxy/wiki/Ubuntu-setup).
### Download
Pre-built binaries are available from [Releases](https://github.com/letheanVPN/Mining/releases).
### Usage
```bash
# Basic usage
./miner-proxy -o pool.example.com:3333 -u YOUR_WALLET -b 0.0.0.0:3333
# With config file (recommended)
./miner-proxy -c config.json
# Test configuration
./miner-proxy --dry-run -c config.json
# Show all options
./miner-proxy --help
```
### Command Line Options
### Options
```
Network:
-o, --url=URL URL of mining server
-a, --algo=ALGO mining algorithm https://xmrig.com/docs/algorithms
--coin=COIN specify coin instead of algorithm
-a, --algo=ALGO mining algorithm
-u, --user=USERNAME username for mining server
-p, --pass=PASSWORD password for mining server
-O, --userpass=U:P username:password pair for mining server
-x, --proxy=HOST:PORT connect through a SOCKS5 proxy
-k, --keepalive send keepalived packet for prevent timeout (needs pool support)
--rig-id=ID rig identifier for pool-side statistics (needs pool support)
--tls enable SSL/TLS support (needs pool support)
--tls-fingerprint=HEX pool TLS certificate fingerprint for strict certificate pinning
--dns-ipv6 prefer IPv6 records from DNS responses
--dns-ttl=N N seconds (default: 30) TTL for internal DNS cache
--daemon use daemon RPC instead of pool for solo mining
--daemon-zmq-port daemon's zmq-pub port number (only use it if daemon has it enabled)
--daemon-poll-interval=N daemon poll interval in milliseconds (default: 1000)
--daemon-job-timeout=N daemon job timeout in milliseconds (default: 15000)
--self-select=URL self-select block templates from URL
--submit-to-origin also submit solution back to self-select URL
-r, --retries=N number of times to retry before switch to backup server (default: 5)
-R, --retry-pause=N time to pause between retries (default: 5)
--user-agent set custom user-agent string for pool
--donate-level=N donate level, default 0%%
-k, --keepalive send keepalive packets
--tls enable SSL/TLS support
Options:
-b, --bind=ADDR bind to specified address, example "0.0.0.0:3333"
-m, --mode=MODE proxy mode, nicehash (default) or simple
--custom-diff=N override pool diff
--custom-diff-stats calculate stats using custom diff shares instead of pool shares
--reuse-timeout=N timeout in seconds for reuse pool connections in simple mode
--no-workers disable per worker statistics
--access-password=P set password to restrict connections to the proxy
--no-algo-ext disable "algo" protocol extension
Proxy:
-b, --bind=ADDR bind to specified address (e.g., "0.0.0.0:3333")
-m, --mode=MODE proxy mode: nicehash (default) or simple
--custom-diff=N override pool difficulty
--access-password=P password to restrict proxy access
API:
--api-worker-id=ID custom worker-id for API
--api-id=ID custom instance ID for API
--http-host=HOST bind host for HTTP API (default: 127.0.0.1)
--http-port=N bind port for HTTP API
--http-access-token=T access token for HTTP API
--http-no-restricted enable full remote access to HTTP API (only if access token set)
TLS:
--tls-bind=ADDR bind to specified address with enabled TLS
--tls-gen=HOSTNAME generate TLS certificate for specific hostname
--tls-cert=FILE load TLS certificate chain from a file in the PEM format
--tls-cert-key=FILE load TLS certificate private key from a file in the PEM format
--tls-dhparam=FILE load DH parameters for DHE ciphers from a file in the PEM format
--tls-protocols=N enable specified TLS protocols, example: "TLSv1 TLSv1.1 TLSv1.2 TLSv1.3"
--tls-ciphers=S set list of available ciphers (TLSv1.2 and below)
--tls-ciphersuites=S set list of available TLSv1.3 ciphersuites
--tls-bind=ADDR bind with TLS enabled
--tls-cert=FILE TLS certificate file (PEM)
--tls-cert-key=FILE TLS private key file (PEM)
Logging:
-l, --log-file=FILE log all output to a file
-A --access-log-file=FILE log all workers access to a file
--no-color disable colored output
-l, --log-file=FILE log all output to file
-A, --access-log-file=FILE log worker access to file
--verbose verbose output
Misc:
-c, --config=FILE load a JSON-format configuration file
-B, --background run the proxy in the background
-V, --version output version information and exit
-h, --help display this help and exit
--dry-run test configuration and exit
-c, --config=FILE load JSON configuration file
-B, --background run in background
-V, --version show version
-h, --help show help
```
## Donations
## Configuration
The default donation fee is 2%, which can be reduced to 1% or completely disabled using the `donate-level` option. This fee applies only when you utilize more than 256 miners.
### JSON Config (config.json)
* XMR: `48edfHu7V9Z84YzzMa6fUueoELZ9ZRXq9VetWzYGzKt52XU5xvqgzYnDK9URnRoJMk1j8nLwEVsaSWJ4fhdUyZijBGUicoD`
```json
{
"mode": "nicehash",
"pools": [
{
"url": "stratum+tcp://pool.example.com:3333",
"user": "YOUR_WALLET",
"pass": "x",
"keepalive": true
}
],
"bind": [
{
"host": "0.0.0.0",
"port": 3333
},
{
"host": "0.0.0.0",
"port": 3334,
"tls": true
}
],
"http": {
"enabled": true,
"host": "127.0.0.1",
"port": 8081,
"access-token": "your-secret-token"
},
"tls": {
"cert": "/path/to/cert.pem",
"cert-key": "/path/to/key.pem"
},
"access-password": null,
"workers": true,
"verbose": false
}
```
## Contacts
* support@xmrig.com
* [X](https://x.com/xmrig_dev)
### Proxy Modes
**NiceHash Mode** (default): Full nonce splitting for maximum efficiency
- Best for large farms with many workers
- Each worker gets unique nonce space
- Maximum reduction in pool connections
**Simple Mode**: Direct passthrough with shared connections
- Simpler setup
- Workers share pool connections
- Good for smaller setups
## Building from Source
### Dependencies
**Linux (Ubuntu/Debian):**
```bash
sudo apt-get install build-essential cmake libuv1-dev libssl-dev
```
**macOS:**
```bash
brew install cmake libuv openssl
```
### Build
```bash
mkdir build && cd build
cmake ..
cmake --build . --config Release
# With debug logging
cmake .. -DWITH_DEBUG_LOG=ON
```
### CMake Options
| Option | Default | Description |
|--------|---------|-------------|
| `WITH_TLS` | ON | SSL/TLS support |
| `WITH_HTTP` | ON | HTTP API |
| `WITH_DEBUG_LOG` | OFF | Debug logging |
| `BUILD_TESTS` | ON | Build unit tests |
## HTTP API
| Endpoint | Description |
|----------|-------------|
| `GET /1/summary` | Proxy statistics |
| `GET /1/workers` | Connected workers list |
| `GET /1/config` | Current configuration |
Example:
```bash
curl http://127.0.0.1:8081/1/summary
```
## High Connection Setup (Linux)
For 1000+ connections, increase file descriptor limits:
```bash
# /etc/security/limits.conf
* soft nofile 1000000
* hard nofile 1000000
# /etc/sysctl.conf
fs.file-max = 1000000
net.core.somaxconn = 65535
net.ipv4.tcp_max_syn_backlog = 65535
```
Then apply:
```bash
sudo sysctl -p
```
## Testing
```bash
cd build
# Run all tests
ctest --output-on-failure
# Run specific test suites
./tests/unit_tests
./tests/integration_tests
# Run with verbose output
./tests/unit_tests --gtest_verbose
```
## License
Copyright (c) 2025 Lethean <https://lethean.io>
Licensed under the European Union Public License 1.2 (EUPL-1.2).