POKR: on-chain poker events
Protocol and consensus12.4.15+

POKR: on-chain poker events

Poker league events recorded on chain: layout, rules and REST routes.

POKR anchors poker game events on chain: kills, scores, tournament results, badge unlocks, shop discount burns and withdrawal anchors. Each event is an OP_RETURN output (or an eMPP segment) whose attached value is unspendable, so every event is also a burn. The node indexes the events, keeps per-player and per-league totals and a daily burn series, and serves them under /api/v1/poker/*. The node only records what the poker app publishes: nothing checks who signed an event or whether the game really happened.

Status in this node #

  • Built-in module pokr (class CPokrModule), always registered: src/modules/builtin_modules.cpp:33. There is no switch to turn it off.
  • Registered after eMPP, so the block's eMPP segments are already stored when POKR reads them (src/modules/builtin_modules.cpp:28-31).
  • Database: <datadir>/modules/pokr.sqlite (src/modules/pokr/pokr_module.cpp:457).
  • REST prefix is poker, not pokr (src/modules/pokr/pokr_module.cpp:855-881). The dashboard tab is labelled POKR.
  • Indexing only: no consensus or relay rule.
  • LOKAD id: "POKR" = 50 4f 4b 52 (src/modules/pokr/pokr_module.cpp:29).
  • Burn thresholds: minimum 1 sat, no maximum by default (DEFAULT_POKR_MIN_BURN_SATS = 1, DEFAULT_POKR_MAX_BURN_SATS = 0). Operator options -pokrminburn=<sats> and -pokrmaxburn=<sats> (0 = no ceiling), registered in src/init.cpp next to -rankminburn since 12.4.6 (before, the node refused to start with them: "Invalid parameter"). They apply to native and eMPP events, on connect and on rescan.

Envelope #

Two transports, both decoded on every connected block (ExtractEventsFromBlock, src/modules/pokr/pokr_module.cpp:373-450):

TransportScript shapeDecodersource column
Native ("Format A")OP_RETURN <push "POKR"> <push kind> <push league> <push event_id> <push subject> [<push object>] [<push payload>]DecodePokrOutput / DecodePokrFormatA, pokr_module.cpp:268, :209native
eMPPOP_RETURN OP_RESERVED <push "POKR" + flat bytes> [more segments]eMPP module, then DecodePokrPayloadFlat, pokr_module.cpp:311empp

Every output of every transaction is scanned. For the eMPP envelope see eMPP; POKR receives each segment's bytes after the 4-byte LOKAD id. An eMPP row whose (txid, vout) was already decoded natively is skipped, and only the first decodable POKR segment of an output is an event (events are keyed by (txid, vout)); later POKR segments of that output are ignored (ExtractEventsFromBlock).

Byte layout #

Native (Format A) #

Five to seven elements after OP_RETURN, counting the LOKAD push. Integers are big-endian.

ElementSizeTypeEndiannessFieldNotes
(opcode)1opcoden/aOP_RETURN0x6a
04bytesn/aLOKAD id04 504f4b52 ("POKR")
11uint8n/aevent_kindmust be a 1-byte data push (01 xx); OP_1 etc. are rejected
21uint8n/aleague_id1-byte data push; league 0 is 01 00, not OP_0
31 or morebytesn/aevent_idtypically a 16-byte UUID; stored as hex
41 or morebytesn/asubject_user_idtypically a 16-byte UUID
5 (optional)1 or morebytesn/aobject_user_id or payloadsee the rules for 6 elements below
6 (optional)8uint64big-endiannumeric_payloadonly with 7 elements

Element counts:

CountElement 5Element 6
5nonenone
68 bytes: numeric_payload; any other non-zero length: object_user_idnone
7object_user_id (non-empty)numeric_payload (exactly 8 bytes)

With 6 elements an 8-byte object id cannot be expressed: it is read as a numeric payload.

eMPP segment body ("flat" layout) #

After the LOKAD id "POKR":

OffsetSizeTypeEndiannessFieldNotes
01uint8n/aevent_kind
11uint8n/aleague_id
21uint8n/aevent_id_len (E)1 to 255
3Ebytesn/aevent_id
3+E1uint8n/asubject_len (S)1 to 255
4+ESbytesn/asubject_user_id
4+E+S1uint8n/aobject_len (O)0 = no object
5+E+SObytesn/aobject_user_idonly if O > 0
5+E+S+O1uint8n/aflagsbit 0 = payload present; other bits ignored
6+E+S+O8uint64big-endiannumeric_payloadonly if bit 0 is set

The segment must end exactly there. Unlike Format A, the flat layout can carry an object id and a payload independently, and an 8-byte object id is unambiguous.

Event kinds #

Any byte value is indexed; unknown values are reported as "unknown" (EventKindName, pokr_module.cpp:64-74). Kinds 1 to 6 are named (pokr_module.cpp:55-62). The meaning of subject and object below is what the totals code assumes (pokr_module.cpp:691-761); the rest is the convention of the older doc/pokr.md.

CodeNameSubjectObjectNumeric payloadEffect on totals
0x01killvictimkiller (optional)freesubject deaths +1; object kills +1 (global and league)
0x02scoreplayernonescore deltasubject total_score + payload (global and league)
0x03tournament_resultplayeroptionalfinal positionsubject wins +1 if payload is 1 or 0xFFFFFFFFFFFFFFFF
0x04badge_unlockplayerbadge idtiersubject badges +1
0x05shop_burnplayerorder or item iddiscountsubject shop_burns +1
0x06withdrawal_anchorplayerred-packet idaddress prefixnone besides burn
otherunknownnone besides burn

Every event adds its burned sats to the subject's total_burn_sats, to the subject's league row and to the daily series.

Versioning #

No version field. New kinds can be added without a node change (they are indexed as unknown with their code).

Validation rules #

Native (Format A):

  1. The script is at least 6 bytes and starts with OP_RETURN (src/modules/pokr/pokr_module.cpp:269-272).
  2. Each element is read by ReadStrictPush: OP_0, OP_1NEGATE and OP_1 to OP_16 are accepted as elements with no data (pokr_module.cpp:123-127); direct pushes 0x01 to 0x4b as-is (:129-135); OP_PUSHDATA1 needs a length of at least 0x4c (:136-146), OP_PUSHDATA2 at least 0x100 (:147-159), OP_PUSHDATA4 at least 0x10000 (:160-174). Any other opcode, or a push past the end, rejects the output (:175).
  3. More than 16 elements, or none, rejects (pokr_module.cpp:281-283); the decoder then requires 5 to 7 (pokr_module.cpp:211).
  4. Element 0 is exactly "POKR" (pokr_module.cpp:285-288, again :213-216).
  5. event_kind and league_id are 1-byte data pushes (pokr_module.cpp:218-222). Because small-integer opcodes carry no data, OP_1 or OP_0 in these slots rejects the output.
  6. event_id and subject_user_id are non-empty (pokr_module.cpp:224-228).
  7. With 6 elements, element 5 is a payload if it has 8 bytes, an object id if it has any other non-zero length, and rejects if empty (pokr_module.cpp:234-251).
  8. With 7 elements, element 5 is a non-empty object id and element 6 is exactly 8 bytes (pokr_module.cpp:254-264).

eMPP (flat):

  1. At least 5 bytes (pokr_module.cpp:314).
  2. event_id_len and subject_len are not 0, and no length runs past the end (pokr_module.cpp:319-331, :336).
  3. A flags byte must be present; with bit 0 set, 8 more bytes must be present (pokr_module.cpp:342-351).
  4. No trailing bytes (pokr_module.cpp:353).

Both transports:

  1. The burned value (native: the output value; eMPP: the value of the whole output hosting the segment, EmppRow::output_sats, credited once per output, see eMPP) must be at least -pokrminburn (default 1 sat), and at most -pokrmaxburn when it is set (> 0).
  2. One event per (txid, vout): INSERT OR IGNORE (pokr_module.cpp:638-642; primary key at :479).

Indexing #

Database pokr.sqlite (CreateSchema, src/modules/pokr/pokr_module.cpp:464-586):

pokr_events:

ColumnTypeNotes
txidTEXT NOT NULL
voutINTEGER NOT NULL
block_heightINTEGER NOT NULL
block_timeINTEGER NOT NULLblock header time
kindINTEGER NOT NULLevent_kind
league_idINTEGER NOT NULL
event_idTEXT NOT NULLlowercase hex
subject_idTEXT NOT NULLlowercase hex
object_idTEXT NOT NULL DEFAULT ''lowercase hex, empty if absent
numeric_valueINTEGER NOT NULL DEFAULT 0payload; a uint64 of 2^63 or more is stored as a negative int64
satsINTEGER NOT NULLburned value
sourceTEXT NOT NULL DEFAULT 'native'native or empp (migration for older databases at pokr_module.cpp:572-585)

Primary key (txid, vout). Indexes: idx_pe_event (event_id), idx_pe_subject (subject_id, kind, block_height DESC), idx_pe_object (object_id, kind, block_height DESC) WHERE object_id != '', idx_pe_league (league_id, kind, block_height DESC), idx_pe_time (block_height DESC, vout ASC).

Totals:

TableKeyColumns
pokr_user_statsuser_idkills, deaths, total_score, wins, badges, shop_burns, total_burn_sats, last_height; indexes on kills, total_score, wins (all DESC)
pokr_league_standings(league_id, user_id)kills, total_score, wins, burn_sats; index (league_id, total_score DESC)
pokr_burns_daily(date, kind, league_id)burn_sats, events; date is the UTC YYYY-MM-DD of the block time; index on date DESC
pokr_metakeylast_indexed_height

Block flow:

  • Connect: decode, then in one transaction insert each event, add its deltas to the three totals tables for the events actually inserted, and set last_indexed_height (ConnectBlock, ApplyEventsLocked).
  • The totals follow only a newly inserted event row: INSERT OR IGNORE then sqlite3_changes. Re-connecting a block, a rescan of an indexed range and a second POKR segment in one output change nothing. Before 12.4.6 the totals were added for every decoded event, ignored ones included, so they counted an event again on every such decode (pokr_module_tests/reconnect_does_not_double_count, rescan_over_indexed_range_does_not_double_count, multi_segment_output_counts_burn_once).
  • Disconnect: in one transaction, collect the keys the block's events touched (subject and killer in pokr_user_stats and pokr_league_standings, (date, kind, league) in pokr_burns_daily), delete the events of height h, rebuild each touched total row from the events that remain (RecomputeUserLocked, RecomputeLeagueUserLocked, RecomputeDailyLocked: a row left without events disappears), last_indexed_height = h - 1. Connecting N blocks then disconnecting K equals connecting Nāˆ’K on every table (pokr_module_tests/connect_disconnect_symmetry_all_depths, disconnect_reconnect_equals_connect). Before 12.4.6 only the events were deleted and the totals kept the disconnected block.
  • Totals as a function of the events (used by the disconnect and by the upgrade): user = subject of any event (deaths = KILL, total_score = sum of SCORE values, wins = TOURNAMENT_RESULT with value 1 or 0xFFFFFFFFFFFFFFFF, badges, shop_burns, total_burn_sats = sum of sats, last_height = max height) plus killer of KILL events (kills, last_height); league row the same per league; daily row = sum of sats and count per (UTC date of block time, kind, league).
  • Upgrade (12.4.6). pokr_events was right in older databases (keyed rows, deleted on disconnect, first segment of an output, full output value); only the totals were wrong. At Init, a database without data_version 2 gets its three totals tables rebuilt from pokr_events in one transaction (RebuildAggregatesLocked), in place, no block read. Log: POKR: indexed data version 1 < 2: rebuilding the totals from pokr_events. Tests: pokr_module_tests/upgrade_from_v1_rebuilds_totals_from_events, feature_module_indexers.py.
  • Startup reconciliation: POKR does not override IndexedTipHeight/ResetForReindex, so the registry never replays or wipes it (src/modules/module_registry.cpp:70-75).
  • Mempool: not indexed.
  • Rescan (rescanmodule pokr, a background job; RescanRange): reads each block from disk, decodes it outside any lock, then writes its events under cs_main and the module mutex after checking that the block is still on the active chain (otherwise the rescan stops, state aborted). last_indexed_height only moves forward, and only if the range starts at or below it + 1. A range above the tip does nothing. It uses the same extraction and insert as a connect, so it is idempotent and builds what a connect builds (rescan_twice_equals_once, rescan_matches_connect).

REST API #

Routes registered through AddModuleRoute, without response-cache TTL (src/api/api_server.cpp:345-348; routes at src/modules/pokr/pokr_module.cpp:855-881). Event objects (EventRowToJson, pokr_module.cpp:883-905):

JSON
{"txid":"<hex>","vout":0,"blockHeight":100,"blockTime":1763100000,"kind":"kill","kindCode":1,
 "leagueId":0,"eventId":"<hex>","subjectId":"<hex>","objectId":"<hex>","numericValue":0,
 "burnSats":546,"source":"native"}

objectId is omitted when empty.

MethodPathParametersAnswer
GET/api/v1/poker/event/<event_id_hex>{"eventId","entries":[event...],"totalBurnSats"}, oldest first; unknown id gives an empty list, not 404
GET/api/v1/poker/tx/<txid>{"txid","events":[event...],"totalBurnSats"}, by output; a transaction without events gives an empty list (12.4.12, the Explorer's transaction page)
GET/api/v1/poker/user/<user_id_hex>{"userId","kills","deaths","totalScore","wins","badges","shopBurns","totalBurnSats","lastHeight"}, zeros for an unknown user
GET/api/v1/poker/user/<user_id_hex>/eventspage (default 1), pageSize (default 25, 1..100){"userId","events":[event...]}: events where the user is subject or object, newest first
GET/api/v1/poker/league/<league_id>[/standings]limit (default 50, 1..500){"leagueId","standings":[{"userId","kills","totalScore","wins","burnSats"}]} ordered by score, then wins, then burn, then user id (the last two since 12.4.6, so ties come out in the same order on every node)
GET/api/v1/poker/burnsdays (default 30, 1..365), league_id{"days","daily":[{"date","burnSats","events"}],"totalBurnSats","totalEvents"}
GET/api/v1/poker/stats{"totalEvents","totalBurnSats","byKind":[{"kind","kindCode","count","burnSats"}],"players","lastIndexedHeight"}; players = rows of pokr_user_stats (12.4.6)
GET/api/v1/poker/activitypage, pageSize (default 25, 1..100){"activity":[event...]} newest first
GET, POST/api/v1/poker/rescan403 rescan_moved. A rescan is an operator action on the authenticated RPC: rescanmodule pokr [start] [end] (see module rescans).

Notes from the code:

  • Ids in paths are matched as given: they must be the lowercase hex stored in the database.
  • /poker/league/<x>: x goes through atoi, so a non-number means league 0 (pokr_module.cpp:1035). Any sub-route other than standings gives 404.
  • /poker/burns without league_id sums every league (fixed in 12.4.6: the days limit was bound to the wrong placeholder, LIMIT NULL failed and the answer was always empty). days limits the number of distinct dates returned, not a time window.
  • lastIndexedHeight falls back to the highest event height when the meta key is missing (pokr_module.cpp:614-627).
  • /poker/rescan answers 403 rescan_moved; rescans run on the authenticated RPC rescanmodule pokr as a background job (12.4.6). A rescan is idempotent since 12.4.6.
  • The handlers run holding the module mutex, so an answer never mixes two blocks or two requests (12.4.6).

Dashboard #

Tab "POKR" (data-tab="pokr", hidden when the module is not loaded), sub-tabs Hub and Activity (share/www/dashboard/js/dashboard.js:2813-2869). The Hub shows cards from /poker/stats and the 10 newest events; Activity shows 50. Each row links to the transaction and the block.

The "Events" and "Players" cards read totalEvents and players of /poker/stats (before 12.4.6 they read events and users, which the API never sent, and always showed 0). The kind column uses the name sent by the API; the local fallback table lacks kind 6.

Limits and edge cases #

  • No authentication: anyone can publish POKR events for any user id. Consumers must decide which senders they trust; the node does not record the funding addresses in pokr_events (they are visible through /api/v1/txs/<txid>).
  • pokr_events and the totals stay consistent through rescans, reorgs and multi-segment eMPP outputs (see Indexing).
  • A 6-element Format A message cannot carry an 8-byte object id.
  • numeric_payload values of 2^63 or more are stored and returned negative; a score with such a payload lowers the total.
  • An event with 0 sats is not indexed (default minimum 1).
  • /api/v1/modules lists pokr with empty version, db path and schema 0 (no Info() override).

Differences from upstream #

POKR is a Lotus-only protocol; there is no upstream or eCash specification. Differences from this repository's older doc/pokr.md:

  • It says the object (killer) is required for kill; the code does not require it.
  • It says the decoder enforces minimal pushes "exactly like the RANK decoder"; the code accepts small-integer opcodes as empty elements, which then fail the 1-byte checks for kind and league.
  • It says kinds from 0x80 are reserved; the code has no such rule.
  • It says the totals are reconciled by a rescan; since 12.4.6 a rescan changes nothing on an indexed range, a disconnect reverts the totals exactly, and an upgrade rebuilds them from the events.
  • It does not describe the eMPP flat layout.

Worked example #

No mainnet POKR transaction could be fetched: on 2026-11-14 the public node answered 503 node_warming_up to every /api/v1/poker/* request. The examples are built by hand from the code; they are not on-chain transactions, and the tree has no POKR unit or functional test.

Native kill in league 0: victim 1111...11 (16 bytes), killer 2222...22, event id 00112233445566778899aabbccddeeff, no payload (6 elements, 61-byte script):

Text
6a 04 504f4b52 01 01 01 00
10 00112233445566778899aabbccddeeff
10 11111111111111111111111111111111
10 22222222222222222222222222222222
BytesMeaning
6aOP_RETURN
04 504f4b52push 4: "POKR"
01 01push 1: event_kind = 1 (kill)
01 00push 1: league_id = 0
10 0011...eeffpush 16: event_id
10 1111...11push 16: subject (victim)
10 2222...22push 16: element 5, 16 bytes, so an object id (killer)

With, say, 546 sats on this output, the block adds one pokr_events row (kind 1, object_id 2222...), deaths +1 and total_burn_sats +546 for 1111..., kills +1 for 2222... (global and league 0), and 546 sats to today's pokr_burns_daily row for kind 1, league 0.

Tournament win over eMPP: kind 3, league 1, same event id, subject 1111...11, no object, payload 1 (46-byte body, 50-byte segment):

Text
6a 50 32 504f4b52 03 01 10 00112233445566778899aabbccddeeff 10 11111111111111111111111111111111 00 01 0000000000000001

6a OP_RETURN, 50 OP_RESERVED, 32 push 50: "POKR", kind 3, league 1, 10 + event id, 10 + subject, 00 no object, flags 01, payload 1 big-endian. This counts as a win (payload 1) and is stored with source = 'empp'.

Source files #

  • src/modules/pokr/pokr_module.h, src/modules/pokr/pokr_module.cpp: decoders, schema, totals, REST.
  • src/modules/empp/empp_module.cpp (SegmentsForBlock), src/modules/empp/empp_decoder.cpp: eMPP transport.
  • src/modules/builtin_modules.cpp, src/modules/module_registry.cpp: registration, reconciliation.
  • src/util/system.cpp: handling of unregistered options.
  • share/www/dashboard/js/dashboard.js: POKR tab.
  • Older notes: doc/pokr.md (poker-app side, relationship with RANK platform poker), doc/lotus-poker-nft-v1.md (NFT metadata that refers to POKR event ids).
Source doc/protocols/pokr.md in the lotusd repository