You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
goPool is a solo Bitcoin mining pool that connects directly to Bitcoin Core over JSON-RPC and ZMQ, exposes Stratum v1 (with optional TLS), and ships with a status UI + JSON APIs for monitoring.
9
+
goPool is a **from-scratch Golang solo Bitcoin mining pool**. It connects directly to Bitcoin Core over JSON-RPC and ZMQ, exposes Stratum v1 (with optional TLS), and ships with a status UI + JSON APIs for monitoring.
10
+
11
+
## What this project is
12
+
13
+
- A solo Bitcoin pool server written in Go from the ground up for this project.
14
+
- A direct integration with Bitcoin Core (no external pool engine dependency).
15
+
- A self-hosted stack: Stratum endpoint, web status UI, and JSON APIs.
16
+
17
+
## Feature highlights
18
+
19
+
-**Solo mining core**: builds and submits Bitcoin blocks directly against Bitcoin Core (`getblocktemplate` + `submitblock`) with JSON-RPC and optional ZMQ acceleration.
-**Share-policy controls**: duplicate checks, nTime and version-rolling checks, worker-match enforcement, stale-job freshness modes, and optional inline submit processing.
23
+
-**VarDiff + hashrate telemetry**: configurable difficulty clamps/targets, EMA smoothing, worker/pool hashrate history, and best-share tracking.
24
+
-**Safety and resilience**: node/job-feed health gating (disconnect/refuse when unsafe), reconnect/invalid-submit banning, pending submission replay, and stale-feed safeguards.
25
+
-**Web status UI + JSON APIs**: live overview, node/pool/server pages, worker pages, and `/api/*` endpoints for monitoring/automation.
26
+
-**Operator controls**: optional admin panel for live settings updates, persist-to-disk controls, log tooling, and guarded reboot action.
27
+
-**Storage and backups**: SQLite state store with atomic snapshots and optional Backblaze B2 upload workflow.
-**Examples are regenerated:** Example files are recreated on each startup to reflect current defaults
42
42
-**Don't edit examples:** Your changes to `.example` files will be lost on restart
43
43
-**Actual configs are protected:** Your configuration files in `data/config/` are gitignored and never overwritten
44
-
-**Cookie authentication preferred:** RPC credentials in `secrets.toml` only work with the `-allow-rpc-credentials` flag. Prefer setting `node.rpc_cookie_path` in `config.toml` for secure cookie-based authentication
44
+
-**Cookie authentication preferred:** RPC credentials in `secrets.toml` only work with the `-allow-rpc-creds` flag. Prefer setting `node.rpc_cookie_path` in `config.toml` for secure cookie-based authentication
45
45
46
46
## Authentication Priority
47
47
48
48
1.**Cookie file** (recommended) - Set `node.rpc_cookie_path` in `config.toml`
49
49
2.**Auto-detection** - goPool searches common locations if `rpc_cookie_path` is empty
50
-
3.**Username/password** (deprecated) - Use `rpc_user`/`rpc_pass` in `secrets.toml` with `-allow-rpc-credentials` flag
50
+
3.**Username/password** (deprecated) - Use `rpc_user`/`rpc_pass` in `secrets.toml` with `-allow-rpc-creds` flag
51
51
52
52
See [operations.md](../../../documentation/operations.md) for detailed configuration options.
Both values appear on the status page and JSON endpoints so you can verify the exact build at runtime.
44
44
45
-
## Initial configuration
45
+
## Starting the pool
46
46
47
-
1. Run `./goPool`; it generates `data/config/examples/` and exits.
48
-
2. Copy the base example to `data/config/config.toml` and edit required values (especially `node.payout_address`, `node.rpc_url`, and ZMQ addresses: `node.zmq_hashblock_addr`/`node.zmq_rawblock_addr`—leave blank to fall back to RPC/longpoll).
49
-
3. Optional: copy `data/config/examples/secrets.toml.example`, `data/config/examples/services.toml.example`, `data/config/examples/policy.toml.example`, `data/config/examples/tuning.toml.example`, and `data/config/examples/version_bits.toml.example` to `data/config/` for sensitive credentials or advanced tuning.
50
-
4. Re-run `./goPool`; it may regenerate `pool_entropy` and normalized listener ports if you later invoke `./goPool -rewrite-config`.
47
+
1. Run `./goPool` once; it generates `data/config/examples/` and exits.
48
+
2. Copy `data/config/examples/config.toml.example` to `data/config/config.toml`.
49
+
3. Set required values in `config.toml` (especially `node.payout_address`, `node.rpc_url`, and optional `node.zmq_hashblock_addr`/`node.zmq_rawblock_addr`).
50
+
4. Optional: copy split files from `data/config/examples/` into `data/config/` (`secrets.toml`, `services.toml`, `policy.toml`, `tuning.toml`, `version_bits.toml`) when you need overrides.
51
+
5. Start goPool again with `./goPool`.
51
52
52
-
## Runtime overrides
53
+
## Runtime flags
53
54
54
55
| Flag | Description |
55
56
|------|-------------|
@@ -62,8 +63,17 @@ Both values appear on the status page and JSON endpoints so you can verify the e
62
63
|`-rpc-url <url>`| Override `node.rpc_url` for this run—useful for temporary test nodes. |
63
64
|`-rpc-cookie <path>`| Override `node.rpc_cookie_path` when testing alternate cookie locations. |
64
65
|`-data-dir <path>`| Override the data directory (logs/state/config/examples) for this run. |
66
+
|`-log-dir <path>`| Override directory for pool/debug/net-debug logs only. |
67
+
|`-pool-log <path>`| Override pool log file path. |
Flags only override values for the running instance; nothing is written back to `config.toml` (except `node.rpc_cookie_path` when auto-detected). Use configuration files for durable behavior.
80
91
81
-
## Launching goPool
82
-
83
-
### Initial run
84
-
85
-
1. Run `./goPool` once without a config. The daemon stops after generating `data/config/examples/`.
86
-
2. Copy `data/config/examples/config.toml.example` to `data/config/config.toml`.
87
-
3. Provide the required values (payout address, RPC/ZMQ endpoints, any branding overrides) and restart the pool.
88
-
4. Optional: copy `data/config/examples/secrets.toml.example`, `data/config/examples/services.toml.example`, `data/config/examples/policy.toml.example`, `data/config/examples/tuning.toml.example`, and `data/config/examples/version_bits.toml.example` to `data/config/` and edit as needed.
89
-
5. If you prefer reproducible derived settings, rerun `./goPool -rewrite-config` once after editing. This writes derived fields such as `pool_entropy` and normalized listener ports back to `config.toml`.
90
-
91
-
### Common runtime flags
92
-
93
-
| Flag | Description |
94
-
|------|-------------|
95
-
| `-network <mainnet|testnet|signet|regtest>` | Force network defaults for RPC/ZMQ ports and version mask adjustments. Only one mode is accepted. |
96
-
|`-bind <ip>`| Override the bind IP for all listeners (Stratum, status UI). Ports remain as configured. |
97
-
|`-listen <addr>`| Override Stratum TCP listen address for this run. |
98
-
|`-status <addr>`| Override status HTTP listen address for this run. |
99
-
|`-status-tls <addr>`| Override status HTTPS listen address for this run. |
100
-
|`-stratum-tls <addr>`| Override Stratum TLS listen address for this run. |
101
-
|`-rpc-url <url>`| Override the RPC URL defined in `config.toml`. |
102
-
|`-rpc-cookie <path>`| Override the RPC cookie path; useful for temporary deployments while keeping `config.toml` untouched. |
103
-
|`-data-dir <path>`| Override the data directory used for config/state/logs for this run. |
Additional runtime knobs exist in `config.toml` plus optional `services.toml`/`policy.toml`/`tuning.toml`, but the flags above let you temporarily override them without editing files.
119
-
Flags such as `-network`, `-rpc-url`, `-rpc-cookie`, `-allow-public-rpc`, and `-secrets` only affect the current invocation; they override the values from `config.toml` or `secrets.toml` at runtime but are not persisted back to the files.
0 commit comments