Nikolaus HegerandClaude Fable 5
d55b970ab6
Three stacked optimizations, each verified bit-exact against the CPU reference (qp-poseidon-core) by the dual-shader component suite and a new GPU/CPU parity example: - mining_u64.wgsl: native 64-bit Goldilocks arithmetic with plonky2-style lazy reduction, used automatically when the adapter supports SHADER_INT64 (all Apple Silicon, NVIDIA, modern AMD). mining.wgsl remains the 32-bit fallback. (+50%) - Midstate precompute: the first two of five sponge permutations absorb the header and high nonce half, both constant per batch; they are now computed once on the CPU (pow_core::mining_midstate) and resumed on the GPU. Batches are clamped so nonces never carry past 2^256. (+77%) - Lazy second squeeze: the first squeeze yields the most significant 256 bits of the hash, which decide hash-vs-target unless exactly equal to the target's high half, so the common reject path skips the final permutation. (+56%) Apple M4 throughput: 2.81 -> 11.4 MH/s at the default 1M batch (criterion large_range_1m/gpu: 355.8ms -> 86.3ms, -75.7%). Also: - Fix criterion GPU bench crash: thread-local worker resources are now tagged with an engine id so multiple GpuEngines per process never mix devices. - Fix stale end-to-end test harness (6-binding layout) and run the full component suite against both shader variants. - New examples: hashrate, gpu_cpu_parity (25 jobs incl. 2^256-boundary crossing), gpu_features. - Add Apple M5 family GPU tiers. 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