3ba996dcdfe8227a14f0267f274429d93ad4c4ca
ci / fmt (pull_request) Successful in 20s
bench / build (pull_request) Successful in 1m2s
ci / clippy (pull_request) Successful in 1m37s
ci / doc (pull_request) Successful in 1m58s
bench / measure (pull_request) Successful in 2m55s
ci / test (pull_request) Successful in 6m50s
quantus/miner#9. Additive metrics in a lair-owned module of the metrics
crate; origin's metrics are untouched so the fleet dashboard keeps working
across origin merges.
Identity:
- miner_build_info{version, commit}: the join key for everything below.
- miner_config_info{engine, gpu_batch_size, gpu_devices, cpu_workers,
gpu_throttle_ms}: two deploys of one commit with different flags are
different experiments.
Per device (handles resolved once at engine init, no label lookups in the
batch path):
- miner_device_hashes_total{device, kernel}, miner_device_solutions_total,
miner_device_lost_total.
- miner_gpu_batch_seconds{device, kernel, phase=gpu|host}: submit-to-mapped
on the device versus everything else in the batch. This is the bubble
#4, #5 and #6 attack, measured directly.
Jobs and results:
- miner_jobs_received_total, miner_stale_hashes_total{engine},
miner_job_pickup_seconds{engine} (issued to picked up; the cancel latency
of a busy worker), miner_results_submitted_total,
miner_results_send_failed_total, miner_seal_latency_seconds (found to
sent), miner_job_idle_seconds_total (sent to next job, node-attributable).
Connection: miner_connects_total, miner_connect_failures_total,
miner_disconnects_total, miner_connected, miner_disconnected_seconds_total.
Origin-owned code touched, each block marked lair: engine-gpu gains a
metrics dependency, a DeviceMetrics handle on GpuContext and timing points
in run_single_batch; miner-service gains found_at on WorkerResult,
created_at on MiningJob and the recording calls; miner-cli sets build info
at startup. Deploy validate now asserts miner_build_info carries the
deployed commit.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CBgs2nSi4H2mdh8kD8vMX5
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) orradeontop(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'sminer-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
Releases
2
quantus-miner v4.0.2-lair.2
Latest
Languages
Rust
77.9%
WGSL
13%
Cuda
7%
Shell
2%