Introduction

dvb-WarpPool is a Rust Bitcoin solo mining pool, written as a modern parallel build to dvb-goPool. Run it privately (mine to your own address) or as a public, non-custodial 0% pool where every visiting miner mines to their own address (per-worker payouts) — either way the finder is paid directly on-chain. See the Public 0% Solo Pool guide. Focus areas:

1. Performance — Rust async (Tokio), pure-Rust ZMQ + NOISE (no libzmq / OpenSSL required), reproducible release builds
2. Miner compatibility — Nerdminer V2, Bitaxe (AxeOS), Avalon Q, Antminer S21/S23 Pro, Whatsminer (MicroBT), NerdNOS/Octaxe
3. OS compatibility — macOS (Intel + Apple Silicon), Windows, Linux x86_64 + aarch64 (deb/rpm/AppImage), Raspberry Pi 5, Umbrel (Docker)
4. Security — memory safety, TLS, JWT + 2FA-TOTP + API tokens, audit log, signed releases (cosign), reproducible builds, auto-update with on-failure rollback
5. Stratum V1 + V2 — plain + TLS for V1, NOISE-NX for V2, V1↔V2 translator as a sidecar
6. Admin profiles — Small / Medium / Large / Enterprise (hot-switch)
7. Modern UI — SvelteKit PWA with i18n (DE/EN/ES/PT-BR/FR/IT/JA/ZH), HealthBanner + UpdateBanner via SSE events, operator marquee announcement banner (Admin → Banner, since v1.21.0), mobile-first
8. Observability — Prometheus /metrics + notifier sinks (ntfy / Telegram / Discord / Slack / Email) + RPC latency histogram

Current Status

The v1.0 line is released and maintained. Latest tag: v1.24.0 (2026-07-24) — the releases page always carries the current version. The phase table below covers the development history that led up to v1.0; post-1.0 changes are tracked in CHANGELOG.md.

Recognized miner vendors (12): Bitaxe / BitForge Nano / NerdMiner / NerdAxe Gamma / NerdQaxe / NerdNOS / NerdOctaxe / BitMain-Stock / Whatsminer / Avalon (A12xx-A15xx) / Avalon Q / Braiins OS / OS+.

Notifier sinks (6): ntfy / Telegram / Discord / Slack / Email-SMTP / VAPID Web Push (PWA background).

Tests (as of v1.24.0): 1201 Rust tests green + 4 ignored (regtest opt-in). 374 svelte-check files / 0 errors / 0 warnings.

Workspace: 18 library crates + 6 binaries (daemon, CLI, setup wizard, translator sidecar, miner simulator, macOS launcher). Single workspace, no external sub-repo.

What’s still open:

• Phase 7.6b — the Sv2 TDP wire path (Option A) is still deferred; the modern template-acquisition goal itself shipped in v1.16.0 as the opt-in Core IPC template source (Option B)

Who builds the pool

dvb-WarpPool is a solo project by dvb-Projekt (dvbprojekt@gmx.de). Code is dual-licensed: AGPL-3.0-or-later for everyone, plus a commercial license for proprietary use (see COMMERCIAL-LICENSE.md). Contributions welcome — see CONTRIBUTING.md for the licensing terms.

Where to find what

Operator Handbook

Architecture

Sv2 Stack

Quick Links

• Source: git.warppool.org/dvb-projekt/dvb-WarpPool
• Documentation: docs.warppool.org
• Public reference instance: pool.warppool.org — non-custodial per-worker mode, 0% fee
• Release pipeline + SBOM: .github/workflows/release.yml
• Bench workflow: .github/workflows/benches.yml
• Repro-verify: scripts/verify-reproducible.sh
• Regtest setup: scripts/regtest-up.sh + regtest-down.sh
• Sister project (Go implementation): dvb-goPool

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

• Configuration Reference — all config.toml fields
• Public 0% Solo Pool — per-worker mode (each miner mines to its own address) + public wallet pages at /users/<address>
• Notifications — set up notifier sinks
• Observability — Prometheus endpoint + Grafana
• Troubleshooting — when something isn’t working

Comparison: dvb-WarpPool vs. ckpool vs. public-pool vs. mkpool

Choosing a self-hosted solo pool comes down to a handful of open-source candidates. This page compares them feature by feature so you can pick the right tool for your setup.

How this table was made — and how to read it fairly:

• Every claim was verified against the source code of the compared projects, not against their marketing. Full re-verification on 2026-07-21 against ckpool master 308410d (2026-07-20), public-pool master 96a9202 (2026-06-05, one commit past 95565ee, which the Umbrel app pins), and mkpool master d2e4819 (2026-07-19). dvb-WarpPool claims reflect v1.24.0.
• All four are actively maintained open-source projects making different trade-offs. ckpool has been the workhorse of solo mining for a decade (the hosted solo.ckpool.org has found hundreds of mainnet blocks); mkpool is a modern multi-coin C++ engine; public-pool is the familiar TypeScript pool with a web UI. Nothing here means “those are bad.”
• The table tracks what ships in the open-source code. Hosted instances (solo.ckpool.org, public-pool.io, mkpool.com) run additional private code you don’t get when self-hosting — mkpool’s README states its database/analytics service, REST API and website are not in the open release, so those rows reflect the engine only. Where a project’s README claims a feature its open code doesn’t implement, we go by the code — and equally, where the code has moved ahead of what this page used to say, the code wins (mkpool’s multi-node failover was listed here as unimplemented and is now wired up end to end).
• Competitor repos move. If a cell is outdated, open an issue — this page is only useful while it’s accurate. All rows — ours and the competitors’ — were last verified 2026-07-21 against the commits named above. The 2026-07-21 pass changed several rows in the competitors’ favour: ckpool has gained a Bitcoin Core IPC template path and BIP54 coinbase handling, and mkpool has gained working multi-node failover, tagged releases and CI. Those corrections are reflected below. The address-ownership owner-panel row was re-verified 2026-07-24 against fresh heads (ckpool 308410d, public-pool 96a9202, mkpool 4785cd5): none of the three has any signed-message ownership mechanism.

Note on the IPC template source — no firstness claim

This row previously said that none of the compared pools carried a Bitcoin Core IPC path. That is no longer true: as of the 2026-07-21 re-check, ckpool ships an in-tree Cap’n Proto mining IPC implementation (ipc/mining/mining.capnp, ipc/mining/mining_ipc.cpp) used for both block notification and template generation, opt-in via the ipcmining and ipctemplate config keys and falling back to getblocktemplate. That is architecturally the same choice dvb-WarpPool made. public-pool and mkpool still go through getblocktemplate only.

It is explicitly not a claim to be “first” or “fastest” with IPC. Stratum Reference Implementation (SRI) was the first consumer of Core’s IPC mining interface, and other projects outside this three-way comparison may well use it too. Core’s IPC interface is itself experimental and has broken its mining.capnp schema across releases, which is why dvb-WarpPool keeps GBT+ZMQ as the default and ships IPC strictly opt-in. The latency figures are our own measurements on our own hardware, not a cross-pool benchmark.

When the others are the better pick

Honesty cuts both ways:

• ckpool — a minimal, battle-hardened C daemon with a decade of track record, if you’re comfortable with logfiles and a unix socket as your interface. It needs the least trust in young code.
• public-pool — the exact software behind public-pool.io, a familiar UI, and a large user base running the same commit.
• mkpool — if you want multi-coin solo mining (BTC, BCH, LTC, merge-mined DOGE, ZEC and more from one binary), fixed-difficulty ports, RPC-node failover, or a lean modern C++ engine, and you don’t need a built-in operator UI, device telemetry, or packaged/signed releases. It also now ships proxy, passthrough and redirector roles for scaling out across machines, and it’s already live on mainnet.
• dvb-WarpPool — if you run mixed home hardware (NerdMiner next to a Bitaxe next to an Avalon), want TLS / SV2 / notifications / energy tracking and a full operator UI without bolting on extra services, and value tested, signed, reproducible releases. Bitcoin-only by design.

See also

• Performance Benchmarks — measured numbers behind the claims, including the 1,000-miner load test
• Scaling Tiers — what this pool is and isn’t designed for
• Getting Started

Solo + Friends — Full TLS Setup Guide

This guide turns a self-hosted dvb-WarpPool into a friends-only pool reachable from the internet via TLS with a real Let’s Encrypt certificate. The OSS distribution covers this tier (see scaling.md) — no commercial extensions needed.

Target audience: you run WarpPool on a Mac or Linux at home with a Fritz!Box (or similar router with DDNS support). You want to invite 5-10 trusted friends to point their miners at your pool over the internet.

Time required: about 15-20 minutes.

Contents

1. Why DuckDNS + Let’s Encrypt
2. Phase 1 — Create a DuckDNS account
3. Phase 2 — Configure router DDNS
4. Phase 3 — Open port 3334 on the router
5. Phase 4 — Run the setup script
6. Phase 5 — Restart the daemon
7. Phase 6 — Verify the certificate
8. Phase 7 — Move your own miners over
9. Phase 8 — Invite your friends
10. Sleep prevention on macOS
11. Maintenance
12. Troubleshooting
13. Security notes for this tier
14. Cheat sheet

Why DuckDNS + Let’s Encrypt

Bitaxe firmware in “Bundled CA” mode (the secure default) validates the server certificate against the Mozilla CA root bundle. A self-signed certificate, no matter how well crafted, is rejected. We need a real cert.

Real certs come free from Let’s Encrypt — but only for a DNS name, not a bare IP. So we also need a “name for your Mac on the internet”. DuckDNS provides exactly that: a free <yourname>.duckdns.org subdomain that always resolves to your current home IP, even when your ISP rotates it.

What you’ll have at the end:

• <sub>.duckdns.org resolves to your router’s public IP, automatically
• The router forwards port 3334 to your Mac
• Your Mac serves a valid Let’s Encrypt cert for <sub>.duckdns.org
• Bitaxes trust the cert (because Let’s Encrypt is in the bundle)
• External miners can connect with full TLS verification

Phase 1 — Create a DuckDNS account

Time: 2 minutes.

1. Open https://www.duckdns.org/ in your browser.
2. Sign in via GitHub, Twitter, Reddit, or Google in the top right.
3. You land on your dashboard. Note:
   • Token — a 32-character hex string at the top right
   • The empty subdomain field with an “add domain” button next to it
4. Type a subdomain name (e.g. warppool-oliver or mypool-mining — anything still free) and click “add domain”.
5. The subdomain appears in your list. Write down:
   • Subdomain (just the warppool-oliver part, no .duckdns.org)
   • Token (top right, 32 hex characters)

You’ll need both in Phase 2 and Phase 4.

Tip: Do not post the token in Slack/Discord/etc. Anyone with it can point your subdomain at a different IP.

Phase 2 — Configure router DDNS

Time: 3 minutes.

DDNS = Dynamic DNS. Your router calls DuckDNS every few minutes to say “the IP for warppool-oliver is now X”. That keeps your subdomain pointed at home even when your provider rotates the IP.

The exact menu paths differ per router. Below is the Fritz!Box workflow (very common in Germany). For other routers, look for “DynDNS” / “Dynamic DNS” in the WAN / Internet section.

Fritz!Box

1. Browser to http://fritz.box/ or http://192.168.178.1/.

2. Log in with your Fritz!Box password.

3. Left menu: Internet → Permit Access (or Freigaben).

4. Tab DynDNS.

5. Enable “Use DynDNS”.

6. DynDNS provider: “Custom” (or “Benutzerdefiniert”).

7. Update URL: paste exactly this line (replace <SUBDOMAIN> and <TOKEN> with your values):

   https://www.duckdns.org/update?domains=<SUBDOMAIN>&token=<TOKEN>&ip=<ipaddr>
   

   The <ipaddr> at the end is a placeholder that the Fritz!Box replaces with your current IP — leave it literally as <ipaddr>.

8. Domain name: <SUBDOMAIN>.duckdns.org (e.g. warppool-oliver.duckdns.org)

9. User: anything (e.g. none) — DuckDNS only checks the token.

10. Password: anything (e.g. none).

11. Click Apply / Übernehmen.

Verification

In a terminal on your Mac:

dig +short warppool-oliver.duckdns.org @8.8.8.8

