public-pool/README.md

Description

A Nestjs and Typescript Bitcoin stratum mining server.

Installation

$ npm install

create an new .env file in the root directory and configure it with the parameters in .env.example

Running the app

# development
$ npm run start

# watch mode
$ npm run start:dev

# production build
$ npm run build

Test

# unit tests
$ npm run test

# test coverage
$ npm run test:cov

Web interface

See public-pool-ui

Deployment

The production Docker image runs database migrations and then starts PM2 automatically. For a manual host deployment, install pm2 (https://pm2.keymetrics.io/), run migrations, then start the app.

$ npm run build
$ npm run migration:run:prod
$ pm2 start dist/main.js

When running the worker app in PM2 cluster mode, start the PM2 daemon with OS-level connection scheduling. The environment variable must be present when the PM2 daemon starts, not only in the worker configuration.

$ NODE_CLUSTER_SCHED_POLICY=none pm2 start ecosystem.config.js

Cluster-mode connection dropping requires Node.js 22.12.0 or newer.

STRATUM_MAX_CONNECTIONS_PER_LISTENER is enforced per worker and Stratum port. Size it using the busiest port: worker count * limit. For example, 28 workers with the default limit of 10000 allow up to 280000 connections on one port.

SV2 pool-assigned extranonces reserve the first of their four prefix bytes for a process namespace and share the remaining 24-bit allocation space across standard and extended channels. Under PM2, the namespace uses NODE_APP_INSTANCE (falling back to pm_id) plus restart_time parity, which keeps workers and overlapping zero-downtime reload generations disjoint without changing the advertised prefix or total extranonce sizes. The effective value is SV2_EXTRANONCE_NAMESPACE_BASE + 2 * worker + (restart_time % 2) and must be at most 255 (up to 128 worker lanes at base zero). Startup fails if a PM2 worker identity is missing or the namespace cannot fit. Independent containers or PM2 worker apps that share mining work must be assigned non-overlapping base ranges; reserve two namespace values per configured Stratum worker.

New-block notification path

The master keeps an authoritative Bitcoin Core getblocktemplate longpoll open; rawblock ZMQ remains a watchdog and duplicate results are discarded. On a new tip, the master publishes a compact subsidy-only SV1 job before serializing the full transaction template. Workers fan that job out through one process-level socket broadcaster, then issue the full fee-paying job as a second clean switch. Payout snapshot creation and Postgres persistence run after the immediate solo publish.

SV2 solo channels pre-stage a native subsidy-only future job for the next height. When the authoritative header arrives, the pool activates that job with only SetNewPrevHash; the same-tip full job follows without a second prevhash switch. Standard and extended candidates retain exact header/body reconstruction, and late network-target candidates remain recoverable without crediting stale shares. Pending SV2 canonical jobs are coalesced per client, while a new-tip activation is moved ahead of any not-yet-started canonical work for that tip. The finite defaults are 16 retained jobs per channel, four queued operations, 256 KiB of outstanding socket writes, and a two-second write-callback deadline. A client is disconnected if SV2_MAX_RETAINED_JOBS_PER_CHANNEL, SV2_MAX_QUEUED_JOB_OPERATIONS, SV2_MAX_SOCKET_BUFFER_BYTES, or SV2_SOCKET_WRITE_TIMEOUT_MS is exceeded; SV2_JOB_RETENTION_MS controls how long stale network candidates remain reconstructable.

SV1_SUBSIDY_BRIDGE_ENABLED=true enables the solo bridge (the default). PPLNS is never allowed to fall back to a miner-address coinbase; optional PPLNS bridge support requires a precomputed subsidy-valued payout snapshot. Retained jobs are kept for STRATUM_JOB_RETENTION_MS so a late network-target candidate can still be reconstructed and submitted, while ordinary old-tip shares are rejected. PPLNS seeds use a non-active snapshot status and are skipped if the next authoritative nBits differs from their preparation basis.

The Redis protocol remains rolling-deploy compatible: new workers retain the legacy mining-info reload path, while the master writes the historical latest key as JSON only after a PPLNS-safe compatibility template is ready. Deploying workers before the master is still the preferred rollout order. When any PPLNS listener is configured and snapshot preparation fails, legacy workers are held on their prior job instead of being woken with a miner-address fallback job.

Two structured log events expose the end-to-end timing:

• block_notification_trace reports Core, bridge, Redis, PPLNS, and persistence stages, separated by payout mode and job type.
• stratum_job_fanout reports client count, bytes, backpressure, and p50/p95/p99/last enqueue time, correlated by eventId.

Docker

The default compose stack includes Public Pool, TimescaleDB, and Redis. TimescaleDB stores normal Postgres tables plus immutable accepted-share rows in a hypertable. Chart and hashrate APIs read from Timescale continuous aggregates plus recent raw shares for realtime buckets. Redis is used only for process messaging and latest mining-template replay.

Start the stack:

$ docker compose up --build -d

Use an external TimescaleDB/Postgres server:

$ DB_HOST=postgres.example.com \
  DB_PORT=5432 \
  DB_USERNAME=public_pool \
  DB_PASSWORD='change-me' \
  DB_DATABASE=public_pool \
  DB_SSL=false \
  docker compose -f docker-compose.external-db.yml up --build -d

The external database must be TimescaleDB-compatible and reachable from the Public Pool container. The startup script waits for the remote DB_HOST:DB_PORT, runs migrations, then starts PM2. Redis still runs locally in this compose file unless REDIS_URL is pointed at an external Redis instance.

Set DB_SSL=true if the external database requires TLS. For private CA or self-signed test deployments, DB_SSL_REJECT_UNAUTHORIZED=false disables certificate verification; do not use that setting for normal internet-facing production databases.

For a fresh external database, create the role/database first:

CREATE USER public_pool WITH PASSWORD 'change-me';
CREATE DATABASE public_pool OWNER public_pool;
\c public_pool
CREATE EXTENSION IF NOT EXISTS timescaledb;
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";

If TimescaleDB is managed by another operator, make sure the public_pool role can create tables, indexes, continuous aggregates, and Timescale policies in the target database.

Run only the database migrations:

$ docker compose run --rm public-pool npm run migration:run:prod

Watch logs:

$ docker compose logs --tail 100 -f public-pool

Back up TimescaleDB:

$ docker compose exec timescaledb pg_dump -U public_pool public_pool > public-pool.sql

Redis does not hold durable accounting data. Losing Redis requires workers to replay the latest template from Redis after reconnect or fall back to the saved RPC block template table.

note: To successfully connect to the bitcoin RPC you will need to add

rpcallowip=172.16.0.0/12
zmqpubrawblock=tcp://0.0.0.0:3000

to your bitcoin.conf.

Testing

Baseline unit regression capture:

$ npm run test:baseline

Unit tests:

$ npm test

Integration tests against real TimescaleDB and Redis:

$ docker compose -f docker-compose.test.yml up --build --abort-on-container-exit

With the full-setup regtest Bitcoin Core running, validate reconstructed empty and full blocks through BIP23 proposal mode:

$ RUN_BITCOIN_REGTEST_INTEGRATION=true \
  npm run test:integration -- bitcoin-regtest-proposal