ALP (SLP2 tokens over eMPP)
Protocol and consensus12.4.15+

ALP (SLP2 tokens over eMPP)

ALP tokens (SLP2 over eMPP) as this node validates and indexes them.

ALP ("Augmented Ledger Protocol", LOKAD id SLP2) is a fungible-token protocol carried as sections inside an eMPP OP_RETURN envelope. A transaction creates a token (GENESIS), mints more of it from a baton (MINT), moves it between outputs (SEND) or destroys some of it (BURN); one transaction may carry several sections. The node does not enforce ALP in consensus or mempool policy: the alp module colours and verifies every confirmed transaction with the rules of the Bitcoin ABC reference indexer, and stores the result in alp.sqlite for the REST API and the dashboard.

Specification and sources #

The official specification is the eCash builders page https://ecashbuilders.notion.site/ALP-a862a4130877448387373b9e6a93dd97. It renders only with JavaScript and its text could not be read for this page. Unverified: the wording of that page. Every rule below is taken from the Bitcoin ABC reference implementations instead, which are what eCash wallets and Chronik use:

  • Chronik, chronik/bitcoinsuite-slp/src/alp/parse.rs (parsing), color.rs (colouring), verify.rs (verification), empp/parse.rs (eMPP pushdata), parsed.rs (output ranges), branch master of github.com/Bitcoin-ABC/bitcoin-abc;
  • ecash-lib 4.12.0, src/token/alp.ts (builders) and src/token/alp.parse.ts.

Chronik names are given in brackets, e.g. [TooFewOutputs].

Status in this node #

  • Module name alp, MODULE_VERSION 1.1.0, SCHEMA_VERSION 2, index format 2 (src/modules/alp/alp_module.h).
  • Always registered; there is no option to disable it (src/modules/builtin_modules.cpp). It parses the transactions itself and does not read the eMPP module's table.
  • Database: <datadir>/modules/alp.sqlite (src/modules/module_registry.cpp:196, CAlpModule::Init).
  • Indexes confirmed blocks only. The mempool hook exists but does nothing: ALP transactions appear only once mined (CAlpModule::OnMempoolTransaction).
  • Tests: alp_decoder_tests, alp_color_tests (rules), token_module_index_tests (connect/disconnect symmetry, rescan idempotence, upgrade), test/functional/feature_module_token_validity.py (REST, reorg, restart, upgrade, dashboard).

Envelope #

ALP has no native OP_RETURN form.

  1. Only the first output of a transaction is read (Chronik color.rs: tx.outputs.first()). It must be OP_RETURN OP_RESERVED (6a 50) followed by pushes (alp::SplitEmpp, src/modules/alp/alp_decoder.cpp, after Chronik empp/parse.rs):
    • any push opcode may be used, minimal or not;
    • an empty push (OP_0, or a push of length 0), OP_1NEGATE, OP_RESERVED, OP_1..OP_16, any other opcode or a truncated push makes the whole envelope unreadable: no ALP for that transaction;
    • every push is one pushdata, numbered from 0, whatever its protocol.
  2. A pushdata that starts with 53 4c 50 32 ("SLP2") is an ALP section; the 4 bytes are removed before decoding. A pushdata shorter than 4 bytes, or with another LOKAD id, is not ALP but still takes its index. A pushdata starting with SLP\0 is reported as a failed ALP parsing (invalid_slp_lokad_id, Chronik [InvalidSlpLokadId]).
  3. eMPP pushes at other outputs are ignored by ALP (the eMPP module still indexes them, see eMPP).

Byte layout #

All multi-byte integers are unsigned little-endian. A size is one byte that must be 0..127 [read_size, SizeOutOfRange]. var-bytes is a size n followed by n bytes. Amounts are 6-byte (48-bit) little-endian integers, at most 281474976710655.

Common header #

offsetsizetypeendiannessfieldnotes
04bytesn/aLOKAD id53 4c 50 32, removed before decoding
01u8n/atoken typepayload offset 0; 0x00 = standard. Any other value is an unknown token type: section type UNKNOWN, token id all zero, nothing more is read
11+Lvar-bytesn/atx typeGENESIS, MINT, SEND, BURN; anything else is a failed parsing unknown_tx_type [UnknownTxType]
......section bodyone of the tables below; bytes left after it are a failed parsing leftover_bytes [LeftoverBytes]

