Skip to content

miner-app: guard fresh installs on disk space, refuse mismatched node/miner pairs - #633

Draft
adamtpang wants to merge 4 commits into
Quantus-Network:mainfrom
adamtpang:fix/disk-space-check-before-node-install
Draft

miner-app: guard fresh installs on disk space, refuse mismatched node/miner pairs#633
adamtpang wants to merge 4 commits into
Quantus-Network:mainfrom
adamtpang:fix/disk-space-check-before-node-install

Conversation

@adamtpang

@adamtpang adamtpang commented Sep 4, 2026

Copy link
Copy Markdown

Overview

Two guards for failures that currently surface only as a silent stall or a generic crash. Both were reproduced on a real Windows 11 machine. Draft because I have no local Flutter toolchain, so CI here is the first compile check.

1. Free disk space before a fresh node install

A fresh install downloads the node and then syncs roughly 100 GB of chain data into ~/.quantus/node_data. MINING.md states 100 GB minimum, 500 GB recommended. The setup screen had no free-space check, so a machine with too little room downloads successfully and then fails partway through sync with no explanation. Observed on a machine with 27 GB free.

  • DiskSpaceService.freeBytesForPath probes the volume holding a path: PowerShell on Windows, df -kP elsewhere. Returns null rather than throwing, so a failed probe never blocks setup on its own.
  • MinerConfig gains bytesPerGb, minNodeDiskBytes, recommendedNodeDiskBytes, sourced from MINING.md.
  • The check runs inside the fresh-install branch only and throws before fetching the node version. It surfaces through the existing catch, so no new UI.

The update path is deliberately not gated. A returning user's binary update is a small download onto a volume that already holds their chain data, and blocking a protocol or security update over disk space would be wrong.

2. Mismatched node and miner auth pair

Node v0.10.0 requires miner QUIC auth; miner releases before v4.0.0 do not support it. The app checks each binary for updates independently and does not gate Start Mining on the pair matching. A user whose miner is older than their node, or whose update was interrupted, can start mining and see only "Miner died during startup".

Reproduced: miner-cli 2.1.2 beside quantus-node 0.10.0, which the official mining script's own probe classifies as "Mixed: stop".

  • PairCompatibilityService.check runs the same --help probe the script runs, against the installed binaries. Returns null if either probe fails, so a broken or wrong-architecture binary stays with the existing "binary not found" path.
  • _startMiner refuses a mixed pair with a snackbar naming both versions and which one to update. Compatible or unknown pairs proceed unchanged.

Validation

Both services follow the existing GpuDetectionService shape: static, Process.run, tagged logger, null on probe failure. Lines are within the 120-character format limit, and the diff conforms to the repo's prefer_single_quotes and always_declare_return_types rules. Not yet compiled locally, relying on CI flutter analyze.

adamtpang and others added 4 commits September 4, 2026 11:13
A fresh install downloads the node and then syncs roughly 100 GB of chain
data into ~/.quantus/node_data (chain/MINING.md: 100 GB minimum, 500 GB
recommended). The setup screen had no free-space check, so a machine with
too little room would download successfully and then fail partway through
sync with no explanation. Observed on a Windows 11 machine with 27 GB free.

- DiskSpaceService.freeBytesForPath: probes the volume holding a path via
  PowerShell on Windows and POSIX `df -kP` elsewhere. Returns null instead
  of throwing so a broken probe can never block setup on its own.
- MinerConfig: bytesPerGb, minNodeDiskBytes (100 GB), recommendedNodeDiskBytes
  (500 GB), sourced from chain/MINING.md.
- node_setup_screen: inside the fresh-install branch only, throw a plain
  Exception before fetching the node version when free space is known and
  below the minimum. It surfaces through the existing catch (progress text
  plus SnackBar), so no new UI is introduced.

The update path is deliberately not gated: a returning user's binary update
is a small download onto a volume that already holds their chain data, and
blocking a protocol or security update over disk space would be wrong.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
…auth pair

Node v0.10.0 (2026-08-13) requires miner QUIC auth; miner releases before
v4.0.0 do not support it. The app checks each binary for updates
independently and does not gate Start Mining on the pair matching, so a
returning user whose miner is older than their node, or whose update was
interrupted, can start mining and see only "Miner died during startup".

Reproduced on a real install: miner-cli 2.1.2 (no --auth-token-file)
alongside quantus-node 0.10.0 (advertises --miner-auth-token-file), which
the official script's own probe classifies as "Mixed: stop".

- PairCompatibilityService.check: runs the same --help probe the script
  runs, on the installed binaries. Returns null if a probe fails so a
  broken binary is handled by the existing "binary not found" path.
- _startMiner: before starting, refuse a mixed pair with a snackbar that
  names both versions and which one to update. Compatible or unknown pairs
  proceed unchanged.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
It landed among the relative imports, which reads as an accident.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
They were added to ChainConfig by mistake, so MinerConfig.bytesPerGb,
minNodeDiskBytes, and recommendedNodeDiskBytes did not exist and the
setup screen referenced three getters that were never declared.

Caught by flutter analyze, which reported six undefined_getter errors in
node_setup_screen.dart. Both classes live in miner_config.dart and the
constants had been appended before the file's last closing brace rather
than the one that ends MinerConfig.

flutter analyze now reports no issues, and dart format at line length 120
leaves all 47 files unchanged.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant