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 #
| Page | Protocol | Kind | Identifier | Envelope | Module | Data file |
|---|---|---|---|---|---|---|
| eMPP | eCash Multi-Push Protocol | Transport | none (carries LOKAD ids) | OP_RETURN OP_RESERVED (6a 50) + pushes | empp | modules/empp.sqlite |
| RANK | Burn-weighted social votes | Application | LOKAD RANK (52 41 4e 4b) | bare OP_RETURN or eMPP | rank | modules/rank.sqlite |
| SLP v1 | Simple Ledger Protocol tokens (types 1, NFT1 group, NFT1 child) | Token | LOKAD SLP\0 (53 4c 50 00) | bare OP_RETURN at output 0, or eMPP | slp | modules/slp.sqlite |
| ALP | Augmented Ledger Protocol tokens | Token | LOKAD SLP2 (53 4c 50 32) | eMPP at output 0 only | alp | modules/alp.sqlite |
| BLOB | Chunked on-chain files | Application | LOKAD BLOB (42 4c 4f 42) | bare OP_RETURN or eMPP | blob | modules/blob.sqlite |
| POKR | Poker league events | Application | LOKAD POKR (50 4f 4b 52) | bare OP_RETURN or eMPP | pokr | modules/pokr.sqlite |
| Coinbase tag | OP_RETURN <tag> <height> in coinbase output 0 | Consensus | tag, logos by default | coinbase vout[0] | none (validation, miner) | none |
| UTXO commitment | MuHash3072 of the UTXO set in every coinbase from Napoleon | Consensus | LOKAD UTXO (55 54 58 4f) | eMPP in the coinbase | none (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.
- 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 insrc/init.cpp:3685and every module's routes are added to/api/v1/throughAddModuleRoute. - Block connected.
CModuleRegistry::ConnectBlock(src/modules/module_registry.cpp:215) calls each module in registration order. It is called from block connection insrc/validation.cpp:2187. - 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 fromsrc/validation.cpp:1679. Each module deletes the rows of that block; what each one does not restore is listed on its page. - 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 mostkGapReindexThreshold= 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 answers503 node_warming_upmeanwhile). The replay runs throughConnectBlockSelective(src/init.cpp:4241). A module that reports no tip (BLOB, POKR) is never replayed or wiped by this step. - 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. - 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 iscs_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. - 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 oldGET/POST /api/v1/<module>/rescanroutes answer403 rescan_moved. A rescan writes each block, or each RANK chunk, while holdingcs_mainand 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 stateaborted. A rescan never moves the module'slast_indexed_height,tip_heightortip_hashbackwards, 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;endis capped at the tip.getmodulerescanstatusreturnsstate(idle,running,complete,cancelled,aborted,failed),module,from,to,height,items,progress,started,finished,resultanderror.cancelmodulerescanstops 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_RETURNit 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_RESERVEDoutput: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_RETURNoutput. 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: ALPSLP2, AgoraAGR0, swapSWP\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).
| Id | Hex | Defined in | Collision |
|---|---|---|---|
RANK | 52 41 4e 4b | src/modules/rank/rank_module.cpp | none |
BLOB | 42 4c 4f 42 | src/modules/blob/blob_module.cpp | none (eCashChat's blog is 62 6c 6f 67, another id) |
POKR | 50 4f 4b 52 | src/modules/pokr/pokr_module.cpp | none (Proof of Writing is POWR, 50 4f 57 52) |
POOL | 50 4f 4f 4c | src/pool/record.h | none |
UTXO | 55 54 58 4f | src/consensus/utxocommitment.h | none |
ENTY | 45 4e 54 59 | rank3 branches (doc/protocols/entity.md) | none |
RNKC | 52 4e 4b 43 | dashboard 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 #
| Method | Path | Answer |
|---|---|---|
| GET | /api/v1/docs | JSON: 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.