Should return your public IP (compare with https://www.whatismyip.com/). If empty: wait 30 seconds and retry — the router needs to push its first update.

Phase 3 — Open port 3334 on the router

Time: 3 minutes.

External miners connect to <sub>.duckdns.org:3334 → the request hits your router → the router needs to know which device to forward it to (your Mac).

Fritz!Box

1. Internet → Permit Access → Port Forwarding (Portfreigaben).
2. Click “Add Device for Sharing” (or edit an existing entry if your Mac is already there).
3. Select your Mac (should appear as MacBook-Pro / mac-mini etc. with IP 192.168.178.10).
4. Click “New Sharing” → “Port Sharing”.
5. Application: “Other Application”.
6. Label: WarpPool TLS Stratum.
7. Protocol: TCP.
8. Port to device: 3334.
9. Public port: 3334.
10. Check “Enable sharing”.
11. OK → Apply.

Verification

On an external device (e.g. your phone with WiFi off, using mobile data):

nc -zv warppool-oliver.duckdns.org 3334

Should print Connection to ... port 3334 [tcp/*] succeeded!.

If it works from your Mac but not from outside, you have a NAT loopback issue on the router. Run the external test from a truly external device.

Phase 4 — Run the setup script

Time: 2 minutes.

Now we fetch the Let’s Encrypt cert.

1. Open a terminal.

2. Switch to the WarpPool folder — replace the path with wherever you cloned the repository:

   cd /path/to/dvb-WarpPool
   

3. Start the script:

   ./scripts/setup-tls-public.sh
   

4. The script will prompt:

   ? DuckDNS Subdomain (without .duckdns.org):
   

   → warppool-oliver

   ? DuckDNS Token (32-hex from your account settings):
   

   → paste the token from Phase 1

5. Then it runs:

   • Installs acme.sh (the Let’s Encrypt CLI client) if missing — ~30s
   • Fetches the cert via DNS-01 challenge:
     • Sets a TXT record at DuckDNS
     • Waits for DNS propagation (~30-60s)
     • Let’s Encrypt verifies the TXT record → confirms domain ownership
     • Cert is issued and saved locally
   • Installs cert + key into ~/Library/Application Support/dvb-WarpPool/tls/{cert,key}.pem
   • The old self-signed files are backed up as .bak-<unix-ts>
   • Registers itself in cron for 60-day auto-renewal

6. At the end you’ll see:

   ✓ TLS setup for warppool-oliver.duckdns.org complete
   
   Next steps:
     1) Restart the WarpPool daemon ...
     2) On the Bitaxe (Pool Configuration): ...
     3) Verify the Fritz!Box settings: ...
     4) Test (from outside or on LAN): ...
   

Phase 5 — Restart the daemon

Time: 30 seconds.

The daemon only reads the cert at startup, so restart it once:

pkill -f dvb-warppool-daemon
sleep 2
open /Applications/dvb-WarpPool.app

After 3-5 seconds the daemon is back. Verify:

tail -20 ~/Library/Application\ Support/dvb-WarpPool/daemon.log | grep -i "tls"

Should show:

spawning TLS stratum listener bind=0.0.0.0:3334 cert=/Users/.../tls/cert.pem
stratum-v1 TLS server listening bind=0.0.0.0:3334 max_conn=64

Phase 6 — Verify the certificate

Time: 1 minute.

Check that the cert appears valid from outside.

echo | openssl s_client -connect warppool-oliver.duckdns.org:3334 \
  -servername warppool-oliver.duckdns.org 2>&1 \
  | grep -E "Verify return code|subject=|issuer=|Server certificate"

Good (what you want):

subject=CN=warppool-oliver.duckdns.org
issuer=C=US, O=Let's Encrypt, CN=R10
Verify return code: 0 (ok)

Bad (something didn’t take):

subject=CN=dvb-WarpPool         ← still the self-signed cert
Verify return code: 18 (self-signed certificate)

If you see the bad result:

• Did you actually restart the daemon? pgrep -f dvb-warppool-daemon should show a different PID than before the restart.
• Does config.toml point at the new cert? grep tls_cert_path ~/Library/Application\ Support/dvb-WarpPool/config.toml

Verify return code: 0 means the cert is valid — Bitaxe firmware will accept it.

Phase 7 — Move your own miners over

Time: 2 minutes per miner.

Example for a BitForge Nano (web UI at http://192.168.178.44/):

1. Browser to http://192.168.178.44/.

2. Pool Configuration → Main Pool tab.

3. Set fields:

   Field	Value
   Stratum Host	warppool-oliver.duckdns.org
   Stratum Port	3334
   Stratum User	(unchanged: bc1q...YOUR_ADDRESS.BitForgeNano)
   Stratum Password	(unchanged, e.g. x)
   TLS	Enabled (Bundled CA) ← finally works

4. Click Save.

5. Bitaxe says “must restart this device after saving” → click Restart.

6. Bitaxe reboots. After ~20 seconds it’s back.

7. The Bitaxe UI should show an active pool connection again under “Status”, with shares ticking.

8. In the WarpPool admin at http://localhost:18334/: the worker table should still show the Bitaxe, with a 🔒 lock icon next to its name indicating the TLS connection. The “Active Miners” tile shows a “N TLS” sub-line counting your TLS connections.

→ Successfully migrated to TLS.

Repeat for any other miner you own (NerdOctaxe, NerdQaxe++, Avalon Q, etc.). ~2 minutes per miner.

Phase 8 — Invite your friends

Send them:

Hey, you can mine on my WarpPool:

• Pool: warppool-oliver.duckdns.org
• Port: 3334
• TLS: yes, “Enabled (Bundled CA)” / “Strict TLS”
• Username: <YOUR_OWN_bech32_address>.<any_worker_name>

Solo pool — 100% of the reward goes to whoever finds the block. If the pool is down, fall back to your backup.

Important: every friend uses their own wallet address as the stratum user. WarpPool is solo mining — the reward goes directly to the address the miner authorizes with.

Let the whole group get block alerts

The pool can push a block found notification to every friend’s phone the second it happens. The easiest way is a shared ntfy topic: you configure [notifier.ntfy] once on the pool, friends just install the ntfy app and subscribe to the topic name — no accounts needed. If you use it, add one line to the invite message above:

• Block alerts: install the ntfy app and subscribe to topic <your-topic-name>

A Telegram group or a Discord channel works too. Full walkthrough: Sharing notifications with friends.

Sleep prevention on macOS

Once your friends are connecting from outside, the pool needs to stay reachable 24/7. By default, macOS suspends the system after 3 hours of idle time (pmset sleep 180). While suspended:

• Bitcoin Core is frozen — getblocktemplate and submitblock time out
• Stratum TCP connections drop (Bitaxes log Connection reset by peer)
• The hashrate chart shows repeated drops to 0 throughout the night, with brief recovery whenever the Mac briefly wakes for Power Nap or notifications

This is handled automatically. Since v1.0.6, the Mac launcher wraps the daemon spawn with caffeinate -i -w <pid>:

• -i = prevent system idle sleep (CPU + network + Bitcoin Core stay up)
• -w PID = caffeinate exits automatically when the daemon dies → no zombie processes, no manual cleanup
• Display sleep keeps working — you can let the screen go dark, the screensaver runs, etc.

Verify it’s active:

ps -A -o pid,ppid,command | grep "caffeinate -i -w $(pgrep -f dvb-warppool-daemon | head -1)"

You should see one caffeinate -i -w <daemon-pid> line.

The admin profile page (/admin/profile) shows a green info card “✓ macOS sleep mode disabled” when this is active. If the card is missing, the launcher couldn’t spawn caffeinate (very unlikely — it’s a system binary on every macOS install).

What this does NOT handle

• Explicit sleep (Apple menu → Sleep, or closing a MacBook lid). The user asked for sleep, so the pool sleeps too. Open the lid / wiggle the mouse and the pool comes back within seconds (daemon stays running across short suspensions; longer suspensions trigger Bitaxe reconnects).
• Hard shutdown / power loss. Use a UPS if you’re worried about this.
• Force-quit of the launcher. If you kill the launcher process directly (Activity Monitor → Force Quit), the daemon survives but caffeinate’s parent process is gone, so caffeinate may exit. Use pkill -f dvb-warppool-daemon or re-open the .app to do a clean restart.

Power consumption

caffeinate -i is only a sleep-prevention flag — it doesn’t pin the CPU or keep the disk spinning. Your Mac mini / MacBook idles at whatever wattage it normally would when the screen is off. The actual pool workload (Stratum I/O + occasional Bitcoin Core RPC) is in the single-digit-watt range on Apple Silicon. No noticeable impact on a Mac mini’s electricity bill.

Disabling sleep prevention

If you want the Mac to be allowed to sleep (e.g. you don’t care about pool uptime overnight), kill the caffeinate process by hand:

pkill caffeinate

The daemon keeps running until macOS suspends it.

There’s currently no config flag to disable sleep prevention — it’s the correct behaviour for nearly every pool operator, and disabling it makes the pool unreliable. Open an issue if you have a real use case for opt-out.

Maintenance

Cert renewal

acme.sh does it automatically every 60 days (Let’s Encrypt certs are valid for 90 days). You don’t have to do anything except restart the daemon after a renewal happens, so it loads the new cert.

A pragmatic cron line that handles this for you:

crontab -e

Add:

0 4 * * * cd $HOME && ~/.acme.sh/acme.sh --cron > /dev/null 2>&1 && pkill -f dvb-warppool-daemon ; sleep 3 ; open /Applications/dvb-WarpPool.app

Runs daily at 4am: checks renewal status, restarts the daemon if anything changed. If there’s nothing to renew, the restart causes no harm — the daemon is back in ~5s and Bitaxes reconnect automatically.

Force a renewal manually

To test:

~/.acme.sh/acme.sh --renew --domain warppool-oliver.duckdns.org --force

The --force bypasses the 60-day limit.

IP changes

As long as the router stays in place, everything keeps working — it updates DuckDNS continuously. Only when you swap the router (new ISP, new hardware) do you need to re-do the DDNS config (Phase 2).

Stopping the pool

Nothing special — close the .app or pkill -f dvb-warppool-daemon. Friends’ Bitaxes automatically fail over to backup, then come back when your pool is back up.

Troubleshooting

Bitaxe says “TLS connection failed”

1. Router port forward gone? nc -zv warppool-oliver.duckdns.org 3334 from outside — must say “succeeded”.

2. DuckDNS not resolving, or pointing at the wrong IP? dig +short warppool-oliver.duckdns.org @8.8.8.8 — must show your current public IP (compare with curl ifconfig.me).

3. Cert expired? (shouldn’t happen because of auto-renewal, but just in case):

   echo | openssl s_client -connect warppool-oliver.duckdns.org:3334 \
     -servername warppool-oliver.duckdns.org 2>&1 \
     | openssl x509 -noout -dates
   

   notAfter=... should be at least 30 days in the future.

4. Bitaxe firmware cache: some Bitaxe firmware versions cache a failed cert. Power cycle the Bitaxe (unplug for 10s, replug). The reset button is not enough.

Script aborted somewhere

Running it again is OK — the script is idempotent. If e.g. acme.sh is already installed, it’s skipped.

To start completely fresh:

~/.acme.sh/acme.sh --remove --domain warppool-oliver.duckdns.org
rm -rf ~/.acme.sh/warppool-oliver.duckdns.org/

Then re-run the script.

Cert doesn’t load after restart

Daemon log still shows the old cert?

lsof -p $(pgrep -f dvb-warppool-daemon) | grep cert.pem

Should point at the new cert. If not: pkill -KILL -f dvb-warppool-daemon (instead of regular pkill) and re-open the .app.

“Rate Limit Exceeded” from Let’s Encrypt

You can only issue 5 certs per week per domain. If you’ve been testing and issued multiple: wait, or use the staging server:

~/.acme.sh/acme.sh --issue --dns dns_duckdns --domain warppool-oliver.duckdns.org \
  --server https://acme-staging-v02.api.letsencrypt.org/directory

Staging certs are NOT in the Mozilla CA bundle — they won’t work for Bitaxe, but they’re fine for verifying that the infrastructure is set up correctly.

Fully rolling back to self-signed

If you want to go back to LAN-only operation:

~/.acme.sh/acme.sh --remove --domain warppool-oliver.duckdns.org
cd ~/Library/Application\ Support/dvb-WarpPool/tls/
# Restore the .bak-* files the script created:
ls -la *.bak-*
# Copy the most recent cert.pem.bak-XXX and key.pem.bak-XXX back:
cp cert.pem.bak-<LATEST> cert.pem
cp key.pem.bak-<LATEST> key.pem
pkill -f dvb-warppool-daemon ; sleep 2 ; open /Applications/dvb-WarpPool.app

Then put the Bitaxe back on port 3333 without TLS (or TLS “Insecure” mode).

Security notes for this tier

This setup gives you:

• Encrypted Stratum traffic (TLS 1.3 with AES-256-GCM)
• Server identity verified via Let’s Encrypt → no man-in-the-middle attack can impersonate your pool
• Friends who type the wrong hostname get a cert mismatch warning → fail-safe rather than silently failing into a stranger’s pool

It does not give you:

• DDoS protection. There is a global connection cap (profile-driven) and a set of opt-in guards — a per-IP concurrent-connection cap ([stratum] max_connections_per_ip, 0 = off by default) plus connect-rate auto-banning ([ratelimit] autoban_*, enabled by default, loopback and private LAN exempt). That blunts noisy clients; it is not upstream DDoS mitigation.
• Authentication beyond bech32 address format by default (anyone with your hostname can point a miner at you and submit shares — to their own address). For an invite-only pool you can pin the accepted payout addresses with [mining] address_allowlist; V1 mining.authorize for any other address is then rejected.
• Worker IP privacy (visible in your admin panel + logs)

For 5-10 friends this is fine. If your DuckDNS hostname leaks publicly and random people start mining to your pool, your only recourse is changing the hostname. For real abuse resistance you need tier 3 — see scaling.md.

Cheat sheet

# Initial setup (one time) — adjust the path to your clone
cd /path/to/dvb-WarpPool && ./scripts/setup-tls-public.sh

# Daemon restart (rarely needed — the daemon picks up renewed certs on its own)
pkill -f dvb-warppool-daemon ; sleep 2 ; open /Applications/dvb-WarpPool.app

# Force a renewal
~/.acme.sh/acme.sh --renew --domain warppool-oliver.duckdns.org --force

# Check cert status
echo | openssl s_client -connect warppool-oliver.duckdns.org:3334 \
  -servername warppool-oliver.duckdns.org 2>&1 \
  | openssl x509 -noout -dates -subject -issuer

# DNS + port reachability from outside
dig +short warppool-oliver.duckdns.org @8.8.8.8
nc -zv warppool-oliver.duckdns.org 3334

Good luck!

Solo + Friends — Ausführliche Anleitung (Deutsch)

Diese Anleitung verwandelt deinen lokalen dvb-WarpPool in einen Pool, den deine Freunde von zu Hause aus mit ihren Minern über das Internet erreichen können — verschlüsselt über TLS, mit echtem Let’s Encrypt-Zertifikat (kein “Insecure Mode” am Miner nötig).

Zeitbedarf: ca. 15-20 Minuten Vorausgesetzt: WarpPool läuft schon lokal auf deinem Mac, Fritz!Box ist dein Router

Inhalt

1. Was wir hier eigentlich machen
2. Phase 1 — DuckDNS-Account anlegen
3. Phase 2 — Fritz!Box: DDNS einrichten
4. Phase 3 — Fritz!Box: Port 3334 freigeben
5. Phase 4 — Setup-Script ausführen
6. Phase 5 — Daemon neu starten
7. Phase 6 — Verifikation
8. Phase 7 — Eigenen Miner umstellen
9. Phase 8 — Freunde einladen
10. Sleep-Schutz auf macOS
11. Wartung
12. Wenn was schiefgeht
13. Security-Hinweise zu dieser Ausbaustufe
14. Zusammenfassung der Befehle

Was wir hier eigentlich machen

Das Problem: Bitaxe-Firmware mit “Bundled CA”-Modus akzeptiert nur Zertifikate von echten Certificate Authorities (Mozilla Root Bundle). Dein aktuelles Self-signed Cert wird abgelehnt. → Wir brauchen ein echtes Cert.

Echte Certs gibt’s gratis bei Let’s Encrypt — aber nur für einen DNS-Namen (nicht für eine bloße IP-Adresse). Du brauchst also einen “Namen für deinen Mac im Internet”. Das macht DuckDNS: gratis Subdomain <wunschname>.duckdns.org, die immer auf deine aktuelle Heim-IP zeigt.

Was du am Ende hast:

• <sub>.duckdns.org zeigt auf deine Fritz!Box-IP (auch wenn sich die ändert)
• Fritz!Box leitet Port 3334 auf deinen Mac weiter
• Mac antwortet mit echtem Cert für <sub>.duckdns.org
• Bitaxe vertraut dem Cert (weil Let’s Encrypt im Bundle ist)
• → Externe Miner können sich verschlüsselt verbinden

Phase 1 — DuckDNS-Account anlegen

Zeit: 2 Min.

1. Browser auf https://www.duckdns.org/ öffnen.
2. Oben rechts mit GitHub, Twitter, Reddit oder Google einloggen (am einfachsten GitHub falls du dort schon einen Account hast).
3. Du landest auf der Übersichtsseite. Oben siehst du:
   • Token: eine 32-stellige Hex-Zahl wie a1b2c3d4-e5f6-...
   • Darunter ein leeres Feld “sub domain” mit “add domain”-Button daneben.
4. Wunschname eintippen (z.B. warppool-oliver oder oliver-pool — was dir gefällt, muss noch frei sein) → “add domain” klicken.
5. Die Subdomain erscheint in der Liste. Notiere dir:
   • Subdomain (nur das warppool-oliver-Teil, ohne .duckdns.org)
   • Token (oben rechts, 32 Hex-Zeichen)

Beides brauchst du in Phase 2 und Phase 4.

Tipp: Den Token nicht in Slack/Discord posten. Wer ihn hat, kann deine Subdomain auf eine fremde IP umlenken.

Phase 2 — Fritz!Box: DDNS einrichten

Zeit: 3 Min.

DDNS = Dynamic DNS. Deine Fritz!Box ruft alle paar Minuten DuckDNS auf und sagt “die IP für warppool-oliver ist jetzt X”. Damit zeigt deine Subdomain immer auf dein Zuhause, auch wenn dein Provider die IP wechselt.

1. Browser auf http://fritz.box/ oder http://192.168.178.1/.

2. Einloggen mit deinem Fritz!Box-Passwort.

3. Linkes Menü: Internet → Freigaben.

4. Reiter DynDNS wählen.

5. Häkchen bei “DynDNS benutzen” setzen.

6. DynDNS-Anbieter: “Benutzerdefiniert” wählen.

7. Update-URL: exakt diese Zeile einfügen (Subdomain + Token durch deine ersetzen):

   https://www.duckdns.org/update?domains=<DEINE_SUBDOMAIN>&token=<DEIN_TOKEN>&ip=<ipaddr>
   

   Beispiel (mit Beispiel-Werten):

   https://www.duckdns.org/update?domains=warppool-oliver&token=a1b2c3d4-e5f6-7890-abcd-ef1234567890&ip=<ipaddr>
   

   Wichtig: Das <ipaddr> am Ende ist ein Platzhalter — den lässt du exakt so stehen. Die Fritz!Box ersetzt das beim Senden mit deiner aktuellen IP.

8. Domainname: <DEINE_SUBDOMAIN>.duckdns.org (z.B. warppool-oliver.duckdns.org).

9. Benutzername: irgendwas Beliebiges (z.B. none) — DuckDNS prüft nur den Token.

10. Kennwort: auch irgendwas (z.B. none).

11. “Übernehmen” klicken.

Test: Im Terminal auf dem Mac:

dig +short warppool-oliver.duckdns.org @8.8.8.8

Sollte deine öffentliche IP zurückgeben (dieselbe wie unter https://www.whatismyip.com/ angezeigt). Falls leer: 30 Sekunden warten, nochmal versuchen — Fritz!Box muss erst einmal updaten.

Phase 3 — Fritz!Box: Port 3334 freigeben

Zeit: 3 Min.

Externe Miner verbinden sich zu warppool-oliver.duckdns.org:3334 → landen bei deiner Fritz!Box → die muss wissen wohin damit (= deinem Mac).

1. Fritz!Box → Internet → Freigaben → Reiter Portfreigaben.
2. Klicke “Gerät für Freigaben hinzufügen” (oder bei einem bereits vorhandenen Gerät auf “Bearbeiten”).
3. Wähle dein Mac-Gerät aus (sollte als hostname-irgendwas oder MacBook-Pro etc. erscheinen — IP 192.168.178.10).
4. Klicke “Neue Freigabe” → “Portfreigabe”.
5. Anwendung: “Andere Anwendung”.
6. Bezeichnung: WarpPool TLS Stratum (für deine Übersicht).
7. Protokoll: TCP.
8. Port an Gerät: 3334
9. Port extern gewünscht: 3334
10. Häkchen bei “Freigabe aktivieren”.
11. “OK” → dann “Übernehmen”.

Test: Auf einem externen Gerät (z.B. dein Handy mit ausgeschaltetem WLAN, also über Mobilfunk):

nc -zv warppool-oliver.duckdns.org 3334

Sollte Connection to warppool-oliver.duckdns.org port 3334 [tcp/*] succeeded! zeigen.

Falls das nicht geht von extern aber vom Mac selbst funktioniert: NAT-Loopback-Problem der Fritz!Box (kennt manche Modelle). Externe Tests aber von extern machen.

Phase 4 — Setup-Script ausführen

Zeit: 2 Min.

Jetzt holen wir das Let’s Encrypt-Cert.

1. Terminal öffnen.

2. In den WarpPool-Ordner wechseln — den Pfad durch dein eigenes Clone- Verzeichnis ersetzen:

   cd /pfad/zu/dvb-WarpPool
   

3. Script starten:

   ./scripts/setup-tls-public.sh
   

4. Das Script fragt dich:

   ? DuckDNS Subdomain (ohne .duckdns.org):
   

   → warppool-oliver (oder was du in Phase 1 gewählt hast)

   ? DuckDNS Token (32-Hex aus deinem Account-Settings):
   

   → den Token aus Phase 1 reinpasten

5. Das Script läuft jetzt durch:

   • Installiert acme.sh (Let’s Encrypt CLI) wenn nicht da → ~30s
   • Holt das Cert via DNS-01-Challenge:
     • Setzt einen TXT-Record bei DuckDNS
     • Wartet bis DNS propagiert ist (~30-60s)
     • Let’s Encrypt prüft den TXT-Record → bestätigt dass du die Domain kontrollierst
     • Cert wird ausgestellt + lokal gespeichert
   • Installiert Cert + Key nach ~/Library/Application Support/dvb-WarpPool/tls/{cert,key}.pem
   • Alte self-signed Files werden als .bak-<unix-ts> gesichert
   • Registriert sich selbst im Cron für Auto-Renewal nach 60 Tagen

6. Am Ende siehst du:

   ✓ TLS-Setup für warppool-oliver.duckdns.org abgeschlossen
   
   Nächste Schritte:
     1) WarpPool-Daemon neustarten ...
     2) Auf der Bitaxe (Pool Configuration): ...
     3) Fritz!Box prüfen: ...
     4) Test (von extern oder im LAN): ...
   

Phase 5 — Daemon neu starten

Zeit: 30 Sek.

Der Daemon lädt das Cert nur beim Start. Also einmal neustarten:

pkill -f dvb-warppool-daemon
sleep 2
open /Applications/dvb-WarpPool.app

Nach 3-5 Sekunden ist der Daemon wieder da. Prüfen:

tail -20 ~/Library/Application\ Support/dvb-WarpPool/daemon.log | grep -i "tls"

Sollte zeigen:

spawning TLS stratum listener bind=0.0.0.0:3334 cert=/Users/Oliver/Library/Application Support/dvb-WarpPool/tls/cert.pem
stratum-v1 TLS server listening bind=0.0.0.0:3334 max_conn=64

Phase 6 — Verifikation

Zeit: 1 Min.

Wir checken dass das Cert von extern als gültig erscheint.

echo | openssl s_client -connect warppool-oliver.duckdns.org:3334 \
  -servername warppool-oliver.duckdns.org 2>&1 \
  | grep -E "Verify return code|subject=|issuer=|Server certificate"

Gut (was du sehen willst):

subject=CN=warppool-oliver.duckdns.org
issuer=C=US, O=Let's Encrypt, CN=R10
Verify return code: 0 (ok)

Schlecht (irgendwas stimmt nicht):

subject=CN=dvb-WarpPool         ← noch das self-signed Cert
Verify return code: 18 (self-signed certificate)

Falls du das schlechte Resultat siehst:

• Hast du den Daemon wirklich neugestartet? pgrep -f dvb-warppool-daemon sollte einen anderen PID zeigen als vor dem Restart.
• Zeigt die config.toml auf das neue Cert? grep tls_cert_path ~/Library/Application\ Support/dvb-WarpPool/config.toml

Bei “Verify return code: 0” — fertig, Cert ist gültig und Bitaxe wird’s akzeptieren.

Phase 7 — Eigenen Miner umstellen

Zeit: 2 Min. pro Miner.

Beispiel BitForge Nano (Web-UI auf http://192.168.178.44):

1. Im Browser zu http://192.168.178.44/ (oder wie auch immer dein Bitaxe im LAN heißt).

2. Pool Configuration → Main Pool Reiter.

3. Felder so setzen:

   Feld	Wert
   Stratum Host	warppool-oliver.duckdns.org
   Stratum Port	3334
   Stratum User	(bleibt: bc1q...DEINE_ADRESSE.BitForgeNano)
   Stratum Password	(bleibt was es war, z.B. x)
   TLS	Enabled (Bundled CA) ← jetzt korrekt

4. Save klicken.

5. Bitaxe meldet “must restart this device after saving” → Restart klicken.

6. Bitaxe rebootet. Nach ~20 Sek. ist er zurück.

7. Im Bitaxe-UI sollte unter “Status” wieder eine aktive Pool-Verbindung stehen + Shares ticken.

8. Im WarpPool-Admin (http://localhost:18334/): Worker-Tabelle sollte den Bitaxe weiter zeigen — mit 🔒-Schloss-Icon neben dem Namen für die TLS-Verbindung. Das “Aktive Miner”-Tile zeigt eine “N TLS”-Subzeile mit der Zahl deiner TLS-Verbindungen.

→ Erfolgreich auf TLS umgestellt.

Wiederholung für alle anderen eigenen Miner (NerdOctaxe, NerdQaxe++, Avalon Q etc.). Pro Miner ~2 Min.

Phase 8 — Freunde einladen

Schick deinen Freunden:

Hey, du kannst auf meinen WarpPool mining:

• Pool: warppool-oliver.duckdns.org
• Port: 3334
• TLS: ja, “Enabled (Bundled CA)” / “Strict TLS”
• Username: <DEINE_EIGENE_bech32-Adresse>.<beliebiger Worker-Name>

Du bekommst 100% des Rewards wenn dein Miner den Block findet (Solo-Pool, kein Sharing). Wenn der Pool offline ist, geh auf deinen Fallback.

Wichtig: Jeder Freund nutzt seine eigene Wallet-Adresse. WarpPool ist Solo — der Reward geht direkt auf die Adresse die der Miner als User angibt.

Block-Alarm für die ganze Gruppe

Der Pool kann jedem Freund eine Block-gefunden-Benachrichtigung aufs Handy schicken, in der Sekunde in der es passiert. Der einfachste Weg ist ein gemeinsames ntfy-Topic: du konfigurierst [notifier.ntfy] einmal am Pool, deine Freunde installieren nur die ntfy-App und abonnieren den Topic-Namen — ganz ohne Accounts. Wenn du das nutzt, ergänze die Einladung oben um eine Zeile:

• Block-Alarm: installiere die ntfy-App und abonniere das Topic <dein-topic-name>

Eine Telegram-Gruppe oder ein Discord-Channel funktionieren genauso. Die komplette Anleitung (englisch): Sharing notifications with friends.

Sleep-Schutz auf macOS

Sobald deine Freunde von außen connecten, muss der Pool 24/7 erreichbar bleiben. Per Default suspendiert macOS das System nach 3 Stunden Idle-Zeit (pmset sleep 180). Während des Sleep:

• Bitcoin Core ist eingefroren — getblocktemplate und submitblock timen aus
• Stratum-TCP-Verbindungen brechen ab (Bitaxes loggen Connection reset by peer)
• Der Hashrate-Chart zeigt nachts mehrere Drops auf 0 mit kurzen Erholungen wenn der Mac für Power Nap oder Notifications kurz aufwacht

Das wird automatisch verhindert. Seit v1.0.6 wrapped der Mac-Launcher den Daemon-Spawn mit caffeinate -i -w <pid>:

• -i = verhindert System-Idle-Sleep (CPU + Netzwerk + Bitcoin Core bleiben wach)
• -w PID = caffeinate beendet sich automatisch wenn der Daemon stirbt → keine Zombie-Prozesse, kein manueller Cleanup
• Display-Sleep funktioniert weiter — du kannst den Bildschirm dunkel werden lassen, Screensaver läuft, alles normal

Verifikation dass es aktiv ist:

ps -A -o pid,ppid,command | grep "caffeinate -i -w $(pgrep -f dvb-warppool-daemon | head -1)"

Solltest eine Zeile sehen: caffeinate -i -w <daemon-pid>.

Die Admin-Profile-Seite (/admin/profile) zeigt eine grüne Info-Card “✓ macOS Sleep-Modus deaktiviert” wenn der Schutz aktiv ist. Falls die Card fehlt: Launcher konnte caffeinate nicht spawnen (sehr unwahrscheinlich — es ist ein System-Binary das auf jedem macOS vorinstalliert ist).

Was NICHT abgedeckt ist

• Expliziter Sleep (Apple-Menü → Ruhezustand, oder MacBook-Deckel schließen). Der User will Sleep, also schläft der Pool auch. Deckel öffnen / Maus bewegen und der Pool ist innerhalb Sekunden zurück (Daemon überlebt kurze Suspensions; bei längeren reconnecten die Bitaxes).
• Hard-Shutdown / Stromausfall. Bei Sorgen: USV nutzen.
• Force-Quit des Launchers. Wenn du den Launcher direkt killst (Activity Monitor → Force Quit), überlebt der Daemon — aber caffeinate’s Parent ist weg, also könnte caffeinate exiten. Sauberer Restart via pkill -f dvb-warppool-daemon oder die .app neu öffnen.

Stromverbrauch

caffeinate -i ist nur ein Sleep-Prevention-Flag — es pinnt nicht die CPU oder hält die Disk drehend. Dein Mac mini / MacBook idled mit dem gleichen Watt-Wert wie sonst auch wenn der Bildschirm aus ist. Der eigentliche Pool-Workload (Stratum-I/O + gelegentliche Bitcoin-Core-RPC) liegt auf Apple Silicon im einstelligen Watt-Bereich. Keine merklichen Auswirkungen auf die Stromrechnung eines Mac mini.

Sleep-Schutz deaktivieren

Wenn der Mac doch schlafen darf (z.B. dir ist Pool-Uptime nachts egal): caffeinate manuell killen:

pkill caffeinate

Der Daemon läuft weiter bis macOS ihn suspendiert.

Es gibt aktuell keinen Config-Flag zum Deaktivieren des Sleep-Schutzes — es ist das richtige Verhalten für fast jeden Pool-Operator, und das Deaktivieren macht den Pool unzuverlässig. Issue aufmachen falls du einen echten Use-Case für Opt-Out hast.

Wartung

Cert-Renewal

acme.sh macht das automatisch alle 60 Tage (Let’s Encrypt-Certs gelten 90 Tage). Du musst nichts tun außer den Daemon einmal neu starten nachdem das Renewal lief, damit er das neue Cert lädt.

Pragmatischer Trick: Cron-Job der das nach jedem Renewal-Versuch macht:

crontab -e

Folgende Zeile dazu:

0 4 * * * cd $HOME && ~/.acme.sh/acme.sh --cron > /dev/null 2>&1 && pkill -f dvb-warppool-daemon ; sleep 3 ; open /Applications/dvb-WarpPool.app

Läuft jeden Tag um 4 Uhr morgens: prüft Renewal-Status, restartet Daemon falls was passiert ist. Wenn nichts zu renewen war, macht der Restart auch keinen Schaden (Daemon ist nach 5s wieder da, Bitaxes reconnecten automatisch).

Manuell Renewal triggern

Falls du testen willst:

~/.acme.sh/acme.sh --renew --domain warppool-oliver.duckdns.org --force

Das --force ignoriert das 60-Tage-Limit.

IP-Wechsel

Solange du die Fritz!Box hast, läuft alles weiter — sie updated DuckDNS ständig. Nur wenn du den Router wechselst (neuer Anbieter, neue Hardware) musst du die DDNS-Config im neuen Router nochmal einrichten (Phase 2).

Stop / Start des Pools

Nichts Besonderes — wie bisher die .app schließen oder pkill -f dvb-warppool-daemon. Bitaxes der Freunde gehen automatisch auf Fallback, kommen zurück sobald dein Pool wieder läuft.

Wenn was schiefgeht

Bitaxe meldet “TLS connection failed”

1. Fritz!Box Port-Forward weg? nc -zv warppool-oliver.duckdns.org 3334 von extern → muss “succeeded” sagen.

2. DuckDNS resolved nicht oder auf falsche IP? dig +short warppool-oliver.duckdns.org @8.8.8.8 → muss deine aktuelle Public-IP zeigen (vergleiche mit curl ifconfig.me).

3. Cert abgelaufen? (sollte nicht passieren wegen Auto-Renewal, aber zur Sicherheit):

   echo | openssl s_client -connect warppool-oliver.duckdns.org:3334 \
     -servername warppool-oliver.duckdns.org 2>&1 \
     | openssl x509 -noout -dates
   

   notAfter=... sollte mindestens 30 Tage in der Zukunft sein.

4. Bitaxe-Firmware-Cache: manche Bitaxe-Firmware-Versionen cachen ein einmal-gefailtes Cert. Bitaxe physisch vom Strom trennen (10 Sek. warten, wieder anstecken), nicht nur Reset-Button.

Script hat irgendwo abgebrochen

Mehrmals ausführen ist OK — das Script ist idempotent. Wenn z.B. acme.sh schon installiert ist, wird es übersprungen.

Falls du komplett neu anfangen willst:

~/.acme.sh/acme.sh --remove --domain warppool-oliver.duckdns.org
rm -rf ~/.acme.sh/warppool-oliver.duckdns.org/

Dann Script nochmal.

Cert lädt nach Restart nicht neu

Daemon zeigt im Log noch das alte Cert?

lsof -p $(pgrep -f dvb-warppool-daemon) | grep cert.pem

Sollte den Pfad zum neuen Cert zeigen. Wenn nicht: nochmal pkill -KILL -f dvb-warppool-daemon (statt normalem pkill) + die .app neu öffnen.

“Rate Limit Exceeded” von Let’s Encrypt

Du darfst nur 5 Certs pro Woche pro Domain. Wenn du beim Testen mehrfach ausgestellt hast: warten oder die Staging-Variante nutzen:

~/.acme.sh/acme.sh --issue --dns dns_duckdns --domain warppool-oliver.duckdns.org \
  --server https://acme-staging-v02.api.letsencrypt.org/directory

Staging-Certs sind nicht in der Mozilla-CA-Liste — funktionieren nicht für Bitaxe, aber zum Testen ob die Infrastruktur läuft.

Komplett rückgängig (zurück auf self-signed)

Falls du doch nur LAN-Betrieb willst:

~/.acme.sh/acme.sh --remove --domain warppool-oliver.duckdns.org
cd ~/Library/Application\ Support/dvb-WarpPool/tls/
# Backup-Files vom Setup-Script restore:
ls -la *.bak-*
# Den jüngsten cert.pem.bak-XXX und key.pem.bak-XXX zurückkopieren:
cp cert.pem.bak-<JÜNGSTER> cert.pem
cp key.pem.bak-<JÜNGSTER> key.pem
pkill -f dvb-warppool-daemon ; sleep 2 ; open /Applications/dvb-WarpPool.app

Plus: Bitaxe wieder auf Port 3333 ohne TLS stellen (oder TLS “Insecure”-Mode).

Security-Hinweise zu dieser Ausbaustufe

Dieses Setup gibt dir:

• Verschlüsselten Stratum-Traffic (TLS 1.3 mit AES-256-GCM)
• Verifizierte Server-Identität via Let’s Encrypt → kein Man-in-the-Middle kann sich als dein Pool ausgeben
• Freunde mit Tippfehler im Hostname bekommen eine Zertifikats-Warnung → fail-safe statt stillem Minen in einen fremden Pool

Es gibt dir nicht:

• DDoS-Schutz (64-Verbindungs-Cap, kein Per-IP-Limit)
• Authentifizierung über das bech32-Adressformat hinaus (jeder mit deinem Hostname kann einen Miner auf dich richten und Shares einreichen — auf die eigene Adresse)
• IP-Privatsphäre der Worker (sichtbar im Admin-Panel + in den Logs)

Für 5-10 Freunde ist das völlig ok. Leakt dein DuckDNS-Hostname öffentlich und Fremde fangen an, auf deinem Pool zu minen, hilft nur ein Hostname-Wechsel. Für echte Abuse-Resistenz brauchst du Stufe 3 — siehe scaling.md.

Zusammenfassung der Befehle

Für später als Spickzettel:

# Setup (1x) — Pfad an dein Clone anpassen
cd /pfad/zu/dvb-WarpPool && ./scripts/setup-tls-public.sh

# Daemon-Restart (selten nötig — erneuerte Certs zieht der Daemon selbst nach)
pkill -f dvb-warppool-daemon ; sleep 2 ; open /Applications/dvb-WarpPool.app

# Manuelles Renewal triggern
~/.acme.sh/acme.sh --renew --domain warppool-oliver.duckdns.org --force

# Cert-Status prüfen
echo | openssl s_client -connect warppool-oliver.duckdns.org:3334 \
  -servername warppool-oliver.duckdns.org 2>&1 \
  | openssl x509 -noout -dates -subject -issuer

# DNS-Resolution prüfen
dig +short warppool-oliver.duckdns.org @8.8.8.8

# Port-Reachability von extern (vom Handy mit Mobilfunk)
nc -zv warppool-oliver.duckdns.org 3334

Viel Erfolg!

Public 0% Solo Pool — Per-Worker Setup & Hardening

This guide turns dvb-WarpPool into a public, non-custodial, 0%-fee solo pool: any miner who connects mines to their own BTC address (taken from the Stratum login), and the full block reward goes straight to the finder on-chain. The pool never holds funds — there is nothing to withdraw, nothing to trust. It is the natural next tier above the friends-only pool in Scaling Tiers.

How it differs from single mode: in the default single mode the whole reward pays one operator address (Solo + Friends). In per_worker mode every miner supplies its own address as the Stratum username, and the coinbase is built per-connection to pay exactly that address — one output, full subsidy, no fee. See the design notes in docs/design/per-worker-coinbase.md.

Honesty: WarpPool has not yet found a mainnet block. Advertise the pool as what it is — a fresh, open, non-custodial solo pool — never as “battle-tested”. The consensus path (per-worker coinbase → real Bitcoin Core accepts the block → reward pays the finder) is verified end-to-end on regtest, but the first mainnet block is still “not yet”.

The project runs one such pool itself — pool.warppool.org, per-worker, 0% fee, non-custodial, currently around a dozen miners. Where this guide says “the reference deployment”, that is the box it means. It has not found a mainnet block either.

Contents

1. Turn on per-worker mode
2. What miners enter
3. Public hardening profile
4. TLS
5. Behind a reverse proxy
6. Deployment checklist

1. Turn on per-worker mode

In config.toml:

[mining]
payout_mode = "per_worker"
# payout_address is IGNORED in per_worker mode (each miner brings its own).
# pool_fee_percent / operator_donation_percent MUST be 0 — the daemon
# refuses to start otherwise (full reward goes to the finder).

That single flag is the whole feature switch. The daemon fails closed on startup if a fee or donation is configured together with per_worker, so you cannot accidentally run a public pool that skims the reward.

Setup wizard shortcut. If you install through the setup wizard (dvb-warppool-setup), the Mining card offers a Pool type choice — Private solo pool vs Public 0% pool. Picking Public 0% pool writes payout_mode = "per_worker" for you, hides the pool-wide payout address (it is unused here), and forces the fee to 0. No hand-editing required.

An invalid or wrong-network login address is rejected at mining.authorize (V1) / channel-open (Sv2) — there is no fallback to an operator address, so a typo never silently pays the wrong person.

2. What miners enter

Miners set their worker/username to their own address, optionally with a rig suffix after a dot:

Username:  bc1qyour-own-address.rig1
Password:  x

• Everything before the first . is the payout address; the rest is a free rig label used only for stats.
• Supported address types: P2PKH, P2SH, P2WPKH, P2WSH, P2TR (Taproot). Any valid mainnet address works.

Public wallet pages & the optional owner panel

Every miner gets a login-free per-wallet page at /users/<address> — the same “look up my address” flow a public solo pool is expected to have. It shows that address’s aggregate hashrate (1 m / 5 m / 1 h / 1 d / 7 d), a per-rig breakdown, lifetime accepted shares, best-ever share difficulty, and the first-seen time. No account, no operator involvement — anyone with the address can open it, and a miner can bookmark their own.

The same numbers are served as ckpool-compatible JSON at GET /api/users/<address> — the exact field names (hashrate1m, hashrate1hr, bestshare, worker[], …) that firmware displays and stats tools like ckstats already parse. Both routes are plain HTTP under the status port, so they sit behind the same reverse proxy as the dashboard (Reverse Proxy).

By default a wallet page is public. A miner who wants more control can prove ownership of the address and unlock an opt-in owner panel — entirely per-miner, nothing the operator has to configure:

1. The page hands out a short one-time challenge message.
2. The miner signs it in their own wallet’s Sign Message box (BIP-137 signed-message — the standard “verify address” feature in Electrum, Sparrow, Bitcoin Core, hardware wallets). No private key leaves the wallet, no funds move, no account is created — the pool only checks the signature.
3. A valid signature sets a short-lived owner cookie for that address and reveals two controls:
   • Privacy — hide the address from the public wallet list and blank its /users/<address> data for everyone but the verified owner.
   • Notifications — point a personal ntfy topic or webhook at this address’s milestones: block-found (this address found a block), personal-best (a new best-ever share across all its rigs), top-100 (first entry into the pool’s all-time top-100 best shares) and rig-offline (one of its rigs dropped). Each event type has its own cooldown, and a found block sends a single headline instead of overlapping alerts.

Ownership signing covers single-key P2PKH / P2WPKH / P2SH-P2WPKH addresses; Taproot (P2TR) can mine but cannot use the owner panel, because the legacy signed-message format has no Taproot variant. Full walk-through in Notifications → Per-wallet miner notifications; the owner panel needs no operator config — see the Configuration Reference note.

Operator-wide directory & leaderboard privacy

The per-miner owner panel above is opt-in and only the miner controls it. As the operator you can additionally set the default exposure of the whole UI, to match the convention of established solo pools (solo.ckpool.org publishes no browsable directory; AtlasPool masks leaderboard addresses). Both default to the open behaviour, so this is opt-in:

[privacy]
# Hide the browsable Workers/wallet directory from anonymous visitors. Each
# /users/<address> page still works by direct link; the logged-in operator still
# sees the full directory (so keep admin auth enabled).
wallet_directory_public = false
# Mask the Bitcoin address in the public best-shares leaderboard (bc1qsx…dvng),
# server-side. The logged-in operator still sees full addresses.
leaderboard_addresses_public = false

This is the recommended posture for a public mainnet pool: miners reach their own page by link, but the pool doesn’t hand out an enumerable list of everyone’s address and rig setup. It does not touch payouts or block construction. See the Configuration Reference.

Accepting donations (optional)

Because a per-worker pool takes 0% of every reward, the only way to fund hosting is a voluntary donation. The dashboard has built-in support for this, and it appears only in per_worker mode — a private solo pool never shows it.

Set the addresses in the admin UI under Admin → Donations (the nav entry is hidden unless the pool runs in per-worker mode):

• On-chain — any valid Bitcoin address. It is validated on save and shown as a bitcoin: QR the visitor’s wallet can open directly.
• Lightning — an LN address / LNURL / BOLT12 string (stored as-is).

Either may be left blank to hide that option. When at least one is set, a Support this pool card with copy buttons and QR codes appears at the bottom of the public dashboard. The addresses are plain operator metadata — they never touch coinbase construction, so setting one can’t affect the fail-closed payout_mode invariant (a donation here is a visitor sending sats to a displayed address, not a share of the block reward).

Under the hood the addresses are stored as pool settings (not config.toml), so no restart is needed; POST /api/admin/donations is admin-authenticated and GET /api/donation-qr/{onchain,lightning} renders the QR SVGs.

3. Public hardening profile

A pool exposed to the internet needs the abuse controls a friends-only pool can skip. Every key below already exists; none is per-worker-specific — they apply to any public deployment. Full detail in the Configuration Reference.

[stratum]
# Bound how many simultaneous V1 connections one source IP may hold. On a
# public pool this stops a single host from hogging slots. Leave 0 only if you
# expect many miners behind one NAT.
max_connections_per_ip = 50

[ratelimit]
enabled = true
connects_per_sec = 5
connect_burst = 20
auths_per_sec = 1.0
auth_burst = 10

# Auto-ban IPs that keep tripping the connect limit (escalating). Loopback and
# private LAN are never banned.
autoban_enabled = true
autoban_strikes = 3
autoban_base_secs = 60
autoban_max_secs = 86400
autoban_window_secs = 600

# Ban a worker that floods invalid shares (share-flood defence). Off by
# default; turn on for a public pool.
reject_ban_enabled = true
reject_ban_min_samples = 100
reject_ban_ratio = 0.9

# Optional subnet access control. `ban_cidrs` denies ranges outright;
# `allow_only = true` flips to a strict whitelist (only allow_cidrs connect).
# ban_cidrs = ["203.0.113.0/24"]
# allow_only = false
# allow_cidrs = ["192.168.0.0/16"]

Optional invite-only variant — combine per-worker payouts with an address allowlist so only known addresses may mine:

[mining]
payout_mode = "per_worker"
address_allowlist = ["bc1qalice...", "bc1qbob..."]

Also switch on automated snapshots before you go public — a public pool’s stats and best-share history are worth keeping:

[backup]
enabled = true
interval_secs = 86400   # daily; the daemon clamps to >= 60
dir = "backups"         # relative paths resolve against the working directory
keep = 7                # 0 = keep everything

These are JSON ledger snapshots. They contain no secrets and no raw shares, so they are safe to copy off-box to ordinary storage.

Sizing profile

A public pool normally runs the gross profile (its defaults are tuned for roughly 21-100 workers): connection cap, VarDiff bounds, memory budget and retention in one bundle. The range in the name is guidance, not a limit — nothing rejects the 101st miner, and profiles hot-switch at runtime without a restart (Admin → Profile).

Resist the urge to move to enterprise the moment you pass 100 miners: its VarDiff defaults are calibrated for PH/s-class farms and will start far too high for Bitaxe/NerdMiner-class hardware, which is exactly what an open 0% pool attracts. Compare the profiles side by side in the admin UI first. See Scaling Tiers.

The node behind the pool

The pool can only mine on the tip it knows about, so the node’s own network position is an operational concern, not a detail:

• Accept inbound connections. Forward TCP 8333 and keep listen=1 on. A node nobody can dial learns about each new block only through its own outbound peers, and every extra millisecond of tip latency is time your miners spend on a job that can no longer win. The health check warns when peers.inbound = 0 on mainnet — take that warning seriously here (Setup Health-Checks).
• Pruned is fine. Solo mining needs no txindex; the reference deployment runs a pruned Bitcoin Core 31.1 with 8333 open at roughly 30 peers.
• Consider a backup node. [[node.backup]] entries make a primary outage a non-event, and solved blocks are submitted to every configured node in parallel — see Resilience.

4. TLS

Firmware that only trusts public CAs needs a real certificate. The Solo + Friends guide walks through DuckDNS + Let’s Encrypt end-to-end; the relevant keys are:

[stratum]
stratum_tls_listen = ":3334"
tls_cert_path = "/etc/dvb-warppool/tls/cert.pem"
tls_key_path  = "/etc/dvb-warppool/tls/key.pem"

Leave the two paths unset to use the daemon’s auto-generated self-signed certificate (fine for NerdMiner/Bitaxe-class firmware that lets you pin it).

5. Behind a reverse proxy

When the status UI is served over HTTPS through nginx/Caddy:

[server]
status_public_url = "https://pool.example.com"
trust_proxy_headers = true    # so per-IP limits see the real client IP
cookie_secure = true          # UI is HTTPS
# status_tls_listen = ":18443"   # or terminate TLS at the proxy instead

See Reverse Proxy for ready-to-paste nginx/Caddy configs (TLS termination, X-Forwarded-For, and the /api/events SSE passthrough).

With trust_proxy_headers = true the daemon trusts X-Forwarded-For. Only enable it when a proxy you control actually sets that header — otherwise a client could spoof its IP past the per-IP limits.

6. Deployment checklist

• payout_mode = "per_worker", no pool fee / donation (daemon starts).
• Bitcoin Core reachable and inbound-reachable (TCP 8333 forwarded, listen=1) so tip changes arrive fast; health check shows no peers.inbound = 0 warning.
• Optionally [node] template_source = "ipc" for lower template latency (needs Core ≥ 31 built with IPC; Core’s IPC interface is itself experimental — GBT stays the default and is the way back).
• [backup] enabled = true with a keep count you’re happy with.
• [ratelimit] enabled = true with autoban_enabled and reject_ban_enabled on.
• max_connections_per_ip set (unless miners sit behind one NAT).
• TLS in front of Stratum (own cert for public-CA-only firmware).
• Reverse proxy: trust_proxy_headers + cookie_secure set correctly.
• Test a miner with your-address.rig1; confirm it appears at /users/<address> and shares are accepted.
• If you publish a landing page, keep the honesty guardrails: no “battle-tested”; mainnet block “not yet”.
• Optional [legal] footer (terms/privacy links) for a public/commercial deployment.

Scaling dvb-WarpPool

dvb-WarpPool is an open-source solo mining pool with operator UX. The codebase covers everything you need to mine to your own wallet with your own hardware, including for a small group of trusted friends. Beyond that, public pool operations introduce a different class of requirements (DDoS, reward sharing, multi-admin, compliance) that the OSS distribution does not address.

This document defines the four deployment tiers, what the OSS stack covers, and where commercial extensions begin. Note that “public” alone does not put a deployment out of OSS scope — a non-custodial per-worker pool is fully covered (see Public 0% Solo Pool); what needs the commercial stack is holding funds, sharing rewards, and running a service with support obligations.

Tier Matrix

The profile is a bundle of defaults, not a hard limit. A profile presets the connection cap, VarDiff bounds, memory budget and retention — nothing enforces the worker range in its name, and the software has been load-tested with 1,000 simulated miners against a single instance (see Benchmarks). Profiles hot-switch at runtime without a daemon restart (Admin → Profile, POST /api/admin/profile); the connection cap is resized live.

Do not jump to enterprise just because you crossed 100 miners. Its VarDiff defaults are calibrated for PH/s-class farms and start far too high for a pool full of Bitaxe/NerdMiner-class hardware. Compare the profiles side by side first (GET /api/admin/profiles/compare, rendered as a table in the admin UI). The optional [mining.auto_profile] switcher exists but is off by default for exactly this reason — see the Configuration Reference.

What the OSS stack ships

Applies to all tiers:

• Stratum V1 plain (:3333) + TLS (:3334), Stratum V2 over NOISE NX (sv2_listen, :3336 in the reference deployment)
• Bitcoin Core solo mining (full reward to the block finder), via getblocktemplate + ZMQ by default, or opt-in via Core’s IPC interface ([node] template_source = "ipc", Core ≥ 31 — Core’s IPC interface is itself experimental)
• Multi-node failover: any number of [[node.backup]] nodes, with submitblock broadcast to all of them in parallel (Resilience)
• Automated JSON ledger snapshots ([backup]) — no secrets, no raw shares
• Per-worker payout mode — a public, non-custodial, 0%-fee solo pool where every miner mines to its own address (from the Stratum login), plus login-free wallet pages at /users/<address>. Because the pool never holds funds and shares no reward, this is a public deployment that stays inside the OSS scope — the commercial line below is about custodial / reward-sharing pools, not about being public. See Public 0% Solo Pool.
• Class-aware VarDiff (Bitaxe / Antminer / Avalon Q / Avalon ASIC / NerdMiner / NerdNOS / Whatsminer)
• Admin UI with Argon2 passwords, optional 2FA, signed auto-update channel, and API tokens with an admin or read-only read scope
• Live miner telemetry probes (AxeOS, MM-Summary for Avalon, WantClue NerdNOS, NerdMiner V2)
• Energy tracking (live / 24h / 7d / lifetime with reset)
• Hashrate chart with best-share overlay + 24h aggregation + Week/Month/Year view from daily aggregates
• Notifier hooks (ntfy, Telegram, Discord, Slack, email, Web Push) for block-found + health-alert events
• Distribution: Linux .deb / .rpm / AppImage, multi-arch container images from the project’s own registry at git.warppool.org, Umbrel community store, plus a macOS .dmg (built manually per release — there is no macOS build runner). Windows .msi is paused (no Windows build runner)

For Solo and Solo + Friends that stack is ready for solo/friends use. The only external steps for the friends tier are:

1. A DNS hostname (e.g. via DuckDNS) pointing at your public IP
2. A Let’s Encrypt certificate (the Bitaxe “Bundled CA” mode requires a CA that’s in the Mozilla root bundle)
3. Router port-forward for the TLS Stratum port (default :3334)

What the OSS stack does NOT ship

These are deliberately scoped out — they’re how a pool transitions from a personal tool into a service.

Tier 3 — what a community pool needs on top

The items below were originally listed here as gaps. Most have since shipped as opt-in core hardening; what remains is operator-supplied infrastructure rather than missing code.

See Security and the Configuration Reference for every key, and Public 0% Solo Pool for a ready-made public hardening profile.

Tier 4 — custodial / service gaps (in addition to Tier 3)

Not a gap any more: the public stats page. The dashboard is viewable anonymously (hashrate, active miners, block history), and a per-worker pool additionally serves login-free wallet pages at /users/<address> plus ckpool-compatible JSON at /api/users/<address>. How much of that anonymous visitors see is controlled by [privacy].

Tier 4 — Compliance / Legal

How to request Tier 3 or Tier 4 extensions

Open an issue in this repo at git.warppool.org/dvb-projekt/dvb-WarpPool/issues:

• Tier 3 (Community Pool): label community-pool
• Tier 4 (custodial / service): label enterprise-inquiry

Please include in the issue body:

• Use case (private / community / commercial)
• Expected number of miners
• Hosting setup (own server / cloud / Umbrel / Mac / etc.)
• Timeline + budget range
• Specific items from the gap list above that you need addressed

Response time: typically 2-5 business days. You will receive a fixed-price proposal (Tier 4) or an hour estimate (Tier 3).

Why this split exists

The OSS distribution is what one person + a small trusted group can run safely themselves. Anything beyond that requires ongoing operations work — DDoS response, payout reconciliation, compliance updates, user support — that does not belong in a publicly forkable codebase. Splitting it this way keeps the core honest about its scope, and lets the project sustain itself if anyone wants to run it at scale.

Configuration Reference

dvb-WarpPool has two configuration files plus a set of env vars for optional subsystems:

• config.toml — all non-sensitive settings (pool behavior, Stratum, VarDiff, notifier schema)
• secrets.toml — auth hashes, RPC credentials, Sv2 keys; always chmod 600
• env vars — opt-in subsystems (auto-update, health-check interval, notifier secrets, debounce tuning)

Defaults are defined in crates/config/src/lib.rs; this page is the operator’s view.

config.toml

[branding]

[branding]
status_brand_name = "dvb-WarpPool"
server_location = "self-hosted"
fiat_currency = "EUR"
pool_donation_address = ""

Controls the strings shown in the UI and in the Prometheus build_info metric. No effect on functionality.

The announcement banner is not configured here. The marquee strip under the header is runtime state in the database, not a config.toml key — see Announcement banner.

[legal]

[legal]
terms_url = "https://example.com/terms"
privacy_url = "https://example.com/privacy"
privacy_last_updated = "2026-02-14"

Optional. All fields default to empty. When empty (the solo default), the UI shows no legal notice. When a public / commercial operator sets terms_url and/or privacy_url, the dashboard footer renders a “By connecting mining device(s) or software to this pool, you acknowledge…” notice linking to those URLs (with the optional privacy_last_updated stamp). The legal texts themselves are the operator’s responsibility. URLs are restricted to http/https.

[privacy]

[privacy]
wallet_directory_public      = true   # false → Workers directory is operator-only
leaderboard_addresses_public = true   # false → mask addresses in the best-shares leaderboard

Optional. Both default to true = the historical open behaviour, so existing deployments are unchanged on upgrade. They control how much a public pool exposes, matching the convention of established solo pools:

• wallet_directory_public = false hides the browsable Workers/wallet directory (/api/wallets and its nav link) from anonymous visitors — like solo.ckpool.org, which has no public directory at all. Each per-address page /users/<address> stays reachable by direct link, and the authenticated operator still sees the full directory. Note: for the operator to keep seeing it, admin auth must be enabled (an unauthenticated request — including the operator’s own browser without a session — is treated as public).
• leaderboard_addresses_public = false masks the Bitcoin address in the public best-shares leaderboard server-side (e.g. bc1qsx…dvng, rig suffix dropped) — like AtlasPool. The authenticated operator still sees full addresses.

Neither affects payouts, block construction, or the per-miner opt-in privacy flag (an address owner can already hide themselves via the signature-gated Owner Area on their /users/<address> page); the two mechanisms are orthogonal.

[logging]

[logging]
debug = false
net_debug = false
json = true        # JSON-formatted for Loki/Promtail; set false for readable stdout

Runtime override via env var: RUST_LOG=warppool=debug takes precedence over the config setting.

[mining]

[mining]
payout_mode = "single"               # "single" (default) | "per_worker"
payout_address = "bc1q..."           # REQUIRED in "single" — block-reward recipient
pool_fee_percent = 0.0                # Default = no pool fee (solo)
pool_fee_address = ""                 # Required when fee_percent > 0
pooltag_prefix = "dvbprojekt-WarpPool"  # max 64 bytes, written to coinbase scriptSig
operator_donation_address = ""
operator_donation_percent = 0.0
# Address-allowlist (Kern-Politur): payout addresses allowed to mine. Empty
# (default) = open to anyone. For a private / invite-only pool.
address_allowlist = ["bc1qalice...", "bc1qbob..."]

payout_mode — where the block reward goes:

• "single" (default): the full reward goes to the single pool-wide payout_address. This is the ordinary solo / friends setup and is 100% backward-compatible.
• "per_worker": each miner mines to their own address, taken from the Stratum login (<address>.<worker>). The pool never holds funds — a public, non-custodial 0%-fee solo pool. In this mode payout_address is ignored and may be empty, and pool_fee_percent / operator_donation_percent must be 0 (the full reward goes to the finder). A miner whose login is not a valid address for this network is rejected. See docs/design/per-worker-coinbase.md.

For multi-user-solo (hosting-service setup) in "single" mode: set pool_fee_percent = 1.0 and pool_fee_address. The sum of fee + donation must not exceed 99%.

When address_allowlist is non-empty, a miner whose payout address (everything before the first . of the worker name) is not listed is rejected — so only your own / invited miners can connect. Empty = open (the default). This gates both transports: V1 mining.authorize, and Stratum-V2 channel-open (rejected with an OpenMiningChannelError). On V2 a miner additionally needs the pool’s NOISE authority key to connect at all.

Public wallet pages & the owner panel have no config. In per_worker mode each miner gets a login-free page at /users/<address> (ckpool-compatible JSON at GET /api/users/<address>). The opt-in owner panel — prove address ownership by signing a BIP-137 challenge, then toggle privacy or set a per-wallet notify target — is driven entirely per miner and is only reachable after that miner verifies ownership; there is no operator key here to set. Do not confuse this with two unrelated settings above: [legal] privacy_url is a legal-footer link for the whole pool (terms/privacy policy), not a per-wallet control, and address_allowlist gates who may mine, not who may see a page. See Public 0% Solo Pool and Notifications.

[node]

[node]
rpc_url = "http://127.0.0.1:8332"
zmq_hashblock_addr = "tcp://127.0.0.1:28332"
zmq_rawblock_addr = "tcp://127.0.0.1:28333"
rpc_cookie_path = "/home/bitcoin/.bitcoin/.cookie"   # optional, alternative to user/pass in secrets.toml

template_source = "gbt"      # "gbt" (default) | "ipc" — see below
ipc_socket_path = ""         # required when template_source = "ipc"
ipc_fee_delta_sats = 0       # ipc only; 0 = off

The cookie takes precedence over user/pass in secrets.toml. Leaving the ZMQ fields empty enables poll-only mode (slower but functional).

template_source picks where block templates come from:

• "gbt" (default) — getblocktemplate over RPC, refreshed on ZMQ block events plus the job_refresh_secs poll. Works with every Bitcoin Core release.
• "ipc" — the Cap’n-Proto mining interface of a multiprocess Bitcoin Core ≥ 31 (bitcoin-node -ipcbind=unix), which pushes a new template via waitNext instead of being polled. Opt-in, and Core’s own IPC mining interface is itself experimental — treat this mode as a prototype and keep "gbt" for an unattended pool.

RPC stays mandatory in both modes (submitblock, health checks, mintime). Config validation rejects any other value, and rejects template_source = "ipc" without an ipc_socket_path.

ipc_socket_path is the -ipcbind Unix socket; Core’s default is <datadir>/<network>/node.sock and a unix: prefix is accepted. Being a Unix socket, pool and node must share a host or a volume (on Umbrel: the Bitcoin app from v1.3.0 with the IPC Mining Interface toggle and Core v31.0 — mount the datadir read-only and resolve the socket inside it).

ipc_fee_delta_sats (ipc only) additionally pushes a fresh template as soon as the template’s fees rise by at least that many sats. 0 (default) = off, which keeps the exact GBT cadence (tip change + job_refresh_secs poll). Values above 2100000000000000 (21 M BTC in sats) are rejected.

Both fields are also settable from the UI under Admin → Bitcoin Core → Template source, including a socket precheck.

[[node.backup]] — multi-node failover

Optional: any number of backup Bitcoin Core nodes. The [node] block is the primary; each [[node.backup]] entry adds a fallback:

[[node.backup]]
rpc_url = "http://192.168.178.99:8332"
rpc_cookie_path = "/mnt/node-b/.bitcoin/.cookie"      # auth option 1
zmq_hashblock_addr = "tcp://192.168.178.99:28332"     # empty = no ZMQ from this node

Per-backup auth resolution, in order: rpc_cookie_path → user:pass embedded in rpc_url (http://user:pass@host:8332 — note this lives in config.toml, mind the file permissions) → the global secrets.rpc_user/rpc_pass.

Failover semantics:

• Sticky with preferred primary. Calls run against the last working node; on transport, auth or warmup errors they hop to the next within the same call (the job loop never stalls). While running on a backup, roughly once a minute one call probes the primary first and switches back as soon as it answers.
• submitblock goes to ALL nodes in parallel — the block moment is the one instant where a dead node can cost real money; any Accepted wins.
• ZMQ subscribes to every node that has a zmq_hashblock_addr; the job loop deduplicates block events by hash, so whichever node reports first triggers the refresh.
• Notifications: a node switch fires node-failover (delivered to sinks that subscribed to on_rpc_down); rpc-down itself now means “no node reachable at all” — a pool running happily on a backup is degraded, not down, and the health snapshot carries a warning instead.

Verified live: primary kill → failover < 1 s with the job stream uninterrupted; primary restart → automatic return ≤ 60 s.

[server]

[server]
pool_listen = ":3333"
status_listen = ":18334"
status_tls_listen = ":18443"          # optional
status_public_url = "https://pool.example.com"   # for push notifications
trust_proxy_headers = false           # only set true when the daemon runs behind Caddy/nginx
cookie_secure = false                 # set true when the UI is served via HTTPS
# job_refresh_secs = 90               # template poll interval, range 10-600 (default 90)
# suppress_health_warnings = ["bitcoin_pruned"]   # hide these health-banner warnings

status_public_url is required by the UI to build absolute URLs for web push and email links. Leave empty when not running behind a reverse proxy.

job_refresh_secs overrides the --refresh-secs CLI argument and accepts 10–600 seconds. The default of 90 s is deliberate: every mining.notify makes an ESP32-class miner (NerdMiner V2, ~250 KH/s) abort its hash loop and reload the coinbase, which resets its displayed hashrate. ASIC miners don’t feel the trade-off either way.

suppress_health_warnings is an opt-in list of Bitcoin Core health-warning keys the dashboard banner should not show — handy for a deliberately pruned node (bitcoin_pruned). It is only the initial value: on first start it seeds a database-backed list that you then manage under Admin → Health (or via the “Hide permanently” button on the banner). Known keys include bitcoin_pruned, bitcoin_no_inbound_listen, bitcoin_no_zmq_hashblock and bitcoin_few_peers.

Running behind nginx or Caddy? See Reverse Proxy for ready-to-paste configs (TLS termination, X-Forwarded-For, and the /api/events SSE passthrough) and how trust_proxy_headers / cookie_secure fit in.

[stratum]

[stratum]
stratum_tls_listen = ":3334"          # optional, V1 TLS
stratum_password = ""                 # empty = address-format auth only
safe_mode = true                      # Conservative validator
tls_cert_path = "/etc/dvb-warppool/cert.pem"
tls_key_path = "/etc/dvb-warppool/key.pem"
tls_reload_secs = 300                 # re-read cert/key on mtime change; 0 = off
sv2_listen = ":34254"                 # optional, Stratum V2
sv2_max_connections = 1024
max_connections_per_ip = 0            # V1 per-IP concurrent cap; 0 = off (Kern-Politur)

max_connections_per_ip bounds how many simultaneous V1 connections (plain + TLS) a single source IP may hold — independent of the global connection cap. 0 (default) is off; loopback is always exempt. Useful on a public pool to stop one host from hogging connection slots, while NAT’d home setups (many miners behind one IP) usually leave it at 0.

Sv2 needs an authority key in secrets.sv2_authority_priv_key_hex (32-byte x-only secp256k1, 64 hex chars). Since v1.0.15 the daemon auto-generates and persists it on first start; only when the secrets file is not writable is Sv2 disabled with a warning (the daemon still starts).

When tls_cert_path/tls_key_path are unset, the daemon generates and reuses a self-signed certificate under <data>/tls/ (SANs: dvb-warppool, dvb-warppool.local, umbrel.local, localhost; downloadable via GET /api/tls-cert and from the connect modal). Point the two paths at your own files to serve a CA-signed certificate instead — needed for miner firmwares that only trust public CAs (see Troubleshooting → TLS).

Renewal is handled by whatever issued the certificate (Caddy, certbot, your PKI). The daemon watches both files and re-reads them when their mtime changes, so an ACME renewal takes effect without a restart and without dropping miners: existing connections keep the certificate they negotiated, new handshakes get the fresh one. tls_reload_secs sets how often the check runs (default 300 s; 0 disables it and restores the old read-once-at-startup behaviour). If a reload fails — a half-written file mid-renewal, say — the previous certificate stays in service and the next check retries, so a bad write never takes the listener down.

[tuning]

[tuning]
max_saved_workers_per_user = 64
max_saved_workers_pool_total = 1024
active_worker_window_secs = 3600      # dashboard "active" window (default 1h)

Storage cap. Above these thresholds, old/idle workers are evicted (FIFO by last_seen_at). active_worker_window_secs controls how long a worker keeps counting as “active” on the dashboard after its last share.

[mining.auto_profile]

[mining.auto_profile]
enabled = false                # opt-in
evaluation_interval_secs = 60
hysteresis_ticks = 5           # consecutive ticks before a switch

Automatic profile switching based on the active miner count. Disabled by default; the admin UI’s manual hot-switch always works regardless.

[profile]

[profile]
kind = "klein"                  # klein|mittel|gross|enterprise (Small/Medium/Large/Enterprise); omit = auto
expected_miner_count = 5        # for auto: estimate used by auto-detection

The profile affects defaults and resource limits. Hot-switchable via POST /api/admin/profile — the config value is only the fallback at first start.

A profile switch also applies that profile’s VarDiff range (initial_diff / min_diff / max_diff, shown per profile on the Hardware page) to the running pool — the change takes effect for new connections immediately and is persisted, so a restart derives the same values. Earlier this was decoupled: the table showed a profile’s VarDiff but the live pool kept the [vardiff] config values. The other VarDiff fields (target_seconds_per_share, window, hysteresis, max_step, idle_*) are not touched by a profile switch. If you set [vardiff] values by hand in config.toml and never switch profiles at runtime, your hand-set values stand.

Beyond VarDiff and the connection cap, a profile switch also drives the miner-poll interval, the retention TTLs, the Stratum-auth rate limit and the HTTP-API rate limit — live, and persisted so a restart re-derives them. The Hardware comparison table labels each row with which behaviour applies:

The same honesty rule as VarDiff applies to retention and the rate limits: hand-set config.toml values for [retention] / [ratelimit] stand as long as you never switch profiles at runtime. Retention maps the profile’s four tiers (raw_shares / agg_5min / telemetry_raw, with agg_5min also driving the 5-minute telemetry tier) onto the live eviction; the operator-only fields (audit_log_secs, api_tokens_retired_secs, push_subscriptions_stale_secs) are never touched by a switch. agg_1h has no TTL eviction — those rows are rolled into daily_aggregates.

Profile defaults at a glance

The four profiles each bundle a set of presets for a pool size. This is the same table shown on the Hardware page (where the active profile’s column is highlighted). The Scope column is the live / restart / guide behaviour from the badge table above. The headers below use the profiles’ English display names; the matching config kind values are klein (Small), mittel (Medium), gross (Large), and enterprise.

¹ Community and Service assume commercial extensions outside the OSS scope — see Scaling Tiers.

What each row means:

• Connection cap — maximum simultaneous miner connections; beyond it new ones are refused.
• RAM target — a rough memory guideline for the size class, not a hard cap (the pool does not pre-allocate it).
• Stratum threads — Tokio worker threads for the Stratum listener (all cores = num_cpus); fixed when the runtime starts.
• DB pool — SQLite connection-pool size (more = more concurrent DB access); fixed at startup, hence restart.
• UI refresh — a guideline for how often the dashboard updates; the backend pushes live events over SSE anyway, so it is advisory only.
• Miner polling — how often the pool polls each miner’s telemetry (temperature / watts / volts).
• VarDiff initial / min / max — the per-profile defaults the running VarDiff starts from and stays within. Sub-1 difficulty stays possible for tiny devices via suggest_difficulty, regardless of min.
• Retention — how long each data class is kept before automatic eviction; larger profiles keep more history.
• Stratum auth / API per min — per-IP rate limits; loopback and the LAN are exempt (see [ratelimit]).

[vardiff]

[vardiff]
enabled = true
target_seconds_per_share = 15.0
window = 8
min_diff = 1.0
max_diff = 65536.0
retarget_after_n_shares = 4
hysteresis = 0.20          # 20% — a new diff that deviates > 20% from the old one triggers a retarget
max_step = 4.0             # max 4× per retarget
initial_diff = 1.0
idle_decay_enabled = true  # time-driven decay for workers that went quiet
idle_grace_factor = 20.0   # × target_seconds_per_share of silence before the first decay step
idle_step_factor = 8.0     # × target between further steps while still quiet
significance_gate = true   # only retarget when the deviation is statistically significant (default on since v1.11.0)
gate_confidence = 0.90     # confidence band of the significance gate

EMA-based, with persisted snapshots in the vardiff_state table. Tests: crates/stratum-v1/src/vardiff.rs.

Significance gate. significance_gate (on by default) makes VarDiff retarget only when the EMA share-rate deviation is statistically significant for the number of shares seen — formally when |ema/target − 1| · √window > z_crit(gate_confidence). A worker producing few shares per window (NerdMiner, NerdNOS and other sub-MH/s / ESP-class miners) has a Poisson-noisy observed rate (≈ 1/√N), and a fixed hysteresis band reads that noise as a real hashrate change — flapping the difficulty and flooding the miner with mining.set_difficulty (the visible ESP32 display flicker). The gate holds the difficulty until the deviation is real; a genuine hashrate change still clears the band promptly (verified live: a 4× change reacts within ~1 share). Set significance_gate = false to retarget purely on the hysteresis band (tighter tracking, more churn). gate_confidence (default 0.90) sets the band — higher = stricter = fewer retargets.

Idle decay. Share-driven retargeting has a blind spot: a worker whose difficulty ended up too high (snapshot from a beefier predecessor device under the same worker name, thermal throttling, a misdetected class) stops producing shares — and without shares there is nothing to trigger the downward retarget. The idle decay closes that loop on a timer: after idle_grace_factor × target_seconds_per_share of silence (default 20 × 15 s = 5 min — the chance a correctly-tuned worker is randomly silent that long is e⁻²⁰), the difficulty steps down by max_step (÷4), then again every idle_step_factor × target until shares flow again or the class min_diff floor is reached. Three guards make this safe against the classic crush bug (M45-goPool#32): the idle clock starts with the session — never from a persisted timestamp, so a reconnecting miner is never punished for the downtime; steps are gradual, never straight to the floor; and the floor is a plain clamp, no formula artifacts. Workers pinned via d= are exempt — an explicit request outranks the automation.

Miner difficulty requests are honored, clamped to the hardware class. Both standard V1 mechanisms work out of the box, no config needed:

• mining.suggest_difficulty(d) — taken as the starting point: the pool sets d immediately, VarDiff stays active and corrects later if the observed share rate doesn’t fit (the spec defines suggest as a hint, not a contract). Works before or after mining.authorize.
• d=<x> in the authorize password field (e.g. password x,d=8192) — pins the difficulty for the session: VarDiff retargeting is disabled, the miner said explicitly what it wants. Useful for devices whose worker name field has a character whitelist (Avalon Q) and for proxy setups.

Both are clamped to the class-tuned [min_diff, max_diff] band — a NerdMiner can’t request 1M (it would starve), an S21 can’t request 0.001 (it would flood the pool). Garbage values (0, negative, non-numeric) are acknowledged but ignored; a hint must never break the session. d= beats suggest; both beat the persisted snapshot from a previous connection.

[ratelimit]

[ratelimit]
enabled = true
connects_per_sec = 5.0     # per peer IP
connect_burst = 20
auths_per_sec = 1.0
auth_burst = 10
idle_evict_secs = 300      # after 5 min without traffic → bucket state is evicted

# Auto-ban: a public IP that keeps tripping the connect limit gets a full,
# escalating ban instead of just being throttled. Loopback + private LAN are
# never banned (local miners can reconnect in bursts).
autoban_enabled = true
autoban_strikes = 10       # connect-limit violations within the window …
autoban_window_secs = 60   # … that trigger a ban
autoban_base_secs = 300    # first ban 5 min; doubles per repeat …
autoban_max_secs = 3600    # … capped at 1 h

# Reject-ratio ban (Kern-Politur) — ban a worker that floods bad shares.
reject_ban_enabled = false      # off by default
reject_ban_ratio = 0.5          # rejected/(accepted+rejected) over this …
reject_ban_min_samples = 50     # … once at least this many shares are seen → ban + drop

# Manual (permanent) ban list — operator-curated. Also editable live via the
# admin API / the Admin → Profile page. Applies to any IP except loopback.
manual_bans = ["203.0.113.7", "198.51.100.42"]

# IP-gate (Kern-Politur) — subnet-level access control, off by default.
ban_cidrs  = ["203.0.113.0/24"]   # deny whole ranges (CIDR or bare IP)
allow_only = false                # true = strict whitelist (only allow_cidrs connect)
allow_cidrs = ["192.168.0.0/16"]  # the whitelist (used only when allow_only = true)

Per-peer-IP token bucket. Triggered limits return mining.authorize with result: false (no disconnect — the miner should not get stuck in a reconnect loop). Auto-ban goes one step further for public IPs: after autoban_strikes connect-limit violations within autoban_window_secs, the IP is rejected outright (before TLS/handshake) for an escalating duration. Set autoban_enabled = false to keep pure throttling. Loopback and private-LAN addresses are exempt by design, so your own miners are never locked out.

The IP-gate adds subnet-level control on top of the single-IP manual_bans: ban_cidrs refuses whole ranges, while allow_only = true flips to a strict whitelist where only allow_cidrs (plus loopback) may connect — handy for a private / invite-only pool. Both take CIDR ranges or bare IPs; malformed entries are dropped (logged) at start; loopback always passes so you can’t lock yourself out. All off by default.

Reject-ratio ban catches a different abuser: a worker that connects fine but floods invalid shares. With reject_ban_enabled = true, once a session has sent at least reject_ban_min_samples shares and its rejected fraction is ≥ reject_ban_ratio, that (public) IP is banned for the escalating auto-ban duration and the connection dropped. Public-IP-only, same as the connect auto-ban — your own LAN/loopback miners are never caught.

[notifier]

See Notifications for detailed sink setup guides.

[notifier]
webpush_subscriptions_path = "/var/lib/dvb-warppool/webpush.json"

[notifier.ntfy]
topic_url = "https://ntfy.sh/my-pool-topic-secret"
on_block_found = true
on_miner_disconnect = false
on_rpc_down = true
on_health_alert = true

[notifier.telegram]               # supports on_block_found + on_health_alert only
bot_token_env = "TELEGRAM_BOT_TOKEN"
chat_id = "123456789"
on_block_found = true
on_health_alert = true

[notifier.discord]                # supports on_block_found + on_health_alert only
webhook_url_env = "DISCORD_WEBHOOK_URL"
on_block_found = true
on_health_alert = true

[notifier.slack]
webhook_url_env = "SLACK_WEBHOOK_URL"
on_block_found = true
on_miner_disconnect = false
on_rpc_down = true
on_health_alert = true

[notifier.email]
smtp_url = "smtps://pool@mail.example.com:465"
from = "pool@example.com"
to = ["operator@example.com"]
password_env = "POOL_SMTP_PASSWORD"
on_block_found = true
on_miner_disconnect = false
on_rpc_down = true
on_health_alert = true

All sinks are optional. The daemon starts fine without a [notifier] section at all. Sinks whose env vars are missing are skipped with a notifier sink skipped warning.

[[webhooks]]

Generic outbound webhooks: the pool POSTs a JSON payload to each configured URL whenever a matching pool event fires. This is the push counterpart to the /api/events SSE pull stream — see Add-ons & Sidecars for when to use which. Repeat the block for multiple targets; omit it entirely and nothing is sent.

[[webhooks]]
url = "http://127.0.0.1:9000/ingest"     # http:// or https:// ONLY
secret_env = "WARPPOOL_WEBHOOK_SECRET"   # optional; enables HMAC signing
# events = [...]                          # omit → default low-frequency set
enabled = true                            # default true

# A second target, opting into high-frequency events:
[[webhooks]]
url = "https://example.com/hook"
events = ["block_found", "health_snapshot", "new_job", "shares_accepted"]

Payload (Content-Type: application/json):

{ "event": "block_found", "ts": "2026-06-19T12:00:00+00:00", "data": { /* the full event object */ } }

