Merged mining
Mining12.4.15+

Merged mining

Mine Lotus with Bitcoin and Litecoin ASICs from Napoleon; proof kinds, work scaling, listeners, RPCs and what a pool operator must do.

Merged mining lets a machine that mines Bitcoin (SHA-256d) or Litecoin (Scrypt) prove Lotus blocks with the same work. The ASIC hashes its usual 80-byte parent header. When that hash is low enough, the header becomes the proof of a Lotus block.

Napoleon upgrade

Everything on this page applies on mainnet only from the Napoleon activation: median time past 1797886200, 21 December 2026 20:50 UTC. Before it, a mainnet block proven by a parent header is invalid and the node judges every block as before. The Napoleon test network has the rules active from its start. See Napoleon.

How it works #

A Lotus block proven this way carries one metadata field with the parent header and the proof that the parent's coinbase commits to this Lotus block. There is one difficulty track: the block gets the same chain work as any block of its nBits. On mainnet the difficulty adjustment itself does not change at Napoleon.

Work scaling #

The parent hash must be at most target(nBits) / M. M is a consensus constant per algorithm, set so that one reference ASIC counts like one GPU.

Parent algorithmM
SHA-256d (Bitcoin)181,000
Scrypt (Litecoin)5

Proof kinds #

FieldParent hashCommitment in the parent coinbaseName in reports
1ScryptClassic 44-byte merged-mining tagtag
2SHA-256dClassic tagtag
3ScryptPositional anchorcompact or wide anchor
4SHA-256dPositional anchorcompact or wide anchor

The tag is the usual merged-mining commitment: fabe6d6d, a merkle root, the tree size and a nonce. The Lotus chain ID is 76 (0x4C); it fixes the slot of Lotus in a pool's merged-mining tree.

The positional anchor is for mining behind an existing Bitcoin or Litecoin pool, where you cannot change the pool's coinbase. The node writes a few bytes of a slow hash of the Lotus block into the extranonce area the pool leaves free. An anchor is at least 8 bytes. Reports call it compact below 16 bytes and wide from 16.

A parent header proves at most one Lotus block. For anchors, the parent's time must be later than the previous Lotus block's median time past and at most 2 hours after the Lotus block's own time.

Mine with ASICs on a node #

The node's stratum server speaks standard Stratum V1 to the machines. Open one listener per algorithm:

Config
stratum=1
stratumlisten=0.0.0.0:3336:sha256d-auxpow
stratumlisten=0.0.0.0:3337:scrypt-auxpow
stratumcoinbase=YOUR_LOTUS_ADDRESS

The port numbers are yours to choose. Then tell the node where the parent work comes from, per algorithm. The first configured wins:

SourceOptionWhat happens
An upstream pool-miningpool=<algo>:stratum+tcp://host:port:<account>[:<password>]The node is a proxy in front of the pool. Every share that meets the pool's difficulty is forwarded. A share that also meets the Lotus target / M becomes a Lotus block.
A parent node-miningparent=<algo>:rpc://user:password@host:port with -miningparentscript=<algo>:<hex scriptPubKey>The node builds the parent coinbase with the tag, and submits the parent block when a share meets the parent target.
NothingA synthetic parent: the machines mine Lotus only.

<algo> is sha256d or scrypt. Point each ASIC at stratum+tcp://<node>:<port>.

Behind a pool: the extranonce grant #

The anchor goes into the extranonce2 bytes the pool grants, after the bytes left to each ASIC (-miningpoolminerbytes, 2 by default). The pool must therefore grant at least the miner's bytes plus 8. A pool that grants fewer cannot be used this way: the node marks it down and tells the miner why. Use the classic tag over RPC for such pools.

Each miner with its own pool account #

With -miningpoolperminer=1 each ASIC names its own Bitcoin or Litecoin pool, and its parent work is credited to its own account there:

ASIC settingValue
URLstratum+tcp://<node>:<listener port>
Worker<Lotus address>.<rig>
PasswordA base64url pool list, or x to use the operator's -miningpool

The node's How to mine page generates the password in the browser. Decoded, it is compact JSON:

JSON
{"v":1,"pools":[{"url":"stratum+tcp://ltc.example.com:3333","user":"alice.l7","pass":"x","priority":0}]}

It holds 1 to 8 pools, tried in priority order. When a pool fails, the session moves to the next one without being dropped.

Who is paid #

  • Without -poolpayouts, every Lotus block pays -stratumcoinbase. The worker name is free text.
  • With -poolpayouts, the part of the worker name before the first dot is the miner's Lotus address, and ASIC work is credited in the pool's window at its Lotus-equivalent weight. See Pool.
