Coinbase tag (OP_RETURN tag + height)
Protocol and consensus12.4.15+

Coinbase tag (OP_RETURN tag + height)

The OP_RETURN tag and height every coinbase carries in its first output, and the rules the node applies to it.

Every Lotus block's coinbase transaction carries, in its first output (vout[0]), a zero-value OP_RETURN <tag> <height> script. Lotus transaction ids do not cover the input script (since Malfix), so this height is what makes two coinbase txids differ. Without it, a miner could repeat a coinbase and overwrite the unspent outputs of the earlier one (CVE-2012-1909). The tag is traditionally logos. This is a consensus rule enforced in block validation, unlike the indexer modules. From 12.4.5 a node can also choose the tag it writes in the blocks it builds (-coinbasetag). The full upstream history of the rule, version by version, is in doc/upstream-logos-rule.md. This page documents what our code does.

Status in this node #

ItemValue
KindConsensus rule (block validity), not an indexer module. No SQLite table, no module entry in /api/v1/modules.
EnforcedAlways, for every block at height ≥ 20,000, and for every block once Napoleon is active (src/validation.cpp:4604-4613)
Napoleon gatepindexPrev->GetMedianTimePast() >= napoleonActivationTime (src/consensus/activation.cpp:117-125). Mainnet 1797886200 = 2026-12-21 20:50 UTC (src/chainparams.cpp:136). Testnet is 21 days earlier (src/chainparams.cpp:276, :317-319). Can be overridden with -napoleonactivationtime.
Miner-side flags-coinbasetag=<tag> (default logos), -coinbasetagafternapoleon (default 0) (src/init.cpp:1664-1685, src/miner.h:71-77)
Old namesNapoleon is upstream's Second Kings (renamed in 12.4.12, same rules). -coinbasetagaftersecondkings and getmininginfo coinbasetag.secondkings / .aftersecondkings remain as deprecated aliases until 12.4.13. <!-- rename-napoleon: keep -->
Data filenone

Envelope #

Text
coinbase vout[0].scriptPubKey = OP_RETURN <tag push> <height push> [anything]
coinbase vout[0].nValue       = 0   (what our miner writes; not a consensus check)
coinbase vin[0].scriptSig     = OP_0 OP_0   (what our miner writes; only the 2..100 byte length rule applies)

Only vout[0] is checked. The tag is an ASCII alphanumeric word (from Napoleon _ is allowed too, e.g. FRENCH_BTC). The height is the block height as a script number. Our miner builds it as CScript() << OP_RETURN << tag << nHeight (src/miner.cpp:108-111).

Byte layout #

Before Napoleon (a hand-written byte parser, src/validation.cpp:4517-4550):

OffsetSizeTypeEndiannessFieldNotes
01opcoden/aOP_RETURN = 0x6arequired
11uint8n/atag lengthmust be exactly 0x05. The byte is read as a raw length, so in practice it must be a direct push.
25ASCIIn/atagletters and digits only ([0-9A-Za-z]); logos = 6c 6f 67 6f 73
71uint8n/aheight length0..3. The byte is read as a raw length.
81..3uintlittle-endianheightunsigned, must equal the block height. Non-minimal encodings are accepted.
8 + nanybytesn/atrailing dataignored

From Napoleon (an opcode parser, src/validation.cpp:4504-4516):

OffsetSizeTypeEndiannessFieldNotes
01opcoden/aOP_RETURNrequired
1varpushpush-length LEtagany push opcode up to OP_PUSHDATA4 (direct, PUSHDATA1/2/4, minimal or not); data must be ≥ 1 byte, letters, digits and _ (_ from 12.4.13), any length
after tagvarscript numberlittle-endian, minimalheightmust be byte-for-byte CScript() << nHeight (minimal push, CScriptNum encoding)
after heightanybytesn/atrailing dataignored

Versioning: there is no version field. The rule changes by activation (Napoleon), as shown in the two tables.

