hi, i'm rob

giteablackbeard/miner

Rust 77.9%WGSL 13.0%Cuda 7.0%Shell 2.0%Go Template 0.1%

External Miner Service for Quantus Network

High-performance external mining service for Quantus Network with support for CPU, GPU, and hybrid CPU+GPU mining.

This fork

Like the official miner, but fast: a native CUDA engine for NVIDIA cards, kept bit-exact with the reference hash and measured against every other miner we can get hold of. No dev fee, no licence server, no telemetry, solo or pool. Apache-2.0, like upstream.

Measured hashrate, three interleaved 30-second rounds per card at the enforced power cap, memory clock locked at 810 MHz, CUDA 13.0 driver 580:

cardpower capthis forkupstream --cuda-gpuquantusminer.com qpow-cuda 1.0.7quanpool-miner 6.2.4 (5% fee)
RTX 5090400 W1104 MH/s94411711234 (1172 after fee)
RTX 4090250 W727 MH/s (loop kernel)
RTX 3060130 W141 MH/s

The 5090 column was measured on the same card in the same session (2026-09-13); the closed pool binaries were run in benchmark mode only. How the pool kernels get their remaining edge, and what has been tried, is written up in issue #27.

Since v4.0.2-lair.2 the binary carries two kernels. The default (unrolled) is fastest on the RTX 5090 and 3060; RTX 40-series cards measure 1.7% better on the rolled-loop one, selected with MINER_CUDA_KERNEL=loop in the environment (it reports as kernel cuda-loop on the metrics). Both are bit-exact with the CPU reference; try each with quantus-bench on your card.

Binaries are on the releases page: one Linux x86_64 quantus-miner carrying cubins for sm_86 (RTX 30), sm_89 (RTX 40) and sm_120 (RTX 50) plus PTX for anything newer, built on Fedora 43 (glibc 2.42 or newer), and quantus-bench, the measurement harness. Nothing is compiled at run time; the driver needs CUDA 13.0 support (580.x).

Reproduce the numbers. quantus-bench pins the power limit it expects, warms up, reports the median of timed windows with their spread, and checks GPU hashes against the CPU reference for random jobs:

# hashrate: median of 5 x 30 s windows, one worker thread per card
./quantus-bench --duration-secs 30 --runs 5 --workers 1 --expect-power-limit 400

# parity: 2000 random jobs, every found hash recomputed on the CPU
./quantus-bench --duration-secs 3 --runs 1 --parity-jobs 2000

Compare builds with interleaved rounds (A, B, A, B, ...) rather than one block of runs each: on a power-capped card, clock drift between blocks looks like a 0.5% code change.

Solo mining against your own node is the serve command below with the node's auth token and certificate fingerprint; nothing else is needed.

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

The node requires a shared auth token and TLS cert pin. Both live under the node's chain config dir (<base-path>/chains/<chain>/):

  • miner-auth-token — shared secret (not logged by the node; read this file)
  • miner-tls-cert-sha256 — SHA-256 of the miner TLS cert (also printed in node logs)
# Preferred: mount/read the node's chain config files
./target/release/quantus-miner serve \
  --node-addr 127.0.0.1:9833 \
  --auth-token-file /path/to/miner-auth-token \
  --tls-cert-sha256-file /path/to/miner-tls-cert-sha256 \
  --cpu-workers 4

# Or pass values directly (token from miner-auth-token; fingerprint also in node logs)
./target/release/quantus-miner serve \
  --node-addr 127.0.0.1:9833 \
  --auth-token <TOKEN> \
  --tls-cert-sha256 <FINGERPRINT> \
  --gpu-devices 1

# Hybrid CPU+GPU mining
./target/release/quantus-miner serve \
  --node-addr 127.0.0.1:9833 \
  --auth-token-file /path/to/miner-auth-token \
  --tls-cert-sha256-file /path/to/miner-tls-cert-sha256 \
  --cpu-workers 4 \
  --gpu-devices 1

Configuration

ArgumentEnvironment VariableDescriptionDefault
--node-addr <ADDR>MINER_NODE_ADDRNode address to connect to127.0.0.1:9833
--auth-token <TOKEN>MINER_AUTH_TOKENShared secret from the node's miner-auth-token file (not logged)required
--auth-token-file <PATH>MINER_AUTH_TOKEN_FILERead the shared secret from a file (preferred)—
--tls-cert-sha256 <HEX>MINER_TLS_CERT_SHA256SHA-256 of the node's miner TLS cert (miner-tls-cert-sha256 / node logs)required
--tls-cert-sha256-file <PATH>MINER_TLS_CERT_SHA256_FILERead the TLS cert fingerprint from a file—
--cpu-workers <N>MINER_CPU_WORKERSNumber of CPU worker threadsAuto-detect
--gpu-devices <N>MINER_GPU_DEVICESNumber of GPU devicesAuto-detect
--gpu-batch-size <N>MINER_GPU_BATCH_SIZEGPU batch size in nonces1000000
--cpu-batch-size <N>MINER_CPU_BATCH_SIZECPU batch size in hashes10000
--gpu-throttle-ms <MS>MINER_GPU_THROTTLE_MSSleep duration (ms) between GPU batches0
--metrics-port <PORT>MINER_METRICS_PORTPrometheus metrics port9900

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) or radeontop (AMD)
  • Windows: Task Manager GPU tab

Examples

All serve examples need the auth token and TLS pin (files or inline values).

# CPU mining with 8 workers
./target/release/quantus-miner serve \
  --auth-token-file /path/to/miner-auth-token \
  --tls-cert-sha256-file /path/to/miner-tls-cert-sha256 \
  --cpu-workers 8

# Pure GPU mining
./target/release/quantus-miner serve \
  --auth-token-file /path/to/miner-auth-token \
  --tls-cert-sha256-file /path/to/miner-tls-cert-sha256 \
  --gpu-devices 1

# GPU mining with throttle (reduce GPU utilization)
./target/release/quantus-miner serve \
  --auth-token-file /path/to/miner-auth-token \
  --tls-cert-sha256-file /path/to/miner-tls-cert-sha256 \
  --gpu-devices 1 --gpu-throttle-ms 50

# Hybrid mining: 4 CPU + 1 GPU workers
./target/release/quantus-miner serve \
  --auth-token-file /path/to/miner-auth-token \
  --tls-cert-sha256-file /path/to/miner-tls-cert-sha256 \
  --cpu-workers 4 --gpu-devices 1

# With verbose logging
RUST_LOG=debug ./target/release/quantus-miner serve \
  --auth-token-file /path/to/miner-auth-token \
  --tls-cert-sha256-file /path/to/miner-tls-cert-sha256 \
  --cpu-workers 2 --gpu-devices 1

# Production setup with metrics
./target/release/quantus-miner serve \
  --node-addr 127.0.0.1:9833 \
  --auth-token-file /path/to/miner-auth-token \
  --tls-cert-sha256-file /path/to/miner-tls-cert-sha256 \
  --cpu-workers 6 \
  --gpu-devices 1 \
  --metrics-port 9900

Protocol

The miner uses a QUIC-based protocol for communication with the node:

  • Transport: QUIC with TLS 1.3 (self-signed certificate, pinned by SHA-256)
  • Auth: Ready { token } must match the node's miner-auth-token
  • ALPN: quantus-miner/2
  • Port: 9833 (default)
  • Messages: Ready (miner→node), NewJob (node→miner), JobResult (miner→node)

For full protocol specification, see the node's MINING.md.

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

33 activities