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 --features gpu --release

The binary will be available at target/release/quantus-miner.

Running

# CPU-only mining (default: auto-detected CPU cores)
./target/release/quantus-miner --cpu-workers 4

# GPU-only mining (requires --features gpu build)
./target/release/quantus-miner --gpu-workers 1

# Hybrid CPU+GPU mining
./target/release/quantus-miner --cpu-workers 4 --gpu-workers 1

# Custom port and metrics
./target/release/quantus-miner --cpu-workers 2 --port 8000 --metrics-port 9900

Configuration

Argument	Environment Variable	Description	Default
--cpu-workers <N>	MINER_CPU_WORKERS	Number of CPU worker threads	Auto-detect
--gpu-workers <N>	MINER_GPU_WORKERS	Number of GPU worker threads	0
--port <PORT>	MINER_PORT	HTTP API port	9833
--metrics-port <PORT>	MINER_METRICS_PORT	Prometheus metrics port	Disabled

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 --features gpu --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

# CPU mining with 8 workers
./target/release/quantus-miner --cpu-workers 8

# Pure GPU mining
./target/release/quantus-miner --gpu-workers 1

# Hybrid mining: 4 CPU + 1 GPU workers
./target/release/quantus-miner --cpu-workers 4 --gpu-workers 1

# With verbose logging
RUST_LOG=debug ./target/release/quantus-miner --cpu-workers 2 --gpu-workers 1

# Production setup with metrics
./target/release/quantus-miner \
  --cpu-workers 6 \
  --gpu-workers 1 \
  --port 9833 \
  --metrics-port 9900

API Endpoints

• POST /mine: Submit mining job
• GET /result/{job_id}: Get job status/result
• POST /cancel/{job_id}: Cancel job

Full API specification: api/openapi.yaml

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 --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-workers 1 --duration 30

# Benchmark hybrid performance
./target/release/quantus-miner benchmark --cpu-workers 4 --gpu-workers 1 --duration 30