Headers: X-WarpPool-Event: <type> always; X-WarpPool-Signature: sha256=<hmac> only when secret_env is set. Verify the signature exactly like a GitHub webhook — HMAC-SHA256(secret, raw_request_body), compared in constant time.

Default event set (when events is empty) — low-frequency only, so a webhook never causes a POST storm out of the box:

• block_found, health_snapshot, update_available, profile_switched

High-frequency events — new_job and shares_accepted fire constantly (a new_job per template, an aggregated shares_accepted up to once a second). Only list them if your consumer can handle the volume; otherwise prefer the default set or the SSE stream. (heartbeat is also available but rarely useful for a webhook.)

Delivery semantics: each POST has a ~10 s timeout and is retried with exponential backoff (3 attempts total). If all attempts fail the event is logged (webhook dropped after retries) and dropped — there is no unbounded buffer, so a down consumer cannot back up the pool.

No SSRF protection — by design. Loopback / LAN targets are explicitly allowed because local sidecars are the main use case. The URL comes from this operator-trusted config, so only the URL scheme is validated. Do not point a webhook at an untrusted URL.

[retention]

[retention]
shares_raw_secs = 3600                    # per-share rows before aggregation (1 h)
shares_agg5_secs = 604800                 # 5-min share buckets (7 d)
miner_telemetry_raw_secs = 3600           # per-poll vendor probe results (1 h)
miner_telemetry_agg5_secs = 604800        # 5-min telemetry buckets (7 d)
workers_secs = 7776000                    # idle worker rows — block-finders kept forever (90 d)
audit_log_secs = 7776000                  # admin actions / logins / token mints (90 d)
api_tokens_retired_secs = 7776000         # grace AFTER revoke/expiry before the row is dropped (90 d)
push_subscriptions_stale_secs = 7776000   # grace after the LAST failed push attempt (90 d)

