Nikolaus HegerandClaude Fable 5
8aa81ec853
Exploring a fully native Metal port of the mining kernel showed it runs ~16% faster than the wgpu path at equal batch size. Decomposing that gap: ~9% is naga's injected runtime bounds checks and forced loop bounding, ~1.5% is mulhi()-based multiplication (inexpressible in WGSL), <1% is the constant address space; the rest is binding/codegen residue. The dominant term is recoverable inside wgpu on every backend: the engine now builds its pipelines with create_shader_module_trusted + ShaderRuntimeChecks::unchecked(). This is sound for our shaders: sources are compiled into the binary, every buffer access is a constant-bounded loop index into fixed-size bindings the engine allocates itself, all loops have static bounds, and both variants remain covered by the dual-shader component suite and the CPU parity example. Apple M4: 11.39 -> 12.34 MH/s at the default 1M batch (+8.3%), 11.74 -> 12.73 MH/s at 8M (+8.4%). Cumulative vs main: 4.4x. New examples/trusted_hashrate.rs measures checked vs trusted on the same shader and CPU-verifies results. 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