- Rust 94.7%
- Shell 2.3%
- HTML 1.9%
- Nix 0.8%
- Just 0.3%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
vnprc
3547740516
config/prod/mint.config.toml shipped pool_pubkey set to G, a structurally
valid compressed pubkey that namespaces every epoch under a well-known
constant instead of a real pool identity.
Both halves, for the two ways this goes wrong:
- naming::validate_pool_pubkey now rejects G by value, so a copied dev
value is caught even if it is otherwise well-formed.
- the prod config ships pool_pubkey commented out with a TODO(operator),
so an unedited prod file fails on the pre-existing "pool_pubkey is
required" error instead of ever reaching the generator-point check.
The dev config needed a replacement key that isn't G: pubkey of
sha256("hashpool dev pool identity"), pinned by a naming.rs test that
derives it independently and compares against the committed config.
Updated every test constant that used G as a pool pubkey to the new dev
key. receive_address is untouched — it is an address, not an identity,
and stays derived from G per its own existing test.
pool_pubkey (and every other [hashpool_mint] setting) is now validated
before setup_mint opens the database, wrapped with the config file path
it loaded, so a refused start never leaves a freshly created mint.sqlite
behind.
Refs vnprc/hashpool#35.
|
||
| .cargo | ||
| benches | ||
| common | ||
| config | ||
| docs | ||
| examples | ||
| protocols | ||
| roles | ||
| scripts | ||
| test/integration-tests | ||
| utils | ||
| .gitignore | ||
| bitcoin-node.nix | ||
| bitcoind.nix | ||
| CHANGELOG.md | ||
| codecov.yaml | ||
| CONTRIBUTING.md | ||
| devenv.lock | ||
| devenv.nix | ||
| devenv.yaml | ||
| flake.lock | ||
| flake.nix | ||
| justfile | ||
| LICENSE-APACHE | ||
| LICENSE-MIT | ||
| LICENSE.md | ||
| README.md | ||
| RELEASE.md | ||
| rustfmt.toml | ||
| SRI_README.md | ||
| sv2-tp.nix | ||
Hashpool
This project is a fork of the Stratum V2 Reference Implementation (SRI) that replaces traditional share accounting with an ecash mint. Instead of internally accounting for each miner's proof of work shares, hashpool issues an "ehash" token for each share accepted by the pool. For a limited time after issuance, ehash tokens accrue value in bitcoin as the pool finds blocks. Miners can choose to accept the 'luck risk' of finding blocks and hold these tokens to maturity or sell them early for a guaranteed payout.
You can find the original SRI README here.
Getting Started
To run Hashpool, first clone the repository and follow the instructions to install nix and devenv.
Once set up, cd into the hashpool directory and run:
devenv shell
devenv up
Development Environment Setup
The development environment initializes a containerized system with the following components:
Components Overview
-
pool- SV2 Mining Pool- coordinates mining tasks and distributes workloads to miners
- issues an ecash token for each share accepted
- manages an internal cashu mint
- receives a blinded message for each mining share
- signs it and returns a blinded signature to the proxy/wallet
-
proxy- SV2 Translator Proxy- talks stratum v1 to downstream miners and stratum v2 to the upstream pool
- manages the cashu wallet
- bundles a blinded message with each share sent upstream to the pool
- receives the blinded signature for each blinded message
- stores each unblinded message with it's unblinded signature (this is an ecash token)
-
jd-client- SV2 Job Declarator Client- talks to bitcoind miner side
- retrieves block templates
- negotiates work with upstream pool
-
jd-server- SV2 Job Declarator Server- talks to bitcoind pool side
- negotiates work with downstream proxy
-
bitcoin-node- Bitcoin Core 31.1 (multiprocess)- official Bitcoin Core node binary with IPC support
- serves block data to sv2-tp via unix socket
-
sv2-tp- SV2 Template Provider (v1.1.1)- connects to bitcoin-node via IPC socket
- serves Stratum V2 block templates to the pool and jd-client
-
miner- CPU Miner- find shares to submit upstream to the proxy
-
mint- CDK Cashu Mint- generate ehash and ecash tokens
- redeem ehash and ecash tokens
-
web-pool- Web Dashboard (Pool Side)- web interface for pool statistics and monitoring
- displays pool hashrate, services, and connected proxies
- deployed at pool.hashpool.dev
-
web-proxy- Web Dashboard (Proxy Side)- web interface for proxy statistics and monitoring
- wallet page displays ehash balance and an ehash faucet
- miners page displays miner connection info and connected miners
- pool page displays upstream pool and blockchain stats
- deployed at proxy.hashpool.dev
-
prometheus/victoria-metrics- Metrics Stores (Two per Deployment)- one metrics store for the pool, one for the translator
- each scrapes
/metricsfrom its service - provides the HTTP API that the corresponding web dashboard queries
Production Deployment
For deploying Hashpool on Debian 12, see the Deployment Guide.
What's New in v0.1.1
- SRI 1.7.0 migration complete: all protocols and utilities now import from crates.io (roles_logic_sv2 deprecated), vendored crates limited to hashpool-specific modifications
- New Template Provider: Bitcoin Core 30.2 (
bitcoin-node) + sv2-tp v1.0.6 replaces the Sjors SV2 fork; connects via unix IPC socket - Ehash mint flow redesign: end-to-end minting and share accounting were reworked across pool, translator, and mint services
- New roles: web services for pool/proxy monitoring and wallet UX
- Testnet staging: dedicated testnet deployment configs and workflow
- Fixed: share difficulty formula in the SV1 translator now uses the SV2
formula (
2^256 / target) matching miner expectations - Fixed: CoinbaseOutputConstraints 6-byte encoding (SRI 1.7.0 pool↔TP protocol)
- Added: Debian 12 deployment workflow (build-in-place + ship-only)
Troubleshooting
TUI detaches but processes keep running
If you try to copy text from the devenv shell while devenv up is running, process-compose can crash and detach the TUI, leaving all background processes running as orphans.
1. Find and kill the orphaned processes:
pgrep -a -f "pool_sv2|translator_sv2|mint|jd_server|jd_client|web_pool|web_proxy|sv2-tp|bitcoin-node|prometheus"
Kill the listed PIDs:
kill <pids...>
2. Verify everything is dead:
pgrep -f "pool_sv2|translator_sv2|mint|jd_server|jd_client|web_pool|web_proxy|sv2-tp|bitcoin-node|prometheus" && echo "still running" || echo "all clear"
3. Remove the stale socket and restart:
rm .devenv/run/pc.sock
devenv up
Contribution
This project is very early. PRs and bug reports are very welcome!