simplepool

What it is

A stratum server, a share ledger, and a read-only dashboard. That is the whole system.

Miners open a TCP connection to port 3334 and speak stratum v1. simplepool builds block templates from bitcoind's getblocktemplate, hands each connection its own job, re-hashes every submission it receives, and writes each accepted one into data/shares.db. If a submission also clears the network target, it goes straight back out via submitblock.

There is no account system. There is no password — the stratum password field is read and discarded. Your identity on the pool is the payout address you authorize with, which means there is nothing to register, nothing to log into, and nothing the operator can quietly change about who you are.

Why "share" and not "work unit"

In solo mode a share is not a claim on anything — the block reward goes to whoever finds the block, and shares exist for hashrate estimation and per-rig accountability. The word is kept anyway, deliberately: share is the term every ASIC firmware, monitoring tool and pool dashboard already uses, and the same column and table names carry through unchanged into pps-classic, where shares genuinely are the unit of account. The meaning shifts between modes; the vocabulary does not.

The two modes

One config key — pool_mode — decides the shape of the coinbase, what a stratum username must be, and whether any off-chain accounting happens at all.

The stack

In solo mode everything to the right of bitcoind is optional. In pps-classic the enforcer and a Thunder node join the picture, because that is where miners actually get paid.

Optionally, setting redis_url mirrors accepted shares, rejects, blocks, tip changes and PPS credits onto Redis pub/sub channels (pool:shares, pool:rejects, pool:blocks, pool:tip, pool:credits). SQLite stays authoritative; the publish is fire-and-forget and a Redis outage cannot cost you a share.

Life of a share

From plugging in an ASIC to a row in the ledger. Identical in both modes except where noted.

1. miner → pool

   mining.subscribe

   The pool allocates this connection a 4-byte extranonce1 and replies with it. The value comes from an atomic counter XORed with the current millisecond, so two rigs subscribing in the same nanosecond cannot collide, and a rig reconnecting days later after the counter has wrapped still gets something fresh.

2. miner → pool

   mining.authorize "<address>[.<rig>]"

   The username is parsed as an address and validated on the spot — bech32 or base58check in solo mode, bare base58 Thunder in pps-classic. An invalid address is rejected with a clear error and written to the rejects table rather than silently accepted. The password is discarded.

3. pool → miner

   mining.set_difficulty + mining.notify

   The connection gets a starting difficulty and the current job. In solo mode the job's cb1/cb2 are rendered against this miner's address, so two rigs on the same pool are working on genuinely different coinbases. The merkle branches, previous hash, nbits and ntime are shared.

4. pool ↔ bitcoind

   Tip watcher

   A background thread re-fetches getblocktemplate every bitcoind_poll_interval_ms (default 30 s). On a new tip the job is rebuilt and broadcast to every connection with clean_jobs = true.

5. miner → pool

   mining.submit

   Carries job_id, the miner's extranonce2, ntime, nonce, and the exact rolled version bits. The pool does not take the miner's word for the hash: it reassembles the coinbase from the cached cb1/cb2 and the two extranonces, recomputes the merkle root, rebuilds the 80-byte header, and double-SHA256s it itself.

6. pool

   Two comparisons, one hash

   The resulting hash is compared against the connection's worker target and against the network target. Above the worker target it is rejected as low difficulty and logged in rejects. Below it, a row lands in shares. Below the network target as well, it is also a block.

7. pool → bitcoind

   Block submission

   A block-shaped share is serialised in full and pushed via submitblock, then recorded in blocks_found with the height, hash, finder, reward and fee. The same submission counts as a paid share and as a block — one hash, both thresholds.

8. pool

   Vardiff tick, then the write

   If the vardiff window has elapsed the connection is retargeted and gets a fresh mining.set_difficulty. Writes are batched: shares queue into a lock-free ring and a writer thread commits every commit_window_ms (100 ms) or every commit_max_shares (100), whichever comes first.

Dividing the search space

The fairness guarantee simplepool makes is narrow and checkable: no two connections are ever searching the same (header, coinbase, nonce) triple.

A block header is 80 bytes, and only three parts of it can vary while you search: the 4-byte nonce, whichever version bits the pool has permitted you to roll, and the merkle_root — which you change indirectly, by changing the coinbase transaction.

The 80-byte header

Where the extranonce lives

The coinbase scriptSig is assembled at share-check time and carries both halves of the standard stratum split:

assigned once per connection yours to search

Together those give each connection 2⁶⁴ distinct coinbases before it would need to reconnect for a fresh extranonce1 — effectively unbounded at any real hashrate. Each extranonce2 value yields a distinct coinbase, therefore a distinct coinbase txid, therefore a distinct merkle root, therefore a fresh 2³² nonce space to sweep.

Version rolling

If a miner advertises support via mining.configure, the pool negotiates a version-bit mask — currently 0x1fffe000, the 16 bits from position 13 to 28. That multiplies the space behind a single (extranonce1, extranonce2) pair by 2¹⁶, so one extranonce2 value covers 2³² × 2¹⁶ = 2⁴⁸ ≈ 280 trillion headers.

The pool never re-derives a rolled version on its own. The miner states the exact version it hashed, the pool reconstructs that header and re-hashes it, and any bit flipped outside the mask makes the submission invalid.

Two rigs, one address

Authorizing as bc1q….basement and bc1q….garage gives you two connections, hence two different extranonce1 values, hence no overlapping work — and two separate rows in workers, so the leaderboard and the per-worker drilldown can tell your boxes apart while the dashboard still rolls them up by address.

Difficulty & vardiff

Every share is measured against two thresholds. One decides whether it counts; the other decides whether it is a block.

Both are 256-bit big-endian numbers, and for a hash h:

share accepted  ⇔  h ≤ worker_target
block found     ⇔  h ≤ network_target

What "difficulty 0.016" means

Bitcoin's pdiff-1 target is 0xffff × 2208. A share at difficulty D is one whose hash is below pdiff_1 / D, so given a worker target the difficulty recorded on the share row is simply:

difficulty = pdiff_1_target / worker_target

Worked example, from a real rig

worker_target = 0x000003e7fc18…            (5 leading hex zeros)
              = 0x03e7fc18 × 2^204

difficulty    = (0xffff × 2^208) / (0x03e7fc18 × 2^204)
              = 65535 × 16 / 65407512
              ≈ 0.01603

That is the number stored in shares.difficulty on every row this connection produces, and — in pps-classic — the number your credit is computed from. Hashrate follows from the share rate:

shares_per_second = H / (D × 2^32)

14 shares in a minute at D = 0.016
  → 0.233 shares/s
  → H = 0.233 × 0.016 × 2^32 ≈ 16 MH/s

The dashboard's hashrate column uses exactly this formula over a rolling window (24 h by default), which is why it is an estimate with visible variance rather than a reading off your ASIC.

Vardiff

Each connection is retargeted to hold a chosen share rate — 12 shares per minute by default, roughly one every five seconds. The knobs:

Solo mode

pool_mode = solo. The whole payout mechanism is the coinbase transaction. There is no ledger of debts, because the pool never owes anyone anything.

The coinbase

Every connection gets a coinbase built against its own payout address, so the block a given rig is hashing on already pays that rig if it lands:

With fee_bps = 0 the fee output disappears entirely and the coinbase is a single payout to the miner. The same happens automatically when the computed fee would land below the relay dust threshold (~546 sats): the operator output is dropped rather than made unspendable, and the miner takes the full reward.

What you get, precisely

• Find a block → your address receives ~99% of subsidy + fees, on-chain, in that block, confirmed the moment the block is.
• Don't find a block → nothing. Not a smaller amount; nothing. No other miner on the pool earns at that height either.
• No inter-miner sharing, no difficulty-weighted accounting, no balance, no withdrawal, no minimum, no pool custody at any point.

The shares and workers tables still fill up. They exist so the dashboard can show a leaderboard, a per-rig drilldown, and the pool's block history — and so that the data model is already the one pps-classic needs. A share here is evidence of work, not a claim.

Username

<bitcoin_address>[.<rig_label>]

bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4
bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4.basement-rig
bcrt1q….test.alice                            # regtest

