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 #
| Item | Value |
|---|---|
| Kind | Consensus rule (block validity), not an indexer module. No SQLite table, no module entry in /api/v1/modules. |
| Enforced | Always, for every block at height ≥ 20,000, and for every block once Napoleon is active (src/validation.cpp:4604-4613) |
| Napoleon gate | pindexPrev->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 names | Napoleon 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 file | none |
Envelope #
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):
| Offset | Size | Type | Endianness | Field | Notes |
|---|---|---|---|---|---|
| 0 | 1 | opcode | n/a | OP_RETURN = 0x6a | required |
| 1 | 1 | uint8 | n/a | tag length | must be exactly 0x05. The byte is read as a raw length, so in practice it must be a direct push. |
| 2 | 5 | ASCII | n/a | tag | letters and digits only ([0-9A-Za-z]); logos = 6c 6f 67 6f 73 |
| 7 | 1 | uint8 | n/a | height length | 0..3. The byte is read as a raw length. |
| 8 | 1..3 | uint | little-endian | height | unsigned, must equal the block height. Non-minimal encodings are accepted. |
| 8 + n | any | bytes | n/a | trailing data | ignored |
From Napoleon (an opcode parser, src/validation.cpp:4504-4516):
| Offset | Size | Type | Endianness | Field | Notes |
|---|---|---|---|---|---|
| 0 | 1 | opcode | n/a | OP_RETURN | required |
| 1 | var | push | push-length LE | tag | any 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 tag | var | script number | little-endian, minimal | height | must be byte-for-byte CScript() << nHeight (minimal push, CScriptNum encoding) |
| after height | any | bytes | n/a | trailing data | ignored |
Versioning: there is no version field. The rule changes by activation (Napoleon), as shown in the two tables.
Validation rules #
- Not checked for genesis (
nHeight > 0) or for blocks below height 20,000 before Napoleon (src/validation.cpp:4604-4608). OtherwiseIsValidCoinbaseHeightScript(vout[0].scriptPubKey, nHeight, napoleon)must hold, or the block is invalid withbad-cb-height(BLOCK_CONSENSUS) (src/validation.cpp:4611). - 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'sFRENCH_BTC). - Before Napoleon: byte 0 must be
OP_RETURNand the script must be at least 2 bytes (src/validation.cpp:4527). - 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_PREFIXatsrc/consensus/consensus.h:29). - 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). - Before Napoleon: the height bytes, read as an unsigned little-endian integer, must equal
nHeight(src/validation.cpp:4550). - 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 exactlyCScript() << nHeight(src/validation.cpp:4512-4515). - 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 withbad-txns-BIP30(src/validation.cpp:1953-1962). - Miner side, not consensus:
-coinbasetagmust be 1..32 ASCII letters, digits or_, or the node refuses to start (CheckCoinbaseTagOption,src/miner.cpp:83-101; startup checksrc/init.cpp:3013-3027).-nocoinbasetagmeanslogos(src/miner.cpp:151). - Miner-side selection for each block (
SelectCoinbaseTag,src/miner.cpp:113-147). It useslogos(reason=default) unless the configured tag is allowed: before Napoleon only with exactly 5 characters (otherwisepre-napoleon-needs-5-chars,:124); after Napoleon only with-coinbasetagafternapoleon=1(otherwiseafter-napoleon-not-enabled,:127). Where consensus checks the coinbase (from height 20,000 or Napoleon), the script is also self-checked withIsValidCoinbaseHeightScript, and it falls back tologos(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 path | What it shows |
|---|---|
GET /api/v1/rpc/getmininginfo | coinbasetag: {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, because0x4cis read as length 76. - Before Napoleon a non-minimal height (e.g.
04 90 05 10 00) fails theheight_len > 3check 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. getblocktemplatedoes not build the coinbase output: external pool software writes the tag and must follow the same rule.ContextualCheckBlockis skipped by-reindex-chainstate(comment abovesrc/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):
| Case | Upstream v8.3.4 to v11.5.1, and v12 before Napoleon | Upstream v12 after Napoleon | Ours before Napoleon | Ours after Napoleon |
|---|---|---|---|---|
logos + correct height | accept | accept | accept | accept |
| other 5-char alphanumeric tag + height (height ≥ 1,018,000) | accept | refuse | accept | accept |
| other tag, no or wrong height (height ≥ 1,018,000) | accept, height not checked | refuse | refuse | refuse |
| tag of a length other than 5 | accept (from 1,018,000) | refuse | refuse | accept |
| PUSHDATA1 tag push | refuse | refuse | refuse | accept |
| coinbase overwriting an unspent coin | no 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):
6a 05 6c6f676f73 03 900510| Offset | Bytes | Meaning |
|---|---|---|
| 0 | 6a | OP_RETURN |
| 1 | 05 | direct push of 5 bytes (tag length) |
| 2 | 6c 6f 67 6f 73 | logos |
| 7 | 03 | direct push of 3 bytes (height length) |
| 8 | 90 05 10 | height, 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:IsValidCoinbaseHeightScriptdeclarationsrc/consensus/consensus.h:COINBASE_PREFIX(logos)src/consensus/activation.cpp,src/chainparams.cpp: Napoleon activationsrc/miner.h,src/miner.cpp:-coinbasetagvalidation,SelectCoinbaseTag, coinbase constructionsrc/init.cpp: option registration and startup checkssrc/rpc/mining.cpp:getmininginfo.coinbasetagsrc/test/validation_block_tests.cpp,src/test/coinbasetag_tests.cpp,test/functional/mining_coinbase_tag.pydoc/upstream-logos-rule.md: upstream history and compatibility analysis
