Pool
How the node's pool pays miners directly in the coinbase, the POOL record it writes on chain, its options, its public API and its dashboard page.
The pool is part of the node. With -poolpayouts, the blocks found through the node's stratum server pay every miner directly, as outputs of the block's own coinbase. There is no pool wallet, no withdrawal and no account: the block is the payment.
None of this is a consensus rule. A pool block is an ordinary block whose coinbase has more outputs.
For miners #
- Mine with your Lotus address as the stratum user:
<Lotus address>.<name>. See Mine Lotus. - Open the Pool page of the node you mine on.
- Find your address under Miners: hashrate, share of the window, what is owed and what was paid.
What to expect:
- Scheme. PPLNS: your part of a block is your part of the recent work, measured over a window of shares. By default the window is 4 times the network difficulty.
- Minimum payout. A balance below
-poolminpayout(1 XPI by default) is not paid in this block. It carries over and is paid in a later one. - Fee.
-poolfeebps, 0 by default. The page shows the value in force. - Maturity. A payout is a coinbase output: spendable after 100 blocks. If the block is orphaned, its credits and payments are reversed.
- Accepted addresses. Pay-to-public-key-hash, pay-to-script-hash and Taproot addresses. Another script type is refused at login with "unsupported payout script type".
Carried-over balances are backed by future pool blocks, not by funds held somewhere. If the pool stops finding blocks, pending balances are not paid. The Balances view shows the total.
How a block is split #
reward = subsidy + half of the fees
fund = the miner-fund outputs
burn = floor(subsidy * poolburnbps / 10000)
R = reward - fund - burn distributed to payees
fee = floor(R * poolfeebps / 10000)
R_miners = R - feeEach address is entitled to R_miners times its weight in the window, in whole satoshis. The node keeps a ledger per address: entitlements credited, minus amounts actually paid on chain. A block pays the largest balances first, at most -poolmaxpayees outputs.
Every node of the pool rebuilds the same ledger from the chain and from the shares the block commits to, so they agree on what is owed.
The POOL record #
Each pool block describes itself in its coinbase, in one or two OP_RETURN outputs using the eMPP envelope with the id POOL. The record holds:
- the pool id (
-poolid,FRENCHBTCby default) and the id of the node that found the block; - a commitment to the share window, with its number of shares and its weight;
- the pool hashrate, the fee and the burn, in basis points;
- for each payee output described: its share of the window and its hashrate.
Addresses and amounts are not repeated: they are the outputs themselves. The record outputs also carry the burn, which is -poolburnbps of the block subsidy (1 basis point by default).
Decode the record of any block:
curl -s http://127.0.0.1:10604/api/v1/pool-public/record/BLOCK_HASHlotus-cli decodepoolrecord BLOCK_HASHconst r = await fetch('/api/v1/pool-public/record/' + blockHash);
const record = await r.json();The Decode view does the same in the browser, and contrib/pool/decode_pool_record.py in the repository is a standalone decoder.
Public API #
All routes are GET, under /api/v1/pool-public/. They give data per address, never worker names or IP addresses. List routes take limit (at most 500).
| Route | Returns |
|---|---|
summary | Pool hashrate, miners, fee, burn, blocks found, effort, luck, pending total, agreement between pool nodes. |
miners | Per address: hashrate, share of the window, owed, total paid, last share. |
miner/<address> | One address: history, payouts and hashrate series. |
next | The split of the block being mined now: payees, amounts, burn, fund. |
blocks | Pool blocks with status, effort and payouts. |
block/<hash> | One pool block: payout outputs and the decoded record. |
record/<hash> | The decoded record of any block, pool block or not. |
balances | Pending balances below the minimum payout. |
hashrate | Time series, for the pool or one address. |
curl -s http://127.0.0.1:10604/api/v1/pool-public/summarySee REST API and the node's OpenAPI document.
The Pool page #
The dashboard's Pool tab shows this node's stratum server and, when pool payouts are on, the pool views:
Overview, How to mine, ASIC and merged mining, Miners, Blocks, Balances, Mine in your browser and Decode.
Run a pool node #
A pool is a set of nodes that trust each other. They exchange shares over the P2P network, only with the peers listed in -trustedblocksource, and every share is verified by its proof of work.
stratum=1
stratumlisten=0.0.0.0:3334:lotushash
stratumcoinbase=YOUR_LOTUS_ADDRESS
poolpayouts=1
poolnodeid=1
trustedblocksource=IP_OF_ANOTHER_POOL_NODE
poolstratumurl=stratum+tcp://node.example.org:3334Rules to respect:
-poolnodeidis required, from 0 to 255, and unique per node.- The pool id, fee, fee address, burn, window and payout options must be identical on every node of the pool. Nodes with a different configuration do not pair.
-poolfeebpsabove 0 requires a valid-poolfeeaddress, or the node refuses to start.-stratumcoinbaseis paid when the window is empty, for example on a new pool.- The node refuses to start with
-poolpayoutstogether with-sharechain, with the miner fund disabled, or with-datacarrier=0.
Check the state with lotus-cli getpoolinfo.
Options #
| Option | Default | Meaning |
|---|---|---|
-poolpayouts | 0 | Pay every miner of the window in the coinbase and write the POOL record. |
-poolid=<id> | FRENCHBTC | Pool id in the record, 1 to 16 letters or digits. |
-poolnodeid=<n> | none, required | This node's id, 0 to 255. |
-poolpplnswindow=<tenths> | 40 | Window in tenths of the network difficulty, 10 to 200. 40 = 4.0 times. |
-poolpplnsmaxshares=<n> | 20000 | Most shares in a window, 100 to 100000. |
-poolminpayout=<amount> | 1 XPI | Smallest balance paid in a coinbase. |
-poolmaxpayees=<n> | 92 | Most payee outputs per coinbase, 1 to 2000. |
-poolfeebps=<n> | 0 | Pool fee in basis points, 0 to 1000, paid to -poolfeeaddress. |
-poolfeeaddress=<address> | none | Address receiving the fee. |
-poolburnbps=<n> | 1 | Burn, in basis points of the block subsidy, 0 to 100. |
-poolrecordmaxbytes=<n> | 223 | Largest record output script, 100 to 8005. |
-poolrefreshsec=<n> | 30 | Rebuild the job this often when the split changed. 0 = only on a new tip. |
-poolsettletimeout=<n> | 600 | Seconds to wait for a block's shares before settling it degraded. |
-poolownertimeout=<n> | 600 | Seconds a block with our pool id waits for its proof before it is treated as a spoof. |
-poolretentiondays=<n> | 30 | Days of shares, jobs and sessions kept in pool.sqlite. 0 = keep everything. |
-poolstratumurl=<url> | none | Public stratum URL printed on the Pool page. Repeatable, at most 4. |
-poolblockpush | 1 | Push the blocks the pool finds to every pool peer at once. |
The pool's data is in <datadir>/modules/pool.sqlite.
Before Napoleon the record may use 2 outputs, which describes up to 92 payees with the default pool id; payees beyond that are still paid. From Napoleon the record may use up to 16 outputs, 820 payees.
Operator commands #
| RPC | What it does |
|---|---|
getpoolinfo | Configuration, ledger digest, pending total, share and job counts, pool peers, the last payout plan. |
getpoolshares | The most recent shares in memory. |
getpoolpayouts | Pool blocks with their payout outputs. |
decodepoolrecord | Decodes the record of a block. |
Related features #
- External stratum coordinator.
-poolnngbridge(default 0) lets a stratum program on the same host get pool templates over the node's NNG interface and report the shares it accepts. They are verified and credited like native shares. It needs-poolpayoutsand-nngrpc. - Block hold. With
-trustedblocksource, a block from a peer outside the pool waits-untrustedblockdelayminutes (default 5) before it is validated.-adaptivehold(default 0) sets that wait at run time from the pool's measured share of the hashrate. - ASIC work. From Napoleon, work from the merged-mining listeners is credited in the same window at its Lotus-equivalent weight. See Merged mining.