The address is required and must be valid bech32 (P2WPKH) or base58check (P2PKH / P2SH) — it is decoded at authorize time, and a typo is rejected immediately rather than discovered when a block is found and paid to nowhere. The optional rig_label is alphanumeric plus _ and -.

pps-classic mode

pool_mode = pps-classic. Every accepted share earns a fixed amount whether or not anyone finds a block. The pool takes the variance; the miner gets a smooth income stream paid out over Thunder.

The value flow, end to end

1. on-chain

   The coinbase pays the pool

   Ordinary output to pool_btc_address for the full net-of-operator-fee reward, plus the operator fee output. No drivechain magic — the pool briefly custodies BTC, which is the tradeoff that makes the rest work at all.

2. per share, automatic

   Each accepted share credits pps_credits

   accrued_sats += floor(difficulty × rate), written by the C proxy and by nothing else. Both the credit and the rate that produced it are stamped onto the share's own row.

3. operator, manual

   BTC is deposited into the Thunder reserve

   From the admin dashboard: a real CreateDepositTransaction through the enforcer's wallet, spending accumulated pool UTXOs into OP_DRIVECHAIN + OP_RETURN. This does move the Ctip. Each one is recorded in the deposits table with the txid and the Ctip sequence before and after.

4. payout worker, daily

   The reserve is drained to miners

   Everyone whose accrued − paid clears PAYOUT_MIN_SATS is paid in a single batched Thunder transaction, once every 24 hours. Section 10 is the mechanism.

The rate is derived, not configured

The obvious way to run PPS is to pick a sats-per-difficulty number and hold it. simplepool deliberately doesn't: a fixed rate goes stale the moment difficulty moves, and can quietly invert into paying miners more than each share is worth. Instead the rate is recomputed from every block template:

gross = coinbasevalue / network_difficulty     # fair value of one diff-1 share
rate  = gross × (1 − fee_bps / 10000)         # what the pool actually pays

credit_per_share = floor(difficulty × rate)   # truncated to whole sats

So the rate tracks both block value and difficulty automatically, and fee_bps is the only fee knob in the system. Every rate the pool publishes is appended to rate_history together with the template inputs it came from, which is what makes check 2 possible.

Username

<thunder_base58_address>[.<rig_label>]

JPbJrEKEaA69dAADY2qfW7dfyYQ
JPbJrEKEaA69dAADY2qfW7dfyYQ.shed-01

Where the fee lands

fee_bps is one number applied in up to two places, and whether that is one deduction or two depends entirely on your addresses.

Which makes the choice of addresses a real economic decision:

Both are coherent; neither is a bug. Pick deliberately, and if you pick the second one, know that you have separated who collects the fee from who carries the risk.

Payouts over Thunder

pps-classic only. The design goal is narrow and unglamorous: never pay twice, and never claim to have paid when you haven't.

Once a day, in one transaction

Payouts run as a daily batch. Once every 24 hours, everyone whose accrued − paid clears PAYOUT_MIN_SATS (10 000 sats by default) goes out together in a single Thunder transaction.

Batching is not an optimisation, it is a requirement. Thunder only advances when a mainchain block commits to it, and its wallet cannot spend the change of an unconfirmed transaction — so paying N miners individually would cost N sidechain blocks, and past a handful of miners the queue would drain slower than it fills. The cost of batching is failure isolation: one bad address fails the whole batch. That is an acceptable trade here, because every recipient is an address the proxy already validated at authorize time, and a failed batch credits nobody and strands nobody — the next run simply retries.

Three clocks, not one

The daily cadence governs when a payout starts. It deliberately does not govern what happens to a batch already in flight, because two of the states a run can end in are ruined by a long wait:

To pay out early, the admin dashboard has a Trigger payout now button. Restarting the worker also runs one immediately.

paid means mined, not sent

pps_credits.paid_sats moves only when a transaction has actually been observed in a block. Crediting at broadcast was tried and abandoned: a transaction sitting in a mempool has discharged no debt, so counting it as paid makes accrued − paid understate what the pool really owes — measured at 265 BTC for over four hours on a test network — and leaves no way back if the transaction never lands.

