Skip to content

Full reference docs, plus four fixes found writing them - #86

Merged
rsantacroce merged 6 commits into
mainfrom
docs/reference-and-fixes
Sep 29, 2026
Merged

rsantacroce merged 6 commits into
mainfrom
docs/reference-and-fixes

Conversation

@rsantacroce

Copy link
Copy Markdown
Collaborator

Rewrites docs/simplepool.html into a complete reference, and fixes the problems that turned up while checking it against the source.

Needs operator action

  • Dashboard now listens on loopback by default (DASHBOARD_BIND=127.0.0.1). Nothing changes behind nginx. A server that serves the dashboard directly on :8081 needs Environment=DASHBOARD_BIND=0.0.0.0 in its systemd drop-in before it is upgraded or redeployed. deploy-to-server.sh re-renders the unit from the template, so without that line the dashboard stops answering on :8081. install.sh sets the right value itself (loopback with nginx, 0.0.0.0 with --no-nginx), and the Docker image sets 0.0.0.0 inside the container.

Changes miner payouts

  • pplns-thunder / pplns-btc: a fee under the dust limit is no longer deducted. When a block's fee_bps came to less than 546 sats, the coinbase had no fee output, so the pool wallet received the whole reward. The distributor still took fee_bps off before crediting miners, so the difference stayed in the pool wallet, credited to no one. It now applies the coinbase's dust rule. This only affects blocks under about 546 × 10000 / fee_bps sats (54,600 at 1%).

Fixes

  • An eighth listener line is now a config error. listen_port takes one of the eight port slots, so only seven extra ports can be bound. An eighth used to load without error and then silently not be bound.
  • install.sh --help no longer says --pps-sats-per-diff defaults to 1000; it defaults to unset, so the rate is derived per template. The installer also warns when the flag is passed.
  • schema.sql documents why the unique blocks_found(hash) index is created by the proxy at startup and not in this file. It also fixes the events_lost comment, which called a counter unix seconds.

Docs

docs/simplepool.html now covers everything below, all checked against the source:

  • every proxy.conf key with its default, allowed values and failure behaviour; the listener sub-keys; what each mode requires; removed keys; command-line flags and exit codes
  • every environment variable for the payout, dashboard and slipstream services
  • the stratum protocol as implemented: methods, notifications, the order submits are checked in, error codes, username rules, d=<n>, vardiff
  • the coinbase layout, byte by byte and per mode
  • ports, all HTTP APIs, Redis channels and upstream RPC calls
  • the full database schema and how a block's status moves
  • hard limits, and build/release/tests

It also corrects stale claims: extranonce1 is no longer XORed with the clock, the stratum password is read for d=<n>, the stat card now says five modes, and a CSS fix stops the page scrolling sideways on phones. The generated sequence diagrams are unchanged, and sequence-diagrams.py --check passes.

CHANGELOG.md has an Unreleased section with the two call-outs above.

Testing

  • make test: all 11 C suites pass. New tests:
    • test_config: 7 listeners load, 8 are refused
    • test_store: a dust-sized fee is not deducted (fails on the old code), and a real fee still is
  • npm test in dashboard/: 189 pass, 2 skipped
  • Started the dashboard with and without DASHBOARD_BIND and checked with lsof that it listens on 127.0.0.1 by default and on * with DASHBOARD_BIND=0.0.0.0.
  • Checked the page at desktop and phone widths: no sideways scrolling at 390px, and every internal link resolves.

Local knowledge-graph output, built per machine; not part of the project.
The server has eight port slots and listen_port takes the first, so only
seven listener lines can be bound. An eighth loaded cleanly and was then
silently dropped: a port the operator configured, advertised and
firewalled, with nothing listening on it. It is now a config error naming
the limit.
When fee_bps of a block came to less than the 546-sat dust limit, the
coinbase dropped the operator output and the pool wallet received the
whole reward, but store_pplns_distribute still took fee_bps off before
crediting miners. The difference sat in the pool wallet credited to
nobody. The distributor now applies the coinbase's dust rule.

Affects pplns-thunder and pplns-btc blocks under ~546*10000/fee_bps sats
(54,600 at 1%). stratum.c's copy of the rule now uses COINBASE_DUST_SATS
instead of a literal.
blocks_found_hash_idx is created by the proxy at startup, after collapsing
duplicate rows, and cannot live here: install.sh applies this file under
set -e on every upgrade, where a UNIQUE index over an old database with
duplicates would abort the upgrade half-done, and this file must not
delete rows from a possibly live shares.db. Also fix the events_lost
comment, which called a counter unix seconds.
The dashboard bound every interface while the installer and docs said it
was loopback behind nginx. /admin is HTTP Basic auth, which must not be
reachable in the clear. DASHBOARD_BIND now defaults to 127.0.0.1, like the
payout and slipstream services.

install.sh sets loopback when nginx fronts it and 0.0.0.0 with
--no-nginx; the Docker image sets 0.0.0.0 inside the container. A server
reached directly on :8081 needs DASHBOARD_BIND=0.0.0.0 in its drop-in
before upgrading.

install.sh also stops claiming --pps-sats-per-diff defaults to 1000 (it
defaults to unset, derived per template) and warns when it is passed.
Adds every proxy.conf key and service environment variable with defaults
and validation, the stratum protocol as implemented, the coinbase layout,
ports, HTTP APIs and Redis channels, the full schema, hard limits, and
build/release/tests, all taken from source.

Fixes claims that had gone stale: extranonce1 is no longer XORed with the
clock, the stratum password is read for d=<n>, there are five modes not
two, and the page no longer scrolls sideways on a phone. CHANGELOG gains
an Unreleased section.
@rsantacroce
rsantacroce merged commit 7f24b9f into main Sep 29, 2026
8 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant