Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Getting Started

Three paths to a running pool:

  1. Docker — multi-arch image, runs on Umbrel-Box, NAS, or any Linux/macOS host
  2. Native Binary — .deb / .rpm / .dmg / .msi / .AppImage for bare-metal hosts and Raspberry Pi 5
  3. From Source — for development or verification

Prerequisite in every case: a running Bitcoin Core (≥27.0 recommended) with the getblocktemplate RPC and ZMQ block-notify enabled. GBT is the default template source. Bitcoin Core ≥31 additionally offers an experimental Cap’n-Proto IPC interface, which the pool can use as an opt-in alternative template source ([node].template_source = "ipc") for a faster template step — see Configuration Reference.

Docker

docker run -d \
  --name warppool \
  --restart unless-stopped \
  -p 18334:18334 \
  -p 3333:3333 \
  -v ~/.warppool:/data \
  git.warppool.org/dvb-projekt/dvb-warppool:latest

Add -p 3334:3334 (V1 TLS) and -p 34254:34254 (Stratum V2) if you enable those listeners.

The container’s default entrypoint is the daemon, so the pool UI comes up at http://localhost:18334. To run the first-run wizard (auto-detects hardware, suggests a profile, tests the Bitcoin RPC) instead, start the container with the wizard binary:

docker run --rm -it -p 8331:8331 -v ~/.warppool:/data \
  git.warppool.org/dvb-projekt/dvb-warppool:latest \
  dvb-warppool-setup --bind 0.0.0.0:8331

Native Binary

Raspberry Pi 5 (aarch64)

# arm64 .deb
wget https://git.warppool.org/dvb-projekt/dvb-WarpPool/releases/download/v1.24.0/dvb-warppool_1.24.0-1_arm64.deb
sudo dpkg -i dvb-warppool_1.24.0-1_arm64.deb
sudo systemctl enable --now dvb-warppool

Storage recommendation: NVMe-HAT > USB-3 SSD > industrial SD. The SQLite WAL plus shares_raw eviction is hard on SD cards under sustained pool load.

macOS / Linux x86_64

Tarball/pkg from the releases page. The macOS .dmg is not signed with an Apple Developer ID and not notarized (that is on the roadmap as phase B), so Gatekeeper flags the download. Strip the quarantine attribute from the .dmg and from the installed app:

xattr -dr com.apple.quarantine ~/Downloads/dvb-WarpPool-v*.dmg
# …mount, drag to /Applications, then:
xattr -dr com.apple.quarantine /Applications/dvb-WarpPool.app

From Source

git clone https://git.warppool.org/dvb-projekt/dvb-WarpPool
cd dvb-WarpPool
cargo build --release --workspace
./target/release/dvb-warppool-setup     # first-run wizard on :8331

Build artifacts land in target/ as usual. If your checkout lives inside a syncing folder (iCloud Drive, Dropbox, …), point cargo somewhere local instead — either export CARGO_TARGET_DIR=~/.cache/dvb-WarpPool/target or a personal, git-ignored .cargo/config.toml with [build] target-dir = …. Adjust the binary path above accordingly.

Stratum V1 vs V2

The pool can run all three listeners side by side in one process. Only the plain V1 listener is on by default; the other two start once they are configured:

  • V1 plain (:3333) — all existing miner firmwares
  • V1 TLS (:3334) — if stratum_tls_listen + cert/key are set in config.toml
  • V2 NOISE-NX (:34254) — if sv2_listen is set. Requires sv2_authority_priv_key_hex in secrets.toml; generate it with dvb-warppool-cli gen-sv2-key. Without the key Sv2 stays disabled with a warning in the log.

The V1 TLS and Sv2 ports are free to choose — :3334 and :34254 are just the values used throughout this handbook. The connect modal in the UI always shows the exact host:port the running instance listens on.

For V1-miner sidecars (e.g. when the pool should expose only Sv2 externally): the bundled dvb-warppool-translator binary. See Phase History → 7.4.

Both transports also support the per-worker payout mode (each miner mines to its own address from the Stratum login) and the public wallet pages at /users/<address>. See Public 0% Solo Pool.

First Block

  1. Configure your miner with stratum+tcp://<pool-host>:3333 as the pool
  2. Use your BTC receive address as the worker name (e.g. bc1q...)
  3. Open the pool UI at http://<pool-host>:18334
  4. The pool hashrate chart shows shares live; the /blocks tab shows found blocks

When a block lands → BlockFoundEvent runs immediately through bitcoin-rpc::submit_block and the notifier sends ntfy / Telegram / Discord / Slack / Email / browser push.

Reading the hashrate chart

The 24-hour dashboard chart shows two things at once, on two axes:

  • The filled area line is the pool hashrate, estimated from accepted shares in 1-minute buckets, read against the left axis (auto-scaled — H/s, KH/s, … up to TH/s).
  • The amber dots are best-share peaks — for each time bucket, the highest real share difficulty seen in it — plotted against a separate right axis (share difficulty, scaled K/M/G/T…). They are not on the left hashrate axis.

The line and the dots answer different questions: the line is how much work is flowing, a dot is how close the best share in that slice came to solving a block. The higher a dot, the rarer that share; the all-time best also appears as Best Share on the dashboard. This is the share’s real hash difficulty, independent of the VarDiff target the miner runs at.

The dots come from the per-bucket peak difficulty carried in /api/hashrate — hover the chart to read the value for that slice. The right axis and the dots only appear on the full chart once at least one peak has been recorded; mini charts and a brand-new pool show the line only. After upgrading from an older version the dots fill in over the first ~24 h, as peak data is recorded going forward.

Next Steps