Skip to content

dvb-projekt/dvb-WarpPool

BranchesTags

Repository files navigation

dvb-WarpPool

dvb-WarpPool

Rust Bitcoin Solo Mining Pool
Stratum V1 + V2 · PWA Operator UI · 657 Tests · Reproducible Builds

License Rust Tests Platforms Signed SLSA

dvb-WarpPool is a from-scratch Rust solo Bitcoin mining pool. The block reward flows directly to your wallet via the coinbase — the pool never holds, forwards, or aggregates your sats. No accounts, no custody, no settlement: when your miners find a block, the reward is yours the moment Bitcoin Core accepts it.

Built for self-hosted operators on hardware ranging from a Raspberry Pi 5 to a Ryzen 7 server. Single binary that runs alongside your own Bitcoin Node, exposes a modern PWA admin cockpit, and ships with end-to-end signed, reproducible builds.

Features

Mining core

  • Stratum V1 (plain + TLS 1.3) listener with persisted EMA-smoothed VarDiff — per-worker difficulty is restored across reconnects and restarts.
  • Stratum V2 server (NOISE_NX encrypted handshake) with both extended and standard channels. Real per-channel Merkle root, full PoW check, and a working block-submit path on both V1 and Sv2.
  • V1↔V2 translator sidecar — legacy V1 miners can talk to V2 pools and vice-versa, with BIP-320 version-rolling.
  • getblocktemplate + ZMQ hashblock for low-latency job refresh: fresh templates go out within milliseconds of Bitcoin Core seeing a new tip.
  • Coinbase construction with optional pool-fee and operator-donation splits. Default: 100 % to the miner address.
  • Network-aware: regtest, signet, testnet4, mainnet — getblocktemplate rules switch automatically (the signet rule is added on signet; a real source of "no template" bugs we ran into and fixed).

Operator UI (SvelteKit PWA)

  • Live Server-Sent Events stream for hashrate, blocks-found, share rate, miner status — no polling, no page reloads.
  • Hashrate charts with 24-hour smoothing, per-record best-share dots on a dedicated difficulty axis, top-3 worker medals, per-worker breakdown including coinbase-decoder for the current job.
  • i18n (8 languages: EN, DE, ES, FR, IT, JA, PT-BR, ZH) with locale auto-detect + manual switcher, persisted in localStorage.
  • Admin cockpit: profile hot-switch, notifier test-fires, audit-log viewer, API-token CRUD, 2FA setup with QR code, retention/eviction config.
  • Mobile-first responsive design — installable as a PWA, with service worker
    • Web-Push subscriptions.

Authentication & security

  • Argon2id password hashing + JWT session cookie (HttpOnly, optional Secure flag behind TLS).
  • API tokens with sha256-only storage (cleartext shown once on creation), per-token scopes, optional expiry.
  • 2FA TOTP (RFC 6238) with ±1 step skew and one-shot reuse prevention.
  • Audit log for every admin action (login, token-create / revoke, profile-switch, update-applied), filterable per actor.
  • HTTP login throttle with constant-time response (no user enumeration).
  • Stratum DoS hardening: line cap (16 KiB), pre-auth handshake timeout, dedup-set bound, Sv2 connection cap + read_buf cap.
  • Web Push receivers go through an SSRF guard (private / loopback / link-local / CGNAT / localhost are blocked) plus a DNS-rebinding resolve check.
  • SQLite DB + data directory locked down with restrictive POSIX permissions (0600 / 0700, unix-gated).
  • Setup wizard refuses to overwrite an existing secrets.toml.
  • Full security-audit pass on v1.0 (5 attack surfaces, double-verified) — see docs/SECURITY.md for the threat-mitigation matrix.

Notifications

Block-found, share-spike, anomaly and admin events fan out to any combination of sinks:

  • ntfy (push) · Telegram · Discord · Slack (incoming webhooks)
  • Email (SMTP with STARTTLS) · VAPID Web Push to the PWA
  • (APNs scaffold present in crates/notifier/ for an iOS sidecar)

Every sink is independently configurable, individually testable from the UI (notifier-test ntfy|telegram|…|all), and rate-limited per sink.

Hardware detection & admin profiles

  • Auto-detects CPU / RAM / NVMe / SATA at startup and recommends an admin profile: Small, Medium, Large, or Enterprise.
  • Each profile maps to a coherent set of runtime parameters: connection cap, share-validation Rayon pool size, retention windows, network-probe cadence.
  • Hot-switch at runtime via the admin cockpit — V1 and V2 connection caps resize live, no restart needed.
  • Vendor probes for AxeOS / NerdNOS / BitMain / Whatsminer / AvalonQ / BraiinsOS miners surface temps, fan, hashrate, last-share-age in the UI.
  • Vendor-aware VarDiff: the user_agent picks a per-class starting difficulty and target interval — from Antminer-class ASICs down to a NerdMiner V2 ESP32 (~250 KH/s), which uses sub-1 difficulty so it still submits a share roughly every 30 seconds instead of once an hour.
  • mDNS-based LAN discovery rounds out the picture: new miners on the subnet show up automatically.

