quip-miner: a Python mining stack for a Substrate chain that solves Ising problems

What problem this solves and who it is for

quip-miner exists to connect a Substrate chain's QuantumPow pallet to actual hardware that can solve the underlying Ising optimization problem. The chain expects miners to fetch a mining snapshot at each new block head, find a valid Ising solution, and submit it as a QuantumPow.submit_proof extrinsic. Without a client like this, you would have to write your own RPC calls, SCALE encoding, and proof submission logic. The intended audience is developers and researchers working with the quip-protocol-rs chain, not general-purpose cryptocurrency miners. The README is explicit that this is experimental software with no production warranties. That warning matters: this is a reference stack for a specific protocol, not a turnkey mining tool.

Architecture: a thin client, not a node

The v0.2 line deliberately strips away everything that made v0.1 a standalone protocol. The old codebase shipped its own consensus, P2P over QUIC, a block store, a REST API, and SPHINCS+ block signing. All of that is gone. The chain is now the source of truth, and quip-miner attaches to it as a client. The architecture diagram shows a SubstrateClient that handles read operations: get_mining_snapshot, subscribe_new_heads, and submit_extrinsic. From there, a miner controller subscribes to new heads, fetches snapshots, dispatches work to workers, and classifies receipts. The shared modules split responsibilities cleanly: substrate_client.py wraps py-substrate-interface for state calls, substrate_submitter.py handles SCALE encoding of MiningResult into QuantumProof, and quantum_proof_of_work.py contains the core functions for nonce derivation, Ising model generation, and sample evaluation. The design is a layered pipeline, and each layer has a single, testable job.

Getting it running: installation and bootstrap

Installation follows standard Python practice. Create a virtual environment, activate it, and pip install the package in editable mode. The dependencies include substrate-interface, scalecodec, dwave-ocean-sdk, numpy, aiohttp, click, and blake3. D-Wave access requires a DWAVE_API_KEY in a .env file, loaded via python-dotenv. The quick start assumes you have the chain running locally via docker compose in a separate repository, quip-protocol-rs. You point the miner at a running faucet with --faucet-url, and it self-funds and self-registers on first run. The bootstrap command is idempotent: it generates a keystore if missing, requests funds, and submits register_miner. With --seed-chain, it also sudo-submits set_difficulty and register_topology on a fresh chain. Re-runs are no-ops that just verify state. The actual mining command is quip-miner cpu, gpu, or qpu, each taking --node-url, --signer-key, --topology, and --rest-port. The cpu subcommand adds --num-cpus, gpu adds --gpu-backend with choices local, metal, and modal, and qpu adds --qpu-type and --daily-budget.

Topology binding: a hard constraint at startup

One of the most interesting design choices is the enforced topology check. The CLI hashes the configured topology with the same blake2_256(SCALE((sorted_nodes, canonical_edges))) recipe the chain uses, and it refuses to start if the hash does not match the chain's registered topology. This is not a soft warning; it is a hard stop. The rationale is clear: if you sample an Ising model on a topology that does not match the chain's expectation, your solutions will be invalid, and you will waste compute. This check saves you from a subtle failure mode where your miner runs but never submits a valid proof. However, it also means you must know the exact topology the chain has registered. The default is zephyr:9,2, but that only works if the chain was seeded with that topology. If you are joining a chain that uses a different one, you must find the correct value or the miner will not start. This is a sensible guard, but it adds a configuration burden that a generic miner would not have.

What the telemetry API tells you

The telemetry API is a small HTTP REST surface that gives you visibility into the miner's state. Endpoints include /health, /api/v1/status for chain head and miner identity, /api/v1/system for a cached hardware descriptor, /api/v1/stats for aggregate MinerCore and controller stats, and /api/v1/block/{n} for substrate-fetched block data. The response envelope is consistent: a success boolean, data or error, and a timestamp. The README notes that the legacy /api/v1/peers, /api/v1/join, /api/v1/gossip, /api/v1/heartbeat, and POST /api/v1/block paths are removed because they were P2P and consensus surfaces with no equivalent in substrate mode. The legacy /telemetry/* SSE stream is also gone; consumers should switch to substrate-side events and Prometheus at http://localhost:9615/metrics. This is a clean break, but it means any tooling built against the v0.1 API will need to be rewritten. The POST /api/v1/solve endpoint, which used to allow direct D-Wave sampling, is disabled in v0.2. So you cannot use the API as a general-purpose Ising solver; it is purely observational.

Limitations and failure modes

The most obvious limitation is that this software is experimental. The README says so in bold at the top. That is not a marketing disclaimer; it means the codebase is likely to change in breaking ways. The v0.1 to v0.2 transition is proof: entire subsystems were deleted. If you build on this, expect similar churn. A second limitation is the keystore format. The keygen command writes a 0o600 JSON keystore with the seed in plaintext. Passphrase-encrypted keystores are scheduled for Phase 7, but they do not exist yet. On a shared machine, a plaintext seed is a real security risk. A third limitation is the tight coupling to a specific chain. This is not a general-purpose mining client. It only works with the quip-protocol-rs chain and its QuantumPow pallet. If the chain changes its snapshot format or proof encoding, the miner must be updated in lockstep. Finally, the QPU path depends on a D-Wave account and API key. Without that, the qpu subcommand is useless. The cpu and gpu paths are more accessible, but gpu requires a backend that matches your hardware, and the README does not detail which GPUs are supported.

Alternatives and how they differ

The closest alternative is writing your own miner using py-substrate-interface directly. That library handles the RPC and SCALE encoding, but you would still need to implement the Ising model generation, the sampling loop, and the proof submission logic yourself. quip-miner provides all of that as a package, so you save significant development time. The difference is in approach: quip-miner is a full stack with a controller, workers, and telemetry, while a hand-rolled client would be a few hundred lines of glue code. Another alternative is to use the chain's own tooling, if any exists, but the README does not mention any. For the QPU part, D-Wave's own ocean SDK is the lower-level building block. quip-miner wraps it, but if you need fine-grained control over sampling parameters or annealing schedules, you might prefer to call the SDK directly. The trade-off is convenience versus control.

Maintenance and licensing considerations

The repository is archived: no. The last push date is unknown, and there are no recent releases retrieved. That makes it hard to assess maintenance cadence. The README mentions Phase 7 as a future milestone for passphrase-encrypted keystores and a HybridSigner with ML-DSA-44, which suggests the project has a roadmap, but there is no timeline. The license is AGPL-3.0. That has implications if you plan to modify the code and offer it as a service: AGPL requires you to make your modified source available to users who interact with it over a network. This is not legal advice, but it is a constraint to be aware of before you build a commercial mining service on top of this code. For personal or research use, the license is less of a burden. Upgrading from v0.1 to v0.2 would be a major effort, since the API surface and architecture changed completely. Anyone adopting this should plan for similar breaking changes in future versions.

Editorial conclusion

Adopt quip-miner if you are a developer or researcher working with the quip-protocol-rs chain and want a reference implementation for the QuantumPow mining loop, especially if you have access to a D-Wave QPU. Do not adopt it for production mining on any other chain, as it is experimental, AGPL-3.0 licensed, and tightly coupled to a specific Substrate pallet. Before use, verify that the chain's registered topology matches your configured --topology, confirm the faucet URL is reachable, and check that your Python environment meets the pinned dependency versions, particularly dwave-ocean-sdk and substrate-interface. Also confirm the keystore's plaintext seed is acceptable for your security posture, since passphrase encryption is not available until Phase 7.

Official sources

1. Official documentation
2. Official README
3. Project repository