feat: add automated mining setup

docs/deep-dives/miner-protocol.md

@@ -99,7 +99,7 @@ pub enum MinerMessage {
 |-------|------|-------------|
 | `job_id` | String | Unique identifier (UUID) |
 | `mining_hash` | String | Header hash (64 hex chars, no `0x` prefix) |
-| `distance_threshold` | String | Difficulty target (U512 as decimal string) |
+| `difficulty` | String | Difficulty target (U512 as decimal string). Must be non-zero. |
 
 Nonce range is not specified -- each miner independently selects a random starting point from the 512-bit nonce space.
 

docs/guides/mining.md

@@ -47,7 +47,58 @@ You shoould keep both your 24 word phrase and your secret secure and do not shar
 
 ---
 
-## Installation (Mac / Linux)
+## Automated Setup
+
+For a guided terminal workflow, use the mining setup script (macOS, Linux, or WSL2):
+
+```bash
+curl -fsSL https://docs.quantus.com/scripts/quantus-mining.sh -o quantus-mining.sh
+chmod +x quantus-mining.sh
+./quantus-mining.sh setup
+./quantus-mining.sh start
+```
+
+The script generates your wormhole inner hash, node identity, and a config file at `~/quantus-mining/mining.conf`. It can deploy either **native binaries** or a **Docker Compose stack** — you choose during setup.
+
+### Deployment modes
+
+| Mode | Command | Best for |
+|------|---------|----------|
+| **Binary** (default) | `./quantus-mining.sh setup` or `setup --mode binary` | macOS; Linux x86_64 |
+| **Docker** | `./quantus-mining.sh setup --mode docker` | Linux ARM64, containerized deploy, or when you prefer not to install binaries locally |
+
+**Binary mode** downloads `quantus-node` and `quantus-miner` into `~/quantus-mining/bin/`.
+
+**Docker mode** requires Docker Desktop (or Docker Engine) with Compose v2 (`docker compose`) and a running daemon. It pulls `ghcr.io/quantus-network/quantus-node` and `ghcr.io/quantus-network/quantus-miner` (release tags from GitHub) and installs a compose stack under `~/quantus-mining/docker/` (`docker-compose.yml`, `init-node.sh`, node keys, and chain data).
+
+**Linux ARM64:** there is no native `quantus-miner` release for Linux ARM64. Use `--mode docker` or an x86_64 host.
+
+### Running the stack
+
+The same commands work for both modes; `RUN_MODE` in `mining.conf` selects binary vs Docker.
+
+**One terminal:** `./quantus-mining.sh start`
+
+- **Binary:** node output in your terminal (foreground); miner runs in the background (`~/quantus-mining/logs/miner.log`). Ctrl+C stops both.
+- **Docker:** both containers attach to your terminal. Ctrl+C stops both.
+
+**Two terminals (matches the manual steps below):** run `./quantus-mining.sh start-node` in one terminal, then `./quantus-mining.sh start-miner` in another after the node is listening.
+
+Add `-d` or `--detach` to run both in the background. Stop with `./quantus-mining.sh stop` from any terminal (works for foreground and detached runs).
+
+**Docker logs (detached or troubleshooting):**
+
+```bash
+cd ~/quantus-mining/docker && docker compose logs -f
+```
+
+Manage settings with `./quantus-mining.sh config show` or `./quantus-mining.sh config set CPU_WORKERS 4`. Editable keys: `NODE_NAME`, `CPU_WORKERS`, `GPU_DEVICES`, `MINER_LISTEN_PORT`, `CHAIN`. In Docker mode, the script regenerates `docker/.env` on start after config changes.
+
+GPU mining is recommended when available. Mining rewards still accumulate at your wormhole address — see [Claiming Rewards](#claiming-rewards) below to move them to your wallet.
+
+Example config template: [mining.conf.example](/scripts/mining.conf.example).
+
+## Manual Installation (Mac / Linux)
 
 ### 1. Download the Node Binary
 
@@ -200,6 +251,9 @@ xattr -d com.apple.quarantine quantus
 
 
 ### **Logs & Diagnostics**
+
+**Binary / manual install:**
+
 ```bash
 # Real-time logs
 tail -f ~/.local/share/quantus-node/chains/planck/network/quantus-node.log
@@ -208,6 +262,13 @@ tail -f ~/.local/share/quantus-node/chains/planck/network/quantus-node.log
 RUST_LOG=info quantus-node [options]
 ```
 
+**Docker (automated setup with `RUN_MODE=docker`):**
+
+```bash
+cd ~/quantus-mining/docker && docker compose logs -f
+# Chain data on disk: ~/quantus-mining/docker/node-data/
+```
+
 #### **Inspect your node's P2P identity:**
 
 ```bash

static/scripts/docker-compose.yml

@@ -0,0 +1,67 @@
+services:
+  quantus-node:
+    image: ghcr.io/quantus-network/quantus-node:${NODE_VERSION:-latest}
+    container_name: ${CONTAINER_NAME:-quantus-node}
+    platform: linux/amd64
+    restart: unless-stopped
+    entrypoint: ["/init-node.sh"]
+    command: >
+      --validator
+      --base-path /var/lib/quantus
+      --chain ${CHAIN:-planck}
+      --node-key-file /node-keys/key_node
+      --rewards-inner-hash ${REWARDS_INNER_HASH}
+      --name ${NODE_NAME:-my-quantus-node}
+      --wasm-execution compiled
+      --db-cache 2048
+      --rpc-cors all
+      --in-peers ${IN_PEERS:-256}
+      --out-peers ${OUT_PEERS:-256}
+      --prometheus-external
+      --miner-listen-port 9833
+      --max-blocks-per-request 64
+      --sync full
+    volumes:
+      - ./init-node.sh:/init-node.sh:ro
+      - ./node-keys:/node-keys
+      - ./node-data:/var/lib/quantus
+    ports:
+      - "${P2P_PORT:-30333}:30333"
+      - "${RPC_PORT:-9944}:9944"
+      - "${PROMETHEUS_PORT:-9615}:9615"
+      - "${HOST_MINER_LISTEN_PORT:-9833}:9833/udp"
+    networks:
+      quantus:
+        # Pinned IPv4: quantus-miner needs --node-addr as IP:port (SocketAddr)
+        # and cannot use hostnames (e.g. host.docker.internal). Change
+        # QUANTUS_DOCKER_SUBNET and QUANTUS_NODE_IPV4 if the default overlaps
+        # another Docker network.
+        ipv4_address: ${QUANTUS_NODE_IPV4:-172.28.0.10}
+
+  quantus-miner:
+    image: ghcr.io/quantus-network/quantus-miner:${MINER_VERSION:-latest}
+    container_name: ${MINER_CONTAINER_NAME:-quantus-miner}
+    platform: linux/amd64
+    restart: unless-stopped
+    command: >
+      serve
+      --node-addr ${MINER_NODE_ADDR}
+      --metrics-port 9900
+    environment:
+      - MINER_CPU_WORKERS=${CPU_WORKERS:-4}
+      - MINER_GPU_DEVICES=${GPU_DEVICES:-0}
+      - RUST_LOG=${MINER_LOG:-info}
+    depends_on:
+      - quantus-node
+    ports:
+      - "${HOST_MINER_METRICS_PORT:-9900}:9900"
+    networks:
+      - quantus
+
+networks:
+  quantus:
+    driver: bridge
+    ipam:
+      driver: default
+      config:
+        - subnet: ${QUANTUS_DOCKER_SUBNET:-172.28.0.0/16}

static/scripts/init-node.sh

@@ -0,0 +1,17 @@
+#!/bin/sh
+# Generates the libp2p node identity on first start, then execs quantus-node.
+# Mounted into the quantus-node container by docker-compose.yml.
+
+set -e
+
+NODE_KEY_DIR="/node-keys"
+NODE_KEY_FILE="${NODE_KEY_DIR}/key_node"
+
+if [ ! -f "$NODE_KEY_FILE" ]; then
+  echo "Generating node key..."
+  mkdir -p "$NODE_KEY_DIR"
+  /usr/local/bin/quantus-node key generate-node-key --file "$NODE_KEY_FILE"
+  echo "Node key generated at: ${NODE_KEY_FILE}"
+fi
+
+exec /usr/local/bin/quantus-node "$@"

static/scripts/mining.conf.example

@@ -0,0 +1,43 @@
+# Quantus mining configuration example
+# Copy to ~/quantus-mining/mining.conf or run: ./quantus-mining.sh setup
+#
+# File permissions should be 600 (the setup script sets this automatically).
+# Never store your 24-word mnemonic in this file — only INNER_HASH is persisted.
+
+# Deployment mode: binary (direct downloads) or docker (compose stack)
+RUN_MODE="binary"
+DOCKER_DIR="docker"
+
+# Node name shown on https://telemetry.quantus.cat/
+NODE_NAME="my-planck-node"
+
+# 32-byte wormhole preimage — required for --rewards-inner-hash
+INNER_HASH="0x..."
+
+# Wormhole SS58 address where mining rewards accumulate (informational)
+WORMHOLE_ADDRESS="..."
+
+# P2P node identity file (relative to QUANTUS_MINING_DIR)
+NODE_KEY_FILE="node_key.p2p"
+
+# Chain spec
+CHAIN="planck"
+
+# QUIC miner server port (node listens; miner connects via --node-addr)
+MINER_LISTEN_PORT=9833
+
+# External miner resource allocation
+# GPU mining recommended: GPU_DEVICES=1, CPU_WORKERS=0
+# CPU-only: leave ~2 cores free for OS/node
+CPU_WORKERS=0
+GPU_DEVICES=1
+
+# Pinned versions (set automatically during setup from GitHub releases)
+# Docker mode: ghcr.io image tags matching those releases.
+NODE_VERSION=""
+MINER_VERSION=""
+
+# Editable via: ./quantus-mining.sh config set KEY VALUE
+#   NODE_NAME, CPU_WORKERS, GPU_DEVICES, MINER_LISTEN_PORT, CHAIN
+#
+# To change INNER_HASH / rewards destination, re-run setup wormhole keygen.