Energy & health

  • Real-time electricity-tariff integration (incl. solar-surplus signal via Home Assistant) — the admin UI shows running cost and net margin.
  • Health-anomaly detection: peer-count, ZMQ-hashblock lag, share-acceptance rate, vendor-probe failures — each surfaces in /healthz and as warnings in the UI.
  • First-run setup wizard with Bitcoin Core health probes (RPC, ZMQ hashblock, ZMQ rawblock) and optional UPnP port forwarding.

Updates & auto-update

  • dvb-warppool-cli check-update + download-update for the manual workflow.
  • Daemon-side /api/admin/update-check + /api/admin/update with optional server-side Cosign verification of SHA256SUMS.
  • Periodic background check (configurable cadence, default 24 h) emits an update_available SSE event — the UI shows a banner without operator polling.
  • Atomic swap (<target>.new → POSIX rename → <target>), optional backup of the old binary, systemd OnFailure rollback hook.

Supply chain

  • Cosign keyless OIDC signatures on SHA256SUMS (verifiable against the workflow-URL identity — no key rotation drama).
  • SLSA Level 3 provenance via slsa-github-generator, attached to every GitHub release.
  • SBOM (SPDX) generated per release via anchore/sbom-action.
  • Reproducible builds — same input → byte-identical output, verifiable via scripts/verify-reproducible.sh.
  • Multi-arch Docker image on ghcr.io/dvb-projekt/dvb-warppool (linux/amd64 + linux/arm64).
  • Native installers across all major platforms (see Install).

Install

Platform How
Umbrel Add the DVB Projekt Community App Store → install dvb-WarpPool.
Docker docker pull ghcr.io/dvb-projekt/dvb-warppool:1.0.9 (multi-arch amd64 + arm64).
Debian / Ubuntu Download .deb from the releases page → sudo apt install ./dvb-warppool_*.deb.
Fedora / RHEL Download .rpm → sudo dnf install ./dvb-warppool-*.rpm.
Linux (other) .AppImage for x86_64 and aarch64.
macOS .dmg for Apple Silicon and Intel — see macOS install notes below.
Windows .msi for x64 (unsigned for now — SmartScreen warning is expected).
From source See Build from source below.

After install, the First-run setup wizard in the admin UI walks you through pointing the daemon at your Bitcoin Node and saving the BTC payout address.

Every release artifact ships with SHA256SUMS + a Cosign keyless OIDC signature and a SLSA 3 provenance attestation — see docs/PACKAGING.md for the verification recipes.

macOS install (unsigned .dmg)

The .dmg is not yet signed with an Apple Developer ID. Without that signature macOS Gatekeeper refuses to verify the bundle and shows the misleading dialog "dvb-WarpPool is damaged and can't be opened". The app itself is fine — Gatekeeper is reacting to the com.apple.quarantine extended attribute that Safari (and any browser) attaches to downloads.

One-line install (recommended):

  1. Download dvb-WarpPool-v1.0.9-aarch64.dmg (Apple Silicon) or …-x86_64.dmg (Intel) from the releases page.

  2. Run:

    curl -fsSL https://raw.githubusercontent.com/dvb-projekt/dvb-WarpPool/main/scripts/macos-install.sh \
    | bash

That downloads + runs scripts/macos-install.sh, which auto-picks the newest dvb-WarpPool-v*.dmg from ~/Downloads/, strips the quarantine attribute, copies the .app into /Applications/, re-registers it with LaunchServices, and unmounts the disk image. After it finishes, double-click the app in /Applications or run open /Applications/dvb-WarpPool.app.

Manual fallback, if you prefer to read what's happening:

# 1. Strip quarantine from the downloaded .dmg
xattr -dr com.apple.quarantine ~/Downloads/dvb-WarpPool-v*.dmg

# 2. Open the .dmg + drag dvb-WarpPool.app into /Applications via Finder

# 3. Strip quarantine from the installed .app too
xattr -dr com.apple.quarantine /Applications/dvb-WarpPool.app

# 4. Open
open /Applications/dvb-WarpPool.app

Apple Developer ID signing + notarization is on the roadmap (Phase B) — once that ships, the workaround disappears.

