Quip Miner

QuIP Miner Repo Skill

Use this skill when a task involves the quip-miner command, the quip-protocol Python package, QuIP quantum proof-of-work mining, Substrate validator integration, miner configuration, hybrid signing wallets, telemetry, topology/proof tools, or repo maintenance for this codebase.

First Checks

• Python: 3.10+.

• Package identity check:

  python -c "from importlib.metadata import version; import quip_cli; print(version('quip-protocol'))"

• CLI check:

  quip-miner --help

• From a source checkout, install only the extras needed for the target backend:

  python -m pip install -e .          # base + CPU/QPU package surface
  python -m pip install -e '.[cuda]'  # NVIDIA CUDA backend
  python -m pip install -e '.[metal]' # Apple Silicon Metal backend
  python -m pip install -e '.[dev]'   # pytest and pytest-asyncio

• Quick environment probe:

  python scripts/quip_backend_probe.py --json

Read references/installation-and-environment.md before diagnosing optional dependencies or backend availability.

Route By Task

• Config, supervisor, and deployment: Use sub-skills/config-supervisor-deployment/SKILL.md for TOML schema, [miner] vs backend sections, resolve-mode(s), top-level quip-miner --config, Docker /data/config.toml, telemetry bind settings, and systemd/container caveats.
• Wallet, bootstrap, identity, and solver registration: Use sub-skills/identity-wallet-bootstrap/SKILL.md for keygen, bootstrap, faucet/dev seeding, NodeDescriptor identify, signer file safety, and mempool solver registration/deregistration.
• Mining backends: Use sub-skills/mining-backends/SKILL.md for quip-miner cpu, gpu, qpu, CPU SA, CUDA, Metal, Modal, D-Wave/gate-model QPUs, QPU budget knobs, unified streaming, and PoW/mempool scheduling.
• Telemetry and attempt archive: Use sub-skills/telemetry-attempt-archive/SKILL.md for /api/v1 endpoints, snapshot aggregation, node health checks, QUIP_RUNTIME_DIR, QUIP_MINING_ATTEMPTS_DIR, and per-solution mining attempt/solution archives.
• Topology and proof validation: Use sub-skills/topology-proof-validation/SKILL.md for dwave_topologies, Advantage2/Zephyr topology files, D-Wave h/J ranges, proof-chain download/revalidation, and dumped BQM records.
• Maintainer testing and release: Use sub-skills/maintainer-testing-release/SKILL.md for targeted pytest, CI invariants, no-inline-sampling lint, PyInstaller selftest, versioning, and hang-debugging procedures.

Shared Operating Rules

• quip-miner --config config.toml is the production entry point. Direct subcommands (cpu, gpu, qpu) are useful for focused runs and tests.
• --mode cpu|gpu|qpu is CLI-only narrowing for a multi-backend config; there is no config-file key for mode selection.
• Mempool participation is config-only and per backend group: put mempool = false or true inside [cpu], [gpu], [metal], [modal], or a QPU vendor section such as [dwave]. A [miner] mempool key is invalid.
• CPU and GPU mempool default on; QPU mempool defaults off because paid samples are opt-in. One substrate account can register one solver type, so the config elects exactly one mempool owner group.
• Live miners pull the registered topology from the chain; do not pass --topology to live mining commands.
• Never store QPU/cloud credentials in TOML. D-Wave uses environment variables such as DWAVE_API_KEY; other providers use their own environment/profile mechanisms.
• The runtime architecture is unified streaming: every backend and both PoW/mempool jobs use a stream-driver subprocess plus shared-memory ring. Do not reintroduce inline _sample/_sample_batch mining paths.
• Use multiprocessing for new background work in this repo; do not add new threading.Thread-based mining or telemetry workers.