diff --git a/docs/guides/mining.md b/docs/guides/mining.md index 67f110e..4119c70 100644 --- a/docs/guides/mining.md +++ b/docs/guides/mining.md @@ -5,10 +5,30 @@ title: Mining and Running a Node # Mining and Running a Node -This guide covers connecting to the Quantus Planck testnet and mining. Works on macOS and Linux (including WSL2 on Windows). +This guide covers connecting to the Quantus Planck testnet and mining. The setup script below runs on macOS and Linux, including WSL2 on Windows. + +**On Windows without WSL2?** Use the [Miner App](https://github.com/Quantus-Network/quantus-apps/releases/latest) (`quantus_miner_windows.zip`) instead. It is a desktop app that downloads the node for you and handles identity, mining, and rewards in one window, with no terminal. Use the **Copy Context** button at the top of this page to copy everything as Markdown -- the full guide plus an AI mining skill. Paste it to an agent like Claude Code to be walked through setup interactively, or keep it as an offline reference. +If you use Claude Code, install the skill from disk in one command instead of pasting. + +macOS, Linux, or Git Bash on Windows: + +```bash +mkdir -p ~/.claude/skills/mining && curl -fsSL https://docs.quantus.com/skills/mining-skill.md -o ~/.claude/skills/mining/SKILL.md +``` + +Windows PowerShell: + +```powershell +New-Item -ItemType Directory -Force "$HOME\.claude\skills\mining" | Out-Null; curl.exe -fsSL https://docs.quantus.com/skills/mining-skill.md -o "$HOME\.claude\skills\mining\SKILL.md" +``` + +The PowerShell version is not a style preference. Windows PowerShell 5.1, still the default on Windows, treats `&&` as a parser error and aliases `curl` to `Invoke-WebRequest`, which does not accept `-fsSL`. Calling `curl.exe` explicitly and separating with `;` works on both 5.1 and PowerShell 7. + +Then run `/mining`. The skill walks the same steps as this guide, and it probes the binaries you actually downloaded before starting anything, so it will not hand you a mismatched node and miner pair. + ## Prerequisites Before starting, you will need: diff --git a/static/skills/mining-skill.md b/static/skills/mining-skill.md index 3383253..c587856 100644 --- a/static/skills/mining-skill.md +++ b/static/skills/mining-skill.md @@ -16,7 +16,7 @@ Mining commands and flags are aligned with chain MINING.md (https://github.com/Q **Critical architecture:** The node is the QUIC server (listens on port 9833 via `--miner-listen-port`). The external miner is the QUIC client (connects via `--node-addr`). Start the node first; wait for it to log that the miner server is listening before starting the miner. Node and miner versions must be a matching pair. -**Miner protocol -- probe the binaries you actually downloaded.** Current GitHub `releases/latest` are pre-auth (node `v0.9.0-endless-sky`, miner `v3.3.1`). Do **not** wait for `miner-auth-token` or pass `--auth-token-file` unless **both** binaries advertise those flags. +**Miner protocol -- probe the binaries you actually downloaded.** As of 2026-09-03, GitHub `releases/latest` are auth-era (node `v0.10.0`, miner `v4.0.2`); node `v0.9.0-endless-sky` / miner `v3.3.1` and earlier are pre-auth. Do **not** wait for `miner-auth-token` or pass `--auth-token-file` unless **both** binaries advertise those flags. Capture `--help` exit status first. A non-zero exit is a broken, quarantined, or wrong-architecture binary -- **stop** and fix it. Do **not** treat a failed probe as pre-auth (`*_auth=no`). Do not pipe `--help` into `grep` until the command itself exits 0. @@ -49,7 +49,7 @@ echo "node_auth=${node_auth} miner_auth=${miner_auth}" Replace `./quantus-node` / `./quantus-miner` with the actual downloaded filenames. `/usr/bin/false` (or any failed `--help`) must exit 1 here and must not print `node_auth=no`. -- **Both no, after successful `--help` (today's latest):** wait only for "miner server listening"; start the miner with `--node-addr` only. +- **Both no, after successful `--help` (pre-auth pair):** wait only for "miner server listening"; start the miner with `--node-addr` only. - **Both yes:** wait for `miner-auth-token` and `miner-tls-cert-sha256` under the chain directory, then pass `--auth-token-file` and `--tls-cert-sha256-file`. ALPN is `quantus-miner/2`. - **Mixed:** stop. Pin a matching pair (`NODE_VERSION` / `MINER_VERSION` in `mining.conf`, then `setup --force`); do not mix independent `releases/latest` tags.