Telling "confirmed" from "gone" is the hard part, because Thunder offers no single durable answer. Two sources are consulted and only positive evidence from either is accepted: get_transaction reporting a block hash (authoritative but transient — it reads back as null once the chain moves past it), and the wallet UTXO set containing an outpoint bearing our txid (durable, because Thunder only admits confirmed UTXOs). Absence is never read as confirmation, and never as eviction either: "the node forgot it" and "it confirmed a while ago" look identical from outside, and guessing wrong in one direction pays twice. So unknown stays unknown, payouts halt, and a human is asked.

The at-most-once protocol

1. write-ahead

   INSERT INTO payouts_in_flight

   One row per worker in the batch, txid = ''. From this moment listDue() skips those workers, so nothing can queue them twice.

2. network

   Broadcast the batch

   One Thunder transaction for everyone. On failure the rows are removed, paid_sats is untouched, and the next run tries again.

3. local

   Stamp the txid — and stop

   The rows stay in flight. Nobody is credited here. A broadcast is not a settlement.

4. a later tick

   Confirmed → one atomic transaction

   paid_sats += for every worker in the batch and the in-flight rows are deleted, together, in a single SQLite transaction. It commits whole or not at all — there is no partial credit across a batch.

The one genuinely ambiguous state is a crash between steps 1 and 2: a broadcast that happened is indistinguishable from one that did not. Those rows are reported by listStuck() at every start and left for an operator to resolve, because the two possibilities demand opposite actions and nothing on the machine can tell them apart.

Auditing every number

The point of the data model. These checks run against a copy of shares.db and consult nothing live — no API, no dashboard, no trust in the operator.

What is written down per share

Each accepted share row carries the difficulty it was measured at, the rate in force when it was accepted (rate_used), and the sats it was credited (credited_sats). Storing the multiplicand alongside the product is the whole trick: the credit can be re-derived years later without knowing what the rate happened to be at the time, and without asking the pool.

Four queries

-- 1. Arithmetic. Every credited share must re-derive from the pair stored
--    on its own row. Nothing current is consulted.
SELECT COUNT(*) FROM shares
 WHERE rate_used > 0
   AND credited_sats <> CAST(difficulty * rate_used AS INTEGER);

-- 2. Provenance. Every rate the pool published must follow from the template
--    inputs recorded beside it. Catches a rate applied consistently but
--    derived wrongly — which (1) cannot see.
SELECT COUNT(*) FROM rate_history
 WHERE ABS(rate_sats_per_diff
       - (block_value_sats * 1.0 / network_difficulty)
         * (1 - fee_bps / 10000.0)) > 1e-9;

-- 3. Linkage. No share may be credited at a rate the pool never published.
SELECT COUNT(*) FROM shares s
 WHERE s.rate_used > 0
   AND s.ts >= (SELECT MIN(ts) FROM rate_history)
   AND NOT EXISTS (SELECT 1 FROM rate_history r
                    WHERE r.rate_sats_per_diff = s.rate_used);

-- 4. Solvency. What the pool mined must cover what it owes.
SELECT (SELECT SUM(reward_sats) + SUM(fee_sats) FROM blocks_found)
     - (SELECT SUM(credited_sats) FROM shares) AS margin_sats;

The first three must return 0. Query 4 should be positive, and close to Σ difficulty × gross × fee_bps/10000 once luck is accounted for — a negative result means the pool cannot pay out of what it has earned, which is the number that actually matters.

Exact equality in check 1 is the right test rather than a tolerance: the proxy is built without -ffast-math, so SQLite reproduces the same IEEE-754 multiply and truncation bit for bit. Shares accepted before rate_used existed carry 0 and are excluded from checks 1 and 3 — their credited_sats is still authoritative, there is simply no stored multiplicand to check it against, and the audit page reports them as unverifiable rather than as failures.

Luck, quantified

SELECT ROUND((SELECT SUM(difficulty) FROM shares)
             / (SELECT network_difficulty FROM pool_meta)) AS expected_blocks,
       (SELECT COUNT(*) FROM blocks_found)                 AS actual_blocks;

Block-withholding audit

