M45-Core-goPool (goPool)

⬇️ Download Pre-Built Releases - Ready-to-run binaries for Linux (AMD64) and macOS (AMD64/ARM64). See RELEASES.md for details.

About

goPool is a solo Bitcoin mining pool that connects directly to Bitcoin Core (bitcoind) over JSON-RPC and ZMQ. It serves miners via Stratum v1 (with optional TLS) and provides a web-based status UI with JSON APIs for monitoring.

Key Features:

Stratum v1 mining protocol with optional TLS support
Direct Bitcoin Core integration via JSON-RPC and ZMQ
Configurable coinbase splits (pool fee, operator donation, miner payout)
Web status UI with HTTPS-first design and auto-generated certificates
Automated backups with optional Backblaze B2 cloud storage
Rate limiting, invalid-submission bans, and reconnect churn protection
Comprehensive test suite with compatibility checks

Build

Requirements:

Bitcoin Core with RPC enabled and ZMQ support recommended
Go toolchain (see go.mod for version)
ZeroMQ library and headers (for github.com/pebbe/zmq4)

Installing Dependencies

Install Go (all distributions):

goPool requires Go 1.24.11 or later. Always use the official golang.org release rather than distribution packages.

Visit https://go.dev/dl/ to download and install the latest Go version for your platform.

Install ZeroMQ:

Ubuntu / Debian:

sudo apt update
sudo apt install -y libzmq3-dev

Fedora / RHEL / CentOS:

sudo dnf install -y zeromq-devel

Arch Linux:

sudo pacman -S zeromq

Alpine Linux:

apk add --no-cache zeromq-dev build-base

Build & Run

# Clone the repository (if not already cloned)
git clone https://github.com/Distortions81/M45-Core-goPool.git
cd M45-Core-goPool

# Run directly
go run .

# Or build binary
go build -o goPool
./goPool

On first run, goPool will generate example configuration files in data/config/examples/ and exit with setup instructions.

Build Tags

goPool supports several build tags for different configurations:

Build Tag	Purpose	Default	Fallback
`debug`	Enable debug logging + network traffic logs	Off	N/A
`verbose`	Enable verbose logging (no network logs)	Off	N/A
`noavx`	Disable hardware-accelerated SHA256	Uses `sha256-simd`	`crypto/sha256`
`nojsonsimd`	Disable hardware-accelerated JSON	Uses `sonic`	`encoding/json`

Logging Levels:

# Debug build with network traffic logging
go build -tags debug -o goPool

# Verbose build without network traffic logging
go build -tags verbose -o goPool

Disable Hardware-Accelerated SHA256:

By default, goPool uses github.com/minio/sha256-simd which provides hardware-accelerated SHA256 hashing:

x86/x64: AVX512, SHA Extensions, AVX2
ARM64: Cryptography Extensions (ARMv8)
Fallback: Pure Go implementation on unsupported platforms

The library automatically selects the best implementation at runtime. However, you can force the use of standard crypto/sha256:

Build without sha256-simd:

# Disable sha256-simd at build time
go build -tags noavx -o goPool

Use runtime flag:

# Disable sha256-simd at runtime
./goPool -sha256-no-avx

When to disable: Only needed for debugging, benchmarking the standard library, or if sha256-simd causes issues. The library handles unsupported platforms automatically.

Disable Hardware-Accelerated JSON:

By default, goPool uses github.com/bytedance/sonic for faster JSON encoding/decoding with JIT compilation and SIMD:

Supported: Linux, MacOS, Windows on AMD64 or ARM64
Fallback: Standard encoding/json on unsupported platforms

# Disable sonic (forces encoding/json)
go build -tags nojsonsimd -o goPool

Combining Build Tags:

# Debug build without SIMD acceleration
go build -tags "debug noavx nojsonsimd" -o goPool

# Verbose build without SIMD acceleration
go build -tags "verbose noavx nojsonsimd" -o goPool

