SLP v1 (Simple Ledger Protocol)
Protocol and consensus12.4.15+

SLP v1 (Simple Ledger Protocol)

SLP v1 tokens (type 1 and NFT1) as this node validates and indexes them.

SLP is a colored-coin token protocol inherited from Bitcoin Cash: a transaction carries an OP_RETURN at output 0 whose pushes describe a token operation (GENESIS creates a token, MINT issues more of it, SEND moves it), and token amounts are attached to the following outputs (vout 1, 2, ...). Consensus never sees SLP: validity is decided off-chain by walking the transaction graph back to a valid GENESIS. lotusd ships an SLP indexer module that decodes every SLP message, validates it against its ancestors, stores the result in <datadir>/modules/slp.sqlite, and serves it under /api/v1/slp/* and on the dashboard SLPv1 tab. It also accepts SLP messages wrapped in an eMPP segment.

Status in this node #

  • Module name slp, module version 1.1.0, SCHEMA_VERSION = 5 reported by /api/v1/modules, index format 2 (src/modules/slp/slp_module.h). The database records schema_version = "4" (layout migrations, CSlpModule::CreateSchema) and index_format = "2" in slp_meta.
  • Specifications: simpleledger slp-token-type-1.md and slp-nft-1.md (github.com/simpleledger/slp-specifications, read in full for this page), and the Bitcoin ABC reference indexer Chronik (chronik/bitcoinsuite-slp/src/slp/*.rs, color.rs, verify.rs) for burns.
  • Always built and always registered; there is no option to disable it. Registered after eMPP, RANK, POKR and BLOB, before ALP (src/modules/builtin_modules.cpp:28-40). eMPP must run first because SLP reads eMPP rows of the same block.
  • Mempool observation: CSlpMempoolHook is registered from src/init.cpp:3701-3702 via RegisterSlpMempoolHook() (src/modules/builtin_modules.cpp:43-47). It never rejects a transaction.
  • Token types decoded: 0x01 (Type 1 fungible), 0x41 (NFT1 child), 0x81 (NFT1 group), plus the reserved 0x02, 0x03, 0x04 which are decoded and validated with exactly the Type 1 rules. Message types: GENESIS, MINT, SEND and COMMIT.
  • Indexing is observational: nothing in validation or mempool policy depends on SLP. Spending tokens in a non-SLP transaction is not prevented by the node; the index records them as spent and burned (rule 18).
  • Tests: slp_decoder_tests, slp_validator_tests, token_module_index_tests (connect/disconnect symmetry, rescan idempotence, upgrade), test/functional/feature_module_token_validity.py (REST, reorg, restart, upgrade, dashboard).

Envelope #

Native form: the scriptPubKey of output 0 of the transaction.

OffsetSizeValueMeaning
010x6aOP_RETURN
110x04direct push of 4 bytes (the only accepted form for the LOKAD id)
2453 4c 50 00LOKAD id "SLP\0"
6...pushestoken_type, transaction_type, then the message fields
  • Pre-filter LooksLikeSlpOpReturn: script at least 6 bytes, byte 0 is OP_RETURN, byte 1 is exactly 0x04, bytes 2..5 are SLP\0 (src/modules/slp/slp_decoder.cpp:339-346). A LOKAD id pushed with OP_PUSHDATA1 is therefore not recognised at all (not even recorded as invalid).
  • Only output 0 is examined (src/modules/slp/slp_module.cpp:639-642). An SLP OP_RETURN at any other output is ignored.
  • Push rules enforced by the strict reader (src/modules/slp/slp_decoder.cpp:34-75):
    • allowed: direct pushes 0x01..0x4b, OP_PUSHDATA1 (0x4c), OP_PUSHDATA2 (0x4d, little-endian 2-byte length), OP_PUSHDATA4 (0x4e, little-endian 4-byte length);
    • forbidden: OP_0 (0x00), OP_1NEGATE (0x4f), OP_1..OP_16 (0x51..0x60) (slp_decoder.cpp:44); any other non-push opcode (slp_decoder.cpp:66);
    • an empty field must therefore be pushed as 4c 00 (OP_PUSHDATA1 with length 0);
    • a push longer than 520 bytes (MAX_SCRIPT_ELEMENT_SIZE) or running past the end of the script is invalid (slp_decoder.cpp:70-71);
    • non-minimal pushes (for example OP_PUSHDATA1 for a 4-byte field) are accepted for every field after the LOKAD id.
  • eMPP form: an eMPP segment whose 4-byte LOKAD id is SLP\0. The segment payload (bytes after the LOKAD id) is re-wrapped as 6a 04 534c5000 <payload> and passed to the same strict decoder (DecodeSlpPayload, src/modules/slp/slp_decoder.cpp:348-366). So the payload is the same push sequence as the native form, starting at token_type. See eMPP for the outer envelope.

Byte layout #

Notation: "push N" is the N-th push after OP_RETURN (push 0 is the LOKAD id). Every field is its own push; sizes are the size of the pushed data, not counting the push opcode. Integers are unsigned big-endian unless stated.

Common header (all message types) #

PushSizeTypeEndiannessFieldNotes
04bytesn/alokad_id53 4c 50 00, must be a direct 0x04 push
11 or 2uintbig-endiantoken_type0x01, 0x02, 0x03, 0x04, 0x41, 0x81; 2-byte form 00 01 is accepted as type 1; anything else rejects (unknown_token_type)
24 to 7ASCIIn/atransaction_typeexactly GENESIS, MINT, SEND or COMMIT (case-sensitive)

GENESIS #

PushSizeTypeEndiannessFieldNotes
30..520bytesn/atoken_tickerstored as-is (suggested UTF-8), no length limit beyond the push limit
40..520bytesn/atoken_namestored as-is
50..520bytesn/atoken_document_urlstored as-is
60 or 32bytesn/atoken_document_hashany other length rejects (bad_doc_hash_len); stored as hex
71uint8n/adecimals0x00..0x09
80 or 1uint8n/amint_baton_voutempty push = no baton; else 0x02..0xff
98uint64big-endianinitial_token_mint_quantityassigned to vout 1
(end)no further bytes allowed (trailing_bytes)

Token types: GENESIS of type 0x41 (NFT1 child) additionally requires a quantity of exactly 1, decimals == 0 and no mint baton (slp-nft-1.md: "GENESIS quantity shall be set to 1", "Shall not have a baton vout"). The token id of a GENESIS is its own txid in display (big-endian) byte order.

MINT #

PushSizeTypeEndiannessFieldNotes
332bytesbig-endian (display order)token_idtxid of the GENESIS
40 or 1uint8n/amint_baton_voutempty = baton destroyed; else 0x02..0xff
58uint64big-endianadditional_token_quantityassigned to vout 1
(end)no further bytes allowed

MINT is rejected for token type 0x41 (nft1_child_mint). It is accepted for 0x01, 0x81 and the reserved types.

SEND #

PushSizeTypeEndiannessFieldNotes
332bytesbig-endian (display order)token_id
48uint64big-endiantoken_output_quantity1amount for vout 1
5..228 eachuint64big-endiantoken_output_quantity2..19amount for vout 2..19

At least 1 and at most 19 amounts; every amount push must be exactly 8 bytes. The amounts run to the end of the script, so there is no trailing-bytes rule for SEND. SEND is accepted for every token type, including NFT1 child.

COMMIT #

PushSizeTypeEndiannessFieldNotes
332bytesn/atoken_id
432bytesn/afor_bitcoin_block_hash
58uint64big-endianblock_height
632bytesn/atoken_txn_set_hash
70..520bytesn/atxn_set_data_urloptional; a missing or malformed push here is silently ignored
(rest)trailing pushes tolerated

COMMIT is decoded and recorded as VALID with no token outputs; its fields are not stored anywhere (only the slp_transactions row).

Validation rules #

Decoding (any failure: the transaction is stored with validity = 2 (invalid), tx_type = 0, token_type = 0 and invalid_reason = the error code, src/modules/slp/slp_module.cpp:646-660):

  1. LOKAD push must be 4 bytes equal to SLP\0 (wrong_lokad) - src/modules/slp/slp_decoder.cpp:383.
  2. token_type push must be 1 or 2 bytes (bad_token_type_len) - src/modules/slp/slp_decoder.cpp:393; and one of the six known values (unknown_token_type) - src/modules/slp/slp_decoder.cpp:96-106, :401.
  3. transaction_type must be one of the four ASCII strings (unknown_tx_type) - src/modules/slp/slp_decoder.cpp:413-429.
  4. Forbidden opcodes, non-push opcodes, truncated pushes, pushes over 520 bytes invalidate the whole message - src/modules/slp/slp_decoder.cpp:44, :66, :70-71.
  5. GENESIS: ticker, name, URL, hash pushes must be present - src/modules/slp/slp_decoder.cpp:113-136; document hash 0 or 32 bytes - :138; decimals one byte <= 9 - :150; baton empty or one byte >= 2 - :162-170; quantity exactly 8 bytes - :173; no trailing bytes - :181.
  6. GENESIS of NFT1 child: quantity must be 1 (nft1_child_qty; slp-nft-1.md "NFT1 Protocol Requirements", Chronik slp/genesis.rs Nft1ChildInvalidInitialQuantity); decimals must be 0 (nft1_child_decimals); no baton (nft1_child_baton) - DecodeGenesis, src/modules/slp/slp_decoder.cpp.
  7. MINT: token id 32 bytes - src/modules/slp/slp_decoder.cpp:210; baton empty or one byte >= 2 - :222-230; quantity 8 bytes - :233; no trailing bytes - :240; not allowed for NFT1 child - :247-251.
  8. SEND: token id 32 bytes - src/modules/slp/slp_decoder.cpp:260; each amount exactly 8 bytes - :276; at most 19 amounts (too_many_send_amounts) - :281; at least one (no_send_amounts) - :288.
  9. COMMIT: token id, block hash, set hash 32 bytes, height 8 bytes - src/modules/slp/slp_decoder.cpp:300-326.

Graph validation (CSlpValidator, src/modules/slp/slp_validator.cpp). A parent is looked up by its txid in the in-memory cache, then in slp_transactions/slp_outputs. Results are VALID (1), INVALID (2) or UNKNOWN (0). Only valid inputs count: "A 'valid token input' is a transaction input (i.e., a spent TXO) where the previous transaction is already known to conform to SLP consensus rules" (slp-token-type-1.md).

  1. Block processing sees the whole chain before the block, and the block's transactions are processed parents first (TopoOrder, src/modules/slp/slp_module.cpp; Lotus blocks are in txid order, so a child can come first in the block). There, a parent without an SLP row is a non-SLP transaction and contributes nothing (SetParentsComplete(true)). In the mempool path a missing parent may simply not be indexed yet and gives UNKNOWN.
  2. A transaction already in the cache or in the database is not re-validated, except an UNKNOWN verdict (e.g. from the mempool), which block processing judges again (CSlpValidator::Validate).
  3. GENESIS: token id = txid, byte-reversed to display order. vout 1 receives initial_qty (if vout 1 does not exist the GENESIS is still valid and the quantity goes nowhere: SLP may colour nonexistent outputs, Chronik color.rs "Coloring SLP always succeeds"). A baton vout that does not exist in the transaction means no baton: the GENESIS stays VALID and had_baton_at_genesis is 0 (slp-token-type-1.md: "If mint_baton_vout is not present or refers to a nonexistent output, then the baton does not exist and the token provably has a one-time issuance").
  4. NFT1 child GENESIS: input 0 must spend a non-baton output with quantity > 0 of a VALID transaction of token type 0x81 (nft1_child_bad_parent_type, nft1_child_no_group_qty). In the mempool path an unindexed parent gives UNKNOWN (nft1_child_parent_unknown).
  5. MINT: at least one input must spend an output flagged as baton of a VALID transaction with the same token_id and token_type, else INVALID (mint_no_baton; UNKNOWN mint_baton_pending only in the mempool path). vout 1 receives additional_qty (a missing vout 1 does not invalidate it). A new baton vout that is empty or does not exist ends the baton; the MINT stays valid ("if mint_baton_vout is empty or refers to a nonexistent vout, the transaction is valid but the baton is lost").
  6. SEND: sum the quantities of all inputs that spend non-baton outputs of VALID transactions with the same token_id and token_type (128-bit sums). If the declared outputs exceed it: INVALID (send_outputs_exceed_inputs; UNKNOWN send_sum_pending_inputs only in the mempool path). Inputs of other tokens are burned without invalidating the SEND.
  7. SEND attribution: amount i goes to vout i+1. Amounts for outputs that do not exist do not invalidate the SEND ("the extra token amounts are simply burned").
  8. COMMIT is always VALID. Token outputs are recorded only for vouts that exist in the transaction.
  9. Spent and burned (MarkSpentAndBurns, src/modules/slp/slp_module.cpp), for every confirmed transaction, SLP or not: each input spending an output of a valid SLP transaction marks that output spent (spender_txid, spent_height). What is burned, per token (after Chronik verify.rs): a valid SEND of the same token passes on the amounts of its existing outputs and burns the rest of its inputs; a valid MINT of the token uses the baton and burns token amounts spent with it; a valid NFT1 child GENESIS consumes the group token at input 0 without burning it; anything else (a non-SLP transaction, an invalid one, one of another token or token type) burns everything it spends of that token, batons included (slp-token-type-1.md: "Tokens are lost when a token-containing UTXO is spent on a non-token transaction (or a wrongly-typed token)"; slp-nft-1.md: "Spending an NFT1 group or child token with the wrong Token Type field in a SEND transaction will result in the token being burned"). One slp_burns row per transaction and token, with burns_mint_batons set when a baton was destroyed.

Not implemented: any limit on the number of outputs other than the 19 amounts.

Indexing #

Database: <datadir>/modules/slp.sqlite (src/modules/module_registry.cpp:196, src/modules/slp/slp_module.cpp:72-79). Schema in CSlpModule::CreateSchema (src/modules/slp/slp_module.cpp:81-316). Amounts are stored as decimal TEXT so the full uint64 range survives.

TableColumnsIndexes
slp_tokenstoken_id TEXT PK, token_type INT, ticker, name, document_url, document_hash (hex) TEXT, decimals INT, mint_baton_vout INT (-1 = none), had_baton_at_genesis INT, genesis_txid TEXT, genesis_height INT, initial_qty TEXT, group_token_id TEXTtoken_type; genesis_height DESC; (token_type, genesis_height DESC); LOWER(ticker); LOWER(name)
slp_transactionstxid TEXT PK, token_id TEXT, token_type INT, tx_type INT (1 GENESIS, 2 MINT, 3 SEND, 4 COMMIT, 0 none), validity INT (0 unknown, 1 valid, 2 invalid), invalid_reason TEXT, block_height INT (-1 = mempool), block_time INT, mempool_seen_at INT, source TEXT (native or empp)(token_id, block_height DESC); block_height DESC; (validity, block_height DESC); (block_height, validity)
slp_outputstxid, vout, token_id, token_type, amount TEXT, is_baton INT, address TEXT, sats INT, spender_txid TEXT, spent_height INT (NULL = unspent); PK (txid, vout)(address, token_id); (token_id, address); (token_id, is_baton); spent_height; spender_txid
slp_inputstxid, n, prev_txid, prev_vout; PK (txid, n)(prev_txid, prev_vout)
slp_nft_childrenchild_token_id TEXT PK, group_token_id, genesis_txid, genesis_height(group_token_id, genesis_height)
slp_burnstxid, token_id, token_type, qty TEXT, burns_mint_batons INT, block_height, block_time; PK (txid, token_id)(token_id, block_height DESC); block_height DESC
slp_metakey TEXT PK, value TEXTkeys schema_version, index_format, last_indexed_height, tip_height, tip_hash

Write path (PersistResult, src/modules/slp/slp_module.cpp:393-582):

  • every SLP-tagged transaction (valid, invalid or unknown) gets one slp_transactions row (upsert: a later block height overrides -1) and one slp_inputs row per input;
  • token outputs go to slp_outputs, with the address decoded from the scriptPubKey (empty for non-standard scripts) and the XPI value in satoshis;
  • a VALID GENESIS inserts the slp_tokens row (an existing row is kept, except that a row first written from the mempool with genesis_height -1 takes the block height when the GENESIS is mined; before 12.4.6 it kept -1 forever, so on a live node, where a GENESIS reaches the mempool first, genesisHeight was -1 and the newest-first token lists were out of order); for an NFT1 child, group_token_id is the token of the output spent by input 0, and a slp_nft_children row is added (same height rule);
  • had_baton_at_genesis is set once, to 1 when the GENESIS created a baton output; slp_tokens.mint_baton_vout keeps the value the GENESIS declared. The REST fields batonStatus, mintBatonVout and mintBatonTxid are derived at read time from the live baton (an unspent baton output of a valid transaction of the token, the same query as /slp/token/{id}/baton), so they follow MINTs, non-SLP spends and reorgs.

Block connect (ProcessBlock, src/modules/slp/slp_module.cpp): one SQLite transaction per block. The block's transactions are taken parents first (TopoOrder). A transaction with an SLP output 0 is decoded natively; otherwise its first eMPP segment with LOKAD SLP\0 (read from the eMPP module for the same height, ordered by txid, vout, segment index) is used. Then every transaction's inputs are checked against slp_outputs for spent marking and burns (rule 18); these lookups are skipped while no stored SLP output is unspent. last_indexed_height, tip_height, tip_hash are updated for every block.

Block disconnect (CSlpModule::DisconnectBlock): for every transaction of the block, delete its rows from slp_transactions, slp_outputs, slp_inputs, slp_burns, and the slp_tokens / slp_nft_children rows it created; clear spender_txid/spent_height of the outputs spent at that height; set the tip to the parent block; clear the validator cache. Connecting N blocks then disconnecting K gives the same database as connecting N-K, and replaying blocks already indexed (a rescan) changes nothing (token_module_index_tests). Disconnected transactions are not put back as mempool rows.

Startup reconcile: the module's tip_height/tip_hash are compared with the chain tip; a module ahead of the chain or on another fork is wiped (ResetForReindex) and replayed (src/modules/module_registry.cpp:47, src/init.cpp, module reconcile).

Upgrade from 12.4.5 and earlier (index format 1) #

An slp.sqlite written before 12.4.6 has no index_format key in slp_meta. Its rows lack the spent marking of outputs spent by non-SLP transactions, keep burns by vout, and may hold NFT1 children with a quantity other than 1 or GENESIS transactions wrongly invalid for a nonexistent baton vout; they cannot be corrected in place. At startup (CSlpModule::UpgradeIndexFormat) the node then:

  1. logs SLP: index format 1 → 2: dropping the old index ...;
  2. drops every SLP data table and creates the new schema;
  3. writes tip_height 0 and tip_hash = the genesis block hash ("indexed up to block 0") and index_format 2.

The startup reconcile then replays blocks 1..tip into the module (a gap replay, or a full reindex if the chain is more than 200,000 blocks long); the node answers 503 node_warming_up until the replay is done. Nothing of the old index is kept (mempool rows are rebuilt as transactions reach the mempool again). A fresh database, or one already at format 2, is not touched.

Mempool (OnMempoolTransaction, src/modules/slp/slp_module.cpp:836-869): native output-0 messages only (eMPP SLP is indexed only when mined). The row is written with block_height = -1 and mempool_seen_at = now. A mempool transaction that is never mined (evicted, double-spent) keeps its -1 row forever; /slp/stats counts these as mempoolUnknown.

Rescan (rescanmodule slp, a background job; RescanRange): reads blocks from disk strictly serially and runs the same ProcessBlock for each one, under cs_main and the module mutex, after checking that the block is still on the active chain (otherwise the rescan stops, state aborted). During a rescan, ProcessBlock moves last_indexed_height, tip_height and tip_hash only when the block is the next one after the indexed tip (WriteTipMeta, m_in_rescan). Re-processing an indexed block never moves them back. Before 12.4.6, /slp/rescan?start=0&end=10 on mainnet left tip_height = 10, and the next startup wiped and rebuilt SLP from genesis.

REST API #

All routes are registered by CSlpModule::RegisterRoutes (src/modules/slp/slp_module.cpp:962-994) through AddModuleRoute, which uses no response cache (TTL 0, src/api/api_server.cpp:345-348). Responses are JSON. Amounts are decimal strings except where noted as numbers (those are 64-bit signed sums). Paging: page (default 1) and pageSize (default 50, max 200 unless noted). Hex ids are lowercase, display byte order.

Method and pathParametersResponse
GET /api/v1/slp/statsnone{tokens, transactions, validTxs, invalidTxs, mempoolUnknown, nftChildren, burns, lastIndexedHeight}
GET /api/v1/slp/tokenspage, pageSize, type (decimal token type){tokens:[{tokenId, tokenType, ticker, name, decimals, genesisHeight, initialQty, mintBatonVout, hadBatonAtGenesis, batonStatus}], total, numPages}, newest GENESIS first
GET /api/v1/slp/token/{tokenId}none{tokenId, tokenType, ticker, name, documentUrl, documentHash, decimals, mintBatonVout, mintBatonTxid, hadBatonAtGenesis, batonStatus, genesisTxid, genesisHeight, initialQty, groupTokenId}; 404 not_found. batonStatus: "none" (no baton ever existed), "active" (a live baton at mintBatonTxid:mintBatonVout), "burnt" (the baton existed and is gone); mintBatonVout is -1 and mintBatonTxid null without a live baton
GET /api/v1/slp/token/{tokenId}/holderspage, pageSize (max 500){tokenId, page, pageSize, holders:[{address, qty}]}; qty is a number
GET /api/v1/slp/token/{tokenId}/batonnone{tokenId, baton:{txid, vout, address, blockHeight}} or baton: null
GET /api/v1/slp/token/{tokenId}/supply-historydays (default 90, 1..3650){tokenId, days, series:[{date, minted, burned, netDelta, cumulativeSupply}]}, UTC days
GET /api/v1/slp/tx/{txid}none{txid, tokenId, tokenType, txType, validity, invalidReason, blockHeight, blockTime, outputs:[{vout, amount, isBaton, address, sats}]}; validity is "valid", "invalid" or "unknown"; 404 not_found
GET /api/v1/slp/tx/{txid}/decodednonesame fields plus tokenTypeName, txTypeName, totalQty (number), summary (one-line text)
GET /api/v1/slp/address/{addr}/balancesnone{address, balances:[{tokenId, amount}]}; amount is a number
GET /api/v1/slp/address/{addr}/utxostoken_id (optional){address, utxos:[{txid, vout, tokenId, amount, sats}]}
GET /api/v1/slp/address/{addr}/historytoken_id, page, pageSize{address, tokenId?, events:[{txid, blockHeight, blockTime, tokenId, qty, direction}]}; direction in or out, qty negative for out
GET /api/v1/slp/nft/group/{tokenId}/childrenpage, pageSize{groupTokenId, total, children:[{childTokenId, genesisTxid, genesisHeight}]}
GET /api/v1/slp/nft/group/{tokenId}/children/fullpage, pageSizeas above plus ticker, name, documentUrl, documentHash per child
GET /api/v1/slp/burnspage, pageSize, token_id{burns:[{txid, tokenId, tokenType, qty, burnsMintBatons, blockHeight}]}, one row per transaction and token (rule 18); txid may be a non-SLP transaction
GET /api/v1/slp/activitylimit (default 50, max 200), before_height{events:[{txid, tokenId, tokenType, txType, validity, blockHeight, blockTime, source}]}
GET /api/v1/slp/searchq (required, cut to 64 chars), limit (default 25, max 100){query, results:[same fields as /tokens items]}; substring match on token id, ticker, name
GET /api/v1/slp/block/{height}/summarynone{height, slpTxCount, valid, invalid, unknown, tokensTouched:[tokenId]} (at most 50 ids)
GET or POST /api/v1/slp/rescannone403 rescan_moved

"Unspent" in balances, utxos, holders, baton and batonStatus means: no confirmed transaction spent the output (spender_txid IS NULL) and no mempool SLP transaction spends it (no slp_inputs row), and the creating transaction is VALID.

Rescans are an operator action on the authenticated JSON-RPC: rescanmodule slp [start] [end] (see module rescans). The SLP routes are not described in /api/v1/openapi.json.

Dashboard #

Tab SLPv1 (data-tab="slp", hidden when the module is not loaded), share/www/dashboard/index.html:262-312, code in share/www/dashboard/js/dashboard.js (loadSlpHub and neighbours, from line 1943):

  • /dashboard/slp hub: stat cards from /slp/stats, last 10 events, recent tokens, recent burns;
  • /dashboard/slp/tokens: token list with search box (/slp/search) and type filter (1, 129 = 0x81, 65 = 0x41);
  • /dashboard/slp/activity, /dashboard/slp/burns (columns TxId, Token, Baton, Qty, Block; the txid links to the explorer transaction page, since the burning transaction need not be an SLP one);
  • /dashboard/slp/token/{tokenId}: token detail (genesis fields, baton badge ACTIVE / BURNT / NONE from batonStatus, current baton, holders, NFT children for groups);
  • /dashboard/slp/tx/{txid}: per-transaction SLP view.

Limits and edge cases #

  • Only output 0, and only a direct-push LOKAD id. An SLP message anywhere else is invisible.
  • Maximum 19 SEND amounts (decoder). The node's relay limit for OP_RETURN data is 8005 bytes (MAX_OP_RETURN_RELAY, src/script/standard.h:85), so the 19-amount SEND (about 215 bytes) is standard.
  • Ticker, name and URL are stored as raw bytes in TEXT columns; invalid UTF-8 is not rejected.
  • UNKNOWN happens only in the mempool path; block processing re-judges it (rules 10, 11).
  • A mempool transaction that is never mined keeps its -1 row, and its slp_inputs rows keep the outputs it spends out of balances.
  • Sums in balances, holders, history, supply-history use SQLite CAST(amount AS INTEGER), a signed 64-bit integer. Unverified: quantities above 2^63-1 are clamped by the cast and a SUM above 2^63-1 makes SQLite raise an integer-overflow error, so those endpoints can be wrong or fail for very large supplies (behaviour of SQLite, not tested here).
  • The API handlers run holding the module mutex (12.4.6), so they never see a half-written block.
  • A GENESIS whose txid appears in both forms (native and eMPP) is indexed once, as native.

Differences from the SLP v1 spec #

Compared with the simpleledger slp-token-type-1.md and slp-nft-1.md specifications (read in full, November 2026) and Chronik:

  • Reserved token types 0x02, 0x03, 0x04 are validated with Type 1 rules instead of being treated as unsupported.
  • COMMIT is accepted and marked VALID with trailing data tolerated; the spec leaves COMMIT mostly undefined.
  • The 2-byte token_type form (00 01) is accepted, as in the spec.
  • SLP inside eMPP is a Lotus extension, not part of the SLP v1 spec.
  • Only a direct 0x04 push is recognised for the LOKAD id.

Worked example #

No mainnet example: on 2026-11-14 every https://lotus-127.givelotus.org/api/v1/slp/* request answered 503 node_warming_up ("Rebuilding module indices from genesis"). The example is the GENESIS from the unit test decode_genesis_tt1 (src/test/slp_decoder_tests.cpp:80-102), encoded with the test's push helper. Output 0 script, 92 bytes:

Text
6a04534c500001010747454e455349530455534454065465746865721168747470733a2f2f7465746865722e746f20aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa0108010208000000003b9aca00
OffsetBytesMeaning
06aOP_RETURN
104push 4
2534c5000LOKAD SLP\0
601push 1
701token_type 1 (Type 1 fungible)
807push 7
947454e45534953GENESIS
1604push 4
1755534454ticker USDT
2106push 6
22546574686572name Tether
2811push 17
2968747470733a2f2f7465746865722e746fdocument URL https://tether.to
4620push 32
47aa x 32document hash
7901push 1
8008decimals 8
8101push 1
8202mint baton at vout 2
8308push 8
84000000003b9aca00initial quantity 1,000,000,000 (10.00000000 USDT with 8 decimals), to vout 1

Indexed result for a transaction with at least 3 outputs: VALID; slp_outputs rows (vout 1, amount 1000000000, is_baton 0) and (vout 2, amount 0, is_baton 1); slp_tokens row with token_id = the txid, had_baton_at_genesis = 1. With only 2 outputs the GENESIS is still VALID, without a baton (had_baton_at_genesis = 0, batonStatus "none").

A SEND of 100, 200 and 300 units of token 1111...11 (decode_send_tt1, src/test/slp_decoder_tests.cpp:104-119), 73 bytes:

Text
6a04534c500001010453454e442011111111111111111111111111111111111111111111111111111111111111110800000000000000640800000000000000c808000000000000012c

6a 04 534c5000 01 01 04 53454e44 (SEND) 20 11..11 (token id) 08 0000000000000064 (100 to vout 1) 08 00000000000000c8 (200 to vout 2) 08 000000000000012c (300 to vout 3). If the transaction has only 3 outputs (vout 0..2), the 300 for vout 3 go nowhere: with 600 units in the inputs, the slp_burns row of that transaction says 300.

Source files #

  • src/modules/slp/slp_types.h - LOKAD id, token and message types, field structs.
  • src/modules/slp/slp_decoder.h, src/modules/slp/slp_decoder.cpp - strict push reader, message decoding, eMPP payload re-wrap.
  • src/modules/slp/slp_validator.h, src/modules/slp/slp_validator.cpp - DAG validation, 128-bit sums, result cache.
  • src/modules/slp/slp_module.h, src/modules/slp/slp_module.cpp - SQLite schema, block connect/disconnect, mempool hook, rescan, REST handlers.
  • src/modules/builtin_modules.cpp - registration order and mempool hook registration.
  • src/modules/empp/empp_module.cpp - SegmentsForBlock, source of eMPP-wrapped SLP.
  • src/test/slp_decoder_tests.cpp, src/test/slp_validator_tests.cpp - unit tests.
  • share/www/dashboard/index.html, share/www/dashboard/js/dashboard.js - SLPv1 tab.
Source doc/protocols/slp.md in the lotusd repository