Validation rules #

  1. Not checked for genesis (nHeight > 0) or for blocks below height 20,000 before Napoleon (src/validation.cpp:4604-4608). Otherwise IsValidCoinbaseHeightScript(vout[0].scriptPubKey, nHeight, napoleon) must hold, or the block is invalid with bad-cb-height (BLOCK_CONSENSUS) (src/validation.cpp:4611).
  2. Tag alphabet: non-empty; before Napoleon every byte in 0-9, A-Z, a-z (IsCoinbaseTag); from Napoleon (12.4.13) those and _ (IsNapoleonCoinbaseTag, e.g. the fleet's FRENCH_BTC).
  3. Before Napoleon: byte 0 must be OP_RETURN and the script must be at least 2 bytes (src/validation.cpp:4527).
  4. Before Napoleon: the tag-length byte must equal COINBASE_PREFIX.size() = 5, and the tag must fit in the script (src/validation.cpp:4531; COINBASE_PREFIX at src/consensus/consensus.h:29).
  5. Before Napoleon: a height-length byte must follow the tag (src/validation.cpp:4539). It must be ≤ 3 and fit in the script (src/validation.cpp:4543).
  6. Before Napoleon: the height bytes, read as an unsigned little-endian integer, must equal nHeight (src/validation.cpp:4550).
  7. From Napoleon: the first opcode must be OP_RETURN. The second must be a push (op <= OP_PUSHDATA4) whose data passes rule 2. The bytes that follow must start with exactly CScript() << nHeight (src/validation.cpp:4512-4515).
  8. From Napoleon (separate check in ConnectBlock): if any output of the coinbase would overwrite a coin that is still unspent in the UTXO view, the block is invalid with bad-txns-BIP30 (src/validation.cpp:1953-1962).
  9. Miner side, not consensus: -coinbasetag must be 1..32 ASCII letters, digits or _, or the node refuses to start (CheckCoinbaseTagOption, src/miner.cpp:83-101; startup check src/init.cpp:3013-3027). -nocoinbasetag means logos (src/miner.cpp:151).
  10. Miner-side selection for each block (SelectCoinbaseTag, src/miner.cpp:113-147). It uses logos (reason=default) unless the configured tag is allowed: before Napoleon only with exactly 5 characters (otherwise pre-napoleon-needs-5-chars, :124); after Napoleon only with -coinbasetagafternapoleon=1 (otherwise after-napoleon-not-enabled, :127). Where consensus checks the coinbase (from height 20,000 or Napoleon), the script is also self-checked with IsValidCoinbaseHeightScript, and it falls back to logos (self-check-failed, :143) if it would not pass.

Tests: src/test/validation_block_tests.cpp (coinbase_height_napoleon_gate :412, coinbase_tag_before_napoleon :509, coinbase_never_overwrites_unspent_outputs :560), src/test/coinbasetag_tests.cpp (8 cases), test/functional/mining_coinbase_tag.py.

Indexing #

N/A as a dedicated index: no module parses the tag and no SQLite table stores it. The coinbase is indexed like any transaction by the explorer index. Its vout[0] is an OP_RETURN output without an address (src/api/tx_handler.cpp:449). The eMPP indexer scans coinbase outputs too, but a coinbase tag never starts with OP_RETURN OP_RESERVED, so it produces no eMPP row.

Reorgs: nothing to undo. It is a stateless validity check.

REST API #

No dedicated route. Ways to see the tag:

Method and pathWhat it shows
GET /api/v1/rpc/getmininginfocoinbasetag: {configured, afternapoleon, napoleon, nextheight, next, reason}: the tag the next block built by this node will carry, and why (src/rpc/mining.cpp:580-597). getmininginfo is on the read-only legacy RPC allowlist (src/api/legacy_rpc_handler.cpp:67). Not cached (route TTL 0).
getblocktemplate (authenticated JSON-RPC)coinbasetxn.coinbasetag: {scriptPubKey, tag, napoleon}: the vout[0] script of the template's own coinbase, its tag, and whether the template's height is under the Napoleon rule. A pool that builds its own coinbase copies scriptPubKey (zero value) and stays valid on both sides of the activation: before it the tag must be exactly 5 characters, after it the height must be the minimal push.
GET /api/v1/txs/{coinbase txid}the raw outputs of the coinbase. The tag is the vout[0] script. Cache TTL 15 s. Unverified: exact field names of the script in this response.

Dashboard #

No dedicated tab. The tag shows only as the first output (OP_RETURN, no address) of the coinbase on the transaction detail page (/dashboard/tx/{txid}).

Limits and edge cases #

  • Before Napoleon the tag length is exactly 5. A PUSHDATA1 tag (6a 4c 05 ...) fails, because 0x4c is read as length 76.
  • Before Napoleon a non-minimal height (e.g. 04 90 05 10 00) fails the height_len > 3 check when 4 bytes long. A 2-byte non-minimal encoding of a 1-byte height would pass.
  • Between heights 1 and 19,999 (before Napoleon) the coinbase script is not checked at all.
  • From Napoleon the miner-side maximum is 32 characters (MAX_COINBASE_TAG_LENGTH, src/miner.h:74). Consensus has no upper bound other than script size.
  • getblocktemplate does not build the coinbase output: external pool software writes the tag and must follow the same rule.
  • ContextualCheckBlock is skipped by -reindex-chainstate (comment above src/validation.cpp:4481).

Differences from upstream / eCash spec #

eCash has no such rule (it uses BIP34 in the scriptSig). Upstream Lotus differences, in short (details and sources in doc/upstream-logos-rule.md):

CaseUpstream v8.3.4 to v11.5.1, and v12 before NapoleonUpstream v12 after NapoleonOurs before NapoleonOurs after Napoleon
logos + correct heightacceptacceptacceptaccept
other 5-char alphanumeric tag + height (height ≥ 1,018,000)acceptrefuseacceptaccept
other tag, no or wrong height (height ≥ 1,018,000)accept, height not checkedrefuserefuserefuse
tag of a length other than 5accept (from 1,018,000)refuserefuseaccept
PUSHDATA1 tag pushrefuserefuserefuseaccept
coinbase overwriting an unspent coinno check (possible from 1,018,000)no check (mandatory height prevents it)no check (mandatory height prevents it)bad-txns-BIP30

Consequence: after Napoleon we accept a superset of upstream v12. A block with a tag other than logos mined by a third party would be accepted by us and rejected by v12 (bad-cb-height), a chain split. This is why -coinbasetagafternapoleon defaults to off and prints a startup warning when enabled (src/init.cpp:3028-3040).

Worked example #

Unverified: the public node lotus-127.givelotus.org answered 503 node_warming_up when this page was written, so no mainnet coinbase was fetched. The example is built from the rule and matches what our miner writes (CScript() << OP_RETURN << "logos" << 1050000) for a block at height 1,050,000 (0x100590):

Text
6a 05 6c6f676f73 03 900510
OffsetBytesMeaning
06aOP_RETURN
105direct push of 5 bytes (tag length)
26c 6f 67 6f 73logos
703direct push of 3 bytes (height length)
890 05 10height, little-endian: 0x100590 = 1,050,000

Before Napoleon: tag length 5, alphanumeric, height length 3, value 1,050,000, so valid. After Napoleon: the push is logos (alphanumeric), then the remaining bytes start with 03 90 05 10 = CScript() << 1050000, so valid. A 7-character tag GIBISfr (6a 07 47494249536672 03 900510) fails before Napoleon (length byte 07 ≠ 5) and passes after it.

Source files #

  • src/validation.cpp: IsCoinbaseTag, IsValidCoinbaseHeightScript, ContextualCheckBlock (bad-cb-height), ConnectBlock (bad-txns-BIP30)
  • src/validation.h: IsValidCoinbaseHeightScript declaration
  • src/consensus/consensus.h: COINBASE_PREFIX (logos)
  • src/consensus/activation.cpp, src/chainparams.cpp: Napoleon activation
  • src/miner.h, src/miner.cpp: -coinbasetag validation, SelectCoinbaseTag, coinbase construction
  • src/init.cpp: option registration and startup checks
  • src/rpc/mining.cpp: getmininginfo.coinbasetag
  • src/test/validation_block_tests.cpp, src/test/coinbasetag_tests.cpp, test/functional/mining_coinbase_tag.py
  • doc/upstream-logos-rule.md: upstream history and compatibility analysis
Source doc/protocols/coinbase-tag.md in the lotusd repository