Sleep prevention. The Mac launcher automatically prevents system sleep while the daemon is running (via macOS caffeinate). Without it, the default 3h idle timeout would suspend Bitcoin Core overnight, RPC calls fail, and the hashrate graph drops to 0. Display sleep keeps working — you can let the screen go dark. Visible status: green info card on the admin profile page ("✓ macOS sleep mode disabled").

Tested on

Platform Architecture Recommended profile
Umbrel Home A8 (8 GB) aarch64 medium / large
Raspberry Pi 5 (8 GB) aarch64 large (with NVMe HAT)
Raspberry Pi 5 (16 GB) aarch64 enterprise (with NVMe HAT)
Raspberry Pi 4 (4 GB) aarch64 small / medium (Pi 5 recommended)
macOS (Apple Silicon + Intel) aarch64 / x86_64 medium / large
Linux server (Ryzen 7 / 32 GB) x86_64 enterprise
Docker multi-arch amd64 + arm64 depends on host

Full install guide + storage recommendations (NVMe HAT for Pi): see docs/PACKAGING.md.

Run a pool for your friends

The OSS stack is ready for a small TLS-secured pool where 5-10 trusted friends point their miners at your home setup over the internet. You need:

  • A free DuckDNS subdomain (1 min signup)
  • Router port-forward for :3334 (TCP, 3 min)
  • A real Let's Encrypt certificate — fetched automatically by the bundled setup script
./scripts/setup-tls-public.sh

The script installs acme.sh, issues the cert via DNS-01 challenge, drops it into the right place, and sets up 60-day auto-renewal. After a daemon restart, friends point their miners at <yoursubdomain>.duckdns.org:3334 with "TLS: Enabled (Bundled CA)" and they're in.

Full step-by-step guide: docs/solo-friends-setup.md (deutsche Version: docs/solo-friends-setup-de.md)

For larger deployments (community pool, public service) see docs/scaling.md — those tiers need extensions that are available as a commercial service via a GitHub issue.

Architecture

dvb-WarpPool/
├── crates/
│   ├── profiles/          # Small/Medium/Large/Enterprise resource tuning
│   ├── config/            # TOML schema (ported from dvb-gopool)
│   ├── hwdetect/          # Hardware detection + profile auto-recommendation
│   ├── stratum-v1/        # Stratum V1 + TLS listener + VarDiff + rate limit
│   ├── stratum-v2/        # Stratum V2 (NOISE_NX) server + client + sessions
│   ├── translator/        # V1 ↔ V2 translator proxy (extended channels)
│   ├── bitcoin-rpc/       # Bitcoin Core JSON-RPC + ZMQ
│   ├── job-builder/       # Block template → Stratum job
│   ├── share-validator/   # SHA256d share check (parallel)
│   ├── storage/           # SQLite + tiered retention + audit log
│   ├── api/               # Axum HTTP + SSE + auth (JWT, 2FA, API tokens)
│   ├── telemetry/         # Prometheus + miner vendor APIs
│   ├── notifier/          # ntfy/Telegram/Discord/APNs/SMTP
│   └── simulator/         # Sim miner, sim node, sim failures
├── apps/
│   ├── dvb-warppool-daemon/        # Main pool binary (V1+V2 hostable in parallel)
│   ├── dvb-warppool-cli/           # Admin CLI
│   ├── dvb-warppool-sim/           # Test-simulator CLI
│   ├── dvb-warppool-setup/         # First-run setup wizard
│   └── dvb-warppool-translator/    # V1↔V2 translation-proxy sidecar
├── ui/                    # SvelteKit PWA
└── docs/                  # ARCHITECTURE.md, SECURITY.md, TESTING.md

Build from source

cargo build --release
cargo test --workspace
cargo run --bin dvb-warppool-daemon -- --config config/example.toml
cargo run --bin dvb-warppool-sim   -- scenario solo-block-found

Build artifacts land in ~/.cache/dvb-WarpPool/target (outside iCloud, see .cargo/config.toml).

Documentation

The full documentation (Architecture / Getting Started / Packaging / Security / Sv2 phase history / Roadmap) is published via mdBook:

License

Licensed under either of the following licenses, at your option:

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

About

Rust Bitcoin Solo Mining Pool — Stratum V1+V2, PWA operator UI, signed multi-arch releases

Topics

rust bitcoin self-hosted stratum mining bitcoin-mining mining-pool solo-mining umbrel stratum-v2

Resources

Readme

License

Apache-2.0, MIT licenses found

Licenses found

Apache-2.0
LICENSE-APACHE
MIT
LICENSE-MIT

Security policy

Security policy
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 10

v1.0.9 Latest
Jun 8, 2026
+ 9 releases

Packages

 
 
 

Contributors

Languages