A miner can hash honestly, submit every share, and quietly discard the one submission that happens to be a block — collecting PPS credit while contributing nothing. payout/audit.js is a standalone read-only CLI that looks for it: over a window, each worker's expected block count is pool_blocks × (worker_diff / pool_diff), and z = (expected − actual) / √expected. It flags a worker when expected ≥ 5 and z ≥ 3 — about a 1-in-740 false positive rate under honest Poisson sampling. No schema changes; safe to run while the proxy is writing.

The data model

One SQLite file, data/shares.db, in WAL mode. The proxy is the only writer; the dashboard and the audit tools only read.

Connect a miner

There is nothing to sign up for. Point the ASIC at the host and put your address in the username field.

URL       stratum+tcp://pool.example.com:3334
Worker    bc1qw508d6…kv8f3t4.rig-01
Password  (anything — it is discarded)

URL       stratum+tcp://pool.example.com:3334
Worker    JPbJrEKEaA69dAADY2qfW7dfyYQ.rig-01
Password  (anything — it is discarded)

Stratum is raw TCP, not HTTP, so it does not pass through the pool's nginx. Miners connect straight to host:3334; only the dashboard is behind the reverse proxy. If you need TLS on stratum itself, that is an nginx stream {} block or stunnel, not something the pool does for you.

If a connection is refused

Configuration

One key = value file, proxy.conf. The keys that change behaviour rather than tuning it:

The payout worker is configured entirely by environment variables, not by this file — PAYOUT_INTERVAL_MS, PAYOUT_SETTLE_INTERVAL_MS, PAYOUT_MIN_SATS, THUNDER_FROM_ADDRESS and friends. The Thunder reserve address is deliberately not a proxy key: the coinbase never touches Thunder, so only the dashboard and the payout worker have any business knowing it.

Running one

One line on a fresh Ubuntu or Debian server, then a single command for everything after.

curl -fsSL https://raw.githubusercontent.com/LayerTwo-Labs/simplepool/main/scripts/install.sh | sudo bash

The installer downloads the published build for the machine's architecture, verifies it against the release SHA256SUMS, then asks for the pool mode, your bitcoind RPC, your addresses, a dashboard domain and admin password, and whether to set up nginx, TLS and the firewall. It writes proxy.conf, loads the schema, installs three systemd units, and tells you what miners should connect to. Every answer is saved, so re-running it is how you change your mind about any of them. Pass --from-source to clone and compile instead.

simplepoolctl status            # services, ports, versions, ledger totals
simplepoolctl doctor            # binary runs? bitcoind answers? DB writable?
simplepoolctl logs payout -f    # one service, or all of them
sudo simplepoolctl restart proxy
sudo simplepoolctl upgrade      # next release, then restart
sudo simplepoolctl uninstall    # --purge also deletes the ledger

What runs

Which commit is running

The build commit is compiled into the binary, so simplepool --version reports what is actually executing rather than what the source tree next to it currently says. A build from a tree with uncommitted changes says so on its own line, because in that case the commit printed above it does not describe the binary. The dashboard's /api/versions answers the same question for the whole stack — simplepool, the enforcer, Thunder, bitcoind — over plain HTTP with no auth.

What it can't do

Stated plainly, because a pool that only advertises its guarantees is telling you half the story.

• It cannot prove a miner hashed anything. It can only check the work it was shown. A rig that finds a block and drops it on the floor looks identical to an unlucky one on any individual sample — which is why the withholding audit is statistical, and why it needs an expectation of at least five blocks before it will say anything.
• In pps-classic the pool custodies BTC. Between mining a block and depositing into Thunder, the reward sits in a pool-controlled wallet. The design that avoided this — a drivechain deposit in the coinbase — does not work at the consensus level. This is a real trust assumption and it is not engineered away.
• Deposits are manual. An operator presses a button per deposit. If nobody does, the reserve runs dry and payouts skip with a logged warning until someone notices.
• An ambiguous crash needs a human. A crash between writing the in-flight rows and broadcasting leaves a state where "it was sent" and "it wasn't" are indistinguishable. The worker refuses to guess, halts, and says so.
• The Thunder payout fee is a flat 100 sats per batch for now, pending observable fee dynamics on that chain.
• Solo mode is solo. If your rig doesn't find the block, you earn nothing for that height. That is the design, not a shortfall.