# Disable only JSON SIMD, keep SHA256 SIMD
go build -tags nojsonsimd -o goPool

# Disable only SHA256 SIMD, keep JSON SIMD
go build -tags noavx -o goPool

Command-Line Parameters

Run ./goPool -h to see all available command-line flags:

Flag	Description
`-allow-rpc-credentials`	Allow loading rpc_user/rpc_pass from secrets.toml when node.rpc_cookie_path is not set
`-bind <ip>`	Bind to specific IP address for stratum listener (e.g. 0.0.0.0 or 192.168.1.100)
`-check-duplicates`	Enable duplicate share checking (disabled by default for solo pools)
`-disable-json-endpoint`	Disable JSON status endpoints for debugging
`-flood`	Enable flood-test mode (force min/max difficulty to 0.01)
`-https-only`	Serve status UI over HTTPS only (auto-generating a self-signed cert if none is present) (default: true)
`-mainnet`	Force mainnet defaults for RPC/ZMQ ports
`-no-clean-bans`	Skip rewriting the ban list on startup (keep expired bans)
`-no-zmq`	Disable ZMQ subscriptions and rely on RPC/longpoll only (SLOW)
`-profile`	Collect a 60s CPU profile to default.pgo on startup
`-regtest`	Force regtest defaults for RPC/ZMQ ports
`-rewrite-config`	Rewrite config file with effective settings on startup
`-rpc-cookie-path <path>`	Override node RPC cookie path (skips autodetection when set)
`-rpc-url <url>`	Override RPC URL (e.g. http://127.0.0.1:8332)
`-secrets <path>`	Path to secrets.toml (overrides default under data_dir/config)
`-signet`	Force signet defaults for RPC/ZMQ ports
`-stdoutlog`	Mirror logs to stdout in addition to writing to files
`-testnet`	Force testnet defaults for RPC/ZMQ ports

Common Usage Examples:

# Run on testnet
./goPool -testnet

# Run on regtest for local development
./goPool -regtest

# Mirror logs to stdout for debugging
./goPool -stdoutlog

# Bind to specific IP address
./goPool -bind 192.168.1.100

# Override RPC URL
./goPool -rpc-url http://127.0.0.1:8332

Configuration

Quick Start Configuration

After your first run, goPool generates example configs in data/config/examples/. Copy and edit them:

cp data/config/examples/config.toml.example data/config/config.toml
nano data/config/config.toml

Minimum Required Settings:

Payout Address - Where your mining rewards go:

[node]
payout_address = "YOUR_BITCOIN_ADDRESS"

Bitcoin Core Connection - Update if not using defaults:

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

Optional but Recommended:

Set server.status_public_url to your pool's public URL for proper redirects
Configure branding.status_brand_name and branding.status_tagline for UI customization
Set mining.pool_fee_percent (default 2.0%)

See operations.md for detailed configuration options.

Config Files

goPool uses three TOML configuration files in data/config/:

config.toml (required) - Primary pool configuration
secrets.toml (optional) - Sensitive credentials (Discord tokens, Clerk keys, RPC auth)
tuning.toml (optional) - Performance tuning overrides

If config.toml is missing, goPool generates examples and exits. Copy and customize data/config/examples/config.toml to get started.

Bitcoin Core Connection

RPC Authentication:

Preferred: Cookie file via node.rpc_cookie_path
Autodetection: goPool searches $BITCOIN_DATADIR and common locations
Override: Use -rpc-cookie-path flag for single-run override
Alternative: Use -allow-rpc-credentials with rpc_user/rpc_pass in secrets.toml (insecure, not recommended)
Public RPC: Set node.allow_public_rpc = true for unauthenticated endpoints (understand security implications)

ZMQ Configuration: Add to your bitcoin.conf:

zmqpubrawblock=tcp://127.0.0.1:28332
zmqpubhashblock=tcp://127.0.0.1:28332
zmqpubrawtx=tcp://127.0.0.1:28332
zmqpubhashtx=tcp://127.0.0.1:28332

Then set in config.toml:

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

To disable ZMQ and use RPC-only mode, use the -no-zmq flag.

Network Listeners

Default ports in config.toml:

Stratum (plain): :3333
Stratum (TLS): :4333
Status UI (HTTP): :8080
Status UI (HTTPS): :4443

TLS Certificates:

Auto-generated: goPool creates self-signed certs on first run (data/tls_cert.pem, data/tls_key.pem)
Custom certs: Replace these files with your own (e.g., from Let's Encrypt)
Auto-reload: Certificates reload hourly automatically
Helper script: scripts/certbot-gopool.sh automates certbot integration

HTTPS-First Mode: By default (-https-only=true), HTTP serves only a safe subset and redirects to HTTPS. Set server.status_public_url to your final public URL for proper redirects and session cookies.

Operation

Running the Pool

Point miners at Stratum:

Plain: stratum+tcp://<pool-host>:3333
TLS: stratum+ssl://<pool-host>:4333

Runtime Configuration Reload:

SIGUSR1 - Reload HTML templates
SIGUSR2 - Reload config/secrets/tuning (status pages only; restart required for listener/auth changes)

Command-Line Flags:

-rpc-cookie-path <path> - Override RPC cookie location
-rpc-url <url> - Override RPC URL
-allow-rpc-credentials - Enable rpc_user/rpc_pass from secrets.toml
-no-zmq - Disable ZMQ, use RPC/longpoll only
-https-only=false - Disable HTTPS-first mode

Monitoring

Status UI:

Access at https://<pool-host>:4443 (default)
Templates in data/templates/
JSON API endpoints under /api/*

Data Storage:

Worker database: data/state/workers.db
Automatic local snapshots for safe backups
Optional Backblaze B2 uploads (configure [backblaze_backup] section)

Additional Documentation

RELEASES.md - Pre-built release packages and upgrade guide
operations.md - Detailed configuration, flags, API reference, logging
performance.md - Capacity planning and benchmark data
TESTING.md - Test suite overview and instructions
data/config/examples/autogen.md - Config generation details

Useful Scripts

scripts/install-bitcoind.sh - Bootstrap local bitcoind with ZMQ
scripts/run-tests.sh - Run complete Go test suite
scripts/profile-graph.sh - Generate CPU profile visualization
scripts/certbot-gopool.sh - Automate Let's Encrypt certificate setup

Name		Name	Last commit message	Last commit date
Latest commit History 397 Commits
.github		.github
data		data
scripts		scripts
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
RELEASES.md		RELEASES.md
TESTING.md		TESTING.md
accept_rate_limiter.go		accept_rate_limiter.go
accept_rate_limiter_test.go		accept_rate_limiter_test.go
accounting.go		accounting.go
accounting_fuzz_test.go		accounting_fuzz_test.go
address.go		address.go
address_roundtrip_test.go		address_roundtrip_test.go
backblaze_backup.go		backblaze_backup.go
backblaze_backup_test.go		backblaze_backup_test.go
ban_expiry_test.go		ban_expiry_test.go
block_test.go		block_test.go
block_validity_compat_test.go		block_validity_compat_test.go
clerk_auth.go		clerk_auth.go
coinbase_btcd_compat_test.go		coinbase_btcd_compat_test.go
coinbase_multi_output_test.go		coinbase_multi_output_test.go
coinbase_test.go		coinbase_test.go
coinbase_wallet_types_test.go		coinbase_wallet_types_test.go
config.go		config.go
config_autoconfig.go		config_autoconfig.go
config_examples.go		config_examples.go
config_test.go		config_test.go
config_validate.go		config_validate.go
const.go		const.go
cross_impl_sanity_test.go		cross_impl_sanity_test.go
debug_flags_off.go		debug_flags_off.go
debug_flags_on.go		debug_flags_on.go
default.pgo		default.pgo
defaults.go		defaults.go
difficulty_compat_test.go		difficulty_compat_test.go
difficulty_fuzz_test.go		difficulty_fuzz_test.go
difficulty_test.go		difficulty_test.go
discord_bot.go		discord_bot.go
discord_bot_test.go		discord_bot_test.go
discord_notify_state.go		discord_notify_state.go
found_block_async.go		found_block_async.go
found_block_test.go		found_block_test.go
go.mod		go.mod
go.sum		go.sum
hash_sha256_common.go		hash_sha256_common.go
hash_sha256_noavx.go		hash_sha256_noavx.go
hash_sha256_simd.go		hash_sha256_simd.go
http_fallback.go		http_fallback.go
job.go		job.go
job_block.go		job_block.go
job_coinbase.go		job_coinbase.go
job_feed.go		job_feed.go
job_hash.go		job_hash.go
job_nozmq_history_test.go		job_nozmq_history_test.go
job_zmq_blocktip_test.go		job_zmq_blocktip_test.go
job_zmq_rawblock_refresh_test.go		job_zmq_rawblock_refresh_test.go
job_zmq_test.go		job_zmq_test.go
json_cache_test.go		json_cache_test.go
jsonx_common.go		jsonx_common.go
jsonx_sonic.go		jsonx_sonic.go
jsonx_std.go		jsonx_std.go
logging.go		logging.go
logo.png		logo.png
main.go		main.go
metrics.go		metrics.go
miner.go		miner.go
miner_auth.go		miner_auth.go
miner_fuzz_test.go		miner_fuzz_test.go
miner_log_found_block_test.go		miner_log_found_block_test.go
miner_registry.go		miner_registry.go
miner_rejects.go		miner_rejects.go
miner_submit.go		miner_submit.go
miner_submit_bench_test.go		miner_submit_bench_test.go
miner_submit_block_safety_test.go		miner_submit_block_safety_test.go
netlog.go		netlog.go
netlog_stub.go		netlog_stub.go
network_params.go		network_params.go
one_time_code.go		one_time_code.go
one_time_code_test.go		one_time_code_test.go
operations.md		operations.md
path_traversal_test.go		path_traversal_test.go
payout_debug_test.go		payout_debug_test.go
payout_test.go		payout_test.go
pending_submissions.go		pending_submissions.go
pending_submissions_test.go		pending_submissions_test.go
performance.md		performance.md
pogolo_compat_test.go		pogolo_compat_test.go
pool_tag.go		pool_tag.go
pow_compat_test.go		pow_compat_test.go
price.go		price.go
profile.svg		profile.svg
profile_sim_test.go		profile_sim_test.go
reconnect_tracker.go		reconnect_tracker.go
rpc.go		rpc.go
rpc_test.go		rpc_test.go
runtime_overrides.go		runtime_overrides.go
saved_workers_bench_test.go		saved_workers_bench_test.go
share_detail.go		share_detail.go
state_db.go		state_db.go

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

M45-Core-goPool (goPool)

About

Build

Installing Dependencies

Build & Run

Build Tags

Command-Line Parameters

Configuration

Quick Start Configuration

Config Files

Bitcoin Core Connection

Network Listeners

Operation

Running the Pool

Monitoring

Additional Documentation

Useful Scripts

About

Uh oh!

Releases 1

Uh oh!

Contributors 2

Uh oh!

Languages

License

Distortions81/M45-Core-goPool

Folders and files

Latest commit

History

Repository files navigation

M45-Core-goPool (goPool)

About

Build

Installing Dependencies

Build & Run

Build Tags

Command-Line Parameters

Configuration

Quick Start Configuration

Config Files

Bitcoin Core Connection

Network Listeners

Operation

Running the Pool

Monitoring

Additional Documentation

Useful Scripts

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 1

Uh oh!

Contributors 2

Uh oh!

Languages