Stratum server
Turn on the node's built-in stratum server, point miners at it, and mine solo; options, limits and protocol.
lotusd has a Stratum V1 mining server built in. Miners connect straight to the node; no proxy or separate pool program is needed. It is off by default.
Turn it on #
stratum=1
stratumlisten=0.0.0.0:3334:lotushash
stratumcoinbase=YOUR_LOTUS_ADDRESS
miningpublichost=node.example.orgRestart the node, then check:
curl -s http://127.0.0.1:10604/api/v1/mining/statuslotus-cli getstratuminfoconst r = await fetch('http://127.0.0.1:10604/api/v1/mining/status');
const status = await r.json(); // status.enabled, status.listeners-miningpublichost is the host name miners should use. It is shown on the node's How to mine page and in mining/status. Leave it unset when the stratum port is not reachable from outside.
Set -stratumcoinbase. Without a valid address the server still starts, with a warning in the log, and the reward of every block it finds is burnt. mining/status then reports payout: "burn".
Point a miner at it #
./lotus-miner-cli -g 0 -o YOUR_LOTUS_ADDRESS \
--stratum stratum+tcp://node.example.org:3334 \
--stratum-user YOUR_LOTUS_ADDRESS.rig1The worker name is <Lotus address>.<name>:
- The part before the first dot must be a Lotus address.
- The name after it keeps only letters, digits,
.,_and-, at most 64 bytes. - The password is ignored.
Who is paid depends on the mode. Without -poolpayouts, every block pays -stratumcoinbase, whatever the worker name. With -poolpayouts, blocks pay the miners' own addresses: see Pool.
Listeners and ports #
-stratumlisten=<bind>:<port>:<algo>[:<difficulty>] opens one port with one algorithm. Give it several times for several ports. When it is set, -stratumbind and -stratumport are ignored.
<algo> | Miners | Notes |
|---|---|---|
lotushash | GPU miners | Native LotusHash stratum. |
sha256d-auxpow (aliases sha256d, sha256) | Bitcoin ASICs | Standard Stratum V1 with version rolling. See Merged mining. |
scrypt-auxpow (aliases auxpow, scrypt) | Litecoin ASICs | Standard Stratum V1. See Merged mining. |
auto, dual | Legacy behaviour; auto is what -stratumport alone gives. |
| Port | Default |
|---|---|
Stratum (-stratumport) | 3334; Napoleon test network 20633 |
Browser miner WebSocket (-stratumwslisten without a port) | 3335; Napoleon test network 13335 |
Difficulty #
Share difficulty 1 is the target of compact bits 0x1d00ffff. A new session starts at -stratumdifficulty, or at the listener's own <difficulty>. Variable difficulty then moves each miner toward one share every -stratumvardifftarget seconds. A share target is never set harder than the block target.
Mine solo without stratum #
Two RPC routes exist for a miner that talks to the node directly.
The node builds the coinbase. getrawunsolvedblock "address" returns a serialized block candidate paying that address; submit the solved block with submitblock. This is what lotus-miner-cli -a <rpc url> does.
lotus-cli getrawunsolvedblock YOUR_LOTUS_ADDRESSYou build the coinbase. getblocktemplate returns the template. Its coinbasetxn object carries what your coinbase must contain:
| Key | Content |
|---|---|
minerfund | The outputs the coinbase must pay. |
coinbasetag | scriptPubKey and tag of the first output, and napoleon: whether the Napoleon rule applies. See Coinbase tag. |
utxocommitment | committed_height, muhash, scriptPubKey, segment. Present from Napoleon only. |
From Napoleon every block's coinbase must carry the UTXO set commitment. Copy coinbasetxn.utxocommitment.scriptPubKey as an output of your coinbase, or put segment in another eMPP output. A block without it is rejected. See UTXO commitment.
Protocol #
The LotusHash listener speaks these methods, one JSON message per line:
| Method | Direction |
|---|---|
mining.subscribe | miner to node |
mining.authorize | miner to node |
mining.set_difficulty | node to miner |
mining.notify | node to miner |
mining.submit | miner to node |
mining.set_extranonce | node to miner (pool mode) |
A Lotus header is 160 bytes, not 80, so mining.notify carries an eleventh parameter: an object with every field needed to build the header ("algo": "lotushash", "scheme": 1). The first ten parameters keep their usual positions.
- Extranonce1 is 4 bytes per session; extranonce2 is 4 bytes, chosen by the miner.
- With
-poolpayouts, extranonce1 is 8 bytes and commits to the payout address, so it is known only atmining.authorize. Sendmining.subscribeandmining.authorizetogether, or handlemining.set_extranonce. A client that ignores it has every share refused. mining.submittakes[worker, job id, extranonce2, ntime, nonce]: ntime is 12 hex characters, nonce 16, both little-endian as in the header.
| Error | Meaning |
|---|---|
[21, "Job not found"], [21, "Stale share"] | Unknown job, or the tip moved. |
[22, "Duplicate share"] | Already submitted on this session. |
[23, "Low difficulty share"] | Hash above the share target. |
[20, "Invalid share: ..."] | Malformed fields, or ntime out of range. |
[20, "Block rejected: ..."] | The share met the block target but the block was refused. |
The full wire format, the header layout, the merkle branch and a worked example are in doc/stratum-lotushash.md of the node's repository. test/functional/test_framework/lotushash_stratum.py is a reference client.
Operator commands #
These RPCs need RPC credentials. They are not on the public API.
| Command | What it does |
|---|---|
getstratuminfo | Listeners, per-algorithm totals, recent failed connections, limits. |
listminingworkers ( "algo" ) | Connected miners with their names, addresses and user agents. |
disconnectminingworker "worker" | Closes the sessions of a label, a name or #<session id>. |
getmergemineinfo | Parent work sources of the merged-mining listeners. |
The public routes GET /api/v1/mining/status, mining/workers, mining/blocks and mining/shares never carry a worker name or a miner's IP address. Workers appear as anonymous labels. See REST API.
Options #
| Option | Default | Meaning |
|---|---|---|
-stratum | 0 | Enable the server. |
-stratumbind=<addr> | 0.0.0.0 | Bind address, when -stratumlisten is not used. |
-stratumport=<port> | 3334 | Port, when -stratumlisten is not used. |
-stratumlisten=<spec> | none | A listener with its algorithm. Repeatable. |
-stratumcoinbase=<address> | none | Address paid by found blocks. |
-miningpublichost=<host> | none | Host shown to miners. |
-miningpublicworkers | 0 on mainnet | Publish per-miner rows, with anonymous labels, on the public API. |
-stratumdifficulty=<n> | 0.5 | Initial share difficulty. |
-stratumvardiff | 1 | Variable difficulty. |
-stratumvardifftarget=<n> | 15 | Target seconds between shares. |
-stratumvardiffretarget=<n> | 90 | Seconds between retarget checks. |
-stratumvardiffmin=<n> | 0.001 | Lowest difficulty vardiff may set. |
-stratumvardiffmax=<n> | 0 | Highest difficulty vardiff may set. 0 = no explicit limit. |
-stratummaxworkers=<n> | 1024 | Concurrent workers. |
-stratummaxperip=<n> | 64 | TCP sessions per source IP (IPv6: per /64). 0 = no limit. |
-stratumperipexempt=<subnet> | none | Subnet exempt from the per-IP cap. Repeatable. |
-stratummsgrate=<rate>[:<burst>] | 200:2000 | Requests per second per session. |
-stratumworkertimeout=<n> | 300 | Worker idle timeout, in seconds. |
-miningdb | 1 | Keep mining history in <datadir>/modules/mining.sqlite. |
If every miner reaches the node through one address, such as a NAT or a proxy, add that address to -stratumperipexempt. Otherwise only 64 miners can connect.
Browser miner listener #
These apply only with -stratum=1. See GPU miner.
| Option | Default | Meaning |
|---|---|---|
-stratumwslisten=<bind>[:<port>[:<diff>]] | none (off) | WebSocket stratum listener. Port 3335 when omitted; initial difficulty 0.005. |
-stratumwspath=<path> | /api/v1/mining/ws | Path the handshake must use. |
-stratumwspublicurl=<url> | none | Absolute ws:// or wss:// URL published in mining/status. |
-stratumwsorigin=<origin> | same host | Allowed Origin, or *. Repeatable. |
-stratumwstrustedproxy=<subnet> | 127.0.0.0/8, ::1/128 | Peers whose client-IP header is believed. |
-stratumwsmaxsessions=<n> | 256 | Browser sessions, counted apart from -stratummaxworkers. |
-stratumwsmaxperip=<n> | 4 | Browser sessions per client IP. |
-stratumwsmaxperaddress=<n> | 16 | Browser sessions per payout address. |
-stratumwsmindiff=<n> | 0.001 | Lowest share difficulty for browser sessions. |
