d99be29a64
On Windows wgpu enumerates each physical GPU once per backend (Vulkan +
DX12) plus a CPU-emulated fallback ("Microsoft Basic Render Driver").
Building a mining context for every entry causes VRAM contention and
OOMs the process during benchmark/serve startup (#61).
Instead of deduplicating by (vendor, device) PCI IDs - which would
collapse rigs with multiple identical cards into a single context - drop
CPU-emulated adapters and keep all adapters from the highest-ranked
backend present (Vulkan/Metal, then DX12). Within a single backend each
physical GPU appears exactly once, so identical cards are preserved by
construction and no physical-ID matching is needed.
Selected adapters are ordered discrete-first so `--gpu-devices 1` picks
the discrete card on hybrid laptops. Skipped adapters are logged at info
level; if nothing usable remains, init fails with an explicit error.
Selection logic is a pure index-based function unit-tested against the
exact enumeration reported in #61, identical multi-GPU rigs, DX12-only
machines, and software-only environments.
Co-authored-by: illuzen <illuzen@users.noreply.github.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