All values are TTLs in seconds; eviction runs inside the daemon’s aggregate loop (raw/agg tables every minute, audit/tokens/push hourly). Defaults match the values that were hardcoded before the block existed — omitting the section changes nothing. workers_secs bounds the one table a client can grow by reconnecting under fresh worker names: idle worker rows are evicted after the TTL, but any worker that ever found a block is kept forever. Two entries are conditional rather than age-based: active API tokens never age out (api_tokens_retired_secs counts from revocation or expiry), and push subscriptions are only dropped when their most recent delivery attempt failed (healthy but rarely-pushed subscriptions survive — on a solo pool the next real push may be months away; 410 Gone endpoints are deleted immediately by the push path itself).

[upnp]

[upnp]
enabled = false              # default off — opt-in
renew_interval_secs = 3000   # 50 min, safely under the default 3600 s lease

[[upnp.forwards]]
port = 3333
protocol = "tcp"             # "tcp" or "udp"
lease_seconds = 3600         # lease requested on every renew (60..=86400)
description = "dvb-WarpPool Stratum V1"

Phase 27: the setup wizard opens forwards once with a 1 h lease; if the pool runs longer, the daemon has to renew them. With enabled = false (default) no UPnP discovery task is started at all. Renewals are idempotent on the router side; the first renew tick runs ~10 s after boot so a crashed daemon recovers its forwards quickly.

[backup] — in-daemon auto-backup

[backup]
enabled = false        # master switch (default off)
interval_secs = 86400  # seconds between backups (clamped to >=60); default daily
dir = "backups"        # output directory (created if missing; relative to CWD)
keep = 7               # keep the newest N snapshots, prune older; 0 = keep all

When enabled = true the daemon writes a JSON ledger snapshot — the exact same format as GET /api/admin/backup (workers, blocks, miners, vardiff, settings; no secrets or raw shares) — to dir every interval_secs, named warppool-backup-<timestamp>.json, and prunes to the newest keep. Off by default: operators who already cron the API endpoint (or back up the SQLite file externally) simply leave it disabled. Note this is unrelated to [[node.backup]], which is Bitcoin-node failover.

[mining.electricity]

Note the path: electricity lives inside [mining], so the table headers are [mining.electricity], [[mining.electricity.tou]] and [mining.electricity.solar] — a bare [electricity] block is ignored.

[mining.electricity]
default_rate_eur_kwh = 0.30  # 0.0 = no tariff known, watt tracking only

[[mining.electricity.tou]]   # optional time-of-use slots, first match wins
name = "HT"
rate_eur_kwh = 0.35
hours = "06:00-22:00"        # wrapping slots like "22:00-06:00" work
weekdays = ["mon", "tue", "wed", "thu", "fri"]   # empty/omitted = every day

[mining.electricity.solar]
enabled = false
kind = "home_assistant"      # or "anker", "generic_http"
url = "http://127.0.0.1:8765/snapshot.json"   # direct URL (sidecars); takes precedence over url_env
url_env = "WARPPOOL_HA_URL"  # env var holding the provider base URL (cloud endpoints)
token_env = "WARPPOOL_HA_TOKEN"               # auth token env var (HA long-lived token, ...)
pv_entity_id = "sensor.pv_power_total"        # required for kind = "home_assistant"
consumption_entity_id = "sensor.house_power"  # optional; omitted → compare against pool power
poll_interval_secs = 60
excess_rate_eur_kwh = 0.0    # rate while PV excess covers the pool
surplus_buffer_w = 200.0     # excess must exceed pool power by this margin (anti-flap)
stale_after_secs = 300       # snapshot older than this → fall back to TOU/default

Drives the cost figures on the energy card: the effective rate per 5-minute bucket is solar-excess (if active), else the first matching TOU slot, else default_rate_eur_kwh. Solar provider credentials for the daemon-managed Anker bridge live in secrets.toml (anker_email/anker_password/anker_country), not here.

Announcement banner (runtime, not config.toml)

Since v1.21.0. The scrolling announcement strip under the public pool header (“maintenance tonight 22:00”, “welcome, new miners”) is runtime state, not a config key: it is set from Admin → Banner or over the API, takes effect without a restart, and expires by itself.

POST validation — all violations return 400:

The text is stored and rendered as plain text (the UI writes it via textContent, never as HTML).

Persistence is two rows in the pool_settings key-value table:

Because the expiry is stored rather than scheduled, the banner self-clears: a missing, unparseable or already-passed banner_expires_at simply yields no banner.

Public read path: while active, GET /api/overview carries a banner object {"text": "...", "expires_at": "<rfc3339>"}. The field is absent when there is no active banner — consumers must treat it as optional, not as an empty string. The UI additionally hides the strip locally at expires_at, so it disappears on time instead of at the next overview poll.

secrets.toml (chmod 600)

rpc_user = "warppool"            # optional, alternative to cookie
rpc_pass = "..."                  # optional, ditto
admin_username = "admin"          # default "admin"
admin_password_hash = "$argon2id$..."   # via `dvb-warppool-cli hash-password`
jwt_secret = "..."                # min 32 bytes recommended; empty → admin auth disabled
sv2_authority_priv_key_hex = "..."  # via `dvb-warppool-cli gen-sv2-key`

