Nikolaus HegerandClaude Fable 5
58615ed3fa
Evaluated all ideas from #80 against the native-u64 kernel. Its three main wins (lazy field arithmetic, precomputed sponge state, conditional second squeeze) were already present in stronger form; two micro-opts carried over and measured positive at large batches (+1.3% at 16M, noise-level at the 1M default): - Hoist midstate/target/start-nonce storage reads out of the nonce loop. - Produce byte-swapped hash words on demand during the target compare, so the reject path skips building the swapped hash entirely. Forcing nonces_per_thread=2 was also tested and regressed; one thread per nonce stays. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
External Miner Service for Quantus Network
High-performance external mining service for Quantus Network with support for CPU, GPU, and hybrid CPU+GPU mining.
Building
# CPU-only build (default)
cargo build -p miner-cli --release
# With GPU support (recommended)
cargo build -p miner-cli --release
The binary will be available at target/release/quantus-miner.
Running
# CPU-only mining (default: auto-detected CPU cores)
./target/release/quantus-miner serve --cpu-workers 4
# GPU-only mining
./target/release/quantus-miner serve --gpu-devices 1
# Hybrid CPU+GPU mining
./target/release/quantus-miner serve --cpu-workers 4 --gpu-devices 1
# Custom port and metrics
./target/release/quantus-miner serve --cpu-workers 2 --port 8000 --metrics-port 9900
Configuration
| Argument | Environment Variable | Description | Default |
|---|---|---|---|
--node-addr <ADDR> |
MINER_NODE_ADDR |
Node address to connect to | 127.0.0.1:9833 |
--cpu-workers <N> |
MINER_CPU_WORKERS |
Number of CPU worker threads | Auto-detect |
--gpu-devices <N> |
MINER_GPU_DEVICES |
Number of GPU devices | Auto-detect |
--gpu-batch-size <N> |
MINER_GPU_BATCH_SIZE |
GPU batch size in nonces | 1000000 |
--cpu-batch-size <N> |
MINER_CPU_BATCH_SIZE |
CPU batch size in hashes | 10000 |
--gpu-throttle-ms <MS> |
MINER_GPU_THROTTLE_MS |
Sleep duration (ms) between GPU batches | 0 |
--metrics-port <PORT> |
MINER_METRICS_PORT |
Prometheus metrics port | 9900 |
GPU Mining
GPU support uses WGPU for cross-platform acceleration:
- macOS: Metal backend (Apple Silicon & Intel)
- Linux: Vulkan/OpenGL backends
- Windows: DirectX 12/Vulkan backends
Setup
Build with GPU support:
cargo build -p miner-cli --release
Platform requirements:
- macOS: Works out-of-the-box
- Linux: Install GPU drivers (
nvidia-driver,mesa-vulkan-drivers) - Windows: Ensure recent graphics drivers are installed
Performance Monitoring
- macOS:
sudo powermetrics --samplers gpu_power -i 1000 - Linux:
nvidia-smi(NVIDIA) orradeontop(AMD) - Windows: Task Manager GPU tab
Examples
# CPU mining with 8 workers
./target/release/quantus-miner serve --cpu-workers 8
# Pure GPU mining
./target/release/quantus-miner serve --gpu-devices 1
# GPU mining with throttle (reduce GPU utilization)
./target/release/quantus-miner serve --gpu-devices 1 --gpu-throttle-ms 50
# Hybrid mining: 4 CPU + 1 GPU workers
./target/release/quantus-miner serve --cpu-workers 4 --gpu-devices 1
# With verbose logging
RUST_LOG=debug ./target/release/quantus-miner serve --cpu-workers 2 --gpu-devices 1
# Production setup with metrics
./target/release/quantus-miner serve \
--cpu-workers 6 \
--gpu-devices 1 \
--port 9833 \
--metrics-port 9900
Protocol
The miner uses a QUIC-based protocol for communication with the node:
- Transport: QUIC with TLS 1.3 (self-signed certificates)
- Port: 9833 (default)
- Messages:
NewJob(from node) andJobResult(from miner)
For full protocol specification, see EXTERNAL_MINER_PROTOCOL.md.
Docker
# Quick start
docker pull ghcr.io/quantus-network/quantus-miner:latest
docker run -d -p 9833:9833 -p 9900:9900 \
ghcr.io/quantus-network/quantus-miner:latest \
--cpu-workers 4 --metrics-port 9900
# Build from source
docker build -t quantus-miner .
docker run -d -p 9833:9833 quantus-miner serve --cpu-workers 4
Benchmarking
# Benchmark CPU performance
./target/release/quantus-miner benchmark --cpu-workers 8 --duration 30
# Benchmark GPU performance
./target/release/quantus-miner benchmark --gpu-devices 1 --duration 30
# Benchmark hybrid performance
./target/release/quantus-miner benchmark --cpu-workers 4 --gpu-devices 1 --duration 30