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(classCPokrModule), 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, notpokr(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 insrc/init.cppnext to-rankminburnsince 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):
| Transport | Script shape | Decoder | source 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, :209 | native |
| eMPP | OP_RETURN OP_RESERVED <push "POKR" + flat bytes> [more segments] | eMPP module, then DecodePokrPayloadFlat, pokr_module.cpp:311 | empp |
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.
| Element | Size | Type | Endianness | Field | Notes |
|---|---|---|---|---|---|
| (opcode) | 1 | opcode | n/a | OP_RETURN | 0x6a |
| 0 | 4 | bytes | n/a | LOKAD id | 04 504f4b52 ("POKR") |
| 1 | 1 | uint8 | n/a | event_kind | must be a 1-byte data push (01 xx); OP_1 etc. are rejected |
| 2 | 1 | uint8 | n/a | league_id | 1-byte data push; league 0 is 01 00, not OP_0 |
| 3 | 1 or more | bytes | n/a | event_id | typically a 16-byte UUID; stored as hex |
| 4 | 1 or more | bytes | n/a | subject_user_id | typically a 16-byte UUID |
| 5 (optional) | 1 or more | bytes | n/a | object_user_id or payload | see the rules for 6 elements below |
| 6 (optional) | 8 | uint64 | big-endian | numeric_payload | only with 7 elements |
Element counts:
| Count | Element 5 | Element 6 |
|---|---|---|
| 5 | none | none |
| 6 | 8 bytes: numeric_payload; any other non-zero length: object_user_id | none |
| 7 | object_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":
| Offset | Size | Type | Endianness | Field | Notes |
|---|---|---|---|---|---|
| 0 | 1 | uint8 | n/a | event_kind | |
| 1 | 1 | uint8 | n/a | league_id | |
| 2 | 1 | uint8 | n/a | event_id_len (E) | 1 to 255 |
| 3 | E | bytes | n/a | event_id | |
| 3+E | 1 | uint8 | n/a | subject_len (S) | 1 to 255 |
| 4+E | S | bytes | n/a | subject_user_id | |
| 4+E+S | 1 | uint8 | n/a | object_len (O) | 0 = no object |
| 5+E+S | O | bytes | n/a | object_user_id | only if O > 0 |
| 5+E+S+O | 1 | uint8 | n/a | flags | bit 0 = payload present; other bits ignored |
| 6+E+S+O | 8 | uint64 | big-endian | numeric_payload | only 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.
| Code | Name | Subject | Object | Numeric payload | Effect on totals |
|---|---|---|---|---|---|
| 0x01 | kill | victim | killer (optional) | free | subject deaths +1; object kills +1 (global and league) |
| 0x02 | score | player | none | score delta | subject total_score + payload (global and league) |
| 0x03 | tournament_result | player | optional | final position | subject wins +1 if payload is 1 or 0xFFFFFFFFFFFFFFFF |
| 0x04 | badge_unlock | player | badge id | tier | subject badges +1 |
| 0x05 | shop_burn | player | order or item id | discount | subject shop_burns +1 |
| 0x06 | withdrawal_anchor | player | red-packet id | address prefix | none besides burn |
| other | unknown | none 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):
- The script is at least 6 bytes and starts with
OP_RETURN(src/modules/pokr/pokr_module.cpp:269-272). - Each element is read by
ReadStrictPush:OP_0,OP_1NEGATEandOP_1toOP_16are accepted as elements with no data (pokr_module.cpp:123-127); direct pushes 0x01 to 0x4b as-is (:129-135);OP_PUSHDATA1needs a length of at least 0x4c (:136-146),OP_PUSHDATA2at least 0x100 (:147-159),OP_PUSHDATA4at least 0x10000 (:160-174). Any other opcode, or a push past the end, rejects the output (:175). - More than 16 elements, or none, rejects (
pokr_module.cpp:281-283); the decoder then requires 5 to 7 (pokr_module.cpp:211). - Element 0 is exactly
"POKR"(pokr_module.cpp:285-288, again:213-216). event_kindandleague_idare 1-byte data pushes (pokr_module.cpp:218-222). Because small-integer opcodes carry no data,OP_1orOP_0in these slots rejects the output.event_idandsubject_user_idare non-empty (pokr_module.cpp:224-228).- 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). - 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):
- At least 5 bytes (
pokr_module.cpp:314). event_id_lenandsubject_lenare not 0, and no length runs past the end (pokr_module.cpp:319-331,:336).- A flags byte must be present; with bit 0 set, 8 more bytes must be present (
pokr_module.cpp:342-351). - No trailing bytes (
pokr_module.cpp:353).
Both transports:
- 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-pokrmaxburnwhen it is set (> 0). - 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:
| Column | Type | Notes |
|---|---|---|
txid | TEXT NOT NULL | |
vout | INTEGER NOT NULL | |
block_height | INTEGER NOT NULL | |
block_time | INTEGER NOT NULL | block header time |
kind | INTEGER NOT NULL | event_kind |
league_id | INTEGER NOT NULL | |
event_id | TEXT NOT NULL | lowercase hex |
subject_id | TEXT NOT NULL | lowercase hex |
object_id | TEXT NOT NULL DEFAULT '' | lowercase hex, empty if absent |
numeric_value | INTEGER NOT NULL DEFAULT 0 | payload; a uint64 of 2^63 or more is stored as a negative int64 |
sats | INTEGER NOT NULL | burned value |
source | TEXT 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:
| Table | Key | Columns |
|---|---|---|
pokr_user_stats | user_id | kills, 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_meta | key | last_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 IGNOREthensqlite3_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_statsandpokr_league_standings,(date, kind, league)inpokr_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_eventswas right in older databases (keyed rows, deleted on disconnect, first segment of an output, full output value); only the totals were wrong. AtInit, a database withoutdata_version2 gets its three totals tables rebuilt frompokr_eventsin 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 undercs_mainand the module mutex after checking that the block is still on the active chain (otherwise the rescan stops, stateaborted).last_indexed_heightonly 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):
{"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.
| Method | Path | Parameters | Answer |
|---|---|---|---|
| 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>/events | page (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/burns | days (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/activity | page, pageSize (default 25, 1..100) | {"activity":[event...]} newest first |
| GET, POST | /api/v1/poker/rescan | 403 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>:xgoes throughatoi, so a non-number means league 0 (pokr_module.cpp:1035). Any sub-route other thanstandingsgives 404./poker/burnswithoutleague_idsums every league (fixed in 12.4.6: the days limit was bound to the wrong placeholder,LIMIT NULLfailed and the answer was always empty).dayslimits the number of distinct dates returned, not a time window.lastIndexedHeightfalls back to the highest event height when the meta key is missing (pokr_module.cpp:614-627)./poker/rescananswers403 rescan_moved; rescans run on the authenticated RPCrescanmodule pokras 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_eventsand 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_payloadvalues of 2^63 or more are stored and returned negative; ascorewith such a payload lowers the total.- An event with 0 sats is not indexed (default minimum 1).
/api/v1/moduleslistspokrwith empty version, db path and schema 0 (noInfo()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):
6a 04 504f4b52 01 01 01 00
10 00112233445566778899aabbccddeeff
10 11111111111111111111111111111111
10 22222222222222222222222222222222| Bytes | Meaning |
|---|---|
6a | OP_RETURN |
04 504f4b52 | push 4: "POKR" |
01 01 | push 1: event_kind = 1 (kill) |
01 00 | push 1: league_id = 0 |
10 0011...eeff | push 16: event_id |
10 1111...11 | push 16: subject (victim) |
10 2222...22 | push 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):
6a 50 32 504f4b52 03 01 10 00112233445566778899aabbccddeeff 10 11111111111111111111111111111111 00 01 00000000000000016a 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 platformpoker),doc/lotus-poker-nft-v1.md(NFT metadata that refers to POKR event ids).