GENESIS #

offsetsizetypeendiannessfieldnotes
01+nvar-bytesn/atoken_tickerno charset check
...1+nvar-bytesn/atoken_name
...1+nvar-bytesn/aurl
...1+nvar-bytesn/adatastored as BLOB
...1+nvar-bytesn/aauth_pubkeystored, not used
...1u8n/adecimalsmust be 0..9 (decimals_out_of_range)
...1sizen/anum_mint_amounts K0..127
...6 x Ku48LEmint amountsamount i goes to output 1+i
...1sizen/anum_batons B0..127; batons go to outputs K+1..K+B

The token id of a GENESIS is its txid, shown as the usual display hex.

MINT #

offsetsizetypeendiannessfieldnotes
032bytesinternaltoken_idthe genesis txid in internal byte order
321sizen/anum_mint_amounts K
336 x Ku48LEmint amountsamount i goes to output 1+i
33+6K1sizen/anum_batons Bbatons go to outputs K+1..K+B

SEND #

offsetsizetypeendiannessfieldnotes
032bytesinternaltoken_idas for MINT
321sizen/anum_output_amounts N0..127; an empty SEND is allowed
336 x Nu48LEoutput amountsamount i goes to output 1+i

BURN #

offsetsizetypeendiannessfieldnotes
032bytesinternaltoken_idas for MINT
326u48LEburn_amountthe intended burn

Token id byte order #

On the wire the 32 token-id bytes of MINT, SEND and BURN are the genesis txid in internal byte order, like a prevout txid inside a transaction: Chronik alp/parse.rs read_token_id builds TokenId::new(TxId::from(token_id)), and ecash-lib alp.ts writes fromHexRev(tokenId). The decoder reverses them, so the token id stored and shown is the display hex of the genesis txid (alp::DecodePayload).

Validation rules #

alp::ColorAndVerify (src/modules/alp/alp_validator.cpp), a port of Chronik color.rs and verify.rs. It takes the transaction and, for each input, the token that input spends (read from alp_outputs, CAlpValidator::SpentTokens).

Parsing (per ALP pushdata, alp::DecodePayload). A failure is recorded as a failed parsing (pushdataIdx, error) and the pushdata is skipped; the other sections still count:

  1. Missing bytes: not_enough_bytes with the field name [NotEnoughBytes].
  2. A size byte above 127: size_out_of_range [SizeOutOfRange].
  3. Unknown tx type for token type 0: unknown_tx_type.
  4. GENESIS decimals above 9: decimals_out_of_range [DecimalsOutOfRange].
  5. Bytes after the section body: leftover_bytes.

Colouring, section by section in pushdata order. A section that breaks a rule is a failed colouring: it colours nothing, and the sections before it stay as they are:

  1. Token types must not decrease from one section to the next: descending_token_type [DescendingTokenType].
  2. A token id may appear in only one MINT or SEND (the GENESIS of the same tx counts): duplicate_token_id [DuplicateTokenId].
  3. GENESIS only at pushdata 0: genesis_must_be_first [GenesisMustBeFirst].
  4. GENESIS and MINT colour mint amount i at output 1+i (amount 0 colours nothing) and baton j at output 1+K+j [atoms_vec_range, batons_range]; SEND colours amount i at output 1+i.
  5. An amount (non-zero) or a baton for an output that does not exist: too_few_outputs [TooFewOutputs].
  6. An output already coloured by an earlier section: overlapping_atoms / overlapping_mint_baton [OverlappingAtoms, OverlappingMintBaton].
  7. BURN colours nothing; it records an intentional burn. A second BURN of the same token id: duplicate_intentional_burn_token_id.
  8. A section of an unknown token type colours every still uncoloured output (except output 0) as "unknown"; such outputs are not balances and are not stored.