An empty admin_password_hash or empty jwt_secret makes every /api/admin/* endpoint return 503 “auth disabled”. Useful for a read-only setup without an admin UI.

Credentials written by the admin UI

These are not meant to be hand-edited — the admin pages write them here, and none of them is ever returned by the API. They exist so the operator does not have to plant env vars by hand: on start the daemon hydrates the env vars that the [notifier] sink configs reference (bot_token_env and friends) from these values.

notifier_telegram_bot_token = "..."   # via Admin → Notifications
notifier_discord_webhook_url = "..."
notifier_slack_webhook_url = "..."
notifier_smtp_password = "..."

anker_email = "you@example.com"       # via Admin → Profile → Photovoltaik
anker_password = "..."                # GET /api/admin/solar only reports anker_creds_set: bool
anker_country = "DE"                  # ISO-3166, default "DE"

With solar.kind = "anker" plus email and password set, the daemon starts the Anker bridge itself as a child process — no separate launchd/systemd service needed.

Phase 21: VAPID Web Push Secrets

vapid_public_key = "B..."      # via `dvb-warppool-cli gen-vapid-keys`
vapid_private_key = "..."      # same command
vapid_contact = "mailto:operator@example.org"   # optional, default mailto:operator@localhost

The public key is served via /api/push/vapid-public-key (public, no-auth — the UI needs it for PushManager.subscribe). The private key stays daemon-side only. If either value is empty, web push is disabled — the daemon log reports “web-push disabled (no vapid keys)”.

Environment Variables

Bitcoin Health Check

When the check is enabled, the daemon emits HealthSnapshot SSE events and fires RpcDown/RpcRecovered notifications on transitions.

Auto-Update

Stratum / Notifier Tuning

Solar/PV Provider (Phase 20.5)

The electricity tariff switches to excess_rate_eur_kwh (typically 0.0) when the PV array produces more than house + pool consume together. Supported kind values: anker (daemon-managed Anker Solix bridge — enter your Anker credentials under Admin → Photovoltaik, the pool runs the bridge itself), home_assistant (REST API, shown below), and generic_http (any endpoint serving the snapshot JSON).

[mining.electricity.solar]
enabled = true
kind = "home_assistant"
url_env = "WARPPOOL_HA_URL"            # e.g. http://homeassistant.local:8123
token_env = "WARPPOOL_HA_TOKEN"        # Long-Lived Access Token
pv_entity_id = "sensor.pv_power_total"
consumption_entity_id = "sensor.grid_load_total"   # optional
poll_interval_secs = 60                # 60s is enough to track PV trends
surplus_buffer_w = 200                 # safety buffer
excess_rate_eur_kwh = 0.0              # self-generated power = free
stale_after_secs = 300                 # fall back after 5 min without a snapshot

Create the token in HA: Profile → Long-Lived Access Tokens → Create Token. Entity IDs are listed under Developer Tools → States.

If consumption_entity_id is omitted, the pool compares the PV value directly against its own consumption (not the whole-house total).

/api/energy reports current_rate_source = "solar-excess" and a solar object containing pv_w / consumption_w / excess_w / age_seconds.

Vendor Probes (Phase 22)

Health Anomaly Check (Phase 20.3b)

Critical alerts (FanStuck, StaleData) are sent to every sink with on_health_alert = true (default). Warnings (ThermalThrottling, VoltageDrop, HashrateDrop) are UI-only via /api/miners/:id/alerts.

Notifier Secrets

The variable names are FREELY CHOSEN — you set the name in config.toml, and the daemon reads that env var.

Typical names:

• TELEGRAM_BOT_TOKEN → notifier.telegram.bot_token_env
• DISCORD_WEBHOOK_URL → notifier.discord.webhook_url_env
• SLACK_WEBHOOK_URL → notifier.slack.webhook_url_env
• POOL_SMTP_PASSWORD → notifier.email.password_env

Test/Debug

Deployment / container overrides

Set by the Docker and Umbrel packaging; rarely touched on a bare-metal install. Every WARPPOOL_* flag below is truthy for exactly 1, true or yes.

CLI Override

dvb-warppool-daemon --help lists the CLI flags that can override individual config values. Common ones:

dvb-warppool-daemon \
  --config /etc/dvb-warppool/config.toml \
  --secrets /etc/dvb-warppool/secrets.toml \
  --data-dir /var/lib/dvb-warppool \   # DB lives at <data-dir>/warppool.db
  --ui-dir /usr/share/dvb-warppool/ui \
  --no-zmq                          # debug-only: force poll-only mode

Reload Behavior

There is currently no hot reload for config.toml. Restart the daemon after every change:

systemctl restart dvb-warppool

The only hot-switchable items are:

• Profile (POST /api/admin/profile) — resizes the connection cap, the VarDiff range, the miner-poll interval, the retention TTLs and the rate limits live (see the live / restart / guide table above)
• Announcement banner (POST/DELETE /api/admin/banner) — effective immediately, and self-expiring
• Manual IP bans (POST /api/admin/ratelimit/ban) — effective immediately
• Suppressed health warnings (Admin → Health) — DB-backed after first start
• Notifier credentials (POST /api/admin/notifier/config) — written to secrets.toml
• Admin tokens (POST /api/admin/tokens) — effective immediately
• 2FA (POST /api/auth/2fa/enable) — effective immediately

See Also

• Getting Started — minimum config for first boot
• Notifications — sink-specific examples
• Setup Health Checks — wizard workflow
• Troubleshooting — common failure modes

Setup Health-Checks

Since Phase 9, the first-run wizard (dvb-warppool-setup) doesn’t just check the Bitcoin Core RPC connection itself — it runs a diagnostic of:

1. Bitcoin Core health — everything reachable over RPC (/api/bitcoin-health)
2. Connectivity snapshot — RPC + ZMQ endpoint reachability, pre-filled from your bitcoin.conf (/api/connectivity-snapshot)

Both checks are entirely local — the wizard never contacts a third party.

Privacy matrix

There are no opt-in external probes and no third-party calls. The wizard reads your bitcoin.conf (when a path is given) purely locally — to pre-fill the form and to filter the config recommendations.

Bitcoin health in detail

A click on “Bitcoin Core health check” makes 5 RPC calls in parallel:

Plus automatic warnings:

Why inbound peers matter for a pool. peers.inbound = 0 is not just a good-citizen nag: a node that nobody can dial reaches the network’s new tip only through its own outbound peers, which adds latency to every block change — and every millisecond your pool keeps handing out a stale job is hashrate spent on a block that can no longer be won. For an internet-facing pool, forward TCP 8333 to the node and keep listen=1 on. The live reference deployment (pool.warppool.org) runs a pruned Bitcoin Core 31.1 with 8333 open, sitting at roughly 30 peers. The warning is skipped when the daemon already sees a LAN peer on 8333 (lan_peer_at_8333), so a node fronted by another host on the same network doesn’t warn spuriously.

Connectivity snapshot

On load (and via “↻ Re-check connection”) the wizard fetches /api/connectivity-snapshot, which:

1. Reads the RPC + ZMQ settings — from your bitcoin.conf if a path is given, otherwise mainnet defaults (:8332) — and pre-fills the form.
2. TCP-dials each endpoint locally (RPC URL, zmqpubhashblock, zmqpubrawblock) with a short timeout and reports each as reachable / unreachable / not-set. Nothing is sent beyond the dial.
3. When no bitcoin.conf is found, it offers a one-click “Create mainnet config” (/api/create-bitcoinconf — writes a config with ZMQ + a random RPC password).

There is no port-bind smoke test, no UPnP discovery, and no external reachability probe in the wizard. Reachability of your public node is a Bitcoin Core concern (see the peers.inbound warning above); persistent UPnP forwarding lives in the daemon ([upnp], see below).

What this looks like in code

Backend in apps/dvb-warppool-setup/src/main.rs:

• bitcoin_health(BitcoinHealthReq) — the 5 RPC calls + the warnings (delegates to warppool_health)
• connectivity_snapshot() — TCP-dials the RPC + ZMQ endpoints and reports each

The warning logic lives in the warppool-health crate (collect_bitcoin_warnings_v2_with_conf) and has 15 unit tests in crates/health/src/bitcoin.rs covering every warning edge case (IBD, low-peers, no-inbound, no-zmq, pruned, verification-progress, no-double-warning-on-IBD, healthy-zero-warnings, plus the inbound / listen / private-LAN-peer cases).

UI in apps/dvb-warppool-setup/src/index.html:

• Bitcoin card with RPC test + health-check button
• Connectivity card with per-endpoint status pills + override boxes
• Status cards with icons (✅⚠️❌), key-value rows, warning list with ⚠ bullet

Phase 10a — bitcoin.conf snippet generator

Instead of just emitting warnings, since Phase 10a the health check generates a copy-paste-ready bitcoin.conf snippet that fixes the identified problems. No direct write — the operator decides what (if anything) to adopt.

What ends up in the snippet

What we deliberately don’t suggest:

• txindex=1 — heavy, many pools don’t need it (pruned is fine for solo)
• server=1 — if the RPC test got through at all, this must already be true
• bind= — the default all-interfaces fits almost every case

Format

# ===== dvb-WarpPool Setup-Wizard Recommendations =====
# ZMQ block notifications for immediate job refresh
zmqpubhashblock=tcp://127.0.0.1:28332
zmqpubrawblock=tcp://127.0.0.1:28333

# More peer slots so Bitcoin Core gets more stable peer discovery
maxconnections=125

# enable listening so incoming peers can connect
# (additionally: forward port 8333/tcp on the router to this machine)
listen=1
# ===== End Recommendations =====

Header + footer as wrapper comments so the operator spots the section immediately — no risk of accidentally overwriting existing settings (all recommendations sit inside a marked block).

UI

In the browser:

• 📋 box containing the snippet as monospace code
• “Copy” button (navigator.clipboard.writeText)
• OS-aware path hint: ~/.bitcoin/bitcoin.conf (Linux), ~/Library/Application Support/Bitcoin/bitcoin.conf (macOS), %APPDATA%\Bitcoin\bitcoin.conf (Windows) — via navigator.platform
• Fallback alert if the clipboard API is unavailable (e.g. http context without a TLS cert)

Daemon UPnP renew loop (Phase 27)

The wizard itself does not open router ports — it has no UPnP feature. Persistent port forwarding is a daemon concern: an opt-in renew loop in the daemon refreshes the forwards listed in the [upnp] block every renew_interval_secs. Opt-in (default enabled = false).

Configuration:

[upnp]
enabled = true
renew_interval_secs = 3000  # 50min, safely below the 3600s lease

[[upnp.forwards]]
port = 3333
protocol = "tcp"
lease_seconds = 3600
description = "Stratum V1"

UPnP add_port is idempotent on the router side (same port + protocol = extend lease, don’t create a second entry). The first renew happens 10s after daemon start (covers crash recovery), then every renew_interval_secs seconds (range 60..=86400). Errors are only logged — the loop keeps running so transient problems don’t permanently kill the forward.

Typical router quirks

• FritzBox default: UPnP-discoverable = yes, but add_port = blocked. The operator has to enable “Allow UPnP status changes via UPnP” in the web UI. We then return add_port: The client is not authorized to map this port.
• OpenWrt: UPnP off by default, has to be installed as a package (miniupnpd).
• ISP routers (Telekom Speedport etc.): UPnP often completely disabled; some models have no UPnP at all.

In all of these cases the wizard shows a clear error with the exact router reason. The operator knows what to do.

Phase 12 — bitcoin.conf parse-existing

Instead of suggesting every recommendation, since Phase 12 the snippet generator filters out lines that are already configured — if the operator supplies the path to their bitcoin.conf.

How it works

1. UI field “bitcoin.conf path” (optional, OS-aware placeholder)
2. Path is sent along with the /api/bitcoin-health POST
3. Server parses the file with parse_bitcoin_conf_str(&str) -> BTreeMap<String, Vec<String>> — line-based, tolerant of:
   • Comments (# ...)
   • Empty lines + whitespace
   • Section headers [main] [test] (ignored, all keys flattened)
   • Multiple values per key (e.g. two zmqpubhashblock= lines)
   • Malformed lines (no = → ignored, no crash)
4. generate_bitcoinconf_snippet(&BitcoinHealth, parsed.as_ref()) filters per recommendation: if !parsed.contains_key("zmqpubhashblock") → push recommendation

Default behavior is preserved

If the path is not set: all recommendations as before. If the path is set but the file isn’t readable: all recommendations + warning “bitcoin.conf at … not readable”.

Example

bitcoin.conf before the health check:

server=1
rpcuser=warppool
zmqpubhashblock=tcp://127.0.0.1:28332
maxconnections=200

What previously would have been suggested in the snippet:

• zmqpubhashblock=tcp://127.0.0.1:28332 (even though it’s already there!)
• zmqpubrawblock=tcp://127.0.0.1:28333 (may be missing)
• maxconnections=125 (even though 200 is already set!)
• listen=1 (may be missing)

What with Phase 12 gets suggested:

• only zmqpubrawblock=tcp://127.0.0.1:28333 and listen=1 — the rest is already configured.

What we do NOT do

• No value-compare: if the operator has maxconnections=10 (bad), we still don’t suggest maxconnections=125 — we trust that the operator chose that value deliberately. We only fix “missing keys”, not “bad values”.
• No direct write: we only parse read-only, no backup risk.
• No TOML/JSON format: bitcoin.conf has its own line-based format, not TOML.

Phase 13 — daemon periodic health check

The setup wizard runs once at first-run. The daemon runs continuous checks in the running pool — and pushes every change as an SSE event so the UI can show a dashboard widget.

Wiring

13a — crate extraction: The health logic was extracted out of the setup wizard into its own crate warppool-health. Since then the setup wizard is just a thin axum wrapper; the daemon can call the same functions directly without code duplication.

13b — periodic task: At startup, the daemon spawns a tokio task that runs the health check every N seconds (default 60). Activated via env:

WARPPOOL_HEALTH_CHECK_INTERVAL_SECONDS=60 dvb-warppool-daemon
# 0 = off (default on when env not set → 60s)

Per tick:

1. Re-resolve RPC auth from config.node.rpc_cookie_path (preferred) or secrets.rpc_user/rpc_pass (the cookie gets rotated on Bitcoin Core restart — we read fresh every time)
2. warppool_health::check_bitcoin_health(&client, &url, &auth).await
3. collect_bitcoin_warnings(&h)
4. event_bus.publish(PoolEvent::HealthSnapshot { ... })

SSE event format

{
  "type": "health_snapshot",
  "at": "2026-05-27T12:00:00Z",
  "rpc_ok": true,
  "peers_total": 12,
  "peers_inbound": 3,
  "ibd": false,
  "pruned": false,
  "zmq_hashblock_ok": true,
  "warnings": [
    "Few peers (3/8 recommended) — tip latency increased"
  ],
  "warning_keys": [
    { "key": "bitcoin_few_peers", "message": "…", "params": { "total": "3" } }
  ]
}

warnings is the legacy array of ready-made strings; warning_keys carries the same warnings structured (stable key + params) so the UI can localise them into all supported languages and so an operator can suppress a warning by key (see below). The UI prefers warning_keys and falls back to warnings.

The UI subscribes via EventSource('/api/events'), dispatches on event.type === 'health_snapshot', and renders a banner/badge with the warnings (HealthBanner.svelte).

What it deliberately does NOT do

• No bitcoin.conf parse in the periodic check — that’s setup-wizard-specific because it generates snippet recommendations. The daemon doesn’t need it.
• No UPnP check in 13b — UPnP state changes rarely and is operator-side. The setup wizard checks once.
• No delta detection — we push every snapshot; the UI does the client-side compare if needed. Saves server state. (Still true today.)
• No read-only API endpoint GET /api/admin/health — the UI uses SSE. The only admin health routes that exist are the suppression ones below. A pull endpoint for CLI scripting is still open; for now, /metrics covers scripted monitoring.

Operator example

# Filter the live SSE stream down to health events
curl -N http://localhost:18334/api/events 2>/dev/null \
    | grep -A1 'event: health_snapshot'

# event: health_snapshot
# data: {"type":"health_snapshot","at":"...","rpc_ok":true,...}

The operator sees, for example, when after weeks of uptime zmq_hashblock_ok=false suddenly shows up (Bitcoin Core restarted without ZMQ config) — and can react without anyone having to monitor hands-on.

Phase 14 — health banner in the dashboard (shipped)

The health_snapshot events are rendered by HealthBanner.svelte as a persistent banner below the header, localised from warning_keys (falling back to the raw warnings strings for older daemons). The banner is dismissable per session on purpose — no localStorage, so a reload brings it back and nothing gets permanently hidden by accident.

Suppressing a warning permanently

Some warnings are correct but irrelevant for a given deployment — a deliberately pruned node, for example, does not need to be told it is pruned on every reload. A logged-in operator can therefore suppress a warning by its stable key:

• In the UI: Admin → Health, or the “hide permanently” control on the banner.
• Over the API: GET /api/admin/health/suppressions, POST /api/admin/health/suppress { "key": "bitcoin_pruned" }, DELETE /api/admin/health/suppress { "key": "bitcoin_pruned" } — all admin-authenticated.

The stable keys are bitcoin_ibd, bitcoin_few_peers, bitcoin_no_inbound_listen, bitcoin_no_inbound_no_listen, bitcoin_no_zmq_hashblock, bitcoin_pruned, bitcoin_verification_progress and ipc_template_stale.

The suppression list lives in the database and is re-read on every health tick, so changes take effect without restarting the daemon. Suppressed keys are filtered out before the legacy warnings strings are built, so a suppressed warning disappears from both fields. Only warnings that carry a key can be suppressed.

IPC template-stale warning

When the pool takes its templates from Bitcoin Core’s IPC interface ([node] template_source = "ipc" — note that Core’s IPC interface is itself experimental), the health loop additionally watches whether templates are still arriving. If none has arrived for longer than 3 job-refresh intervals (at least 90 s), it raises the suppressible ipc_template_stale warning — a permanently dead socket (node downgraded below Core 31, IPC toggle off, mount gone) would otherwise fail silently as “no new jobs”. It is deliberately only a warning: there is no automatic fallback to GBT; the way back is setting [node] template_source = "gbt" and restarting.

See also

• Notifications — rpc-down / rpc-recovered events are fired by the same health loop
• Observability — warppool_rpc_ready + RPC latency histogram
• Troubleshooting — when the wizard shows “cookie not readable” or UPnP finds no gateway

Resilience (Multi-Node)

A solo pool is only as available as the Bitcoin Core node behind it. A single bitcoind is a single point of failure: if it crashes, falls behind, or is restarted for an upgrade, the pool can’t build templates — and worst of all, a node that’s down at the exact second you solve a block can cost you the reward. dvb-WarpPool lets you run one or more backup nodes so a primary outage becomes a non-event.

Add a backup node

Backup nodes live in config.toml. The [node] block is your primary; add any number of [[node.backup]] entries below it:

[node]
rpc_url = "http://127.0.0.1:8332"
zmq_hashblock_addr = "tcp://127.0.0.1:28332"

[[node.backup]]
rpc_url = "http://192.168.1.50:8332"
zmq_hashblock_addr = "tcp://192.168.1.50:28332"   # "" = no ZMQ from this node (poll-only)
# rpc_cookie_path = "/mnt/node-b/.bitcoin/.cookie" # optional — see auth below

Authentication is resolved per backup, in this order:

1. rpc_cookie_path — a local second node with its own data dir.
2. user:pass embedded in the URL (http://user:pass@host:8332) — a remote node with its own credentials (this lives in config.toml, so mind the file permissions).
3. Nothing — the global secrets.rpc_user / rpc_pass are reused (handy when the backup is provisioned identically to the primary).

The [node] block is read at startup only — restart the daemon after adding or changing a backup. This briefly interrupts mining; miners reconnect on their own.

The full field reference is in the Configuration Reference.

How failover behaves

• Sticky, primary-preferred. Calls run against the last working node. On a transport, auth, or warm-up error they hop to the next node within the same call — the job loop never stalls. While running on a backup, about once a minute one call probes the primary first and switches back the moment it answers.
• submitblock goes to every node in parallel. The block moment is the one instant a dead node can cost real money, so the solved block is broadcast to all nodes at once; the first Accepted wins.
• ZMQ subscribes to every node that sets zmq_hashblock_addr. Block events are deduplicated by hash, so whichever node reports first triggers the template refresh — you automatically get the lowest-latency node.
• Degraded ≠ down. A pool happily running on a backup is degraded, not down: the health snapshot carries a warning, and rpc-down fires only when no node is reachable at all.

Verified live: primary kill → failover in under a second with the job stream uninterrupted; primary restart → automatic return within ~60 s.

Notifications

• node-failover — the active node changed (failover to a backup, or return to the primary).
• rpc-down — no node reachable at all.
• rpc-recovered — RPC is answering again after an rpc-down.

All three go to sinks that enabled on_rpc_down.

See Notifications for sink setup.

Tips

• Put the backup on separate hardware and power — a backup on the same machine only covers bitcoind crashes, not host failures.
• A node without ZMQ still works as an RPC failover target (poll-only); set zmq_hashblock_addr = "" to skip ZMQ from a node that doesn’t expose it.
• Order matters only as preference: the primary is always tried first on the periodic probe; backups are tried in the order they appear.

See also

• Configuration Reference — full [[node.backup]] fields
• Notifications — node-failover / rpc-down events
• Setup Health-Checks

Notifications

dvb-WarpPool can notify the operator over several independent channels when relevant pool events occur — most importantly block found. Configuration lives in config.toml under [notifier]; secrets (API tokens, webhook URLs, SMTP passwords) are always referenced via env var, never inline.

Currently active (Phase 15):

Events

The daemon emits these event types:

Each sink can toggle which events it cares about (all bool). ntfy, Slack and Email support on_block_found, on_miner_disconnect, on_rpc_down and on_health_alert; Telegram and Discord support on_block_found and on_health_alert. Defaults everywhere: on_block_found = true and on_health_alert = true, the rest off. Since v1.0.16 all sinks can also be configured from the admin UI (tokens land write-only in secrets.toml).

Retry: 3 attempts per sink — the first immediately, then after 10 s and after 30 s. If everything fails, it gets logged but the daemon keeps running — a notifier failure must never disrupt mining.

Per-wallet miner notifications

Everything above is the operator’s notifier: pool-wide sinks configured in config.toml, firing on any block or any health event. A public 0%-fee per-worker pool, where every miner mines to their own address, needs the opposite: each miner wants alerts about their own address only — without the operator wiring anything up, and without an account.

That is what the owner panel on a wallet page provides. It is a separate, self-service path with no config.toml involvement at all:

1. A miner opens their public page at /users/<address>.
2. They click verify ownership, sign the one-time challenge in their wallet’s Sign Message box (BIP-137 — no key revealed, no funds moved, no account), and submit the signature.
3. Once verified, a Notifications field appears. They paste a personal target and save it — for this address only.

The target is a single http(s) URL — either an ntfy topic URL or a generic webhook. The daemon POSTs an ntfy-compatible request (Title / Priority / Tags headers + a text body), so an ntfy topic renders as a proper push notification and a plain webhook receives the text body.

Because the target is miner-supplied (untrusted), every per-wallet POST goes through the same SSRF guard as outbound webhooks — internal / link-local hosts (127.0.0.1, 169.254.169.254, 10.x, …) are refused and redirects are not followed, so a miner can’t turn the daemon into a proxy onto the operator’s LAN. Delivery failures are logged and dropped; a miner’s dead endpoint never affects mining or the operator’s own sinks.

This is not the payout engine. The owner panel is a free, non-custodial notification + privacy feature in the OSS core — signing a message proves an address is yours, nothing more. It is unrelated to any reward-sharing or custody product.

Taproot note: ownership signing works for single-key P2PKH / P2WPKH / P2SH-P2WPKH addresses. A Taproot (P2TR) miner can mine and gets a public page, but cannot open the owner panel — the legacy signed-message format has no Taproot variant.

Sharing notifications with friends

A solo+friends pool is more fun when everyone gets the 🎉 the moment a block is found — not just the operator. Every server-side sink above is a broadcast channel, so nothing new needs to be built: you just point the sink at something your whole group can see.

ntfy: the zero-friction option

ntfy is the easiest way to let a whole group subscribe — no accounts, no bots, no invites. The topic name is the subscription:

1. You (the operator) configure [notifier.ntfy] as shown below.
2. Each friend installs the ntfy app (Android / iOS / web — see ntfy.sh) and subscribes to the exact same topic name, e.g. my-secret-pool-topic-abc123.
3. Done — every block-found (and whatever else you enabled) lands on every subscribed phone simultaneously.

Two things to keep in mind:

• The topic name is the only secret. On public ntfy.sh, anyone who knows it can read your pool events and post their own messages to the topic. Pick a long random string, share it privately, rotate it if it leaks. Pool events carry no sensitive data (worker names, block height, health states) — the realistic worst case is a prankster posting fake “block found” messages.
• If your group outgrows the shared-secret model, self-hosted ntfy (or a paid ntfy.sh tier) adds real access control: reserved topics with read-only access for subscribers.

Telegram: group chat instead of DM

The chat_id doesn’t have to be your private chat — a group works exactly the same way:

1. Create a Telegram group with your friends.
2. Add your bot to the group.
3. Send any message in the group, then fetch https://api.telegram.org/bot<TOKEN>/getUpdates and look for the group’s "chat":{"id":-100…} — group ids are negative; copy the minus sign too.
4. Put that id into chat_id and restart the daemon.

Everyone in the group now sees every notification, and the group doubles as the place to celebrate.

Discord and email

• Discord — webhooks post into one channel; pick a channel on a server your friends are on (instead of a private one) and you’re done.
• Email — to is a list, every address gets its own copy: to = ["you@example.com", "friend-a@example.com", "friend-b@example.com"].

What about Web Push?

The PWA background push subscribe button lives on the admin notifications page, which requires the operator login — so treat Web Push as the operator’s personal channel and use the sinks above for the group.

ntfy.sh

Simple and account-free. A single topic URL is enough.

[notifier.ntfy]
topic_url = "https://ntfy.sh/my-secret-pool-topic-abc123"
on_block_found = true
on_miner_disconnect = false
on_rpc_down = true

On your phone, install the ntfy app, subscribe to the same topic name, done. Topic names are effectively a shared secret — choose a hard-to-guess string.

For self-hosted ntfy, just use topic_url = "https://ntfy.your-domain.com/topic".

Telegram

Create a bot via @BotFather → note the token. You get a chat_id by sending the bot a message and then fetching https://api.telegram.org/bot<TOKEN>/getUpdates (look for "chat":{"id":…}).

[notifier.telegram]
bot_token_env = "TELEGRAM_BOT_TOKEN"
chat_id = "123456789"
on_block_found = true

Then in the daemon environment:

TELEGRAM_BOT_TOKEN="123:abc..." dvb-warppool-daemon

With systemd: Environment="TELEGRAM_BOT_TOKEN=…" in the unit file, or better an EnvironmentFile=/etc/default/dvb-warppool with chmod 600.

Discord

In the server settings under Integrations → Webhooks, create a new webhook and copy the URL. The URL is effectively the auth token — anyone who has it can post.

[notifier.discord]
webhook_url_env = "DISCORD_WEBHOOK_URL"
on_block_found = true

DISCORD_WEBHOOK_URL="https://discord.com/api/webhooks/…" dvb-warppool-daemon

Slack

Create a Slack app in your workspace → enable Incoming Webhooks → generate a webhook for a channel. The payload uses Block Kit (header + section with mrkdwn) for clean layout.

[notifier.slack]
webhook_url_env = "SLACK_WEBHOOK_URL"
on_block_found = true
on_miner_disconnect = false
on_rpc_down = true

Email (SMTP)

lettre-based, with rustls — no openssl-sys. Two URL schemes:

• smtps://user@host:465 — implicit TLS (common with providers like Posteo, Migadu, Fastmail, Hetzner)
• smtp://user@host:587 — STARTTLS (gmail, many mail servers)

[notifier.email]
smtp_url = "smtps://pool@mail.example.com:465"
from = "pool@example.com"
to = ["operator@example.com", "monitoring@example.com"]
password_env = "POOL_SMTP_PASSWORD"
on_block_found = true
on_miner_disconnect = false
on_rpc_down = true

POOL_SMTP_PASSWORD="…" dvb-warppool-daemon

password_env is optional — if omitted, no SMTP AUTH is attempted (useful for a local MTA like Postfix on localhost:25 that relays internally).

With multiple recipients, each one gets their own letter — also a simple way to notify the whole team at once.

Test workflow

After configuration:

1. Restart the daemon — logs show notifier sink ready for each working sink. If an env var is missing or a required config field is empty, you’ll see notifier sink skipped with a reason; the daemon starts anyway.
2. In the admin UI under /admin/notifications → “Server-Side Sinks (Daemon)” lists all active sinks.
3. Per sink, a Test button → POST /api/admin/notifier/test?sink=<name> fires a test event at just that one. The badge switches to ok/err.
4. Test all sinks button → POST /api/admin/notifier/test with no param.

The same via CLI:

curl -X POST \
  -H "Authorization: Bearer wpat_…" \
  http://pool.local:18334/api/admin/notifier/test?sink=ntfy

Web Push (PWA, VAPID — Phase 21)

In addition to the 5 server-side sinks above, there’s background push straight to your phone via VAPID Web Push. Works even when the PWA is closed (iOS 16.4+, Android, desktop). No 3rd-party service required — push goes directly from the pool daemon to the browser push service (FCM/Mozilla/Apple).

Operator setup

# 1. Generate VAPID keys
dvb-warppool-cli gen-vapid-keys >> /etc/dvb-warppool/secrets.toml

# 2. Optional: set contact mailto (otherwise defaults to mailto:operator@localhost)
echo 'vapid_contact = "mailto:operator@example.org"' >> /etc/dvb-warppool/secrets.toml

# 3. Restart the daemon
systemctl restart dvb-warppool

Daemon log shows web-push sender ready. If not: VAPID keys weren’t found in secrets.toml — push stays disabled, other notifiers run anyway.

User subscribe flow

1. Open the pool UI, log in
2. Go to /admin/notifications → “Enable background push” button
3. Browser asks for permission → “Allow”
4. Subscription is registered with the pool, from now on pushes arrive

Which events fire push

Other events (SharesAccepted tick, NewJob, etc.) do NOT fire push — too spammy for background notifications.

iOS quirks

• Required: add the PWA to the home screen (Safari share menu → “Add to Home Screen”). In a regular Safari tab, iOS ignores Web Push.
• iOS 16.4+ is the minimum version (March 2023). On older iOS versions the UI shows a Browser unsupported badge.

Security note

The VAPID private key is sensitive — anyone holding it can impersonate your pool to the push services. secrets.toml chmod 600. On suspected leak: generate new keys + invalidate all subscriptions (a restart is enough — stale subscriptions get deleted on the first 401 response).

Outbound webhooks

For any target not built in as a dedicated sink (PagerDuty, Opsgenie, a custom endpoint, a home-automation hook), the pool ships a generic outbound webhook with HMAC signing — no vendor lock-in. Configure one or more in config.toml:

[[webhooks]]
url = "https://example.com/hook"
secret_env = "MY_HOOK_SECRET"   # optional — HMAC-SHA256 over the request body
events = []                     # empty = default low-frequency set
# enabled = true                # set false to disable without deleting the block

• Payload: JSON { "event": "<type>", "ts": "<rfc3339>", "data": { … } } — ts is an RFC3339 string (e.g. "2026-06-19T12:00:00+00:00"), not a unix number.
• Headers: X-WarpPool-Event: <type> and, when secret_env is set, X-WarpPool-Signature: sha256=<hmac-hex> (GitHub-style, verify against the raw body).
• Events: the default set is low-frequency — block_found, health_snapshot, update_available, profile_switched. Opt into the high-frequency new_job / shares_accepted explicitly via events only if you want the POST storm.
• Delivery: 10 s timeout per request, 3 attempts (immediate, then after 1 s and 3 s). After that the event is logged and dropped — there is no unbounded buffer, so a down consumer cannot back the pool up. Loopback/LAN targets are allowed by design (operator-controlled, no SSRF block).

See also Extending → public API & webhooks.

Other Phase B options

• Matrix — not implemented; PR welcome, analogous to the Slack sink pattern.

See also

• Setup Health Checks — RPC-down/recovered are fired by the same health loop
• Observability — notifier counter warppool_notifier_events_sent_total
• Configuration Reference — all config.toml fields

Observability

dvb-WarpPool exposes its runtime state in two complementary ways:

1. Pull — Prometheus-compatible /metrics endpoint
2. Push — Notifier sinks (see Notifications) for operator-aware events

A good setup uses both: Prometheus scrapes every 15s for trends and alerts, and critical events (block found, RPC down) go out immediately as notifications.

/metrics Endpoint

Path: GET /metrics on the regular API port (default 18334). Format: Prometheus text exposition text/plain; version=0.0.4.

Authentication: none — the endpoint is read-only and contains no secrets. If your pool network is public and you don’t like that, put a reverse proxy with basic auth in front of it.

Base counters (always present)

Aggregated pool gauges (always present)

Computed per scrape from the pool stats, the live network snapshot, and the most recent completed 5-minute share bucket.

warppool_pool_hashrate_hps uses the completed bucket on purpose: the in-progress bucket holds only a fraction of its 5-minute window and would read low. For a solo pool with a single small miner this value is noisy by nature (few shares per bucket — Poisson scatter), so smooth it in PromQL rather than trusting a single sample:

avg_over_time(warppool_pool_hashrate_hps[15m])

Phase 16: extended pool metrics

These are active as soon as the daemon hands PoolMetrics to the API state (automatic when the daemon binary is running; optional in test setups).

Total active miners = sum(warppool_active_connections).

Histogram buckets (seconds): 0.001, 0.005, 0.01, 0.05, 0.1, 0.25, 0.5, 1.0, 2.5, 5.0, +Inf. Prometheus cumulative semantics — each observation increments every bucket ≥ its value.

Example query (Grafana):

# p99 RPC latency, last 5 minutes
histogram_quantile(0.99, rate(warppool_bitcoin_rpc_latency_seconds_bucket[5m]))

# RPC call rate
rate(warppool_bitcoin_rpc_latency_seconds_count[1m])

Phase 22: per-miner vendor probe metrics

When the daemon’s miner_poll_loop is running (default), configured miners are polled on the active profile’s interval — 30 s on Small down to 1 s on Enterprise (see the profile table) — and their telemetry values are exposed as gauges:

None fields are skipped — if a miner doesn’t report voltage_mv, for example, the metric is simply omitted for that miner (instead of 0, which would wreck the operator’s trend lines).

If WARPPOOL_AUTO_PROBE_DISCOVERED=true is set, miners discovered via mDNS are also included with label="discovered" — the operator can separate them with:

# Configured miners only
warppool_miner_hashrate_ghs{label!="discovered"}

# Discovered miners (not in the DB)
warppool_miner_hashrate_ghs{label="discovered"}

Example queries:

# Total pool hashrate (sum of all miners)
sum(warppool_miner_hashrate_ghs)

# Maximum temperature across all miners — operator alarm if > 85°C
max(warppool_miner_temperature_c)

# Hashrate per worker per watt (efficiency)
warppool_miner_hashrate_ghs / warppool_miner_power_w

# Which miners have a failing probe cycle?
warppool_miner_probe_health == 0

Phase 15/16: notifier metrics

When a notifier is configured:

result = "ok" or "err". event is one of block-found, miner-disconnect, rpc-down, rpc-recovered, node-failover, health-alert, test.

Example query: sink failure rate (a hint at wrong env vars or blocked webhooks):

rate(warppool_notifier_events_sent_total{result="err"}[5m])
  / ignoring(result) group_left
  rate(warppool_notifier_events_sent_total[5m])

Rate-limit / IP bans

Present when the rate-limiter is wired (the daemon does this automatically). Counts only — no per-IP labels (cardinality and operator privacy).

# Alert hint: auto-banner suddenly very active (abuse wave or misconfig)
warppool_auto_bans_active > 20

Grafana Dashboard

A starter dashboard with the most important panels:

{
  "title": "dvb-WarpPool",
  "panels": [
    {
      "title": "Blocks Found",
      "type": "stat",
      "targets": [{ "expr": "warppool_blocks_found_total" }]
    },
    {
      "title": "Pool Hashrate (H/s)",
      "type": "timeseries",
      "targets": [{
        "expr": "avg_over_time(warppool_pool_hashrate_hps[15m])"
      }]
    },
    {
      "title": "Active Connections",
      "type": "timeseries",
      "targets": [
        { "expr": "warppool_active_connections{protocol=\"v1\"}", "legendFormat": "v1" },
        { "expr": "warppool_active_connections{protocol=\"v2\"}", "legendFormat": "v2" }
      ]
    },
    {
      "title": "RPC Latency (p50/p99)",
      "type": "timeseries",
      "targets": [
        { "expr": "histogram_quantile(0.50, rate(warppool_bitcoin_rpc_latency_seconds_bucket[5m]))", "legendFormat": "p50" },
        { "expr": "histogram_quantile(0.99, rate(warppool_bitcoin_rpc_latency_seconds_bucket[5m]))", "legendFormat": "p99" }
      ]
    },
    {
      "title": "Bitcoin Core Health",
      "type": "stat",
      "targets": [
        { "expr": "warppool_rpc_ready" },
        { "expr": "warppool_rpc_ibd" }
      ]
    }
  ]
}

(A full dashboard with variables and annotations may follow later as packaging/grafana/dashboard.json.)

Prometheus scrape config

scrape_configs:
  - job_name: dvb-warppool
    scrape_interval: 15s
    static_configs:
      - targets: ['pool.local:18334']

Alert recipes

RPC unreachable > 2min

- alert: WarppoolRpcDown
  expr: warppool_rpc_ready == 0
  for: 2m
  annotations:
    summary: "Pool {{ $labels.instance }} has no RPC connection to the Bitcoin node"

No shares > 10min (miner offline?)

- alert: WarppoolNoShares
  expr: rate(warppool_shares_accepted_total[10m]) == 0
  for: 10m
  annotations:
    summary: "Pool {{ $labels.instance }} is receiving no shares"

RPC latency p99 > 1s

- alert: WarppoolRpcSlow
  expr: |
    histogram_quantile(0.99,
      rate(warppool_bitcoin_rpc_latency_seconds_bucket[5m])
    ) > 1
  for: 5m

Notifier sink failing persistently

- alert: WarppoolNotifierBroken
  expr: |
    rate(warppool_notifier_events_sent_total{result="err"}[15m])
      / ignoring(result) group_left
      rate(warppool_notifier_events_sent_total[15m]) > 0.5
  for: 15m
  annotations:
    summary: "Notifier sink {{ $labels.sink }} failing >50% — check config"

SSE Events (separate story)

Alongside /metrics, /api/events runs a Server-Sent-Events stream that pushes live events to the UI. The full set of event types:

It’s primarily intended for the UI banners; for monitoring, use /metrics — Prometheus is more robust against scraping pauses. The same events can be pushed to your own endpoint instead — see [[webhooks]].

Note that the operator announcement banner is not an SSE event: the UI picks it up from the banner field of /api/overview (see Announcement banner).

See also

• Setup Health-Checks
• Notifications
• Configuration Reference

Troubleshooting

A pragmatic fix-guide for the most common problems. For each symptom: brief explanation → diagnostics → fix.

General: reading logs

journalctl -u dvb-warppool -f --since "5 min ago"

For Docker:

docker logs -f dvb-warppool --since 5m

Temporarily raise the log level:

RUST_LOG=warppool=debug,info dvb-warppool-daemon

Targeted per crate:

RUST_LOG=warppool_stratum_v1=trace,warppool_bitcoin_rpc=debug,info dvb-warppool-daemon

RPC

getblockchaininfo failed: HTTP 401 — credentials rejected

Cookie or user/pass mismatch.

Diagnosis:

# Cookie auth:
cat ~/.bitcoin/.cookie       # should be "user:hexhash"
# user/pass auth:
grep -E "^rpc(user|password)" ~/.bitcoin/bitcoin.conf

Fix:

• Cookie mode: make sure node.rpc_cookie_path in config.toml points to the correct file. Bitcoin Core has its own cookie files for regtest/testnet (~/.bitcoin/regtest/.cookie, ~/.bitcoin/testnet3/.cookie). The setup wizard typically shows the right path.
• user/pass mode: in secrets.toml, rpc_user + rpc_pass must match the values in bitcoin.conf. In secrets.toml, not config.toml — otherwise the daemon complains at startup.
• On permission errors: bitcoind runs as a different user; the cookie is 0600 and unreadable for your warppool user. The setup wizard catches this and suggests chmod g+r + group-add.

getblocktemplate failed: -8 ...

Bitcoin Core is reachable, but says no to the template.

Possible causes:

• IBD running: warppool_rpc_ibd == 1. Wait until sync completes.
• Wallet locked: getblocktemplate without -walletbroadcast=0 needs an unlocked wallet in Core. Unusual in a pool context, though — we use GBT without a wallet.
• Too few peers: getpeerinfo shows 0 or 1. Core then refuses to mine to avoid ending up on a minority fork. Fix: wait, or use -minimumchainwork=0 for tests.

RPC latency high (Prometheus shows p99 > 1s)

Diagnosis:

• Are many RPCs running in parallel? The daemon normally does ~1-5/s in steady state. If p99 is high: is Bitcoin Core on a slow disk or swapping?
• tx-index=1 setup on HDD: makes GBT slow. SSD recommended.
• Pruned node + old block request: doesn’t happen on the normal pool path, but backup/restore workflows can trigger it.

Fix: usually a disk bottleneck. iotop / iostat shows this quickly.

ZMQ

Daemon only uses poll-loop, no ZMQ

Symptom: job refresh runs poll-only because no ZMQ watcher is active — the [node] zmq_hashblock_addr in config.toml is empty or missing (it is not an env var). If a configured channel later drops, the log shows:

zmq channel closed — falling back to polling only

Fix: set in config.toml:

[node]
zmq_hashblock_addr = "tcp://127.0.0.1:28332"

And in bitcoin.conf:

zmqpubhashblock=tcp://127.0.0.1:28332

Bitcoin Core must be restarted after this change.

ZMQ connection refused / timeout

Bitcoin Core isn’t listening on the ZMQ port. Diagnosis:

ss -tlnp | grep 28332
# Expected output: bitcoind listens on 0.0.0.0:28332 or 127.0.0.1:28332

If nothing: the bitcoin.conf line is missing or Bitcoin Core wasn’t restarted.

If 0.0.0.0: ZMQ is exposed — often necessary with a Docker bridge (daemon and bitcoind in different containers). On a direct host tcp://127.0.0.1:28332 should be enough.

Stratum / miner connections

Workers reconnect-loop every few seconds

Symptom: many session ended with shares_accepted = 0 in the logs. Many miner-disconnect events in the notifier (or, with Phase 15 debounce, one every 30s).

Common causes:

• Wrong worker address: a V1 miner submits an address the ShareValidator doesn’t accept. Logs show mining.authorize with a bad address.
• VarDiff too aggressive: the initial diff was too high, the miner can’t produce shares within the target_seconds_per_share window, retargets down quickly, and some firmwares don’t like rapid retargets. Fix: a higher min_diff or a lower initial_diff in [vardiff].
• Auth rate limit kicks in: at >auths_per_sec auth attempts per IP you get rejected. In the log: auth rate-limited. For legitimate cases with multiple workers behind NAT: raise the rate limit.

Miner can’t connect at all

# Is the pool port reachable?
nc -v pool.local 3333
# TLS port?
openssl s_client -connect pool.local:3334 -showcerts

If local is OK but external isn’t: firewall / NAT. The UPnP wizard in setup (Phase 11) can open this automatically, but only if the FritzBox / router allows UPnP. Some ISP routers have UPnP off by default.

External miner suddenly can’t connect (auto-banned)

A public IP that repeatedly trips the connect rate limit is auto-banned and dropped before the handshake (default: 10 strikes / 60 s → escalating 5 min … 1 h). Loopback and private LAN are never auto-banned. Check the ban state via /metrics (warppool_auto_bans_active, warppool_manual_bans) or the Admin → Profile panel. Clear a manual ban with POST /api/admin/ratelimit/unban; relax auto-ban via [ratelimit].autoban_* (or autoban_enabled = false).

Dashboard shows “API unreachable → HTTP 429”

The HTTP API is per-IP rate-limited (api_rpm, profile-driven; over the limit → HTTP 429 + Retry-After). Loopback and private LAN are exempt (the LAN exemption was widened in v1.4.1 — before that, reaching the dashboard over the box’s LAN IP with several tabs + polling could trip it). If you still see it from a genuinely remote IP, switch to a larger profile (bigger api_rpm) or put a reverse proxy with its own limits in front.

Miner is on the wrong protocol port

Each protocol has its own endpoint: Stratum V1 plain on 3333, V1-over-TLS on 3334, Stratum V2 on 34254 (defaults; the connect modal in the UI shows the exact host:port for all three). A miner in SV2 mode pointed at 3333 fails its NOISE handshake against the line-based V1 listener; a V1 miner on 34254 dies in the encrypted framing. Since v1.0.22 both listeners detect this mismatch and log a warning naming the right port — grep -i "point it at" in the pool log finds it. (Real-world example: #60, a Bitaxe in SV2 mode configured with the V1 port.)

TLS: handshake fails with BadCertificate

Symptom: the miner works on port 3333 but not on the TLS port; the daemon log shows, once per reconnect attempt:

WARN tls handshake failed peer=192.168.x.y:nnnnn error=received fatal alert: BadCertificate

The alert comes from the miner: its firmware verifies the server certificate and rejects the pool’s self-signed one. What works depends entirely on what the firmware offers (ESP-Miner family naming):

A bundled-CA-only firmware insists on a certificate signed by a public CA — that is the whole point of the check, so there is no self-signed workaround. Realistic options:

1. Stay on plain :3333 for that miner. In a home LAN this is a perfectly reasonable trade-off (TLS on Stratum mainly guards against on-path tampering; the share data itself is not secret).
2. Serve a CA-signed certificate: if you own a domain, issue e.g. a Let’s Encrypt certificate for pool.example.com (DNS-01 challenge — the host doesn’t need to be publicly reachable), point the DNS record at the pool’s LAN IP, set [stratum] tls_cert_path/tls_key_path to the issued files and connect the miner to pool.example.com:3334. Renewal (90 days for LE) plus a daemon restart is your responsibility.
3. Ask the vendor for a firmware update — ESP-Miner mainline already ships the “TLS (Custom CA certificate)” mode, so forks usually pick it up over time.

A plaintext miner pointed at the TLS port produces a different error (tls handshake failed ... received corrupt message-style) — that is a forgotten SSL toggle, not a certificate problem.

Notifier doesn’t fire

notifier sink skipped: env var foo not set

At daemon start, the env vars for the sink aren’t present. With systemd:

[Service]
EnvironmentFile=/etc/default/dvb-warppool

With /etc/default/dvb-warppool as a chmod-600 file:

TELEGRAM_BOT_TOKEN=123:abc...
DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/...
POOL_SMTP_PASSWORD=...

For Docker: via -e KEY=val or an env-file in docker-compose.yml.

Test button shows err

Click Test in the admin UI → err badge. The specific error shows as a tooltip on the badge (hover). Common cases:

• Telegram: bot not found — wrong bot_token. chat not found — wrong chat_id or the bot was removed from the chat.
• Discord: Unknown Webhook — webhook was deleted.
• Slack: invalid_payload — very rare; usually a typo in the webhook URL.
• Email: Could not resolve host — wrong SMTP host. authentication failed — wrong password env. unable to connect: connection refused — wrong port or firewall.

Spam from miner-disconnect events

Per-worker debounce is 30s (WARPPOOL_DISCONNECT_DEBOUNCE_SECS). If that’s too noisy: set the env var to 300 (5min).

If a single worker keeps disconnecting: that’s a real problem on the miner side — check the logs on the miner hardware (the Bitaxe web interface has Logs; Antminer has SSH access).

Auto-update

Update fails: download/verify: sha256 mismatch

The release asset was changed between when you saw the release and downloaded it (rare), or you passed the wrong sha256. For POST /api/admin/update, always take the sha256 from the release notes file or from the forge API itself — never type it manually.

Update applied but daemon keeps restarting (StartLimitBurst)

The Phase 8f rollback hook fired. The systemd journal shows:

OnFailure=dvb-warppool-rollback.service triggered

rollback.sh copies the .backup back and runs systemctl restart. If the backup is also broken: install the old version manually or roll back from a snapshot.

cosign verify-blob failed

When cosign_verify=true is set in the update request: the signature doesn’t match the asset. Possible causes:

• The asset is authentic but the signature file is stale
• The asset has been tampered with

The default is cosign_verify=false — only use cosign if you’ve explicitly configured the trust anchor (public key or Sigstore root).

Setup wizard

“Cookie not readable”

Most likely a permission issue. The setup wizard shows the exact path + suggested fix:

sudo usermod -a -G bitcoin warppool   # one-time
sudo chmod g+r ~/.bitcoin/.cookie     # after every Core restart

Cleaner: configure bitcoind with rpcauth=warppool:saltedhash and use user/pass mode instead of the cookie.

UPnP test “no gateway found”

The router has UPnP off, or the daemon is bound to the wrong interface. Some ISP routers (Vodafone, some FritzBoxes with a locked-down user account) don’t allow UPnP from the outside.

Fix:

• Enable UPnP in the router web interface
• Alternatively: set port forwarding manually (3333/3334)

bitcoin.conf snippet suggests recommendations for keys that are already set

If the setup wizard says “add zmqpubhashblock=...” even though it’s already there — usually the wrong conf path. Check bitcoin-cli -datadir=… getrpcinfo to see the datadir that’s actually in use.

API / UI

/api/admin/* returns 401

Admin auth is configured but the token is missing from the request:

curl -H "Authorization: Bearer wpat_…" http://pool.local:18334/api/admin/notifier/sinks

Generate a token with dvb-warppool-cli token-create -n my-script — the raw token is shown only once.

/api/admin/* returns 503 “auth disabled”

secrets.toml has no admin_password_hash or jwt_secret. Fix:

dvb-warppool-cli hash-password

and paste the output into secrets.toml.

UI doesn’t load — Failed to fetch /api/...

Direct --ui-dir mode or dev mode? In dev (pnpm dev), Vite runs with a proxy /api → http://127.0.0.1:18334. In production: the UI is served directly by the daemon via --ui-dir. Check the daemon startup log:

serving static UI from daemon ui_dir=/usr/share/dvb-warppool/ui

If not present: the --ui-dir flag is missing or the directory doesn’t exist.

Announcement banner doesn’t show up

The marquee announcement (Admin → Banner, since v1.21.0) is stored as two pool_settings rows — text plus an RFC3339 expiry — and served in the banner field of GET /api/overview. It is suppressed when the text is empty, the expiry is missing/unparseable, or the expiry is already in the past — in that case the field is omitted from the response entirely, not sent as an empty string. So:

curl -s http://pool.local:18334/api/overview | grep -o '"banner":[^}]*}'

If that prints nothing, the announcement has expired (or was cleared) — re-post it via Admin → Banner or POST /api/admin/banner with {"text": "...", "duration_secs": 3600}. Constraints the API enforces: at most 200 characters, no control characters, and duration_secs between 60 (1 minute) and 7776000 (90 days). Ending it early is DELETE /api/admin/banner; both writes land in the audit log (banner.set / banner.clear).

Vendor probes (Phase 22)

Miner is discovered via mDNS but no telemetry

Possible causes:

vendor=avalon and vendor=avalonq are separate adapters — one matches MTavg/MTmax/GHS av, the other THSspd/TMax/Cur_Load. If you add a Q with vendor=avalon, lots of None values come back.

Manual add command

curl -X POST -H "Authorization: Bearer wpat_..." \
  -H "Content-Type: application/json" \
  -d '{"host":"192.168.1.42:4028","vendor":"avalonq","label":"avalonq-1"}' \
  http://pool.local:18334/api/admin/miners

Port 4028 is the CGMiner default. Some vendors reconfigure it — in that case, pass the correct port number.

Last resort

Daemon panicked and won’t come up

Look at the logs. Common cases:

• DB migration failed: sqlx::migrate throws on an inconsistent schema
• Config file broken: TOML parse error with line number
• Port taken: another pool / service on 3333

Rebuild storage DB from scratch

systemctl stop dvb-warppool
mv /var/lib/dvb-warppool/warppool.db /var/lib/dvb-warppool/warppool.db.broken
systemctl start dvb-warppool   # daemon creates a fresh DB and runs migrations

You will lose:

• VarDiff snapshots per worker (every miner starts at initial_diff)
• Aggregated hashrate history (raw shares > 1h are evicted anyway)
• Audit log

Blocks-found is NOT the source of truth in the DB — those live in the Bitcoin blockchain itself. The block list is lazily re-populated on the first request via getblock RPCs.

See also

• Setup health checks — preventive diagnostics during setup
• Auto-update — update path + rollback
• Configuration Reference

Packaging & Installation

dvb-WarpPool ships in multiple formats. The release pipeline (.github/workflows/release.yml, executed by the self-hosted Forgejo runner) builds the Linux + Docker artifacts in parallel on every v* tag and signs them with the project Cosign key (cosign.pub in the repo root).

macOS and Windows are not built by CI — there are no macOS/Windows runners on the forge. The macOS .dmg + tarballs are produced per release on a Mac with packaging/macos/build-macos-release.sh and attached manually (which also means SHA256SUMS gets regenerated over the full asset set and re-signed — see §8 of docs/ci-forgejo-porting.md in the repository; that note is not part of this handbook). The Windows .msi is paused.

Update paths: After the initial install via one of the formats below, you can apply updates in two ways:

1. Package manager (apt/dnf/docker pull/Umbrel app updater) — classic, idempotent, controlled
2. Built-in auto-update since Phase 8 — the admin UI shows an update banner; one click runs download + sha256 verify + optional cosign verify + atomic_swap + systemd hint. See Auto-Update for the workflow.

Overview

Linux .deb (Debian / Ubuntu / Mint)

# download from the release page on git.warppool.org:
wget https://git.warppool.org/dvb-projekt/dvb-WarpPool/releases/download/v1.24.0/dvb-warppool_1.24.0-1_amd64.deb
sudo apt install ./dvb-warppool_1.24.0-1_amd64.deb

# first-run wizard (Bitcoin Core RPC, pool profile, payout address):
sudo dvb-warppool-setup

# start the daemon:
sudo systemctl enable --now dvb-warppool

# UI: http://localhost:18334

What the postinst does:

• creates the system user warppool
• creates /var/lib/dvb-warppool/ (data, mode 0700, owner warppool) and /var/log/dvb-warppool/
• chgrp warppool /etc/dvb-warppool so the setup wizard can atomically write into it via sudo
• systemctl daemon-reload

Logs: journalctl -u dvb-warppool -f

Linux .rpm (Fedora / RHEL / openSUSE)

sudo dnf install ./dvb-warppool-1.24.0-1.x86_64.rpm
sudo dvb-warppool-setup
sudo systemctl enable --now dvb-warppool

post_install_script does the same as the .deb postinst (system user, directories, daemon-reload).

Linux AppImage (portable, no-root)

chmod +x dvb-WarpPool-1.24.0-x86_64.AppImage
./dvb-WarpPool-1.24.0-x86_64.AppImage

Also available as an aarch64 AppImage for ARM boards (Raspberry Pi 5, Pine64, Rock-Pi):

chmod +x dvb-WarpPool-1.24.0-aarch64.AppImage
./dvb-WarpPool-1.24.0-aarch64.AppImage

The first launch opens the setup wizard if no ~/.config/dvb-warppool/config.toml exists. After that the daemon starts directly and the UI is reachable at http://localhost:18334.

Raspberry Pi 5 (Raspberry Pi OS / Ubuntu 24.04 for arm64)

dvb-WarpPool runs very well on the Pi 5 — the Cortex-A76 cores have significantly better single-thread performance than the Pi 4 (relevant for Stratum connection handling and Bitcoin RPC). 8 GB RAM is enough for the gross (Large) profile with a few hundred workers; with 16 GB, enterprise is realistic.

Fastest path: .deb package

# Raspberry Pi OS / Ubuntu / Debian for arm64:
wget https://git.warppool.org/dvb-projekt/dvb-WarpPool/releases/download/v1.24.0/dvb-warppool_1.24.0-1_arm64.deb
sudo apt install ./dvb-warppool_1.24.0-1_arm64.deb
sudo dvb-warppool-setup
sudo systemctl enable --now dvb-warppool

Alternative: Docker (with Bitcoin Core sidecar)

docker run -d --name warppool \
  --restart unless-stopped \
  -p 3333:3333 -p 18334:18334 \
  -v /etc/dvb-warppool:/config:ro \
  -v warppool-data:/data \
  git.warppool.org/dvb-projekt/dvb-warppool:1.24.0

Multi-arch image — Docker automatically pulls the arm64 variant on the Pi.

Storage recommendation

• NVMe HAT (e.g. Pimoroni NVMe Base, Geekworm X1003) strongly recommended. The pool DB (SQLite WAL + shares_raw eviction every 60s) puts heavy pressure on SD cards — a typical SD only lasts months under pool load, an NVMe lasts years.
• If using SD: high-quality industrial-grade SD (e.g. Sandisk Industrial, Western Digital Endurance) — no cheap consumer SDs.
• A USB-3 SSD is the middle-ground option if no NVMe HAT is available.

Bitcoin Core on the same Pi

8 GB RAM is enough for both (pool + Bitcoin Core with prune=10000), as long as the mempool isn’t extremely full. 16 GB is more comfortable. Bitcoin Core on its own needs 5–7 GB under normal load.

With a separate Bitcoin Core host (e.g. an Umbrel / Start9 on the LAN), 4 GB RAM is also enough on the Pi 5 for the pool alone.

hwdetect detects the Pi automatically

The setup wizard reads /proc/device-tree/model and identifies the Pi model. On the Pi 5, Environment::RaspberryPi is set, and the profile recommendation system offers gross (Large) as the highest recommended tier for that hardware — a recommendation, not an enforced cap — plus the NVMe storage hint as Severity::Info.

Pi 4 works too

The Pi 4 is tested, but the Pi 5 is recommended (higher per-core performance). Pi 3 and Pi Zero only make sense for klein (Small) profiles and are not intended for production use.

macOS .dmg

⚠ Unsigned — Gatekeeper warning on first launch. Notarization with an Apple Developer ID is planned for Phase B.

1. Open the .dmg → drag dvb-WarpPool.app into the Applications folder
2. Right-click → “Open” → confirm “Open” (Gatekeeper override)
3. The first launch opens a Terminal with the setup wizard
4. Subsequent launches: double-clicking the app opens the UI in the browser automatically

State: ~/Library/Application Support/dvb-WarpPool/ (config + data + logs)

Windows .msi

⏸ Releases currently ship no .msi. There has been no Windows build runner since the move to the project’s own forge, so the release pipeline skips this job (.github/workflows/release.yml, job 6). The WiX packaging (packaging/windows/main.wxs) is still maintained and the artifact returns as soon as a Windows runner exists. Until then, build it yourself with cargo wix on a Windows machine, or run the pool via Docker or the Linux packages. The steps below apply to an .msi you built yourself.

⚠ Unsigned — SmartScreen warning on first launch. Code-signing with an EV certificate is planned for Phase B.

1. Double-click the .msi → “More info” → “Run anyway”
2. Installs to C:\Program Files\dvb-WarpPool\
3. Start the setup wizard manually: Start menu → dvb-warppool-setup
4. Daemon via Task Scheduler or Command Prompt: dvb-warppool-daemon.exe --config C:\ProgramData\dvb-warppool\config.toml

Docker

docker run -d --name warppool \
  -p 3333:3333 -p 18334:18334 \
  -v /etc/dvb-warppool:/config:ro \
  -v warppool-data:/data \
  git.warppool.org/dvb-projekt/dvb-warppool:1.24.0 \
  --config /config/config.toml --data-dir /data

First run: the admin account needs /config writable — once

The first visit to /admin asks you to create an admin account, and the daemon writes those credentials to secrets.toml next to your config.toml. With /config mounted read-only (as above) that write fails and the UI reports that the secrets file is not writable.

The write is atomic (temp file + rename), so it needs the directory writable — bind-mounting only secrets.toml read-write is not enough. Two ways round it:

a) Open a window for the first run, then close it. Drop :ro (and make the directory writable by the container’s uid if you run with user:), create the account, then restore :ro and recreate the container. Only the one-time bootstrap needs this: everything the admin UI stores afterwards — donation addresses, tab toggles, suppressed warnings — lives in the database under --data-dir, so read-only config is fine from then on.

b) Pre-provision secrets.toml. If it already carries admin_username, admin_password_hash and jwt_secret, no bootstrap is needed and /config can stay read-only from the start.

If you run the container as a non-root user: — note that the daemon only reads secrets.toml, but it must be able to read it. Leave the file owned by that uid with mode 600; a root-owned 600 file locks the daemon out.

Multi-arch (amd64 + arm64) is selected automatically — no --platform needed.

Signature verification (Cosign)

Every release includes SHA256SUMS plus a Cosign signature bundle (SHA256SUMS.bundle), verified against the project cosign key (cosign.pub in the repo root). Cosign 3.x writes the bundle format rather than a bare .sig, so pass --bundle:

cosign verify-blob \
  --key cosign.pub \
  --bundle SHA256SUMS.bundle \
  SHA256SUMS
# must print: Verified OK

# then against the individual files:
sha256sum --check SHA256SUMS

GitHub-era releases (<= v1.15.0) were keyless-OIDC-signed and shipped a SHA256SUMS.sig — those artifacts are gone with the account, see the repo history for the steps they used.

Build provenance

Releases ≤ v1.15.0 (GitHub era) shipped SLSA-3 provenance via slsa-github-generator (*.intoto.jsonl in the release assets). That generator is GitHub-OIDC-bound and does not run on the self-hosted forge, so newer releases rely on the project Cosign signature (above) plus reproducible builds (rebuild byte-for-byte and compare SHA256SUMS, see reproducible builds) for supply-chain assurance instead.

SBOM (SPDX)

sbom.spdx.json in every release lists all crates with their versions and licenses (via anchore/sbom-action). Usable with syft / grype for vulnerability audits.

Phase B — open loose ends

• macOS Notarization: xcrun notarytool submit with a Developer ID certificate + Apple ID + app-specific password. Since the .dmg is currently built manually on a Mac (no macOS runner), notarization would be a local step there; if a macOS runner is ever added, APPLE_ID, APPLE_TEAM_ID and APPLE_NOTARY_PASSWORD would go into the Forgejo Actions secrets.
• Windows code-signing: signtool sign with an EV certificate. Azure Code Sign is an alternative for CI-friendly token-based signing.
• Logo / icon design: Currently only a 1×1 placeholder in the AppImage; macOS and Windows have no icon. Once the design is finalized (see ROADMAP.md), it needs to be placed under packaging/{appimage,macos,windows}/.

Reverse Proxy (nginx / Caddy)

The daemon serves its HTTP API + UI on status_listen (default :18334) as plain HTTP. For a public or friends pool you usually want it behind a reverse proxy that terminates TLS (HTTPS) on port 443, so miners and the dashboard reach it over an encrypted, named endpoint (https://pool.example.com).

You have two ways to get HTTPS — pick one:

1. Built-in TLS — set status_tls_listen (and provide a cert) and the daemon serves HTTPS directly. Simplest; no extra software. See Configuration Reference.
2. Reverse proxy (this page) — an established web front (nginx / Caddy) does TLS, HTTP/2, automatic certificate renewal, access logs and its own rate-limit, forwarding to the daemon over loopback. This is the recommended setup once the pool is internet-facing.

Stratum is not HTTP. Only the API/UI (:18334) goes through an HTTP reverse proxy. The Stratum endpoints — plain :3333, TLS :3334, and Stratum V2 on its own sv2_listen port (the reference deployment uses :3336, NOISE NX handshake) — are raw TCP protocols. Expose those ports directly (or through an L4/TCP load balancer such as nginx stream {} or HAProxy TCP mode), never through an HTTP server {} / reverse_proxy block.

Two settings that matter behind a proxy

When the daemon runs behind a proxy, set both of these in config.toml under [server]:

[server]
# The proxy now sees the real client; the daemon only sees the proxy's loopback
# address. Setting this true makes the daemon trust the proxy's X-Forwarded-For
# header for the real client IP — used by the audit log and the per-IP rate-limit
# and ban list. See the warning below.
trust_proxy_headers = true

# The login cookie is only sent over HTTPS. Set true whenever the UI is reached
# via https:// (i.e. always, behind a TLS-terminating proxy).
cookie_secure = true

⚠️ Only set trust_proxy_headers = true behind a proxy you control. If the daemon is reachable directly from the internet with this on, any client can forge X-Forwarded-For and spoof its IP into your audit log and past your IP bans. Bind status_listen to loopback (127.0.0.1:18334) so only the proxy can reach it. See Security.

Public wallet pages (/users/<address>)

A per-worker 0% pool exposes a login-free page per miner at /users/<address>, with ckpool-compatible JSON at /api/users/<address> for firmware and ckstats. Both are ordinary HTTP on the same status port as the dashboard, so the catch-all location / (nginx) / reverse_proxy (Caddy) below already forwards them — no per-route config needed (unlike /api/events, they are plain request/response, no buffering tweaks). Just confirm they answer through the proxy: curl https://pool.example.com/api/users/<some-address> should return the ckpool-style JSON, and https://pool.example.com/users/<address> should load the wallet page.

Server-Sent Events (/api/events)

The dashboard’s live updates (block-found, new-job, …) use a long-lived Server-Sent-Events stream at GET /api/events. A proxy that buffers responses or times the connection out will break live push. Both examples below disable response buffering and raise the read timeout for that path.

Caddy

Caddy gets you automatic HTTPS (Let’s Encrypt) with almost no config:

pool.example.com {
    reverse_proxy 127.0.0.1:18334 {
        # SSE: stream the response, don't buffer it.
        flush_interval -1
    }
}

That’s the whole file. Caddy fetches and renews the certificate, terminates TLS, forwards X-Forwarded-For / X-Forwarded-Proto automatically, and flush_interval -1 keeps /api/events flowing.

nginx

server {
    listen 443 ssl http2;
    server_name pool.example.com;

    ssl_certificate     /etc/letsencrypt/live/pool.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/pool.example.com/privkey.pem;

    # Dashboard, API, and the public wallet pages (/users/<address> +
    # ckpool-compatible /api/users/<address> JSON) — all plain HTTP, no
    # per-route tuning needed.
    location / {
        proxy_pass http://127.0.0.1:18334;
        proxy_http_version 1.1;
        proxy_set_header Host              $host;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # Server-Sent-Events stream: no buffering, long-lived connection.
    location /api/events {
        proxy_pass http://127.0.0.1:18334;
        proxy_http_version 1.1;
        proxy_set_header Host              $host;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header Connection        '';
        proxy_buffering off;
        proxy_cache off;
        proxy_read_timeout 1h;
    }
}

# Redirect plain HTTP → HTTPS
server {
    listen 80;
    server_name pool.example.com;
    return 301 https://$host$request_uri;
}

Use certbot (certbot --nginx -d pool.example.com) for the certificate.

Checklist

• status_listen = "127.0.0.1:18334" — daemon only reachable via the proxy.
• trust_proxy_headers = true and cookie_secure = true in [server].
• /api/events is proxied without buffering (Caddy flush_interval -1 / nginx proxy_buffering off).
• Public wallet pages reachable through the proxy: /users/<address> loads and /api/users/<address> returns JSON (per-worker pools only; served by the catch-all block, no special config).
• Stratum ports (:3333 plain, :3334 TLS, sv2_listen e.g. :3336) exposed directly, not via the HTTP proxy.
• After changing [server], restart the daemon.

Security

Operator-focused overview of what dvb-WarpPool protects, how it does so, and which responsibilities remain with the operator.

Threat Model

The pool sits between four actor classes with different levels of trust:

Threat → Mitigation Matrix

Auth Stack

dvb-WarpPool has three orthogonal auth paths:

1. JWT cookie — browser UI, normal login flow
2. API tokens — bearer token for scripts (wpat_<32hex> prefix)
3. 2FA-TOTP — optional additional factor for (1)

Login Flow

POST /api/auth/login {username, password, totp_code?}
  -> verify Argon2id hash against admin_password_hash
  -> 2FA active? check totp_code (RFC 6238, ±1 step skew)
  -> mint JWT mit sub=username, exp=now+24h
  -> set HttpOnly Cookie warppool_session=<jwt>
  -> audit: login.ok | login.fail

API Token Flow

POST /api/admin/tokens {name, ttl_secs?, scope?}  (auth required)
  -> generate token: format "wpat_" + 32 hex chars (128 bits entropy)
  -> store sha256(token) + name + scope + expires_at
  -> response: {id, name, scope, token, expires_at}
  -> CLIENT MUST STORE THE TOKEN IMMEDIATELY — only the hash is kept afterwards
  -> audit: token.create

Authorization: Bearer wpat_abc123...   (subsequent requests)
  -> sha256(token) lookup in api_tokens WHERE revoked_at IS NULL AND (expires_at IS NULL OR expires_at > now)
  -> match found → AuthIdentity{sub: "token:<name>", exp: ...}
  -> fire-and-forget touch_api_token (last_used_at = now)

2FA Setup

POST /api/auth/2fa/setup
  -> mint_2fa_setup(issuer="dvb-WarpPool", account=username)
  -> generate base32 secret + otpauth:// URL
  -> persist with enabled=0
  -> audit: 2fa.setup

(User scans QR or enters secret in Authenticator app)

POST /api/auth/2fa/enable {code}
  -> verify_totp(secret, code) → ok
  -> UPDATE admin_2fa SET enabled=1, enabled_at=now
  -> issue single-use recovery codes (hashed at rest, shown once)
  -> audit: 2fa.enable

2FA Recovery Codes

Enabling 2FA also issues a set of single-use recovery codes. They are shown exactly once at enable time and only their hashes are stored — the same one-shot rule as API tokens. Write them down before leaving that screen.

At login, the totp_code field also accepts a recovery code: a plausible- looking code is checked against the unused set, and on match it is consumed (one use, never again) and the login succeeds. This is the way back in when the authenticator device is lost — without it, a lost phone means losing admin access to the pool.

GET /api/auth/2fa/status reports recovery_remaining, so the UI can warn as the pile runs low. POST /api/auth/2fa/recovery/regenerate rotates the set (invalidating all outstanding codes); this is also the way to refresh codes while 2FA stays active, since enable refuses to run twice.

Recovery-code logins are audited separately as login.recovery, including how many codes remain — an unexpected entry there is a strong signal of account compromise.

Key Material

Audit Logging

All state-changing admin actions are persisted in audit_log:

Fields: at (timestamp), actor (user, or token:<name>, or ? for failed login), action, target (optional, action-specific), peer_ip (with X-Forwarded-For resolution when trust_proxy_headers=true), ok (boolean), details (optional, e.g. error description).

Retrieve via GET /api/admin/audit?limit=100&actor=admin or CLI:

dvb-warppool-cli audit --limit 50 --actor admin

The table has indexes on at, actor, action for fast filtering.

Eviction is automatic. The daemon’s retention loop calls evict_audit_older_than([retention].audit_log_secs) — default 90 days — at most once per hour, so the DELETE does not run on every 60 s tick. Set [retention].audit_log_secs to change the window. (Earlier releases had no daemon-side eviction and required a cron job; that is no longer the case.)

TLS

dvb-WarpPool has two separate TLS surfaces:

Stratum-V1 TLS (port :3334 typical)

Optional. If stratum.tls_cert_path + stratum.tls_key_path are set, a second listener runs alongside the plain port. Rustls 0.23, default suite (TLS 1.2 + 1.3, no TLS 1.0/1.1).

The operator provides cert+key themselves — typically via Let’s Encrypt (certbot with DNS challenge when the pool is not publicly reachable) or mkcert for LAN-only setups.

Stratum-V2 NOISE (sv2_listen, :3336 in the reference deployment)

NOISE-NX handshake (Stratum V2 2024 spec: secp256k1 + EllSwift + Schnorr) via the noise_sv2 crate, pure Rust. Static authority key in secrets.sv2_authority_priv_key_hex. The public key the V2 miner needs as its server-pubkey is available three ways:

• Pool UI: dashboard → “⛏ Miner verbinden” button → the connect modal shows the V2 endpoint and the server pubkey with a copy button.
• API: GET /api/overview → field sv2_authority_pubkey_b58 (Base58, unauthenticated; the public key is by design not a secret).
• CLI: dvb-warppool-cli sv2-pubkey reads secrets.toml, derives the pubkey and prints it on stdout — handy for headless / SSH setups where the UI is not reachable.

In contrast to classic TLS, NOISE has no PKI — the miner must learn the pool pubkey OOB (out of band). That is the Sv2 standard.

API TLS (HTTPS for /api + UI)

Optional via server.status_tls_listen. Operators frequently put a reverse proxy (Caddy with auto-LetsEncrypt) in front instead and let the daemon speak only HTTP on 127.0.0.1. In that case: set server.trust_proxy_headers = true so that the audit log sees real client IPs.

Reproducible Builds + Signing

Phase 8b: cargo [profile.release] with lto = "fat" (single-threaded LTO, deterministic) + RUSTFLAGS=--remap-path-prefix=... + cargo-home + cargo-git remap. CI builds twice in matrix jobs and compares sha256 — fails on drift.

Local end-user verification:

scripts/verify-reproducible.sh v1.24.0
# fetches the release tarball, extracts the daemon binary, rebuilds locally
# with the same flags + compares sha256

Phase 8g: POST /api/admin/update accepts cosign_verify: bool. If true, cosign verify-blob runs as an external subprocess before atomic_swap. The operator must set the WARPPOOL_COSIGN_BIN env var — otherwise hard-fail (500), not a silent skip.

Cosign verify uses the project cosign key (cosign.pub in the repo root): cosign verify-blob --key cosign.pub --bundle. (GitHub-era releases ≤ v1.15.0 were keyless via GitHub Actions OIDC + Fulcio; that path is GitHub-bound and gone since the move to the self-hosted forge.) For anyone who wants a second path: the GPG workflow has been available since Phase 6, but is not enabled by default.

Stratum Hardening

Rate Limiting (Phase 3)

Token bucket per peer IP. Defaults:

To a rate-limited auth the server responds with result: false (no disconnect) so that the miner does not enter a reconnect loop — that would only keep loading the limit bucket and fill the connection cap.

idle_evict_secs (default 300) clears limiter state buckets for IPs that have had no traffic for 5 min — so that server memory stays linearly bounded and does not grow with the unique-IP count.

Auto-ban + manual ban list ([ratelimit])

A public IP that repeatedly trips the connect limit (default: 10 strikes / 60 s) is fully banned — rejected before the TLS/handshake — for an escalating duration (base 5 min, doubling, capped at 1 h). Loopback and private LAN (10/8, 172.16/12, 192.168/16, link-local) are never auto-banned, so local miners that reconnect in bursts can’t lock themselves out. Tunable via [ratelimit].autoban_* (off via autoban_enabled = false). On top, an operator-curated [ratelimit].manual_bans list (admin API /api/admin/ratelimit/{bans,ban,unban} + UI panel) blocks specific IPs permanently — these apply to any IP including LAN, but loopback stays exempt (so the operator can’t lock out the local UI); a deliberate ban overrides only the auto-ban’s LAN exemption.

Reject-ratio auto-ban ([ratelimit].reject_ban_*)

Off by default. When enabled, a worker whose rejected-share ratio (rejected / (accepted + rejected)) is at or above reject_ban_ratio once at least reject_ban_min_samples shares have been observed is banned for the same escalating auto-ban duration as the connect auto-ban. Public-IP-only — loopback and private LAN are never banned this way, so a noisy local miner can’t lock itself out. Because a ban is an access-control decision, an active ban is enforced on the next connect even if the token-bucket rate-limit (enabled = false) is turned off, as long as the ban mechanism that produced it (autoban_enabled or reject_ban_enabled) is set.

IP-gate — CIDR deny-list + allow-only whitelist ([ratelimit])

Off by default. ban_cidrs is a deny-list of IPv4/IPv6 CIDR ranges (a bare IP is treated as /32 / /128) — any connect from a listed range is refused before TLS/handshake. Setting allow_only = true flips the listener into a whitelist: only IPs matching allow_cidrs may connect. Loopback always passes regardless of the gate, so the operator can never lock out the local UI / local miners. Malformed CIDR entries are skipped (logged once at load). Like the bans, the gate is an access-control decision and applies even when the rate-limit is disabled.

Per-IP connection cap ([stratum].max_connections_per_ip)

Default 0 (unlimited). When set, a single peer IP may hold at most that many concurrent Stratum connections; further connects from the same IP are dropped at accept time. This bounds single-host connection exhaustion independently of the profile-wide connection cap. Loopback is exempt.

Payout-address allowlist ([mining].address_allowlist)

Empty by default (open — any Bitcoin address may mine). When populated, only the listed payout addresses may mine: the address is everything before the first . in the worker name. Enforced identically on Stratum V1 (mining.authorize is rejected) and Stratum V2 (the channel-open returns an error for Standard and Extended channels). Useful for a private “pool for friends” deployment.

Public-exposure privacy switches ([privacy])

Two booleans control what an anonymous visitor may read. Both default to true, i.e. the historical open behaviour — a solo or friends pool keeps working unchanged after an upgrade. A public deployment should review them explicitly, because the defaults publish more than a public pool usually wants:

[privacy]
wallet_directory_public      = false
leaderboard_addresses_public = false

The authenticated operator always sees the unmasked data — these switches only affect the anonymous view. They complement the tab-visibility gating added in v1.19.1 (see the residual-risk table at the end of this page for what is still open on the unauthenticated read surface).

HTTP-API rate limit (api_rpm)

Separately from Stratum, the whole HTTP API is per-IP token-bucket limited (profile-driven api_rpm); over the limit returns HTTP 429 + Retry-After. Loopback and private LAN are exempt so the operator’s own UI is never throttled; the limit targets public remote clients only.

Connection Cap

Profile-dependent (klein: 16, mittel: 64, gross: 256, enterprise: 4096). Over-limit connects are dropped at accept time; semaphore-based, no per-connection allocation beforehand. The profile is hot-switchable, so this is a tuning knob rather than a fixed ceiling.

Conservative Mode (safe_mode)

When stratum.safe_mode = true (default): the share validator rejects unusual shares (unusual version bits, suspicious ntime drift). The operator can set this to false when testing experimental hardware.

Audit-Friendly Defaults

Backup & Restore

GET /api/admin/backup exports the SQLite DB as plain, unencrypted SQLite bytes. Restore via POST /api/admin/restore. There is no built-in encryption — the export contains 2FA secrets and API-token hashes (see below), so encrypt it yourself (age, gpg, an encrypted volume) before it leaves the host.

Audit: backup.export + backup.restore. On backup.restore a fresh migration runs after the import so that schema drifts between the backup version and the current version are resolved.

What is in the backup: all DB tables incl. admin_2fa.secret_base32, api_tokens.token_hash, audit_log. What is NOT included: secrets.toml, config.toml, ~/.bitcoin/.cookie. Anyone backing up both must protect them separately.

Sandbox + Privileges

Pool listen ports are all >1024 (3333/3334/…) — no CAP_NET_BIND_SERVICE required.

Disclosure

Please report security findings via coordinated disclosure: email first to dvbprojekt@gmx.de, an issue on git.warppool.org only after a fix. We are a small crew without a formal bug bounty — good-faith reports are acknowledged with credit.

SECURITY.md in the repo root holds the official policy

• PGP key on request.

What is intentionally NOT implemented

Accepted residual risks after the security audit (Phase 32)

Reproducible Builds

dvb-WarpPool produces bit-identical release binaries: anyone with the same source commit, the same Rust toolchain, and a Linux-x86_64 host can rebuild the release and compare it against sha256. This closes the gap between “we trust the build maintainer” and “we only trust the source code”.

Why

• Supply-chain resilience — if someone pushes a compromised binary, they either changed the source (visible diff) or patched the binary after the fact (sha256 mismatch).
• Cosign signatures say “the build came from the project” (GitHub-era releases ≤ v1.15.0 additionally carried SLSA workflow provenance). Reproducible builds additionally say “the build is the source”.
• Audit-friendly — pool operators can periodically verify that the pulled image matches the tagged source.

How we achieve it

Cargo profile (in Cargo.toml)

[profile.release]
lto = "fat"           # single-threaded LTO, no parallelism drift
codegen-units = 1     # a single LLVM pass
strip = "symbols"     # removes debug-info drift
panic = "abort"
incremental = false   # explicit

lto = "thin" was deliberately switched to “fat” — thin-LTO is faster (parallel) but can produce byte drift between host configurations.

Toolchain pin

rust-toolchain.toml pins the rustc + cargo version. CI and local verification use exactly this version.

Path remapping

Build-time paths ($CARGO_HOME, $GITHUB_WORKSPACE, $HOME) would otherwise end up embedded as debug info in the binary. We remap them to generic strings:

RUSTFLAGS="\
  --remap-path-prefix=$WORKSPACE=/repo \
  --remap-path-prefix=$HOME/.cargo/registry=/cargo/registry \
  --remap-path-prefix=$HOME/.cargo/git=/cargo/git"

SOURCE_DATE_EPOCH

repro.yml and scripts/verify-reproducible.sh both derive SOURCE_DATE_EPOCH from the commit timestamp, so a verification build uses the same convention as the reference build. Archive formats (deb/rpm, tarballs) use it for mtime fields instead of now(). (The Rust binary itself currently does not embed timestamps, but wrappers and installers do.)

Cargo.lock

We commit Cargo.lock and the build uses --locked. This also pins every transitive dependency version.

Verifying — CI side

repro.yml runs on manual dispatch and as a fixed step of the release routine:

build-a ─┐
         ├─► verify-determinism (sha256 comparison)
build-b ─┘

Two matrix runs build the same dvb-warppool-daemon binary from the same commit. On drift the workflow fails and prints both sha256s.

The push-to-main auto-trigger is currently off: the double release build is too heavy for the 2-vCPU Forgejo runner. It returns if a bigger runner is added.

Verifying — end-user side

scripts/verify-reproducible.sh is a bash script that:

1. determines the latest release tag (or an explicitly passed tag)
2. sets SOURCE_DATE_EPOCH from the commit timestamp
3. locally runs cargo build --release -p dvb-warppool-daemon --locked with the path-remapping flags
4. downloads the published release asset
5. compares both sha256s and exits 0 (match) or 1 (drift)

Note (post-Forgejo migration): the script still resolves the tag and the asset URL against the old GitHub repository, which is no longer reachable. Until it is ported to the git.warppool.org release API, pass the tag explicitly and compare against a manually downloaded asset from the Forgejo releases page.

# Verify the latest release
./scripts/verify-reproducible.sh

# A specific version
./scripts/verify-reproducible.sh v0.1.0

# Keep build artifacts for debugging
./scripts/verify-reproducible.sh --keep-target

Limitations

• Linux-x86_64 only — macOS .dmg and Windows .msi are not byte-deterministic (code signing, installer metadata). Cosign signatures cover those. Since the move to Forgejo there are no macOS or Windows CI runners either: the macOS assets are built and signed manually per release, and the Windows .msi is paused (the WiX sources stay maintained).
• Glibc drift — if a pool operator builds on an old distro (Debian Buster) while the CI runner uses Ubuntu Latest, glibc drift can occur. Workaround: build in the same Docker image the CI uses, or use a static MUSL build (phase 8c).
• LLVM version drift — rust-toolchain.toml pins rustc, but the LLVM version shipped with it varies minor across rustup channels. We accept this as a known limitation.

When the build drifts

1. Local HEAD vs tag commit:

   git rev-parse HEAD
   git rev-parse refs/tags/<TAG>
   git checkout <TAG>  # if different
   

2. Match the Rust toolchain:

   rustup show active-toolchain
   # should match rust-toolchain.toml
   

3. Check RUSTFLAGS:

   echo "$RUSTFLAGS"
   # must contain the three --remap-path-prefix entries
   

4. Glibc version:

   ldd --version
   # CI uses Ubuntu LTS — a minor mismatch is OK, a major one breaks it
   

5. If everything matches but drift persists: please file an issue with both sha256s and the ldd --version output.

Auto-Update

Auto-update shipped across Phases 8c–8g: update-check + verified download as CLI subcommands (8c Foundation), then atomic swap + health check + rollback wired into the daemon itself (8d Wiring onward). All of it is in the current release; the sections below cover the CLI entry points and the daemon flow.

CLI update commands (Phase 8c)

Two CLI commands, manually triggered by the operator:

dvb-warppool-cli check-update

Fetches the latest release from the project forge (Forgejo) and compares it against the installed version (CARGO_PKG_VERSION from the CLI binary).

$ dvb-warppool-cli check-update
Installed:    1.4.0
Latest:       v1.4.1 (Release v1.4.1)
Update:       1.4.0 → 1.4.1  (available)

Release-Assets:
  · dvb-warppool-v1.4.1-x86_64-unknown-linux-gnu.tar.gz (15728640 bytes)
  · dvb-warppool-v1.4.1-aarch64-unknown-linux-gnu.tar.gz (14680064 bytes)
  · dvb-warppool_1.4.1-1_amd64.deb (9437184 bytes)
  · SHA256SUMS (1280 bytes)
  · SHA256SUMS.bundle (2048 bytes)

Optional --json for scripting. --repo owner/name for forks or tests.

dvb-warppool-cli download-update

Downloads a release asset with sha256 verification. The Linux/macOS assets are tarballs (dvb-warppool-<tag>-<triple>.tar.gz); the CLI verifies the tarball’s sha256 and then extracts the dvb-warppool-daemon binary to --to. It performs no atomic swap and no restart — that’s the operator’s job, so the workflow stays auditable.

# Host-matching asset, auto-detected via the Rust target-triple
# (x86_64-unknown-linux-gnu / aarch64-unknown-linux-gnu / *-apple-darwin)
$ dvb-warppool-cli download-update \
    --to /tmp/dvb-warppool-daemon \
    --sha256 abcd1234...  # tarball-sha aus SHA256SUMS

Download: dvb-warppool-v1.4.1-x86_64-unknown-linux-gnu.tar.gz (15728640 bytes)
✓ 15728640 bytes geladen, sha256=abcd1234...
✓ dvb-warppool-daemon (13007200 bytes) aus dem Tarball extrahiert → /tmp/dvb-warppool-daemon
→ Installieren (Operator-Schritt — kein Auto-Swap):
    sudo install -m 755 /tmp/dvb-warppool-daemon /usr/local/bin/dvb-warppool-daemon
    sudo systemctl restart dvb-warppool

The sha256 you pass is the tarball’s hash — the SHA256SUMS lines cover the published assets (the .tar.gz), not the binary inside. On mismatch the downloaded tarball is deleted — no “tainted download” left lying around. --asset <substring> overrides the host auto-detection. --tag vX.Y.Z downloads a specific release instead of latest — to pin a known-good version or downgrade off a bad one (pass the tag with its v prefix; it hits releases/tags/<tag> instead of releases/latest).

Recommended operator flow

#!/bin/bash
set -euo pipefail
TAG=$(dvb-warppool-cli check-update --json | jq -r .latest)
[ "$TAG" = "null" ] && exit 0  # no update

# fetch SHA256SUMS from the release and verify with cosign
curl -sSfLO https://git.warppool.org/dvb-projekt/dvb-WarpPool/releases/download/$TAG/SHA256SUMS
curl -sSfLO https://git.warppool.org/dvb-projekt/dvb-WarpPool/releases/download/$TAG/SHA256SUMS.bundle
curl -sSfLO https://git.warppool.org/dvb-projekt/dvb-WarpPool/raw/branch/main/cosign.pub
# Project-key signing since the forge migration: the signature ships as a
# self-contained cosign 3.x *bundle*, so verify with --bundle, not --signature.
# GitHub-era releases (<= v1.15.0) were keyless-signed with a detached
# SHA256SUMS.sig — those assets are gone with the account.
cosign verify-blob \
  --key cosign.pub \
  --bundle SHA256SUMS.bundle SHA256SUMS

# extract the expected sha256 for the host tarball
TRIPLE="x86_64-unknown-linux-gnu"   # or aarch64-unknown-linux-gnu / *-apple-darwin
ASSET="dvb-warppool-${TAG}-${TRIPLE}.tar.gz"
EXPECTED=$(awk -v a="$ASSET" '$2 == a {print $1}' SHA256SUMS)

# download + verify the tarball, then extract the daemon binary to --to
dvb-warppool-cli download-update --asset "$TRIPLE" \
  --to /tmp/dvb-warppool-daemon --sha256 "$EXPECTED"

# manual swap (the daemon's POST /api/admin/update automates this)
sudo install -m 755 /tmp/dvb-warppool-daemon /usr/local/bin/dvb-warppool-daemon
sudo systemctl restart dvb-warppool

Crate internals (warppool-autoupdate)

#![allow(unused)]
fn main() {
use warppool_autoupdate::UpdateChecker;

let checker = UpdateChecker::new("dvb-projekt/dvb-WarpPool");
let release = checker.fetch_latest().await?;
if let Some(newer) = checker.is_newer_than(&release, env!("CARGO_PKG_VERSION"))? {
    // update available
}
}

Modules:

• version — semver-subset parser (major.minor.patch + optional -pre), compared via Ord. Pre-release < stable (semver convention).
• release — forge release API (GitHub-compatible JSON schema) with minimal serde deserialization (no octocrab — that would be 30+ transitive deps for 3 fields).
• download — download_verified(client, url, dest, expected_sha) with streaming write + SHA-256 accumulator. Mismatch → file deleted.
• swap — atomic_swap(new, current, backup_to) with POSIX rename (atomic on the same filesystem). Sets chmod 0755 on the new binary, optionally backs up the old one to backup_to.

Phase 8d — API endpoints

Since Phase 8d the daemon exposes two admin-protected endpoints for GUI-driven auto-update (activated via env-var WARPPOOL_AUTOUPDATE_REPO=owner/name, otherwise 503).

GET /api/admin/update-check

Returns latest-release metadata + newer flag in a single request.

curl -H "Authorization: Bearer $TOKEN" \
     http://localhost:18334/api/admin/update-check
{
  "current": "1.4.0",
  "latest": "v1.4.1",
  "name": "Release v1.4.1",
  "prerelease": false,
  "newer": "1.4.1",
  "assets": [
    {"name": "dvb-warppool-v1.4.1-x86_64-unknown-linux-gnu.tar.gz", "size": 15728640, "url": "..."},
    {"name": "SHA256SUMS", "size": 1280, "url": "..."}
  ]
}

Audit: update.check with the resolved latest tag as target.

POST /api/admin/update

Downloads the chosen asset, verifies sha256, and — for the Linux/macOS .tar.gz assets — extracts the dvb-warppool-daemon binary before the atomic rename into target_path. asset is an optional substring match; omit it and the daemon picks the asset matching its own host target-triple. Native installers (.msi/.dmg/.deb/.rpm/.AppImage) are rejected here — use the platform installer. Does not send a restart — the operator does that via systemctl restart from the restart_hint field.

curl -X POST -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "asset": "x86_64-unknown-linux-gnu",
       "sha256": "abcd1234...",
       "target_path": "/usr/local/bin/dvb-warppool-daemon",
       "backup_path": "/var/lib/dvb-warppool/backup/daemon.v1.4.0"
     }' \
     http://localhost:18334/api/admin/update

{
  "tag": "v1.4.1",
  "asset": "dvb-warppool-v1.4.1-x86_64-unknown-linux-gnu.tar.gz",
  "bytes": 15728640,
  "sha256": "abcd1234...",
  "target_path": "/usr/local/bin/dvb-warppool-daemon",
  "backup_path": "/var/lib/dvb-warppool/backup/daemon.v1.4.0",
  "installed_from_archive": true,
  "restart_hint": "systemctl restart dvb-warppool"
}

Audit: update.applied (ok=true) or update.failed (ok=false with details). The operator can review the update history via /api/admin/audit.

Activation

In dvb-warppool.service (systemd):

[Service]
Environment="WARPPOOL_AUTOUPDATE_REPO=dvb-projekt/dvb-WarpPool"

Or directly:

WARPPOOL_AUTOUPDATE_REPO=dvb-projekt/dvb-WarpPool dvb-warppool-daemon

Phase 8e — Periodic auto-check + SSE event

When auto-update is enabled (WARPPOOL_AUTOUPDATE_REPO=…), the daemon spawns a background task that runs fetch_latest every N hours. On a newer release an update_available SSE event is pushed to the event bus — the UI subscribes to it and can show an “Update available” banner without the operator having to click update-check manually.

Activation

# Standard: 24h interval
WARPPOOL_AUTOUPDATE_REPO=dvb-projekt/dvb-WarpPool dvb-warppool-daemon

# Custom interval
WARPPOOL_AUTOUPDATE_REPO=dvb-projekt/dvb-WarpPool \
WARPPOOL_AUTOUPDATE_INTERVAL_HOURS=6 \
  dvb-warppool-daemon

# Periodic disabled, on-demand only via /api/admin/update-check
WARPPOOL_AUTOUPDATE_REPO=dvb-projekt/dvb-WarpPool \
WARPPOOL_AUTOUPDATE_INTERVAL_HOURS=0 \
  dvb-warppool-daemon

Initial delay is 60s after daemon start so that not every pool instance hits the forge at the same time.

SSE event schema

Subscribe via Browser EventSource at /api/events. The event looks like:

event: update_available
data: {"type":"update_available","at":"2026-05-26T12:00:00Z","current":"0.1.0","latest":"v0.2.0","name":"Release 0.2.0","prerelease":false}

JavaScript example for a UI banner:

const es = new EventSource("/api/events");
es.addEventListener("update_available", (ev) => {
  const data = JSON.parse(ev.data);
  showBanner(`Update available: ${data.current} → ${data.latest}`);
});

On errors (rate-limit, network-down)

The task logs warn! and retries on the next interval. With the default 24 h interval a pool makes fewer than 2 release-API requests a day, so no rate limit on the forge side is anywhere near being a concern.

Phase 8f — Systemd OnFailure rollback

So that a bad auto-update doesn’t leave the daemon in a permanently-down state, the shipped dvb-warppool.service has an OnFailure= hook that on repeated crashes (StartLimitBurst=4 times within StartLimitInterval=300s) restores the most recent backup and restarts.

Layout

/usr/lib/systemd/system/dvb-warppool.service           ← main service
/usr/lib/systemd/system/dvb-warppool-rollback.service  ← oneshot helper
/usr/lib/dvb-warppool/rollback.sh                      ← restore script

Flow

1. Daemon starts with the new binary.
2. Crash within 5s → systemd Restart=on-failure retries.
3. After 4 crashes in 5 minutes → systemd gives up and triggers OnFailure=dvb-warppool-rollback.service.
4. rollback.sh:
   • Finds /var/lib/dvb-warppool/backup/daemon.* (youngest mtime wins)
   • Atomically installs it to /usr/bin/dvb-warppool-daemon (with install -m 755)
   • Moves the backup to <backup>.applied-<timestamp> so it isn’t picked again as a rollback source (prevents restart loops)
   • systemctl restart --no-block dvb-warppool.service
5. Daemon now starts with the old binary — back online.
6. Operator sees in the journal: journalctl -u dvb-warppool-rollback.service

Configuration via env-vars

In /etc/default/dvb-warppool (or systemctl edit dvb-warppool-rollback):

WARPPOOL_BACKUP_DIR=/var/lib/dvb-warppool/backup
WARPPOOL_TARGET_BIN=/usr/bin/dvb-warppool-daemon
WARPPOOL_SERVICE=dvb-warppool.service

All have sensible defaults — only override if the deployment deviates from the standard.

Creating a backup

Rollback only works if a backup was saved before the update. So set backup_path in the POST /api/admin/update body:

{
  "asset": "x86_64-unknown-linux-gnu",
  "sha256": "...",
  "target_path": "/usr/bin/dvb-warppool-daemon",
  "backup_path": "/var/lib/dvb-warppool/backup/daemon.v1.4.0"
}

The atomic_swap function moves the current binary to backup_path before installing the new one — so on a crash rollback.sh has something to restore.

Testing the helper (local, without systemd)

tmp=$(mktemp -d)
bin=$(mktemp -d)
echo "OLD" > "$tmp/daemon.v0.1.0"
echo "CRASHY" > "$bin/dvb-warppool-daemon"
# mock systemctl so no real restart runs
printf '#!/bin/bash\necho mocked\n' > "$tmp/systemctl"
chmod +x "$tmp/systemctl"
PATH="$tmp:$PATH" \
  WARPPOOL_BACKUP_DIR="$tmp" \
  WARPPOOL_TARGET_BIN="$bin/dvb-warppool-daemon" \
  packaging/systemd/rollback.sh
cat "$bin/dvb-warppool-daemon"  # → OLD

Phase 8g — Cosign-verify integrated

POST /api/admin/update can optionally run a cosign verify-blob subprocess invocation before the sha256 check. GitHub-era releases (≤ v1.15.0) used sigstore’s keyless OIDC flow; since the move to the self-hosted forge, verification uses the project cosign key (cosign.pub in the repo root).

Why subprocess instead of pure-rust sigstore

The pure-rust sigstore crate would pull in 30+ transitive deps (ASN.1, X.509, certificate-chain parser, rekor client). A cosign CLI subprocess is:

• Transparent — the operator sees the exact command in the audit log
• Current — cosign updates come from sigstore, not from us
• Minimal — no extra Rust deps

Trade-off: the operator must have cosign installed.

Activation

Two prerequisites:

1. Server-side env-var WARPPOOL_COSIGN_BIN=/usr/local/bin/cosign set (typically in the systemd unit’s Environment="...").
2. Request body cosign_verify: true + cosign_args: [...].

If cosign_verify=true but the env-var is not set → 500 “WARPPOOL_COSIGN_BIN env-var not set”. Deliberately hard-fail so the operator doesn’t get a false sense of security.

Example request

curl -X POST -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "asset": "x86_64-unknown-linux-gnu",
       "sha256": "abcd1234...",
       "target_path": "/usr/bin/dvb-warppool-daemon",
       "backup_path": "/var/lib/dvb-warppool/backup/daemon.v1.4.0",
       "cosign_verify": true,
       "cosign_args": [
         "--bundle=/etc/dvb-warppool/SHA256SUMS.bundle",
         "--key=/etc/dvb-warppool/cosign.pub"
       ]
     }' \
     http://localhost:18334/api/admin/update

Internally (after the asset download) the server fetches the release’s signed SHA256SUMS asset and runs cosign verify-blob on that file — the release signs only SHA256SUMS, not each individual asset, so SHA256SUMS is the blob the signature covers. cosign verify-blob checks the signature against its last (blob) argument, so that argument must be SHA256SUMS, never the asset. Once the signature checks out the server binds the asset to it: the downloaded asset’s sha256 (the sha256 you passed) must appear as that asset’s line in the now signature-verified SHA256SUMS, otherwise the update is refused (403):

# the blob (last arg) is the SHA256SUMS file the release signed —
# NOT the asset; per-asset integrity comes from its line inside it.
$WARPPOOL_COSIGN_BIN verify-blob \
    --bundle=<path to SHA256SUMS.bundle> \
    --key=<path to cosign.pub> \
    <downloaded SHA256SUMS>

Note that cosign_args are passed through verbatim, so the bundle (or, for an archived GitHub-era release, a detached --signature) has to be reachable from the daemon — a local path or a URL cosign can fetch.

If cosign exits ≠ 0 → the downloaded asset (and the SHA256SUMS temp) are deleted, response 403, audit update.failed with cosign verify-blob failed: exit N. The same 403 fires if the asset’s sha256 is not listed in — or mismatches — the verified SHA256SUMS.

Security model

Defense in depth: sha256 alone doesn’t protect against a “malicious operator with the correct hash”; cosign alone doesn’t protect against bit-drift during download. Both together are the right production configuration.

Phase 8 — completed

Platform availability

Since the move to the self-hosted forge, CI runs on the project’s own runners — and there is currently neither a macOS nor a Windows runner. That changes what a release contains:

Consequences for auto-update:

• macOS assets can lag the release. They are attached shortly after publish, not at publish time, so a macOS host that checks for an update within that window sees the new tag but not yet its asset. The binaries job deliberately does not depend on the macOS build, so a Mac being offline never blocks a release. Because the manual step re-signs the checksums, SHA256SUMS and SHA256SUMS.bundle are replaced when the macOS assets land — re-fetch both if you grabbed them before.
• Windows has no asset at all right now. The CLI’s x86_64.msi host mapping and the WiX packaging sources (packaging/windows/, cargo-wix) are kept maintained, and the .msi returns as soon as a Windows runner is registered. Until then, Windows users build from source.
• macOS GUI installs go through the .dmg 1-click flow (POST /api/admin/update/install-macos-dmg) once that asset is present.

Other limitations today

• No diff updates (full binary only). At 15 MB / release that’s harmless.
• Cosign-verify is operator-side (see flow above), not built into the CLI — deliberately, so the operator sees the trust anchor.

See also

• Notifications — update_available SSE event + UpdateBanner
• Observability — warppool_build_info label gauge shows the active version
• Troubleshooting — sha256 mismatch, cosign failure, rollback cycle

Add-ons & Sidecars

dvb-WarpPool is designed to be extended from the outside — a clean, stable contract that lets you (or a commercial vendor) build extra functionality without forking the core.

The sidecar model (and the AGPL boundary)

dvb-WarpPool is licensed under AGPL-3.0-or-later (see LICENSE). The single most important rule for an add-on:

An add-on must be a separate process (a “sidecar”) that talks to the pool over its HTTP API / SSE — never an in-process Rust crate linked into the daemon.

Why this matters:

• A crate compiled into the AGPL daemon becomes a derived work → it is covered by the AGPL and its source must be offered to users.
• A separate process that only consumes the pool’s public API/SSE is an independent work. You can license it however you like — including keeping a proprietary commercial add-on closed-source. (For commercial use of the core itself, see COMMERCIAL-LICENSE.md.)

This is not a theoretical pattern — two sidecars already ship with the project:

• the Stratum V1↔V2 translator (dvb-warppool-translator), and
• the Solar bridge (a small Python service the pool polls over HTTP; see Configuration Reference → [solar], kind = "generic_http").

Dock points (the extension contract)

A sidecar has four ways to integrate:

1. Read API — GET /api/overview, /api/workers, /api/blocks, /api/hashrate, /api/best-shares, /api/version. These are public (no auth), return JSON, and are the stable surface (see below). Caveat: the [privacy] block can redact parts of the payload for unauthenticated callers — wallet_directory_public = false masks payout addresses in /api/workers, leaderboard_addresses_public = false masks them in the /api/hashrate leaderboard. The routes stay reachable; an operator token (see below) always sees the unmasked data. If your sidecar needs full addresses, give it a read token rather than relying on the defaults.
2. Live events (pull) — GET /api/events is a Server-Sent-Events stream. Event types: block_found, new_job, shares_accepted, health_snapshot, profile_switched, update_available (plus heartbeat). Subscribe instead of polling when you need to react in real time (e.g. a billing or notification add-on reacting to block_found). The stream also emits transport-level events your client should tolerate: hello on connect and lagged (with a count) when a slow consumer dropped out of the broadcast buffer — on lagged, refetch a snapshot instead of assuming continuity.
3. Live events (push) — outbound webhooks. Configure one or more [[webhooks]] and the pool POSTs a JSON payload to your URL when a matching event fires. This is the inverse of the SSE stream: instead of holding a connection open, your sidecar exposes an HTTP endpoint and the pool calls it. See the comparison below and Configuration Reference → [[webhooks]].
4. Inbound data — the generic_http provider pattern: your sidecar exposes a small JSON endpoint and the pool polls it. This is how the Solar bridge feeds live PV data into /api/energy. A clean way to push into the pool without touching its code.
5. Authenticated actions — for anything beyond public reads, use an API token (Admin → API tokens). Prefer a read-only token for least privilege (next section).

Webhook (push) vs SSE (pull) — which to use

Both carry the same event types; pick by how your sidecar wants to receive them:

Rule of thumb: a cloud function or no-code automation that can’t keep a connection open → webhook. A persistent local process that wants every share update → SSE. The webhook payload is { "event", "ts", "data" }, signed with X-WarpPool-Signature when a secret is configured (verify it like a GitHub webhook). Loopback/LAN webhook targets are allowed (there is no SSRF block — the URL is operator-trusted config), so a local sidecar can receive POSTs at http://127.0.0.1:….

Authentication & least privilege

API tokens carry a scope:

• admin (default) — full access, including mutating POST/PUT/DELETE.
• read — GET/HEAD/OPTIONS only. Any mutating request is rejected with 403 Forbidden. A handful of especially sensitive operator endpoints (e.g. the Bitcoin-Core admin routes) reject read tokens outright, even on GET — those need an admin token or an interactive admin session.

Give an add-on a read token, not an admin one: even if the add-on (or its host) is compromised, it cannot reconfigure the pool. Create one with:

curl -X POST https://your-pool/api/admin/tokens \
  -H "Authorization: Bearer <admin-token-or-session>" \
  -H "content-type: application/json" \
  -d '{"name": "my-sidecar", "scope": "read"}'

The raw token is returned once — store it in the sidecar’s secret store.

API stability

• Stable surface: the public read endpoints listed above, the /api/events SSE stream, and /api/version. Build add-ons against these.
• Versioning: the project follows SemVer. Breaking changes to the stable surface happen only on a MAJOR version bump. New fields may be added within a minor release — parse defensively (ignore unknown fields). Recent example: v1.21.0 added a banner object (announcement marquee, set through POST /api/admin/banner) to /api/overview; a strict-schema client that rejects unknown fields would have broken on it, a defensive one did not.
• Check the running version at GET /api/version → { current, latest, update_available }. Pin or feature-detect against current if you depend on a recent field.
• Admin / mutating endpoints (/api/admin/*) are operator tooling and may evolve faster; if you depend on them, pin to a specific release.

A minimal read-only sidecar (sketch)

import requests, sseclient   # pip install requests sseclient-py

POOL = "http://127.0.0.1:18334"

# Option A — poll a snapshot every 10s
ov = requests.get(f"{POOL}/api/overview").json()
print(ov["pool"]["best_share_difficulty"], ov["active_miners"])

# Option B — react to live events
for ev in sseclient.SSEClient(f"{POOL}/api/events"):
    if ev.event == "block_found":
        ...  # do your thing — notify, bill, log

No token is needed for the public reads above; add an Authorization: Bearer <read-token> header only if you later consume an authenticated endpoint.

Architecture

dvb-WarpPool is a Rust workspace with 18 library crates + 6 binaries. A clear layering — from pure schema crates without async at the bottom up to the async-orchestrated binaries on top — keeps the system testable and lets sub-crates run standalone (e.g. the translator as a sidecar without the pool daemon).

Crate Overview

Schema + foundation (no async)

Core mining layer

Storage + API

Operational subsystems

Tools

Binaries

Data Flow (happy path)

                            +---------------------+
                            | Bitcoin Core        |
                            | (mainnet / regtest) |
                            +---------------------+
                              | RPC          | ZMQ pub
                              v              v
                            +---------------------+
                            | bitcoin-rpc         |
                            |  - getblocktemplate  |
                            |  - submitblock       |
                            |  - hashblock watch   |
                            +---------------------+
                                   |
                                   v
                            +---------------------+
                            | job-builder         |
                            |  - coinbase splits  |
                            |  - merkle tree      |
                            |  - StratumJob       |
                            +---------------------+
                                   |
                       +-----------+-----------+
                       v                       v
              +------------------+   +------------------+
              | stratum-v1       |   | stratum-v2       |
              |  TCP / TCP+TLS   |   |  TCP+NOISE       |
              +------------------+   +------------------+
                       |                       |
                       v                       v
               V1 miners (Bitaxe,       V2 miners / translator
               NerdNOS, AntminerS23)
                       |                       |
                       v                       v
                      submit (extranonce, nonce, ntime)
                                   |
                                   v
                            +---------------------+
                            | share-validator     |
                            |  - PoW check        |
                            |  - block detection  |
                            +---------------------+
                                   |
                       +-----------+-----------+
                       v                       v
              +------------------+   +------------------+
              | storage          |   | block-submit-loop|
              |  - record_share  |   |  - assemble block|
              |  - vardiff_state |   |  - submitblock   |
              +------------------+   +------------------+
                                              |
                                              v on success
                            +---------------------+
                            | notifier            |
                            |  fire BlockFound    |
                            +---------------------+
                              |    |    |    |    |
                              v    v    v    v    v
                            ntfy tg disc slack email

Daemon Task Topology

dvb-warppool-daemon is a Tokio multi-reactor with roughly a dozen long-lived tasks plus per-connection tasks. All tasks share one CancellationToken for graceful shutdown.

                  +------- main() async -------+
                  |                            |
                  +- spawn ---------+----------+
                          |         |
                  +-------+-------+ +------------------+
                  | Stratum-V1     | Stratum-V2        |
                  | accept loop    | accept loop       |
                  | (+ TLS)        | (+ NOISE)         |
                  +----------------+ +-----------------+
                          |               |
                  per connection: session task
                          |               |
                          v               v
                  +---------------------------------+
                  | block_found_tx broadcast        |
                  +---------------------------------+
                          |
                  +-------+--------+
                  | block_submit_  |
                  | loop           |
                  +----------------+
                          |
                  Bitcoin Core RPC submitblock
                          |
                  +-------+--------+
                  | notifier.notify(BlockFound)     |

                  +- spawn ---------+----------+
                  | job_refresh_loop                |
                  |  - poll getblocktemplate (60s)  |
                  |  - ZMQ hashblock fast path      |
                  |  - drain & build job            |
                  |  - push to stratum handles      |
                  +---------------------------------+

                  +- spawn ---------+----------+
                  | aggregate_loop (60s tick)       |
                  |  - storage.aggregate_5min       |
                  |  - SharesAccepted SSE event     |
                  +---------------------------------+

                  +- spawn ---------+----------+
                  | health_check_loop (60s tick)    |
                  |  - check_bitcoin_health         |
                  |  - SSE HealthSnapshot           |
                  |  - RpcDown/Recovered notify     |
                  +---------------------------------+

                  +- spawn ---------+----------+
                  | periodic_update_check (24h)     |
                  |  - Forge Releases API           |
                  |  - SSE UpdateAvailable          |
                  +---------------------------------+

                  +- spawn ---------+----------+
                  | miner_poll_loop (vendor probes) |
                  +---------------------------------+

                  +- spawn ---------+----------+
                  | HTTP API (axum on :18334)       |
                  |  - REST endpoints               |
                  |  - SSE /api/events              |
                  |  - static UI from --ui-dir      |
                  +---------------------------------+

(Later phases added further opt-in loops on the same pattern: UPnP lease renewal, the Anker-bridge supervisor, and the daily energy aggregation.)

Shared State

Tokio tasks share Arc<...> handles instead of global statics:

Storage Schema

Core tables from phases 1-15; the schema is created programmatically from a bundled SCHEMA_SQL constant (CREATE TABLE IF NOT EXISTS …, run by init_schema() in crates/storage/src/lib.rs) — there are no sqlx file migrations. Later phases added the device tables (miners, miner-telemetry raw/5min), the per-day energy history (daily_aggregates) and goPool-import bookkeeping on the same pattern.

Timestamp convention. DATETIME columns are written by SQLite itself (CURRENT_TIMESTAMP → YYYY-MM-DD HH:MM:SS, space separator, UTC); pool_settings string values are written by Rust as RFC3339 (T separator). The two are not lexically comparable ('T' > ' '), so cutoffs against DATETIME columns must be computed inside SQL (datetime('now', '-N seconds')), never bound as Rust-formatted strings — a v1.0.16 bug filtered out every active worker exactly this way. The full rules live in the warppool-storage module docs.

The Sv2 Stack in Detail

Stratum V2 is a binary-framed protocol with a NOISE handshake in front. Two subprotocols matter in the pool context:

1. Mining subprotocol (implemented) — channel-based, extranonce-aware, version rolling per BIP-320, per-channel set-target.
2. Template Distribution Protocol (TDP; foundation in phase 7.6a, wiring in 7.6b deferred) — replaces getblocktemplate with push-driven template updates straight from the Bitcoin node.

Standard vs. extended channels. Both are supported; pick by role. Standard is header-only mining for end devices: the pool computes the merkle root and ships ready-to-hash work — smaller frames, no merkle work on the device. Extended hands the miner coinbase_prefix/suffix plus the merkle path and full extranonce rolling, which is what proxies, translators and farm aggregators need to manage their own search space (our own translator opens an extended channel upstream for exactly that reason). A single Bitaxe-class device gains nothing from extended — nonce + version rolling is ample search space for its hash rate — and pays with bigger jobs and per-job merkle work on the ESP32. Recommendation: standard channel for solo devices, extended for proxy/aggregation setups. VarDiff converges per connection either way; a difficulty difference between the two modes is just convergence state, not quality.

V1 miner ----TCP plain---->  stratum-v1 server  ----------+
                                                          |
V1 miner ----TCP+TLS------>  stratum-v1 TLS server -------+
                                                          |
                                                          v
                                              +------------------+
                                              |  job-builder     |
                                              |  share-validator |
                                              +------------------+
                                                          ^
                                                          |
V2 miner ----TCP+NOISE----> stratum-v2 server (sv2_listen,  +
                                       reference deployment :3336)
                                                          |
V1 miner ----TCP--+                                       |
                  |                                        |
                  v                                        |
     dvb-warppool-translator (sidecar) --TCP+NOISE--------+
       - SetupConnection
       - OpenExtendedMiningChannel with user_identity
       - SubmitSharesExtended with miner extranonce
       - receives NewExtendedMiningJob + SetNewPrevHash
       - maps to V1 mining.notify + slushpool prev_hash + BIP-320 version rolling

The concrete wire format lives in crates/stratum-v2/src/messages.rs with roundtrip tests. The NOISE handshake uses the SRI noise_sv2 stack (secp256k1 + EllSwift + Schnorr-signed certificates, spec-conformant since the Sv2 modernisation) — pure Rust, no OpenSSL.

Connection Lifecycle Hooks

Both Stratum servers expose an optional ConnectionSink trait. For authenticated workers (V1: mining.authorize, V2: OpenChannel with user_identity) on_authorized fires; on connection end on_disconnect.

The daemon implements a NotifierConnectionSink struct that implements both traits. A per-worker debounce (default 30s) keeps flapping miners from firing a notification on every reconnect. The same hooks feed the live worker sets (TLS/Sv2 badges) and the peer-IP refcount map used by the energy accounting (“Disconnected” devices are excluded from watts/kWh).

   v1.Session::run
         |
   handle_authorize → connection_sink.on_authorized
         |
   ... shares ...
         |
   loop exit → connection_sink.on_disconnect

   v2.handle_connection
         |
   process_frame → channels().iter() → new user_identity?
         |                                    → on_authorized
   ... shares ...
         |
   loop exit → for each notified_user → on_disconnect

Event Bus + SSE

PoolEventBus is a tokio broadcast channel with PoolEvent variants:

The API’s /api/events opens one SSE stream per client with the current subscription set. The UI uses it for HealthBanner + UpdateBanner + toast events.

Configuration Layers

/etc/dvb-warppool/
├── config.toml         # non-sensitive settings
├── secrets.toml        # chmod 600 — admin hash, jwt secret, rpc pass, sv2 key
└── pool.db             # SQLite (path configurable)

Env vars for opt-in subsystems (see the Configuration Reference): WARPPOOL_HEALTH_CHECK_INTERVAL_SECONDS, WARPPOOL_AUTOUPDATE_REPO, WARPPOOL_DISCONNECT_DEBOUNCE_SECS, sink-specific tokens, etc.

Lifecycle (daemon boot)

1. Parse CLI (clap) + ENV
2. Load config.toml + (optional) secrets.toml
3. Validate config (mining.payout_address required, ratelimit constraints, …)
4. Init tracing subscriber (JSON when logging.json)
5. Open SQLite + run migrations
6. Resolve admin profile (persisted value in pool_settings beats the config default)
7. Construct BitcoinRpc with with_metrics(pool_metrics)
8. Probe RPC (warning on failure; the daemon still starts)
9. Construct Notifier from config
10. Construct PoolMetrics (Arc-shared)
11. Build the initial job (or skip when RPC failed)
12. Spawn the Stratum V1 listener (+ TLS listener when cert/key configured)
13. Spawn the Stratum V2 listener when sv2_listen is configured (the authority key is auto-generated into secrets.toml if missing)
14. Spawn job_refresh_loop (poll + optional ZMQ)
15. Spawn block_submit_loop
16. Spawn aggregate_loop (60s)
17. Spawn health_check_loop when WARPPOOL_HEALTH_CHECK_INTERVAL_SECONDS > 0
18. Spawn periodic_update_check when WARPPOOL_AUTOUPDATE_REPO + interval > 0
19. Spawn the HTTP API (axum on status_listen)
20. Install signal handlers (SIGTERM → cancel.cancel() → all tasks shut down)
21. The tokio::main event loop runs until cancel

Crate Dependencies (DAG)

Simplified crate graph (not every edge; no cyclic deps):

profiles --+
hwdetect --+--> config
              |
              +--> storage
              +--> bitcoin-rpc --+
              +--> bitcoin-ipc   |
              +--> job-builder   |
              +--> share-validator
              +--> stratum-v1 -----+
              +--> stratum-v2 -----+
              +--> translator -----+
              +--> telemetry -----+
              +--> notifier ------+
              +--> autoupdate ----+
              +--> health --------+
              +--> uninstall -----+
              +--> api -----------+
              +--> simulator -----+
                                 |
                                 v
                  dvb-warppool-daemon
                  dvb-warppool-cli
                  dvb-warppool-setup
                  dvb-warppool-translator
                  dvb-warppool-sim
                  dvb-warppool-mac-launcher

Crates and their one-directional deps:

• telemetry ← none (foundation for metrics)
• bitcoin-rpc → telemetry (for the RPC latency histogram, phase 16.3)
• api → notifier + autoupdate + telemetry + storage + …
• daemon → all library crates plus runtime deps (tokio, sqlx, …)

Testing Strategy

Three layers, plus one extra operator-driven layer:

As of v1.24.0: 1201 tests + 4 ignored, all green. UI side: pnpm svelte-check → 374 files, 0 errors.

See TESTING.md for details + the simulator workflow.

dvb-WarpPool — UI Design Concept

Research snapshot: May 2026. Direct site fetches were not available — all findings come from web-search synthesis + review sources. The concepts are not copies but an inspiration synthesis.

1. Findings

atlaspool.io

• Address-first flow: wallet address as a search input at the top, no login. Visibility toggle for screenshots — smart.
• Stats stack: real-time hashrate, mining streak, pool contribution, active workers, best share, first-seen, est. block time, achievements (gamification, announced for 2026).
• Network context: block height, network hashrate, difficulty, BTC price as a glance row — good, because mining without network context is meaningless.
• Hashrate graph with multiple timeframes: 1D/1W/1M/All — standard, but clean.
• Refresh every 2 min — no real-time push, polling instead. Room for improvement.

ocean.xyz

• Permissionless, address-keyed: no accounts. Stats stick to the payout address.
• “Shares in reward window”: the TIDES-specific metric is prominent — they make their payout logic visible.
• Quick-read metrics (daily earnings, lifetime, progress-to-payout, unpaid) as cards. Not glamorous, highly informative.
• Updated Feb 2026 — UI rather functional-conservative, no show-off.

DeepSea dashboard (community frontend for Ocean)

• Retro CRT terminal aesthetic: scanlines, phosphor glow — deliberately nostalgic.
• Three themes: DeepSea (blue), Bitcoin (orange), Matrix (green). Theme as identity.
• Chart.js with block annotations, worker cards with ASIC detection, pool donut, sound effects on new block.
• Atmosphere over information density — emotional engagement through audio + visuals.

Braiins / general 2026 trends

• Zoomable hashrate charts, regex filtering for workers, API-first.
• The 2026 split: techno-futurist (dark + neon + shaders + bento) vs. editorial (cream + serif + whitespace). Crypto almost always sits in the first camp.
• Sidebar + cards (the Linear/Vercel/Stripe pattern) scales without restructuring.
• Glassmorphism: used sparingly by now; brutalism is gaining as a counter-movement.

2. Three Design Concepts

Concept A — “Warp Drive” (cinematic cosmos)

• Style: glassmorphism + deep space. WebGL stars in the background (subtle, ≤40 particles), shader gradients à la Stripe/Vercel, glass cards with backdrop-filter.
• Palette: #05060B (void), #0F1226 (deep), #7B5CFF (warp violet), #00E0FF (plasma cyan), #F7931A (BTC orange as accent, used sparingly).
• Type: headers Space Grotesk (700, tight tracking). Body Inter (15px). Numerics JetBrains Mono (tabular-nums).
• Layout: 12-column bento grid, asymmetric. Hero = large live-hashrate block (4×3), small cards for workers/block history.
• Data viz: animated counters (Web Animations API), sparklines with gradient fill, hashrate chart with scroll-driven annotations for found blocks.
• Modern techniques:
  • View Transitions API for address lookup → dashboard
  • CSS @scroll-timeline for block-history reveal
  • color-mix() for theme-reactive glow states
  • Popover API for the worker detail drawer
• Mobile: bento collapses to a single-column stack via container queries. WebGL shaders fall back to a static gradient under prefers-reduced-motion.
• Pros: emotional, “future of mining”, clearly differentiates from the predecessor. Risk: WebGL performance on old phones; glass can ruin readability if the background gets too busy.

Concept B — “Stratum” (brutalist terminal)

• Style: monospace-first, hard lines, visible grid, ASCII accents. Inspiration: Linear logs + Bitaxe AxeOS + Recurse-Center vibe.
• Palette: #0A0A0A (true black), #1A1A1A (panel), #E8E8E8 (text), #39FF14 (signal green for “alive”), #FF4D00 (alert orange). Pure, four tones.
• Type: entirely Berkeley Mono or JetBrains Mono. Headers larger (28-40px), body 14px. No second family.
• Layout: sidebar (240px) + long-scroll main panel. Sections styled like terminal output with ───── separators. Command palette (⌘K) as the central navigation.
• Data viz: ASCII-style sparklines (▁▂▃▅▇▆▄▂), heatmaps as CSS grid with color-mix(), block history as a log stream with timestamps.
• Modern techniques:
  • text-wrap: balance for headlines
  • Container queries instead of breakpoints — every card adapts locally
  • Anchor positioning for tooltips on chart data points
  • @property for animatable CSS variables (hashrate pulse)
• Mobile: the sidebar becomes a top bar with a hamburger; long-scroll stays — brutalism scales honestly.
• Pros: technically credible (matches the Rust backend), extremely performant, ages well. Risk: too sober for a Bitcoin-maxi audience expecting “wow”; onboarding is harder for non-techies.

Concept C — “Aurora Bento” (editorial neo-bento)

• Style: bento grid with generous whitespace, soft cream against a deep-night-mode toggle, mesh-gradient accents. A mix of Apple bento + Stripe mesh + Notion editorial.
• Palette: dark default: #0B0D10, #15181D, #F2EFE8 (warm cream text), #FF7A1A (BTC orange as hero accent), #A8FF60 (signal lime). Light mode inverts cleanly.
• Type: headers General Sans (display, 700). Body Inter (16px, generous). Numerics Geist Mono.
• Layout: bento with 3 size classes (S/M/L), clear hierarchy. Hero card = hashrate, M = worker grid, S = BTC price / block height / difficulty.
• Data viz: soft animated counters (spring physics via WAAPI), area charts with mesh-gradient fill, worker cards with mini donuts for share contribution, block-found as a confetti burst (CSS motion-path).
• Modern techniques:
  • CSS motion-path for the block-found animation
  • View Transitions between light/dark
  • color-mix() + oklch() for perceptually uniform theme shifts
  • Container queries for bento card adaptation
• Mobile: bento reflows into a magazine scroll, large tap targets, prominent PWA install prompt.
• Pros: accessible for newcomers + deep enough for pros, photographs well (marketing!), light/dark equally strong. Risk: bento is slightly worn out in 2026 — differentiation has to come from craft + micro-interactions, otherwise it’s “yet another SaaS dashboard”.

3. Recommendation

Concept A “Warp Drive” — because the name WarpPool already sets the direction and the users explicitly want to move away from the classic predecessor look. Warp Drive uses the most modern web capabilities (View Transitions, scroll-timeline, color-mix, WebGL) without falling into bento arbitrariness (C) or terminal harshness (B). It delivers the “wow” for marketing screenshots while staying functionally usable — as long as glass effects are applied with discipline (cards only, never on charts). Fallback path: if performance tests fail, concept C is a clean retreat with a similar palette. Concept B can land later as a power-user theme option (“Terminal Mode”).

4. Implementation Status (as of v1.24.0)

Concept A is implemented in ui/ (SvelteKit 2 + Svelte 5 runes, adapter-static, SPA mode). What is actually live:

Routes

Components