Stratum server
Mining12.4.15+

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 #

Config
stratum=1
stratumlisten=0.0.0.0:3334:lotushash
stratumcoinbase=YOUR_LOTUS_ADDRESS
miningpublichost=node.example.org

Restart the node, then check:

Shell
curl -s http://127.0.0.1:10604/api/v1/mining/status

-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.

Warning

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 #

Shell
./lotus-miner-cli -g 0 -o YOUR_LOTUS_ADDRESS \
  --stratum stratum+tcp://node.example.org:3334 \
  --stratum-user YOUR_LOTUS_ADDRESS.rig1

The 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>MinersNotes
lotushashGPU minersNative LotusHash stratum.
sha256d-auxpow (aliases sha256d, sha256)Bitcoin ASICsStandard Stratum V1 with version rolling. See Merged mining.
scrypt-auxpow (aliases auxpow, scrypt)Litecoin ASICsStandard Stratum V1. See Merged mining.
auto, dualLegacy behaviour; auto is what -stratumport alone gives.
PortDefault
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.

Shell
lotus-cli getrawunsolvedblock YOUR_LOTUS_ADDRESS

You build the coinbase. getblocktemplate returns the template. Its coinbasetxn object carries what your coinbase must contain:

KeyContent
minerfundThe outputs the coinbase must pay.
coinbasetagscriptPubKey and tag of the first output, and napoleon: whether the Napoleon rule applies. See Coinbase tag.
utxocommitmentcommitted_height, muhash, scriptPubKey, segment. Present from Napoleon only.
Napoleon upgrade

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:

MethodDirection
mining.subscribeminer to node
mining.authorizeminer to node
mining.set_difficultynode to miner
mining.notifynode to miner
mining.submitminer to node
mining.set_extranoncenode 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 at mining.authorize. Send mining.subscribe and mining.authorize together, or handle mining.set_extranonce. A client that ignores it has every share refused.
  • mining.submit takes [worker, job id, extranonce2, ntime, nonce]: ntime is 12 hex characters, nonce 16, both little-endian as in the header.
ErrorMeaning
[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.

CommandWhat it does
getstratuminfoListeners, 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>.
getmergemineinfoParent 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 #

OptionDefaultMeaning
-stratum0Enable the server.
-stratumbind=<addr>0.0.0.0Bind address, when -stratumlisten is not used.
-stratumport=<port>3334Port, when -stratumlisten is not used.
-stratumlisten=<spec>noneA listener with its algorithm. Repeatable.
-stratumcoinbase=<address>noneAddress paid by found blocks.
-miningpublichost=<host>noneHost shown to miners.
-miningpublicworkers0 on mainnetPublish per-miner rows, with anonymous labels, on the public API.
-stratumdifficulty=<n>0.5Initial share difficulty.
-stratumvardiff1Variable difficulty.
-stratumvardifftarget=<n>15Target seconds between shares.
-stratumvardiffretarget=<n>90Seconds between retarget checks.
-stratumvardiffmin=<n>0.001Lowest difficulty vardiff may set.
-stratumvardiffmax=<n>0Highest difficulty vardiff may set. 0 = no explicit limit.
-stratummaxworkers=<n>1024Concurrent workers.
-stratummaxperip=<n>64TCP sessions per source IP (IPv6: per /64). 0 = no limit.
-stratumperipexempt=<subnet>noneSubnet exempt from the per-IP cap. Repeatable.
-stratummsgrate=<rate>[:<burst>]200:2000Requests per second per session.
-stratumworkertimeout=<n>300Worker idle timeout, in seconds.
-miningdb1Keep mining history in <datadir>/modules/mining.sqlite.
Note

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.

OptionDefaultMeaning
-stratumwslisten=<bind>[:<port>[:<diff>]]none (off)WebSocket stratum listener. Port 3335 when omitted; initial difficulty 0.005.
-stratumwspath=<path>/api/v1/mining/wsPath the handshake must use.
-stratumwspublicurl=<url>noneAbsolute ws:// or wss:// URL published in mining/status.
-stratumwsorigin=<origin>same hostAllowed Origin, or *. Repeatable.
-stratumwstrustedproxy=<subnet>127.0.0.0/8, ::1/128Peers whose client-IP header is believed.
-stratumwsmaxsessions=<n>256Browser sessions, counted apart from -stratummaxworkers.
-stratumwsmaxperip=<n>4Browser sessions per client IP.
-stratumwsmaxperaddress=<n>16Browser sessions per payout address.
-stratumwsmindiff=<n>0.001Lowest share difficulty for browser sessions.
Source share/www/docs/stratum.md in the lotusd repository
Checked against src/stratum/stratumconfig.cpp src/stratum/stratumconfig.h src/chainparamsbase.cpp src/rpc/mining.cpp doc/stratum.md doc/stratum-lotushash.md doc/mining-dashboard.md doc/browser-miner.md