---
# System prepended metadata

title: Quantus External Miner — Concise Checklist

---

# Quantus External Miner — Concise Checklist

This checklist summarizes day-to-day engineering tasks for CPU and GPU paths, build flags, validation, metrics, and rollout steps.

Last updated: see roadmap.md for context and rationale.

---

## 0) Prerequisites

- Rust toolchain: stable (see rust-toolchain file)
- Workspace build sanity:
  - CPU only: `cargo build -p miner-cli`
  - With CUDA support: `cargo build -p miner-cli --features cuda`
- Metrics available: run with `--metrics-port <port>`

---

## 1) CPU Engines

### 1.1 Build & Run
- Baseline:
  - Build: `cargo build -p miner-cli`
  - Run: `quantus-miner --engine cpu-baseline --metrics-port 9919`
- Fast:
  - Run: `quantus-miner --engine cpu-fast --metrics-port 9919`
- Montgomery (auto-detects backend):
  - Run: `quantus-miner --engine cpu-montgomery --metrics-port 9919`
  - Optional chunking knob: `--progress-chunk-ms 5000`
- Backend override (for A/B):
  - `MINER_MONT_BACKEND=portable|bmi2|bmi2-adx|umulh`

### 1.2 Verification (local)
- Parity tests:
  - `cargo test -p engine-montgomery -q`
- End-to-end sanity:
  - Confirm distances and winners match `cpu-fast` on small ranges (unit tests cover this).

### 1.3 Observability
- Ensure backend metric is present:
  - `miner_engine_backend{engine="cpu-montgomery", backend="<name>"} = 1`
- Keep chunking equal across engines when comparing hashrates for apples-to-apples.

---

## 2) GPU — CUDA (Feature-Gated)

### 2.1 Build & Select
- Build CUDA-enabled binary:
  - `cargo build -p miner-cli --features cuda`
- Select engine (error and exit if CUDA unavailable):
  - `quantus-miner --engine gpu-cuda --metrics-port 9919`

### 2.2 Staged Implementation
- G1 — Bring-up:
  - [ ] Device: 8×64 Montgomery CIOS with 64-bit products + __umul64hi.
  - [ ] Host: SHA3-512 for a small nonce window (copy back y in normal domain).
  - [ ] Parity: CPU vs GPU y values → identical SHA3 → identical distances.
- G2 — Device SHA3 + Early-exit:
  - [ ] Device: Keccak-f[1600] (24 rounds) optimized for 64-byte input.
  - [ ] Device: threshold compare and early-exit via atomic flag; ordered candidate write.
  - [ ] Host: poll flag; return EngineStatus; maintain hash_count semantics.
- G3 — Tuning:
  - [ ] Tune K nonces/thread, block sizes, occupancy.
  - [ ] Unroll Montgomery limbs and Keccak rounds; minimize spills.
  - [ ] Move constants (m, n, n0_inv, R^2, target, threshold) to constant memory.
  - [ ] (Optional) Multi-GPU orchestration.

---

## 3) Testing & Validation

### 3.1 CPU Property Tests
- Portable Montgomery vs pow-core step_mul (multiple steps).
- Backend parity:
  - x86_64: BMI2 & BMI2+ADX vs portable.
  - aarch64: UMULH vs portable.
- End-to-end small ranges: `cpu-montgomery` vs `cpu-fast`.
- Command: `cargo test -q`

### 3.2 GPU Parity (as kernels land)
- G1: Device Montgomery → host SHA3 parity over small windows.
- G2: Full device parity vs `cpu-fast` for small ranges.
- Optional “shadow mode”: sample small fraction of work to cross-check on CPU.

---

## 4) Metrics & Dashboards

- Core series:
  - `miner_hash_rate` (global gauge)
  - `miner_job_hash_rate{engine,job_id}`, `miner_thread_hash_rate{engine,job_id,thread_id}`
  - `miner_job_hashes_total{engine,job_id}`, `miner_thread_hashes_total{engine,job_id,thread_id}`
  - `miner_jobs_total{status}`, `miner_effective_cpus`
- Backend info:
  - `miner_engine_backend{engine="cpu-montgomery", backend="<name>"}` = 1
- Best practice:
  - When comparing engines/backends, keep `--progress-chunk-ms` equal (e.g., 5000).

---

## 5) A/B Procedure (Apples-to-Apples)

- Pick a node; run back-to-back 5–10 min windows with identical settings:
  - Engine A (e.g., `cpu-fast`)
  - Engine B (e.g., `cpu-montgomery`)
  - Optionally force backend: `MINER_MONT_BACKEND=bmi2-adx` (on ADX-capable x86_64)
- Keep:
  - Same workers (`--workers`)
  - Same chunking (`--progress-chunk-ms`)
  - Same job mix/range sizes
- Compare:
  - Overall hashrate
  - Per-job rates
  - Stability and latency to early-cancel

---

## 6) Build & Feature Matrix

- Default (CPU-only): `cargo build -p miner-cli`
- With CUDA: `cargo build -p miner-cli --features cuda`
- Service features (implicit via workspace):
  - `metrics` on by default; `montgomery` on by default
  - `cuda` must be enabled explicitly to select GPU engine

---

## 7) Release Gates

- CPU:
  - [ ] Unit/property tests pass on x86_64 and aarch64.
  - [ ] Backend parity validated (ADX and UMULH on capable hosts).
  - [ ] Dashboard review: uplift vs `cpu-fast`, stable metrics.
- GPU:
  - [ ] G1 parity achieved (device Montgomery → host SHA3).
  - [ ] G2 full device parity and stable early-exit.
  - [ ] Tuning pass with documented settings and measured wins.
- Docs:
  - [ ] roadmap.md updated
  - [ ] engine-montgomery/readme.md updated
  - [ ] GPU README (once kernels land)

---

## 8) Troubleshooting

- `gpu-cuda` selection errors:
  - Built without CUDA feature → rebuild with `--features cuda`.
  - CUDA init failed → check driver/device; the service will fail fast by design.
- Low CPU hashrate:
  - Increase chunking: `--progress-chunk-ms 5000`
  - Verify backend selection in logs/metrics (`bmi2-adx`, `bmi2`, `umulh`)
- Metrics missing:
  - Ensure `--metrics-port` specified.
  - Confirm `miner_engine_backend` appears for `cpu-montgomery`.

---

## 9) Quick Commands

- Build (CPU): `cargo build -p miner-cli`
- Build (CUDA): `cargo build -p miner-cli --features cuda`
- Run (Montgomery): `quantus-miner --engine cpu-montgomery --metrics-port 9919 --progress-chunk-ms 5000`
- Force backend:
  - `MINER_MONT_BACKEND=bmi2-adx quantus-miner --engine cpu-montgomery ...`
- Run (CUDA, fail fast if unavailable): `quantus-miner --engine gpu-cuda --metrics-port 9919`
- Tests: `cargo test -q`

---