Protocols supported by lotusd
Protocol and consensus12.4.15+

Protocols supported by lotusd

Every on-chain data protocol this node parses or indexes, and how the modules process them.

This is the reference for every on-chain data protocol this node parses or indexes: what each one is for, its exact byte layout, the rules our code applies (with file:line references), how it is stored, which REST endpoints expose it and what the dashboard shows. These pages are compiled into the lotusd binary at build time. They are served at GET /api/v1/docs and shown in the Docs tab of the dashboard. The node reads nothing from disk to serve them.

The pages describe the code at the commit they were built from. Where something could not be checked against code, tests or live data, the page says Unverified:.

The protocols #

PageProtocolKindIdentifierEnvelopeModuleData file
eMPPeCash Multi-Push ProtocolTransportnone (carries LOKAD ids)OP_RETURN OP_RESERVED (6a 50) + pushesemppmodules/empp.sqlite
RANKBurn-weighted social votesApplicationLOKAD RANK (52 41 4e 4b)bare OP_RETURN or eMPPrankmodules/rank.sqlite
SLP v1Simple Ledger Protocol tokens (types 1, NFT1 group, NFT1 child)TokenLOKAD SLP\0 (53 4c 50 00)bare OP_RETURN at output 0, or eMPPslpmodules/slp.sqlite
ALPAugmented Ledger Protocol tokensTokenLOKAD SLP2 (53 4c 50 32)eMPP at output 0 onlyalpmodules/alp.sqlite
BLOBChunked on-chain filesApplicationLOKAD BLOB (42 4c 4f 42)bare OP_RETURN or eMPPblobmodules/blob.sqlite
POKRPoker league eventsApplicationLOKAD POKR (50 4f 4b 52)bare OP_RETURN or eMPPpokrmodules/pokr.sqlite
Coinbase tagOP_RETURN <tag> <height> in coinbase output 0Consensustag, logos by defaultcoinbase vout[0]none (validation, miner)none
UTXO commitmentMuHash3072 of the UTXO set in every coinbase from NapoleonConsensusLOKAD UTXO (55 54 58 4f)eMPP in the coinbasenone (validation, miner)none

