Skip to content

mining docs: correct the pre-auth claim, add a Windows path and a PowerShell-safe install #15

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
adamtpang wants to merge 3 commits into from
Closed

mining docs: correct the pre-auth claim, add a Windows path and a PowerShell-safe install #15

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
0d471c6
mining-skill: correct the "current releases are pre-auth" claim
adamtpang Sep 4, 2026
9b2e07d
mining guide: a Windows path without WSL2, and a one-command skill in…
adamtpang Sep 4, 2026
ff2a6f0
mining guide: give the skill install a PowerShell variant that actual…
adamtpang Sep 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 21 additions & 1 deletion docs/guides/mining.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
4 changes: 2 additions & 2 deletions static/skills/mining-skill.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -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.

Expand Down