Mine to AlphaPool DATUM in One Copy-Paste

You are setting up a self-sovereign mining stack on this Windows PC for a beginner, using
WSL2 (Ubuntu inside Windows): a Bitcoin Knots full node (the Bitcoin BLAKE2b chain) plus a
DATUM Gateway pointed at the AlphaPool DATUM pool. The user's own node builds the blocks; the
pool splits the coinbase and pays the user's address directly inside each block. Non-custodial.
No signup.

You are running on WINDOWS (PowerShell). You will drive Ubuntu inside WSL2 with
  wsl -d Ubuntu -- bash -lc '<command>'
Work step by step. Run the commands yourself, verify each step, and STOP AND ASK if anything is
ambiguous or fails. Explain briefly what you are doing. Be idempotent. Anything that needs
Administrator rights must run in an ELEVATED PowerShell (Start-Process powershell -Verb RunAs)
and the user will approve the UAC prompt — tell them before you trigger it. Never open RPC to
the network. Never touch any existing Bitcoin wallet or data directory except the ones this
guide creates.

==================================================================================
FACTS — use exactly, do not "improve" them
==================================================================================
Chain:            Bitcoin BLAKE2b (Bitcoin Knots 29.4.1 mainnet). First BLAKE2b block 961640.
                  Do NOT set chain=testnet4/regtest.
Node software:    Bitcoin Knots 29.4.1.knots20260508 (official Linux build, run inside WSL2)
Download base:    https://bitcoinknots.org/files/29.x/29.4.1.knots20260508/
  file:           bitcoin-29.4.1.knots20260508-x86_64-linux-gnu.tar.gz
  checksums:      SHA256SUMS  (same folder) — verification is MANDATORY
Gateway software: CONVOY DATUM Gateway (BLAKE2b + header-v2 build)
  repo:           https://github.com/CONVOYMining/datum_gateway.git  (branch: master)
  required:       history MUST contain commit 56c31f4 (older builds produce invalid shares)
AlphaPool DATUM:  host us2.alphapool.tech   port 28916
  pool pubkey:    b831b2d6f1eaedb3da5b9e3702728edea0a32d6ce783a1452b2861c4d1b74d6b4c2ad5461bcf43485a6bac2cedf8da43d51164262ef6bcdb27f2242ada066d29
  fee:            2.00% pool ops, flat 8×D window split, paid in-block to the miner's address
Ports:            node P2P 8333 (optional), node RPC 8332 (localhost ONLY),
                  gateway stratum 23334 (LAN — Windows firewall must allow it),
                  gateway UI/API 7152 (localhost ONLY)
Disk/time:        ~20 GB free on the drive holding WSL (node is pruned). First sync downloads
                  the chain's history: plan on 1–3 days. Mining starts automatically once the
                  node is synced — the gateway simply waits.
Requirements:     Windows 11 22H2 or newer (for WSL "mirrored" networking so LAN miners can
                  reach the gateway). Windows 10 works with the port-forward fallback in Step 8.