The data files are under <datadir>/modules/ (src/modules/module_registry.cpp:196, file names in each module's Init). GET /api/v1/modules shows the path in its db field, except for BLOB and POKR, which report an empty one (see their pages).

How the module protocols are processed #

Every application protocol above, except the coinbase tag, is a chain module: a class implementing IChainModule (src/modules/chain_module.h). Modules are not consensus code. They read connected blocks, write their own SQLite database and add REST routes. A malformed message is skipped, never rejected.

  1. Registration. RegisterBuiltinModules (src/modules/builtin_modules.cpp:27) registers, in this order: eMPP, RANK, POKR, BLOB, SLP, ALP. eMPP must come first: RANK, POKR, BLOB and SLP read the segments eMPP stored for the same block (ALP parses output 0 of each transaction itself). There is no command-line switch to turn a module off. The registry is created in src/init.cpp:3685 and every module's routes are added to /api/v1/ through AddModuleRoute.
  2. Block connected. CModuleRegistry::ConnectBlock (src/modules/module_registry.cpp:215) calls each module in registration order. It is called from block connection in src/validation.cpp:2187.
  3. Block disconnected (reorg). CModuleRegistry::DisconnectBlock (src/modules/module_registry.cpp:233) calls the modules in reverse order, so eMPP is undone last. It is called from src/validation.cpp:1679. Each module deletes the rows of that block; what each one does not restore is listed on its page.
  4. Startup reconcile. ReconcileWithChainTip (src/modules/module_registry.cpp:47) compares each module's indexed tip with the chain tip. In sync: nothing to do. Behind by at most kGapReindexThreshold = 200,000 blocks (src/modules/module_registry.h:166) on the active chain: the missing blocks are replayed. Ahead of the chain, on a fork, or further behind: the module is wiped and rebuilt from genesis (the node answers 503 node_warming_up meanwhile). The replay runs through ConnectBlockSelective (src/init.cpp:4241). A module that reports no tip (BLOB, POKR) is never replayed or wiped by this step.
  5. Mempool. Only SLP and ALP register a mempool hook (src/modules/builtin_modules.cpp:43-53), and it is observational: it never rejects a transaction. The other modules index confirmed transactions only.
  6. REST reads. Every module route runs holding the module mutex (LockedRouteAdder, src/modules/module_rescan.cpp). A module has a single SQLite connection shared by the block writer and the HTTP workers, and its statement cache gives every caller the same prepared statement for the same SQL. Without the lock a handler read the rows of a block still being written, and two handlers running the same query got each other's rows (fixed in 12.4.6). A handler therefore answers from one committed state, between two blocks. The lock order is cs_main, then the module mutex, as in block connection. The dashboard's RANK lookups (src/api/dashboard_handler.cpp) open their own read-only connection for one query and do not share statements.
  7. Rescan. RANK, POKR, BLOB, SLP and ALP can re-read a height range of the active chain from disk (RescanRange). A rescan is an operator action, available only on the authenticated JSON-RPC (src/rpc/modules.cpp): One rescan runs at a time on the whole node, in a background thread (src/modules/module_rescan.cpp). At shutdown it is cancelled and joined before the modules close. The methods are not in the anonymous allowlist of /api/v1/rpc, so neither REST nor the NNG tunnel can reach them. The old GET/POST /api/v1/<module>/rescan routes answer 403 rescan_moved. A rescan writes each block, or each RANK chunk, while holding cs_main and then the module mutex. Before writing, it checks that the block is still on the active chain: if a reorg removed it, the rescan stops with state aborted. A rescan never moves the module's last_indexed_height, tip_height or tip_hash backwards, and never across a gap: the position advances only when the range starts at or below the indexed height + 1. A rescan of an already indexed range therefore leaves the next startup reconcile with nothing to do. What a rescan does to the module's own rows and totals is described on each page.
    • rescanmodule <module> [start=0] [end=tip] starts it and returns at once; end is capped at the tip.
    • getmodulerescanstatus returns state (idle, running, complete, cancelled, aborted, failed), module, from, to, height, items, progress, started, finished, result and error.
    • cancelmodulerescan stops the job after the block or chunk it is writing.

GET /api/v1/modules lists the loaded modules with version, db and schema. The dashboard hides the tab of a module that is not loaded.

Common building blocks #

  • LOKAD id. A 4-byte prefix naming the protocol of a payload. In a bare OP_RETURN it is the first push, which must be a direct 4-byte push (04 xx xx xx xx). In eMPP it is the first 4 bytes of each push.
  • eMPP segment. One push of an OP_RETURN OP_RESERVED output: LOKAD id (4 bytes) + payload. See eMPP for the push rules that every eMPP-carried protocol inherits.
  • Burn amount. RANK, POKR and BLOB weigh a message by the satoshis locked in its OP_RETURN output. 1 XPI = 1,000,000 sats.
  • Endianness. Each page states the byte order of every multi-byte field. They differ between protocols: SLP amounts are big-endian, ALP amounts are 6-byte little-endian, coinbase heights are little-endian script numbers.

LOKAD ids: registry check #

Checked on 2026-11-16 against the public lists of eCash, the chain our LOKAD and eMPP conventions come from:

  • the eCash registry, Bitcoin ABC doc/standards/op_return-prefix-guideline.md (last change c66209e47, 2026-09-11, 15 ids);
  • the ids Cashtab parses without registering them, cashtab/src/config/opreturn.ts (3a7c11d0a, 2026-09-17: ALP SLP2, Agora AGR0, swap SWP\0, blog, rlog, SOL0, DICE, ROLL, the trophy emoji, ...), and the constants of Chronik, ecash-agora and metachronik in the same repository;
  • the older Bitcoin Cash list, etc/protocols.csv (2020-04-17, 31 ids).
IdHexDefined inCollision
RANK52 41 4e 4bsrc/modules/rank/rank_module.cppnone
BLOB42 4c 4f 42src/modules/blob/blob_module.cppnone (eCashChat's blog is 62 6c 6f 67, another id)
POKR50 4f 4b 52src/modules/pokr/pokr_module.cppnone (Proof of Writing is POWR, 50 4f 57 52)
POOL50 4f 4f 4csrc/pool/record.hnone
UTXO55 54 58 4fsrc/consensus/utxocommitment.hnone
ENTY45 4e 54 59rank3 branches (doc/protocols/entity.md)none
RNKC52 4e 4b 43dashboard label only (share/www/shared/js/lokad.js)none

SLP\0 and SLP2 are the eCash token protocols themselves (registered as eToken, and ALP), used as specified. Not a LOKAD id: eMPP is a dashboard label for the 6a 50 envelope.

The registry is first come, first served: an id is claimed by a pull request to that file. None of ours is claimed there.

REST surface for these pages #

MethodPathAnswer
GET/api/v1/docsJSON: docs[] with name, title, size, sha256, url, and count. README first.
GET/api/v1/docs/<name>The Markdown, text/markdown; charset=utf-8. <name>.md and index (= README) also work. ETag is the SHA-256 of the document; a matching If-None-Match gets 304.
GET/api/v1/docs/<unknown>404 JSON {"error":"not_found",...}. Names are looked up in the embedded table only, so nothing like ../ can reach the filesystem.

The dashboard tab is at /dashboard/docs and /dashboard/docs/<name>#<section>.

Not covered here #

These are parsed by the node but are not data protocols carried in transactions, and have their own documents in doc/ of the source tree: merge-mining AuxPoW commitments (doc/auxpow.md), Stratum (doc/stratum.md, doc/stratum-lotushash.md), NNG (doc/nng.md), the X address format (doc/xaddress.md), and the general REST API (doc/api-v1.md, also in the dashboard API tab).

Editing these pages #

The pages live in doc/protocols/*.md. Any .md file added there is embedded at the next build (share/www/embed_docs.py, wired in src/api/CMakeLists.txt). File names may only use letters, digits, - and _. The dashboard renderer supports a subset of Markdown: headings, paragraphs, pipe tables, fenced code, lists, blockquotes, code, bold, italic and links. Raw HTML is shown as text. Link to another page as [eMPP](empp.md) or [eMPP layout](empp.md#byte-layout). Section anchors are GitHub-style slugs of the heading. test_lotus --run_test=protocol_docs_tests checks that every file is embedded byte for byte and that every link between pages resolves.

Source doc/protocols/README.md in the lotusd repository