miner/README.md

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

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

Argument	Environment Variable	Description	Default
--node-addr <ADDR>	MINER_NODE_ADDR	Node address to connect to	127.0.0.1:9833
--auth-token <TOKEN>	MINER_AUTH_TOKEN	Shared secret from the node's miner-auth-token file (not logged)	required
--auth-token-file <PATH>	MINER_AUTH_TOKEN_FILE	Read the shared secret from a file (preferred)	—
--tls-cert-sha256 <HEX>	MINER_TLS_CERT_SHA256	SHA-256 of the node's miner TLS cert (miner-tls-cert-sha256 / node logs)	required
--tls-cert-sha256-file <PATH>	MINER_TLS_CERT_SHA256_FILE	Read the TLS cert fingerprint from a file	—
--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) 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