quip-miner
Experimental software. Use at your own risk. No production warranties.
The v0.3 mining stack for the
quip-validator Substrate
chain. A coordinator follows the chain head and stages Ising problems for the
miner subprocesses; when a solution clears the difficulty gate, the coordinator
submits a QuantumPow.submit_proof extrinsic. The miners run simulated
annealing and Gibbs sampling on CPU, CUDA, and Metal, and quantum annealing on
D-Wave hardware.
This is a Rust workspace. The coordinator and the chain integration are Rust. The solver contract — the wire protocol, the consensus primitives, and the shared solver harness — lives in quip-solver-core and is consumed from crates.io. The miner binaries ship from their own repositories.
Repository layout
crates/— the Cargo workspace:quip-coordinator(the binary),quip-miner-exec(a miner that shells out to an external solver), andquip-mock-miner(the miner test double).docker/— image builds and the example coordinator config.
The miner binaries live in quip.network/quip-miner-{cpu,cuda,metal,dwave}.
The quip-proto, quip-protocol, and quip-solver-core dependencies come
from crates.io at v0.0.0; their source of truth is
quip.network/quip-solver-core.
CUDA card support
The CUDA miner supports NVIDIA GPUs with compute capability 7.0 through 12.1
(Volta through consumer Blackwell). The floor is set by the kernels (they use
__nanosleep, an sm_70+ instruction); the ceiling by NVRTC 12.9, which the
quip-miner-cuda image ships. The host needs an NVIDIA driver from a
CUDA 12.9-supported branch (r535 or newer) and the NVIDIA container runtime
(--gpus all). Kernels are JIT-compiled per card for its detected
capability; capabilities outside the range are clamped, and capabilities the
toolkit lacks (for example 8.8) fall back to the next lower architecture via
the driver's forward-compatible PTX JIT.
Documentation
AGENTS.md— build, test, and run commands; repository conventions.COORDINATOR.md— how the coordinator works (chain access, feeder, routing, supervision, session protocol).NEWMINER.md— how to add a new miner and wire it into the coordinator.docs/VERSIONING.md— the release-tag standard.
The solver contract — the wire protocol, the Sampler trait, handshake,
credits, cancel, and exit codes — is specified in the
quip-solver-core
repository (SPEC.md).
Build and run
The workspace builds from the repository root (toolchain pinned in
rust-toolchain.toml):
cargo build --workspaceRun the coordinator against a config that lists the miners and the validators:
quip-coordinator --config ./docker/config.tomlSee AGENTS.md for the full command set and COORDINATOR.md for the run model.
Testing
The workspace tests run offline by default:
cargo test --workspaceLive devnet integration tests
crates/quip-coordinator/tests/devnet_submit.rs drives the real chain client
against a running node. The tests are #[ignore]d and gated on the
QUIP_DEVNET environment variable, so the default cargo test run stays
offline. Three milestones:
- M1 — snapshot read: decode a live
MiningSnapshot(runtime API + SCALE). - M2 — proof submit: register
//Alice, solve the PoW Ising locally, and submit aQuantumPow.submit_proofextrinsic; assert on-chain acceptance. - M3 — mempool decode: propose a
QuantumComputeMempooljob order, then confirmfetch_mempool_ordersdiscovers itsorder_idfrom the head-blockJobProposedevent, storage-readsJobOrders(order_id), and builds a Job.
Start a local devnet from the chain repo
(quip-validator) with
make local-3-node or docker compose up. Both publish node RPC on
ws://127.0.0.1:9944. Then run:
QUIP_DEVNET=ws://127.0.0.1:9944 \
cargo test -p quip-coordinator --test devnet_submit -- --ignored --nocaptureOne constraint: use a loopback URL (ws://127.0.0.1:…) or wss://. subxt
rejects plain ws:// to a non-loopback host as insecure. To reach a remote
node, tunnel its RPC port to localhost first.
M3 self-seeds — it proposes its own order against the canonical plain-ising-v1
spec the runtime seeds at genesis, so it runs on a fresh devnet with an empty
mempool.
What changed from v0.2
In v0.2 this repository was a single Python mining stack that attached to the chain. v0.3 splits it apart:
- The coordinator and chain integration are Rust (
crates/), talking to the node over subxt. - Each miner is a standalone binary in its own repository, supervised by the coordinator over a local socket. The Python miner stack is gone.
- The solver contract — proto, consensus primitives, harness, and the Python
wheel — moved to
quip.network/quip-solver-core. This repository holds no Python.
License
AGPL-3.0-or-later. See LICENSE.