Verification, one entry per token (Chronik TokenTxEntry): the sections first, in order, then standalone BURNs, then failed colourings, then bare burns:

  1. GENESIS and UNKNOWN are valid.
  2. MINT is valid only if an input spends a mint baton of the token: else missing_mint_baton [MissingMintBaton]. Token amounts spent by a MINT are burned.
  3. SEND is valid if the token atoms spent are at least the sum of its amounts: else insufficient_input_sum [InsufficientInputSum], and everything spent of that token is burned. The excess of a valid SEND is burned. A baton of the token spent by a SEND is burned (the SEND stays valid).
  4. A BURN without a section of its token is its own entry, valid; it is invalid only when the token's baton is spent with it. The atoms actually destroyed are those spent (a bare burn), whatever the BURN says; both numbers are stored.
  5. A bare burn: tokens spent by inputs while the transaction has no section of that token. Their atoms (and batons) are burned; the entry is invalid (bare_burn). This includes a transaction with no ALP at all that spends an ALP output.
  6. A failed colouring joins the entry of its token if there is one (it keeps that entry's validity), else it is an invalid entry with the colouring error as reason.
  7. More than 32767 inputs: every section invalid, too_many_tx_inputs [MAX_TX_INPUTS].
  8. The outputs coloured by an invalid entry are uncoloured: only outputs of valid entries are stored.

The transaction's top-level type, token and validity are those of its first section entry (section 0); a transaction whose every ALP pushdata failed to parse is invalid with the first parsing error as reason.

Order inside a block: transactions are processed parents first (Lotus blocks are in txid order, so a child can come before its parent), TopoOrder in src/modules/alp/alp_module.cpp.

Not implemented: mint vaults and auth_pubkey semantics (Chronik has none for ALP standard tokens either).

Indexing #

Tables created in CAlpModule::CreateSchema (src/modules/alp/alp_module.cpp). Amounts are stored as decimal TEXT.

tablecolumnskey and indexes
alp_tokenstoken_id TEXT, ticker, name, url TEXT, data BLOB, auth_pubkey BLOB, decimals INTEGER, genesis_txid TEXT, genesis_height INTEGER, initial_qty TEXT (sum of genesis mint amounts), num_batons INTEGERPK token_id; idx_alp_tokens_height (genesis_height DESC); idx_alp_tokens_ticker_lc (LOWER(ticker))
alp_transactionstxid TEXT, token_id TEXT, tx_type INTEGER (0 NONE, 1 GENESIS, 2 MINT, 3 SEND, 4 BURN, 5 UNKNOWN), validity INTEGER (1 valid, 2 invalid), invalid_reason TEXT, block_height, block_time, mempool_seen_at (always 0), num_entries, failed_parsings TEXT (idx:error,...)PK txid; idx_alp_tx_token (token_id, block_height DESC); idx_alp_tx_height (block_height DESC). One row per tx with ALP pushdata; top-level fields from section 0
alp_sectionstxid, idx, token_id, token_type, tx_type (0 = no section), pushdata_idx (-1 = none), validity, invalid_reason, intentional_burn (NULL = none), actual_burn, burns_mint_batons, failed_colorings TEXT, block_heightPK (txid, idx); idx_alp_sections_token (token_id, block_height DESC)
alp_outputstxid, vout, token_id, amount TEXT, is_baton, address TEXT (empty for non-standard scripts), sats, spender_txid TEXT, spent_height INTEGERPK (txid, vout); idx_alp_out_addr (address, token_id); idx_alp_out_token_addr (token_id, address); idx_alp_out_spent_height; idx_alp_out_spender_txid
alp_burnstxid, token_id, qty TEXT (atoms actually destroyed), intentional TEXT (BURN amount, NULL if none), burns_mint_batons, block_heightPK (txid, token_id); idx_alp_burns_token (token_id, block_height DESC); idx_alp_burns_height (block_height DESC)
alp_metakey, valuekeys last_indexed_height, tip_height, tip_hash, index_format
  • Connect: one SQLite transaction per block (CAlpModule::ProcessBlock). Every transaction whose first output is an eMPP envelope, and every transaction spending a stored ALP output, is verified. Input lookups are skipped while no stored ALP output is unspent.
  • Spent marking: every ALP output a confirmed transaction spends gets spender_txid and spent_height, whatever that transaction is. Balances and UTXOs are the outputs with spender_txid IS NULL.
  • A token row is inserted only by a valid GENESIS (ON CONFLICT(token_id) DO NOTHING).
  • Disconnect: deletes every row of the block's transactions from the data tables (tokens by genesis_txid), clears spender_txid/spent_height on outputs spent at that height, and moves the tip meta to the parent (CAlpModule::DisconnectBlock). Connecting N blocks then disconnecting K gives the same database as connecting N-K (token_module_index_tests).
  • Replaying a block already indexed (a rescan) changes nothing: rows are upserted and the spent columns are kept.
  • Startup reconcile: if the stored tip hash is still on the active chain the module replays the gap, otherwise it is wiped (ResetForReindex) and rebuilt from genesis; see src/init.cpp (module reconcile) and src/modules/module_registry.cpp.

Upgrade from 12.4.5 and earlier (index format 1) #

An alp.sqlite written before 12.4.6 has no index_format key in alp_meta. Its rows follow the old rules (display-order token ids, last section only, outputs spent by non-ALP transactions still unspent) and cannot be corrected in place. At startup (CAlpModule::UpgradeIndexFormat) the node then:

  1. logs ALP: index format 1 → 2: dropping the old index ...;
  2. drops every ALP data table (including the old alp_inputs, no longer used) 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. A fresh database, or one already at format 2, is not touched.

REST API #

All routes are registered through the module registry with cache TTL 0 (no response cache). Errors use the common envelope {"error": code, "message": text, "status": n}. Token ids and txids are matched as exact lowercase hex.

methodpathparametersresponse
GET/api/v1/alp/token/{token_id}{tokenId, ticker, name, url, decimals, genesisTxid, genesisHeight, initialQty (string), numBatons}; 404 not_found; 400 missing_token_id
GET/api/v1/alp/tokenspage (default 1), pageSize (default 50, max 200){tokens: [{tokenId, ticker, name, decimals, genesisHeight, initialQty, numBatons}], total, numPages}, newest genesis first
GET/api/v1/alp/tx/{txid}{txid, tokenId, txType (int), txTypeName, validity ("valid", "invalid"), invalidReason, blockHeight, blockTime, outputs: [{vout, tokenId, amount (string), isBaton, address, sats, spentTxid (null if unspent), spentHeight}], sections: [{idx, tokenId, tokenType, txType, txTypeName, pushdataIdx, validity, invalidReason, intentionalBurn (string or null), actualBurn (string), burnsMintBatons, failedColorings: []}], failedParsings: [{pushdataIdx, error}]}; 404 not_found (also for a non-ALP tx that only burned tokens: see alp/burns)
GET/api/v1/alp/address/{addr}/balances{address, balances: [{tokenId, amount (integer)}]}, unspent non-baton outputs
GET/api/v1/alp/address/{addr}/utxos{address, utxos: [{txid, vout, tokenId, amount (string), sats}]}; other sub-path: 404 unknown_subroute; missing: 400 bad_path
GET/api/v1/alp/activitylimit (default 50, 1..200){events: [{txid, tokenId, txType (int), validity, blockHeight, blockTime}]}
GET/api/v1/alp/burnspage, pageSize (default 50, max 200), token_id (optional){burns: [{txid, tokenId, qty (string), intentional (string or null), burnsMintBatons, blockHeight}]}
GET/api/v1/alp/stats{tokens, transactions, validTxs, invalidTxs, burns, lastIndexedHeight}
GET, POST/api/v1/alp/rescan403 rescan_moved. A rescan is an operator action on the authenticated RPC: rescanmodule alp [start] [end] (see module rescans).

Handlers: src/modules/alp/alp_module.cpp from CAlpModule::RegisterRoutes. The ALP routes are not described in openapi.json.

Dashboard #

Tab "ALP" (data-module="alp", hidden when /api/v1/modules does not list the module) in share/www/dashboard/index.html; code in share/www/dashboard/js/dashboard.js from loadAlp.

  • Hub: stat cards from alp/stats, latest 10 events (alp/activity), 10 newest tokens, 10 recent burns.
  • Sub-tabs Tokens, Activity, Burns (/dashboard/alp/tokens, /activity, /burns). Burn rows link to the explorer transaction page (/dashboard/tx/{txid}): the burning transaction need not be an ALP one.
  • Detail pages /dashboard/alp/token/{id} and /dashboard/alp/tx/{txid}. The tx page shows token, type, validity, block, reason, a Sections table (every entry with pushdata index, type, token, validity, reason, burned amount), unreadable pushdata, and the token outputs with the transaction that spent each one.

Limits and edge cases #

  • Maximum amount per field 2^48 - 1; at most 127 amounts per section.
  • Relay policy limits OP_RETURN data (MAX_OP_RETURN_RELAY 8005, src/script/standard.h:85), but a miner can include larger non-standard outputs; ALP reads them all.
  • Rescan (rescanmodule alp, a background job): blocks are reprocessed serially through the same ProcessBlock, each one under cs_main and the module mutex, so already indexed rows are upserted. The tip meta is not moved backwards (WriteTipMeta, m_in_rescan). The handlers run holding the module mutex.
  • A failed-parsing-only row has an empty token_id and txTypeName "NONE".
  • No mempool view: an unconfirmed ALP transaction returns 404 from alp/tx.
  • An eMPP envelope that is unreadable as a whole (e.g. an empty push) is not reported as ALP; Chronik reports it as a failed eMPP parsing. Inputs it spends are still bare burns.

Differences from Chronik #

  • Chronik also indexes the mempool; this node indexes ALP from blocks only.
  • Chronik reports a transaction whose eMPP envelope cannot be parsed at all as a token transaction with a failed parsing; this node stores nothing for it (it cannot be told apart from another protocol's broken envelope), but still marks the tokens it spends as burned.

Worked example #

The production node used for examples (lotus-127.givelotus.org) answered 503 node_warming_up ("Rebuilding module indices from genesis") on 2026-11-14 for /api/v1/alp/stats, /alp/activity and /empp/stats, so the example below is constructed from the decoder code, not taken from mainnet (the same layout is exercised by alp_decoder_tests). Unverified: whether any ALP transaction exists on Lotus mainnet.

GENESIS of a token LTK, 2 decimals, 1000.00 units to vout 1 and a mint baton at vout 2:

Text
6a5029534c5032000747454e45534953034c544b0b4c6f74757320546f6b656e0000000201a0860100000001
bytesmeaning
6aOP_RETURN
50OP_RESERVED (eMPP marker)
29push of 41 bytes (one segment)
534c5032LOKAD id "SLP2"
00token type 0 (standard)
07 47454e45534953section type "GENESIS"
03 4c544bticker "LTK"
0b 4c6f74757320546f6b656ename "Lotus Token"
00url, empty
00data, empty
00auth_pubkey, empty
02decimals 2
011 mint amount
a08601000000100000 (u48 LE) to vout 1, shown as 1000.00
011 baton, at vout 2

Result: alp_tokens row with token_id = this txid, initial_qty "100000", num_batons 1; alp_outputs rows (vout 1, amount "100000", is_baton 0) and (vout 2, amount "0", is_baton 1), provided the transaction has at least 3 outputs.

SEND of that token, 600.00 to vout 1 and 400.00 to vout 2 (token id written here as 11..11 for brevity, which reads the same in both byte orders; in practice the genesis txid in internal byte order, i.e. its display hex reversed byte by byte):

Text
6a5037534c5032000453454e4411111111111111111111111111111111111111111111111111111111111111110260ea00000000409c00000000
bytesmeaning
6a 50OP_RETURN OP_RESERVED
37push of 55 bytes
534c5032"SLP2"
00token type 0 (standard)
04 53454e44section type "SEND"
11 x 32token_id
022 output amounts
60ea0000000060000 to vout 1
409c0000000040000 to vout 2

If the inputs spend the 100000-unit output, the SEND is valid and nothing is burned; if they spent 150000 units, 50000 would be recorded in alp_burns. If they spent only 90000 units, the SEND would be invalid (insufficient_input_sum), outputs 1 and 2 would carry no token, and the 90000 units would be recorded as burned.

Source files #

  • src/modules/alp/alp_types.h: LOKAD id, enums, decoded structs.
  • src/modules/alp/alp_decoder.h, src/modules/alp/alp_decoder.cpp: section decoder, eMPP pushdata split.
  • src/modules/alp/alp_validator.h, src/modules/alp/alp_validator.cpp: colouring and verification, input tokens.
  • src/modules/alp/alp_module.h, src/modules/alp/alp_module.cpp: schema, upgrade, block connect/disconnect, REST handlers, mempool hook.
  • src/modules/builtin_modules.cpp, src/modules/module_registry.cpp: registration order, datadir, reconcile.
  • share/www/dashboard/index.html, share/www/dashboard/js/dashboard.js: ALP tab.
Source doc/protocols/alp.md in the lotusd repository