Warning

With -poolpayouts, work from a miner that gives no valid Lotus address still counts, and its share of every pool block is burnt.

Add Lotus to existing pool software #

Pool software that already merge-mines other chains can use the RPC interface. It supports the classic tag only; anchors come only from the node's own stratum server.

Shell
lotus-cli createauxblock YOUR_LOTUS_ADDRESS sha256d

lotus-cli submitauxblock HASH AUXPOW_HEX
RPCUse
createauxblock "address" ( "algo" )Returns the block to commit to. algo is scrypt or sha256d.
submitauxblock "hash" "auxpow" ( "kind" )Submits the serialized proof. Without kind the parent algorithm is detected.
getauxblockWithout arguments: a template paying -auxpowaddress. With "hash" "auxpow": submit, answers true or false. With "address" ( "algo" ): same as createauxblock.

The template looks like this:

JSON
{
  "hash": "0000abc...def",
  "chainid": 76,
  "previousblockhash": "000059a...",
  "coinbasevalue": 1000000000,
  "bits": "1d00ffff",
  "height": 830421,
  "target": "00000000000001aa3f...",
  "multiplier": 181000,
  "algo": "sha256d"
}

target is the bound the parent hash must meet, already divided by multiplier. The same template is returned to the same address and algorithm while the tip holds and the mempool is unchanged, or the template is younger than 60 s. A parent coinbase serialized with its witness is accepted.

What a pool operator must do #

  1. Run a node at a version that includes Napoleon, synced, before the activation. See Upgrade.
  2. Choose the route: the node's ASIC listeners, or createauxblock and submitauxblock from your own pool software.
  3. With your own pool software, check that chain ID 76 is free in your merged-mining tree, and set -auxpowalgo=sha256d on the node if you are a Bitcoin pool.
  4. With the ASIC listeners behind an upstream pool, check that the pool grants enough extranonce2 bytes for the anchor.
  5. Set -stratumcoinbase, or -auxpowaddress for getauxblock without arguments. A listener without a payout address burns the reward.
  6. Test on a test network first. Before Napoleon, nothing mined this way is valid on mainnet.

See what is mined #

getblock reports powalgo (lotushash, scrypt, sha256d), prooffield (0 to 4), auxparent and, for anchors, anchorbytes. getmininginfo reports mmv2active, mmv2activationtime and each algorithm's multiplier. The dashboard has an ASIC and merged mining view, and GET /api/v1/mining/proofs/<hash> returns the decoded proof of a block.

Reject reasonCause
high-hashParent hash above target / M.
bad-auxpow-chainidThe parent header's version carries chain ID 76.
bad-auxpow-commitmentThe tag does not commit to this block.
bad-auxpow-parent-reusedThe parent header already proves an ancestor.
bad-auxpow-anchor-notfreshParent time not after the previous block's median time past.
bad-auxpow-anchor-timetoonewParent time more than 2 hours after the block's own time.
bad-metadata-inactiveA proof where the rules are not active.

Options #

OptionDefaultMeaning
-stratumlisten=<bind>:<port>:<algo>[:<difficulty>]nonesha256d-auxpow or scrypt-auxpow for ASICs.
-miningpool=<spec>noneUpstream pool of one algorithm.
-miningpoolminerbytes=<n>2Extranonce2 bytes left to each ASIC, 2 to 8.
-miningpoolpassthrough0Each ASIC authorizes upstream with its own name and password.
-miningpoolperminer0Each ASIC names its own pool in its password.
-miningpoolperminerfallback1A miner that names no pool uses the -miningpool entry.
-miningparent=<spec>, -miningparentscript=<spec>noneParent node over RPC and its payout script.
-miningmaxsessions=<n>256Open sessions on the ASIC listeners together.
-miningmaxsessionsperip=<n>128Sessions from one IP address. Raise it for a farm behind one address.
-auxpowaddress=<address>noneAddress paid by getauxblock without arguments.
-auxpowalgo=<algo>scryptDefault algorithm of the RPC templates: scrypt or sha256d.

Pool credentials in lotus.conf are sensitive: keep the file readable by its owner only.

Source share/www/docs/merged-mining.md in the lotusd repository
Checked against doc/auxpow.md doc/auxpow-btc-ltc.md doc/asic-merged-mining.md src/chainparams.cpp src/rpc/mining.cpp src/stratum/stratumconfig.cpp src/stratum/parentjob.cpp src/init.cpp