==================================================================================
STEP 0 — Ask the user (do not proceed with placeholders)
==================================================================================
Ask for ONE thing: the payout address the coinbase should pay.
  - Recommended: a native-SegWit address starting with bc1q from a wallet dedicated to THIS
    chain (the fork's Knots bitcoin-qt wallet, Shrike, or Sparrow-BLAKE2b). Legacy 1... and
    3... addresses are also valid. NEVER use a seed/wallet that also holds real Bitcoin.
  - If the user has no address, offer to create one in a fresh wallet on the node they are
    about to run (Step 6). Only do this if they explicitly say yes.
Optionally ask for a short coinbase tag (their name/handle). Default: AlphaPool.
Confirm: this PC should stay on, plugged in, and logged in; first sync takes 1–3 days.

==================================================================================
STEP 1 — Windows checks and WSL2 + Ubuntu
==================================================================================
[System.Environment]::OSVersion.Version        # Build >= 22621 means Windows 11 22H2+
wsl --status ; wsl --version ; wsl -l -v
If WSL or the "Ubuntu" distro is missing:   wsl --install -d Ubuntu
  (Windows may require a reboot and Ubuntu will ask to create a Linux username/password on first
  start. After that, tell the user to re-run this whole prompt.)
Make sure Ubuntu is WSL version 2:  wsl --set-version Ubuntu 2
Free disk on the drive holding WSL (usually C:): Get-PSDrive C | Select Free   → need >= 20 GB

==================================================================================
STEP 2 — WSL networking (mirrored) + systemd, then restart WSL
==================================================================================
Write $env:USERPROFILE\.wslconfig containing exactly (merge if the file already exists):
[wsl2]
networkingMode=mirrored

Enable systemd inside Ubuntu:
wsl -d Ubuntu -u root -- bash -lc 'grep -q "^systemd=true" /etc/wsl.conf 2>/dev/null || printf "[boot]\nsystemd=true\n" >> /etc/wsl.conf'
wsl --shutdown
Start-Sleep 8
wsl -d Ubuntu -- bash -lc 'systemctl is-system-running; whoami; uname -m'
  → expect "running" or "degraded", the Linux username (call it $U below), and x86_64.

==================================================================================
STEP 3 — Prerequisites inside Ubuntu
==================================================================================
wsl -d Ubuntu -- bash -lc 'sudo apt update && sudo apt install -y git build-essential cmake pkgconf libcurl4-openssl-dev libjansson-dev libsodium-dev libmicrohttpd-dev psmisc curl jq'
(sudo will ask for the Linux password the user created; that is normal.)

==================================================================================
STEP 4 — Install Bitcoin Knots 29.4.1 inside Ubuntu (verify checksums — mandatory)
==================================================================================
wsl -d Ubuntu -- bash -lc '
set -e; mkdir -p ~/knots-dl && cd ~/knots-dl
F=bitcoin-29.4.1.knots20260508-x86_64-linux-gnu.tar.gz
curl -fLO https://bitcoinknots.org/files/29.x/29.4.1.knots20260508/$F
curl -fLO https://bitcoinknots.org/files/29.x/29.4.1.knots20260508/SHA256SUMS
sha256sum --ignore-missing --check SHA256SUMS
tar -xzf $F
sudo install -m 0755 bitcoin-*/bin/bitcoind bitcoin-*/bin/bitcoin-cli /usr/local/bin/
bitcoind --version | head -1'
The checksum line MUST print "...: OK" and the version MUST be v29.4.1.knots20260508. Else STOP.

==================================================================================
STEP 5 — Configure and start the node (pruned mainnet, RPC on localhost)
==================================================================================
Inside Ubuntu: if ~/.bitcoin/bitcoin.conf already exists, STOP and show it to the user first.
Generate: RPCUSER=datum ; RPCPASS = output of `openssl rand -hex 24`
Pick dbcache: 2048 if the PC has >= 8 GB RAM (wsl -d Ubuntu -- free -g), else 1024.
Write /home/$U/.bitcoin/bitcoin.conf (dir mode 700, file mode 600) with exactly:

server=1
daemon=0
rpcbind=127.0.0.1
rpcallowip=127.0.0.1
rpcuser=<RPCUSER>
rpcpassword=<RPCPASS>
prune=4000
dbcache=<2048 or 1024>
blockmaxweight=785000
blocknotify=curl -fsS -o /dev/null http://127.0.0.1:7152/NOTIFY

Create /etc/systemd/system/knots-node.service inside Ubuntu (sudo tee):

[Unit]
Description=Bitcoin Knots node (BLAKE2b chain)
After=network-online.target
Wants=network-online.target
[Service]
Type=simple
User=$U
ExecStart=/usr/local/bin/bitcoind -conf=/home/$U/.bitcoin/bitcoin.conf -datadir=/home/$U/.bitcoin
Restart=on-failure
RestartSec=15
TimeoutStopSec=900
[Install]
WantedBy=multi-user.target

wsl -d Ubuntu -- bash -lc 'sudo systemctl daemon-reload && sudo systemctl enable --now knots-node && sleep 30 && bitcoin-cli getblockchaininfo | jq "{chain,blocks,headers,verificationprogress,pruned}"'
Expect chain "main", pruned true, blocks/headers climbing. (Full sync = 1–3 days; keep going.)

==================================================================================
STEP 6 — Validate the payout address with the node (protects against stranded coins)
==================================================================================
wsl -d Ubuntu -- bash -lc 'bitcoin-cli validateaddress "<PAYOUT_ADDRESS>" | jq "{isvalid,address,iswitness}"'
"isvalid" MUST be true, else STOP and ask for a correct address.
ONLY if the user asked you to create a wallet:
  bitcoin-cli -named createwallet wallet_name="alphapool-payout" descriptors=true
  bitcoin-cli -rpcwallet=alphapool-payout getnewaddress "" bech32      ← the payout address
  bitcoin-cli -rpcwallet=alphapool-payout backupwallet "/home/$U/alphapool-payout-BACKUP.dat"
  Tell the user in bold to copy that backup file out of WSL to a safe place NOW
  (it is visible in Windows Explorer at \\wsl$\Ubuntu\home\$U\). Lost file = lost coins.

==================================================================================
STEP 7 — Build the CONVOY DATUM Gateway, configure it, run it as a service
==================================================================================
wsl -d Ubuntu -- bash -lc '
set -e; cd ~; [ -d datum_gateway ] || git clone https://github.com/CONVOYMining/datum_gateway.git
cd ~/datum_gateway && git checkout master && git pull --ff-only
git merge-base --is-ancestor 56c31f4 HEAD && echo "COMMIT CHECK OK" || { echo "COMMIT CHECK FAILED"; exit 1; }
cmake . && make -j$(nproc) && ls -l ./datum_gateway'
If COMMIT CHECK FAILED: STOP. Do not mine with this build.

APIPASS = output of `openssl rand -hex 16`. Write /home/$U/datum_gateway/datum_gateway_config.json
(mode 600) with exactly this, filling the <...> values:

{
  "bitcoind": {
    "rpcuser": "<RPCUSER>",
    "rpcpassword": "<RPCPASS>",
    "rpcurl": "http://127.0.0.1:8332"
  },
  "stratum": {
    "listen_addr": "0.0.0.0",
    "listen_port": 23334,
    "vardiff_min": 4096,
    "vardiff_target_shares_min": 8
  },
  "api": {
    "listen_addr": "127.0.0.1",
    "listen_port": 7152,
    "admin_password": "<APIPASS>",
    "modify_conf": true
  },
  "mining": {
    "pool_address": "<PAYOUT_ADDRESS>",
    "coinbase_tag_primary": "AlphaPool",
    "coinbase_tag_secondary": "<TAG>",
    "allow_hasher_time_rolling": false
  },
  "datum": {
    "pool_host": "us2.alphapool.tech",
    "pool_port": 28916,
    "pool_pubkey": "b831b2d6f1eaedb3da5b9e3702728edea0a32d6ce783a1452b2861c4d1b74d6b4c2ad5461bcf43485a6bac2cedf8da43d51164262ef6bcdb27f2242ada066d29",
    "pool_pass_workers": true,
    "pool_pass_full_users": true,
    "pooled_mining_only": true
  }
}
Validate: wsl -d Ubuntu -- bash -lc 'jq . ~/datum_gateway/datum_gateway_config.json >/dev/null && echo JSON OK'

Create /etc/systemd/system/datum-gateway.service inside Ubuntu (sudo tee):

[Unit]
Description=DATUM Gateway → AlphaPool
After=knots-node.service network-online.target
Wants=knots-node.service
[Service]
Type=simple
User=$U
WorkingDirectory=/home/$U/datum_gateway
ExecStart=/home/$U/datum_gateway/datum_gateway -c /home/$U/datum_gateway/datum_gateway_config.json
Restart=always
RestartSec=10
[Install]
WantedBy=multi-user.target

wsl -d Ubuntu -- bash -lc 'sudo systemctl daemon-reload && sudo systemctl enable --now datum-gateway && systemctl status datum-gateway --no-pager | head -12'
NOTE: until the node is fully synced the gateway logs that templates are unavailable and
retries — expected. Do not "fix" it.

==================================================================================
STEP 8 — Let LAN miners reach the gateway (Windows side, needs Administrator)
==================================================================================
Tell the user a UAC prompt is coming, then run in an ELEVATED PowerShell:
  New-NetFirewallRule -DisplayName "AlphaPool DATUM stratum 23334" -Direction Inbound -Protocol TCP -LocalPort 23334 -Action Allow -Profile Private,Domain
  Set-NetFirewallHyperVVMSetting -Name '{40E0AC32-46A5-438A-A0B2-2B479E8F2E90}' -DefaultInboundAction Allow
  powercfg /change standby-timeout-ac 0      # never sleep while plugged in
Windows 10 fallback (no mirrored networking): instead of relying on mirrored mode, forward the
port to WSL's IP and refresh it at logon:
  $ip = (wsl -d Ubuntu -- hostname -I).Trim().Split(' ')[0]
  netsh interface portproxy add v4tov4 listenport=23334 listenaddress=0.0.0.0 connectport=23334 connectaddress=$ip
Windows LAN IP for the miners:
  (Get-NetIPAddress -AddressFamily IPv4 | Where-Object {$_.InterfaceAlias -notmatch 'vEthernet|Loopback|WSL'} | Select-Object -First 1).IPAddress

==================================================================================
STEP 9 — Auto-start at logon (keeps WSL and both services alive)
==================================================================================
schtasks /Create /F /TN "AlphaPool-DATUM" /SC ONLOGON /RL LIMITED /TR "wsl.exe -d Ubuntu -u root -- bash -c \"systemctl start knots-node datum-gateway; exec sleep infinity\""
schtasks /Run /TN "AlphaPool-DATUM"
(With mirrored mode nothing else is needed. On the Windows 10 fallback, also add the portproxy
refresh from Step 8 to a small .ps1 that the task runs first.)

==================================================================================
STEP 10 — Verify (run all, report results)
==================================================================================
wsl -d Ubuntu -- bash -lc 'systemctl is-active knots-node datum-gateway; bitcoin-cli getblockchaininfo | jq "{blocks,headers,verificationprogress}"; bitcoin-cli getdeploymentinfo | jq ".deployments.blake2b"; journalctl -u datum-gateway -n 15 --no-pager'
Test-NetConnection -ComputerName localhost -Port 23334     # TcpTestSucceeded should be True
Once synced: wsl -d Ubuntu -- bash -lc "bitcoin-cli getblocktemplate '{\"rules\":[\"segwit\",\"blake2b\"]}' | jq -r '.rules[]'"  → must include "!blake2b"

==================================================================================
FINAL REPORT — print this for the user, filled in
==================================================================================
✅ Node: Bitcoin Knots 29.4.1 running inside WSL2 as service knots-node (pruned). Sync: <X>% —
   mining starts automatically at 100% (est. 1–3 days). Check anytime from PowerShell:
   wsl -d Ubuntu -- bitcoin-cli getblockchaininfo
✅ Gateway: datum-gateway service running, pointed at us2.alphapool.tech:28916 (AlphaPool DATUM).
✅ Payout address (validated by your node): <PAYOUT_ADDRESS>
✅ Auto-start task "AlphaPool-DATUM" installed; firewall opened for TCP 23334; sleep disabled on AC.
➡️  Point every BLAKE2b miner (Antminer A3, Innosilicon S11, Obelisk SC1, iBeLink, …) at:
      URL:      stratum+tcp://<WINDOWS_LAN_IP>:23334
      Worker:   <PAYOUT_ADDRESS>   (or <PAYOUT_ADDRESS>.rigname)
      Password: x
📊 Your stats: https://knots.alphapool.tech/tides/miner   (enter the payout address)
🔧 Gateway UI (this PC only): http://127.0.0.1:7152  (admin password saved in the config)
🔒 RPC stays on localhost. Keep this PC on and logged in. Back up any wallet you created.

You are setting up a self-sovereign mining stack on this Ubuntu machine for a beginner:
a Bitcoin Knots full node (the Bitcoin BLAKE2b chain) plus a DATUM Gateway pointed at the
AlphaPool DATUM pool. The user's own node builds the blocks; the pool splits the coinbase and
pays the user's address directly inside each block. Non-custodial. No signup.

Work step by step. Run the commands yourself, verify each step, and STOP AND ASK if anything
is ambiguous or fails. Explain briefly what you are doing as you go. Be idempotent: if a step
is already done, verify it and move on instead of redoing it. Never run anything as root
except via sudo where shown. Never open RPC to the network. Never modify any Bitcoin wallet or
data directory except the ones this guide creates.

==================================================================================
FACTS — use exactly, do not "improve" them
==================================================================================
Chain:            Bitcoin BLAKE2b (Bitcoin Knots 29.4.1 mainnet). Last SHA256d block 961639;
                  first BLAKE2b block 961640. Do NOT set chain=testnet4/regtest.
Node software:    Bitcoin Knots 29.4.1.knots20260508 (official build)
Download base:    https://bitcoinknots.org/files/29.x/29.4.1.knots20260508/
  x86_64 file:    bitcoin-29.4.1.knots20260508-x86_64-linux-gnu.tar.gz
  aarch64 file:   bitcoin-29.4.1.knots20260508-aarch64-linux-gnu.tar.gz
  checksums:      SHA256SUMS  (same folder) — verification is MANDATORY
Gateway software: CONVOY DATUM Gateway (BLAKE2b + header-v2 build)
  repo:           https://github.com/CONVOYMining/datum_gateway.git  (branch: master)
  required:       history MUST contain commit 56c31f4 (older builds produce invalid shares)
AlphaPool DATUM:  host us2.alphapool.tech   port 28916
  pool pubkey:    b831b2d6f1eaedb3da5b9e3702728edea0a32d6ce783a1452b2861c4d1b74d6b4c2ad5461bcf43485a6bac2cedf8da43d51164262ef6bcdb27f2242ada066d29
  fee:            2.00% pool ops, flat 8×D window split, paid in-block to the miner's address
Ports:            node P2P 8333 (optional inbound), node RPC 8332 (localhost ONLY),
                  gateway stratum 23334 (LAN), gateway UI/API 7152 (localhost ONLY)
Disk/time:        ~20 GB free (node is pruned). First sync downloads the chain's history:
                  plan on 1–3 days depending on connection/CPU. Mining starts automatically
                  once the node is synced — the gateway simply waits.

==================================================================================
STEP 0 — Ask the user (do not proceed with placeholders)
==================================================================================
Ask for ONE thing: the payout address the coinbase should pay.
  - Recommended: a native-SegWit address starting with bc1q from a wallet dedicated to THIS
    chain (the fork's Knots bitcoin-qt wallet, Shrike, or Sparrow-BLAKE2b). Legacy 1... and
    3... addresses are also valid. NEVER use a seed/wallet that also holds real Bitcoin.
  - If the user has no address, offer to create one in a fresh wallet on the node they are
    about to run (Step 5 describes how). Only do this if they explicitly say yes.
Optionally ask for a short coinbase tag (their name/handle, max ~20 chars). Default: AlphaPool.
Confirm they know: this machine should stay on and connected; first sync takes 1–3 days.

==================================================================================
STEP 1 — Prerequisites
==================================================================================
sudo apt update
sudo apt install -y git build-essential cmake pkgconf libcurl4-openssl-dev libjansson-dev \
  libsodium-dev libmicrohttpd-dev psmisc curl jq
Confirm: 64-bit Ubuntu (uname -m prints x86_64 or aarch64), >= 20 GB free (df -h ~),
RAM (free -g). Record the login username (whoami) — call it $U below.

==================================================================================
STEP 2 — Install Bitcoin Knots 29.4.1 (verify checksums — mandatory)
==================================================================================
mkdir -p ~/knots-dl && cd ~/knots-dl
ARCH=$(uname -m)   # x86_64 or aarch64
F="bitcoin-29.4.1.knots20260508-${ARCH}-linux-gnu.tar.gz"
curl -fLO "https://bitcoinknots.org/files/29.x/29.4.1.knots20260508/${F}"
curl -fLO "https://bitcoinknots.org/files/29.x/29.4.1.knots20260508/SHA256SUMS"
sha256sum --ignore-missing --check SHA256SUMS      # MUST print "<file>: OK". If not: STOP.
tar -xzf "$F"
sudo install -m 0755 bitcoin-*/bin/bitcoind bitcoin-*/bin/bitcoin-cli /usr/local/bin/
bitcoind --version | head -1       # expect "Bitcoin Knots version v29.4.1.knots20260508"

==================================================================================
STEP 3 — Configure the node (pruned mainnet, RPC on localhost)
==================================================================================
mkdir -p ~/.bitcoin && chmod 700 ~/.bitcoin
If ~/.bitcoin/bitcoin.conf already exists, STOP and show it to the user before changing it.
Generate credentials: RPCUSER=datum ; RPCPASS=$(openssl rand -hex 24)
Pick dbcache: 2048 if RAM >= 8 GB, else 1024.
Write ~/.bitcoin/bitcoin.conf (mode 600) with exactly:

server=1
daemon=0
rpcbind=127.0.0.1
rpcallowip=127.0.0.1
rpcuser=<RPCUSER>
rpcpassword=<RPCPASS>
prune=4000
dbcache=<2048 or 1024>
blockmaxweight=785000
blocknotify=curl -fsS -o /dev/null http://127.0.0.1:7152/NOTIFY
# Optional: forward TCP 8333 on the router to this machine so other nodes can reach you.

Create /etc/systemd/system/knots-node.service (via sudo tee):

[Unit]
Description=Bitcoin Knots node (BLAKE2b chain)
After=network-online.target
Wants=network-online.target
[Service]
Type=simple
User=$U
ExecStart=/usr/local/bin/bitcoind -conf=/home/$U/.bitcoin/bitcoin.conf -datadir=/home/$U/.bitcoin
Restart=on-failure
RestartSec=15
TimeoutStopSec=900
KillSignal=SIGTERM
[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload && sudo systemctl enable --now knots-node
Wait ~30 s, then: bitcoin-cli getblockchaininfo | jq '{chain,blocks,headers,verificationprogress,pruned}'
Expect chain "main", pruned true, and blocks/headers climbing. (verificationprogress reaches ~1.0
only when fully synced — that is the 1–3 day part. Continue with the remaining steps now.)

==================================================================================
STEP 4 — Validate the payout address with the node (protects against stranded coins)
==================================================================================
bitcoin-cli validateaddress "<PAYOUT_ADDRESS>" | jq '{isvalid,address,iswitness}'
"isvalid" MUST be true. If false: STOP and ask the user for a correct address. Coins mined to an
invalid address cannot be paid out.

==================================================================================
STEP 5 — (ONLY if the user asked) create a fresh payout wallet on this node
==================================================================================
bitcoin-cli -named createwallet wallet_name="alphapool-payout" descriptors=true
bitcoin-cli -rpcwallet=alphapool-payout getnewaddress "" bech32      # this is the payout address
bitcoin-cli -rpcwallet=alphapool-payout backupwallet "/home/$U/alphapool-payout-BACKUP.dat"
Tell the user in bold: copy /home/$U/alphapool-payout-BACKUP.dat to a safe place offline NOW.
If this file and ~/.bitcoin/wallets/alphapool-payout are lost, the coins are lost. Then run
Step 4 on the new address.

==================================================================================
STEP 6 — Build the CONVOY DATUM Gateway (BLAKE2b build)
==================================================================================
cd ~ && ( [ -d datum_gateway ] || git clone https://github.com/CONVOYMining/datum_gateway.git )
cd ~/datum_gateway && git checkout master && git pull --ff-only
git merge-base --is-ancestor 56c31f4 HEAD && echo "COMMIT CHECK OK" || echo "COMMIT CHECK FAILED"
If it prints FAILED: STOP. Do not mine with this build.
cmake . && make -j"$(nproc)"
ls -l ~/datum_gateway/datum_gateway      # the built binary must exist

==================================================================================
STEP 7 — Gateway config (pool mode → AlphaPool)
==================================================================================
APIPASS=$(openssl rand -hex 16)
Write ~/datum_gateway/datum_gateway_config.json (mode 600) with exactly this, filling the
<...> values (RPC creds from Step 3, payout address from Step 4, tag from Step 0):

{
  "bitcoind": {
    "rpcuser": "<RPCUSER>",
    "rpcpassword": "<RPCPASS>",
    "rpcurl": "http://127.0.0.1:8332"
  },
  "stratum": {
    "listen_addr": "0.0.0.0",
    "listen_port": 23334,
    "vardiff_min": 4096,
    "vardiff_target_shares_min": 8
  },
  "api": {
    "listen_addr": "127.0.0.1",
    "listen_port": 7152,
    "admin_password": "<APIPASS>",
    "modify_conf": true
  },
  "mining": {
    "pool_address": "<PAYOUT_ADDRESS>",
    "coinbase_tag_primary": "AlphaPool",
    "coinbase_tag_secondary": "<TAG>",
    "allow_hasher_time_rolling": false
  },
  "datum": {
    "pool_host": "us2.alphapool.tech",
    "pool_port": 28916,
    "pool_pubkey": "b831b2d6f1eaedb3da5b9e3702728edea0a32d6ce783a1452b2861c4d1b74d6b4c2ad5461bcf43485a6bac2cedf8da43d51164262ef6bcdb27f2242ada066d29",
    "pool_pass_workers": true,
    "pool_pass_full_users": true,
    "pooled_mining_only": true
  }
}

Validate JSON: jq . ~/datum_gateway/datum_gateway_config.json >/dev/null && echo JSON OK

==================================================================================
STEP 8 — Run the gateway as a service (it waits for the node to finish syncing)
==================================================================================
Create /etc/systemd/system/datum-gateway.service (via sudo tee):

[Unit]
Description=DATUM Gateway → AlphaPool
After=knots-node.service network-online.target
Wants=knots-node.service
[Service]
Type=simple
User=$U
WorkingDirectory=/home/$U/datum_gateway
ExecStart=/home/$U/datum_gateway/datum_gateway -c /home/$U/datum_gateway/datum_gateway_config.json
Restart=always
RestartSec=10
[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload && sudo systemctl enable --now datum-gateway
systemctl status datum-gateway --no-pager | head -12
NOTE: until the node is fully synced the gateway will log that templates are unavailable and
retry — that is expected. Do not "fix" it.

==================================================================================
STEP 9 — Let miners on the LAN reach the gateway
==================================================================================
LANIP=$(ip -4 route get 1.1.1.1 | awk '{print $7; exit}')
If ufw is active (sudo ufw status): sudo ufw allow 23334/tcp
The miners will use: stratum+tcp://$LANIP:23334

==================================================================================
STEP 10 — Verify (run all, report results)
==================================================================================
systemctl is-active knots-node datum-gateway                  # both "active"
bitcoin-cli getblockchaininfo | jq '{blocks,headers,verificationprogress}'
bitcoin-cli getdeploymentinfo | jq '.deployments.blake2b'     # active:true once synced past 961640
journalctl -u datum-gateway -n 15 --no-pager
curl -s -o /dev/null -w "gateway UI http %{http_code}\n" http://127.0.0.1:7152/
Once synced, also: bitcoin-cli getblocktemplate '{"rules":["segwit","blake2b"]}' | jq -r '.rules[]'
  → must include "!blake2b".

==================================================================================
FINAL REPORT — print this for the user, filled in
==================================================================================
✅ Node: Bitcoin Knots 29.4.1 running as service knots-node (pruned). Sync: <X>% — mining starts
   automatically when this reaches 100% (est. 1–3 days). Check anytime:
   bitcoin-cli getblockchaininfo | jq .verificationprogress
✅ Gateway: datum-gateway service running, pointed at us2.alphapool.tech:28916 (AlphaPool DATUM).
✅ Payout address (validated by your node): <PAYOUT_ADDRESS>
➡️  Point every BLAKE2b miner (Antminer A3, Innosilicon S11, Obelisk SC1, iBeLink, …) at:
      URL:      stratum+tcp://<LANIP>:23334
      Worker:   <PAYOUT_ADDRESS>   (or <PAYOUT_ADDRESS>.rigname)
      Password: x
📊 Your stats: https://knots.alphapool.tech/tides/miner   (enter the payout address)
🔧 Gateway UI (this machine only): http://127.0.0.1:7152  (admin password saved in the config)
🔒 RPC stays on localhost. Keep this machine on. Back up any wallet you created.

You are setting up a self-sovereign mining stack on this Mac for a beginner: a Bitcoin Knots
full node (the Bitcoin BLAKE2b chain) plus a DATUM Gateway pointed at the AlphaPool DATUM pool.
The user's own node builds the blocks; the pool splits the coinbase and pays the user's
address directly inside each block. Non-custodial. No signup.

Work step by step. Run the commands yourself, verify each step, and STOP AND ASK if anything
is ambiguous or fails. Explain briefly what you are doing. Be idempotent: if a step is already
done, verify it and move on. Use sudo only where shown. Never open RPC to the network. Never
modify any Bitcoin wallet or data directory except the ones this guide creates.

==================================================================================
FACTS — use exactly, do not "improve" them
==================================================================================
Chain:            Bitcoin BLAKE2b (Bitcoin Knots 29.4.1 mainnet). First BLAKE2b block 961640.
                  Do NOT set chain=testnet4/regtest.
Node software:    Bitcoin Knots 29.4.1.knots20260508 (official signed macOS build)
Download base:    https://bitcoinknots.org/files/29.x/29.4.1.knots20260508/
  Apple Silicon:  bitcoin-29.4.1.knots20260508-arm64-apple-darwin.tar.gz
  Intel:          bitcoin-29.4.1.knots20260508-x86_64-apple-darwin.tar.gz
  checksums:      SHA256SUMS  (same folder) — verification is MANDATORY
Gateway software: CONVOY DATUM Gateway (BLAKE2b + header-v2 build)
  repo:           https://github.com/CONVOYMining/datum_gateway.git  (branch: master)
  required:       history MUST contain commit 56c31f4 (older builds produce invalid shares)
AlphaPool DATUM:  host us2.alphapool.tech   port 28916
  pool pubkey:    b831b2d6f1eaedb3da5b9e3702728edea0a32d6ce783a1452b2861c4d1b74d6b4c2ad5461bcf43485a6bac2cedf8da43d51164262ef6bcdb27f2242ada066d29
  fee:            2.00% pool ops, flat 8×D window split, paid in-block to the miner's address
Ports:            node P2P 8333 (optional), node RPC 8332 (localhost ONLY),
                  gateway stratum 23334 (LAN), gateway UI/API 7152 (localhost ONLY)
Paths (macOS):    node data  $HOME/Library/Application Support/Bitcoin
                  gateway    $HOME/datum_gateway
                  services   $HOME/Library/LaunchAgents (launchd user agents)
                  logs       $HOME/Library/Logs/knots-node.log, datum-gateway.log
Disk/time:        ~20 GB free (node is pruned). First sync downloads the chain's history:
                  plan on 1–3 days. Mining starts automatically once synced — the gateway waits.
Note:             A Mac that sleeps stops mining. A desktop/Mac mini is ideal; a laptop must stay
                  plugged in with the lid open (or clamshell + external display).

==================================================================================
STEP 0 — Ask the user (do not proceed with placeholders)
==================================================================================
Ask for ONE thing: the payout address the coinbase should pay.
  - Recommended: a native-SegWit address starting with bc1q from a wallet dedicated to THIS
    chain (the fork's Knots bitcoin-qt wallet, Shrike, or Sparrow-BLAKE2b). Legacy 1... and
    3... addresses are also valid. NEVER use a seed/wallet that also holds real Bitcoin.
  - If the user has no address, offer to create one in a fresh wallet on the node they are
    about to run (Step 5). Only do this if they explicitly say yes.
Optionally ask for a short coinbase tag (their name/handle). Default: AlphaPool.
Ask whether you may disable system sleep (pmset) so the Mac keeps mining. Confirm 1–3 day sync.

==================================================================================
STEP 1 — Prerequisites (Xcode CLT + Homebrew + libraries)
==================================================================================
uname -m                      # arm64 (Apple Silicon) or x86_64 (Intel) — call it $ARCH
xcode-select -p || xcode-select --install     # if it opens a dialog, wait for it to finish
brew --version || echo "Homebrew missing"     # if missing, install from https://brew.sh (the
                                              # user must approve; then re-open the terminal)
brew install cmake pkgconf curl jansson libsodium libmicrohttpd argp-standalone epoll-shim git jq
df -h ~                        # need >= 20 GB free
sysctl -n hw.memsize           # bytes; >= 8 GiB → dbcache 2048, else 1024

==================================================================================
STEP 2 — Install Bitcoin Knots 29.4.1 (verify checksums — mandatory)
==================================================================================
mkdir -p ~/knots-dl && cd ~/knots-dl
F="bitcoin-29.4.1.knots20260508-${ARCH}-apple-darwin.tar.gz"
curl -fLO "https://bitcoinknots.org/files/29.x/29.4.1.knots20260508/${F}"
curl -fLO "https://bitcoinknots.org/files/29.x/29.4.1.knots20260508/SHA256SUMS"
grep " ${F}\$" SHA256SUMS | shasum -a 256 -c -      # MUST print "<file>: OK". If not: STOP.
tar -xzf "$F"
xattr -dr com.apple.quarantine bitcoin-*/ 2>/dev/null || true     # avoid Gatekeeper blocks
sudo mkdir -p /usr/local/bin
sudo install -m 0755 bitcoin-*/bin/bitcoind bitcoin-*/bin/bitcoin-cli /usr/local/bin/
bitcoind --version | head -1       # expect "Bitcoin Knots version v29.4.1.knots20260508"

==================================================================================
STEP 3 — Configure the node (pruned mainnet, RPC on localhost) and run it via launchd
==================================================================================
D="$HOME/Library/Application Support/Bitcoin"; mkdir -p "$D"; chmod 700 "$D"
If "$D/bitcoin.conf" already exists, STOP and show it to the user before changing it.
Generate: RPCUSER=datum ; RPCPASS=$(openssl rand -hex 24)
Write "$D/bitcoin.conf" (mode 600) with exactly:

server=1
daemon=0
rpcbind=127.0.0.1
rpcallowip=127.0.0.1
rpcuser=<RPCUSER>
rpcpassword=<RPCPASS>
prune=4000
dbcache=<2048 or 1024>
blockmaxweight=785000
blocknotify=curl -fsS -o /dev/null http://127.0.0.1:7152/NOTIFY

Write ~/Library/LaunchAgents/tech.alphamine.knots-node.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0"><dict>
  <key>Label</key><string>tech.alphamine.knots-node</string>
  <key>ProgramArguments</key><array>
    <string>/usr/local/bin/bitcoind</string>
    <string>-conf=/Users/<USER>/Library/Application Support/Bitcoin/bitcoin.conf</string>
    <string>-datadir=/Users/<USER>/Library/Application Support/Bitcoin</string>
  </array>
  <key>RunAtLoad</key><true/>
  <key>KeepAlive</key><true/>
  <key>ExitTimeOut</key><integer>900</integer>
  <key>StandardOutPath</key><string>/Users/<USER>/Library/Logs/knots-node.log</string>
  <key>StandardErrorPath</key><string>/Users/<USER>/Library/Logs/knots-node.log</string>
</dict></plist>

launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/tech.alphamine.knots-node.plist \
  || launchctl kickstart -k gui/$(id -u)/tech.alphamine.knots-node
sleep 30; bitcoin-cli getblockchaininfo | jq '{chain,blocks,headers,verificationprogress,pruned}'
Expect chain "main", pruned true, blocks/headers climbing. (Full sync = 1–3 days; keep going.)

==================================================================================
STEP 4 — Validate the payout address with the node (protects against stranded coins)
==================================================================================
bitcoin-cli validateaddress "<PAYOUT_ADDRESS>" | jq '{isvalid,address,iswitness}'
"isvalid" MUST be true. If false: STOP and ask for a correct address.

==================================================================================
STEP 5 — (ONLY if the user asked) create a fresh payout wallet on this node
==================================================================================
bitcoin-cli -named createwallet wallet_name="alphapool-payout" descriptors=true
bitcoin-cli -rpcwallet=alphapool-payout getnewaddress "" bech32          # the payout address
bitcoin-cli -rpcwallet=alphapool-payout backupwallet "$HOME/alphapool-payout-BACKUP.dat"
Tell the user in bold: copy ~/alphapool-payout-BACKUP.dat to a safe place offline NOW. If it and
the wallet folder are lost, the coins are lost. Then run Step 4 on the new address.

==================================================================================
STEP 6 — Build the CONVOY DATUM Gateway (BLAKE2b build)
==================================================================================
cd ~ && ( [ -d datum_gateway ] || git clone https://github.com/CONVOYMining/datum_gateway.git )
cd ~/datum_gateway && git checkout master && git pull --ff-only
git merge-base --is-ancestor 56c31f4 HEAD && echo "COMMIT CHECK OK" || echo "COMMIT CHECK FAILED"
If FAILED: STOP. Do not mine with this build.
export PKG_CONFIG_PATH="$(brew --prefix)/lib/pkgconfig:$PKG_CONFIG_PATH"
cmake -DCMAKE_PREFIX_PATH="$(brew --prefix)" . && make -j"$(sysctl -n hw.ncpu)"
ls -l ~/datum_gateway/datum_gateway      # the built binary must exist

==================================================================================
STEP 7 — Gateway config (pool mode → AlphaPool)
==================================================================================
APIPASS=$(openssl rand -hex 16)
Write ~/datum_gateway/datum_gateway_config.json (mode 600) with exactly this, filling <...>:

{
  "bitcoind": {
    "rpcuser": "<RPCUSER>",
    "rpcpassword": "<RPCPASS>",
    "rpcurl": "http://127.0.0.1:8332"
  },
  "stratum": {
    "listen_addr": "0.0.0.0",
    "listen_port": 23334,
    "vardiff_min": 4096,
    "vardiff_target_shares_min": 8
  },
  "api": {
    "listen_addr": "127.0.0.1",
    "listen_port": 7152,
    "admin_password": "<APIPASS>",
    "modify_conf": true
  },
  "mining": {
    "pool_address": "<PAYOUT_ADDRESS>",
    "coinbase_tag_primary": "AlphaPool",
    "coinbase_tag_secondary": "<TAG>",
    "allow_hasher_time_rolling": false
  },
  "datum": {
    "pool_host": "us2.alphapool.tech",
    "pool_port": 28916,
    "pool_pubkey": "b831b2d6f1eaedb3da5b9e3702728edea0a32d6ce783a1452b2861c4d1b74d6b4c2ad5461bcf43485a6bac2cedf8da43d51164262ef6bcdb27f2242ada066d29",
    "pool_pass_workers": true,
    "pool_pass_full_users": true,
    "pooled_mining_only": true
  }
}
jq . ~/datum_gateway/datum_gateway_config.json >/dev/null && echo JSON OK

==================================================================================
STEP 8 — Run the gateway via launchd (it waits for the node to finish syncing)
==================================================================================
Write ~/Library/LaunchAgents/tech.alphamine.datum-gateway.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0"><dict>
  <key>Label</key><string>tech.alphamine.datum-gateway</string>
  <key>ProgramArguments</key><array>
    <string>/Users/<USER>/datum_gateway/datum_gateway</string>
    <string>-c</string>
    <string>/Users/<USER>/datum_gateway/datum_gateway_config.json</string>
  </array>
  <key>WorkingDirectory</key><string>/Users/<USER>/datum_gateway</string>
  <key>RunAtLoad</key><true/>
  <key>KeepAlive</key><true/>
  <key>ThrottleInterval</key><integer>10</integer>
  <key>StandardOutPath</key><string>/Users/<USER>/Library/Logs/datum-gateway.log</string>
  <key>StandardErrorPath</key><string>/Users/<USER>/Library/Logs/datum-gateway.log</string>
</dict></plist>

launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/tech.alphamine.datum-gateway.plist \
  || launchctl kickstart -k gui/$(id -u)/tech.alphamine.datum-gateway
tail -n 15 ~/Library/Logs/datum-gateway.log
NOTE: until the node is fully synced the gateway logs that templates are unavailable and
retries — expected. Do not "fix" it.
If the macOS firewall is on (/usr/libexec/ApplicationFirewall/socketfilterfw --getglobalstate):
  sudo /usr/libexec/ApplicationFirewall/socketfilterfw --add ~/datum_gateway/datum_gateway
  sudo /usr/libexec/ApplicationFirewall/socketfilterfw --unblockapp ~/datum_gateway/datum_gateway
If the user approved: sudo pmset -a sleep 0 disksleep 0 displaysleep 10

==================================================================================
STEP 9 — Verify (run all, report results)
==================================================================================
launchctl print gui/$(id -u)/tech.alphamine.knots-node | grep -E "state|pid"
launchctl print gui/$(id -u)/tech.alphamine.datum-gateway | grep -E "state|pid"
bitcoin-cli getblockchaininfo | jq '{blocks,headers,verificationprogress}'
bitcoin-cli getdeploymentinfo | jq '.deployments.blake2b'     # active:true once synced past 961640
curl -s -o /dev/null -w "gateway UI http %{http_code}\n" http://127.0.0.1:7152/
LANIP=$(ipconfig getifaddr en0 || ipconfig getifaddr en1)
Once synced, also: bitcoin-cli getblocktemplate '{"rules":["segwit","blake2b"]}' | jq -r '.rules[]'
  → must include "!blake2b".

==================================================================================
FINAL REPORT — print this for the user, filled in
==================================================================================
✅ Node: Bitcoin Knots 29.4.1 running via launchd (tech.alphamine.knots-node, pruned).
   Sync: <X>% — mining starts automatically at 100% (est. 1–3 days). Check anytime:
   bitcoin-cli getblockchaininfo | jq .verificationprogress
✅ Gateway: tech.alphamine.datum-gateway running, pointed at us2.alphapool.tech:28916 (AlphaPool).
✅ Payout address (validated by your node): <PAYOUT_ADDRESS>
➡️  Point every BLAKE2b miner (Antminer A3, Innosilicon S11, Obelisk SC1, iBeLink, …) at:
      URL:      stratum+tcp://<LANIP>:23334
      Worker:   <PAYOUT_ADDRESS>   (or <PAYOUT_ADDRESS>.rigname)
      Password: x
📊 Your stats: https://knots.alphapool.tech/tides/miner   (enter the payout address)
🔧 Gateway UI (this Mac only): http://127.0.0.1:7152  (admin password saved in the config)
🔒 RPC stays on localhost. Keep this Mac awake and plugged in. Back up any wallet you created.