BINGO_PLAY — Group 17, Code 1
A group bingo game played for CloudCoin. Each play sends the player’s card and a locker holding at least 1 CC. The coins go into a shared pot. The first card to complete a line against the balls drawn so far wins a configurable share of the pot as a new locker.
IMPLEMENTED, NOT YET DEPLOYED (16 November 2026)
The server side is written and unit-tested in the RAIDAX repository (bingo.c, docs/bingo.md) but no RAIDA answers Group 17 yet.
Quick reference
| Command Group | 17 (Bingo) |
| Command Code | 1 (0x01) |
| Host | RAIDA 3 only. Every other RAIDA answers 18 ERROR_WRONG_RAIDA. |
| Server function | cmd_bingo_play in bingo.c |
| Body layout | Challenge (16) + card (25) + entry locker key (16) + reserved (32) + terminator (2) = 91 bytes |
| Transport | TCP only. The server waits for its core to download the entry locker, typically 2–10 s. |
| Encryption | Any type the node allows, including Type 0 |
| Authentication | None. The entry locker is the payment. |
| Cost | The full value of the entry locker, which must be at least 1 CC |
| Responses | 247 win, 248 lose, 249 no bingo, all with the body below |
How the game works
- One game. RAIDA 3 keeps a single drum of 75 balls and a single pot. Every minute it draws one ball, uniformly at random, into its list of called balls.
- The called balls are secret. No command and no reply reveals them. A play learns only whether its card has won.
- Every play pays. The server downloads the entry locker into its own wallet and adds the whole value to the pot. A locker can hold any coin or coins, as long as their combined value is at least 1 CC.
- Winning. The server checks the card against the called balls. Any full row, column or diagonal wins, and the free centre square counts as marked. The first play that completes a line wins. Plays are checked one at a time, so there is exactly one winner per round.
- The payout is
floor(pot × payout_percent / 100)whole CloudCoins, put into a new locker made by the server.payout_percentis set in the server’s configuration (default 90; 100 pays the whole pot). What is not paid out, the percentage cut plus any fraction lost by rounding down, stays with the server. - Reset. After a win the pot is set to zero, every called ball goes back into the drum, and the round number goes up by one. For the next 60 seconds no balls are drawn and every play is answered 248 (Bingo, you lose). Coins paid during that minute go into the new pot. Drawing then resumes.
- Server restart. The game lives only in the server’s memory. If RAIDA 3 restarts, the round in progress has no winner and everything starts over: round 1, an empty pot and a full drum. Coins already paid in are not returned, and a retry of an old entry key is answered 96.
- Empty drum. If all 75 balls are drawn with no winner, every valid card has a line, and the next valid play wins.
The card
The client creates a random card when the game starts and sends it with every play. It may change the card between plays: each play is a separate paid ticket.
| Column | B | I | N | G | O |
|---|---|---|---|---|---|
| Numbers | 1–15 | 16–30 | 31–45 | 46–60 | 61–75 |
The card is 25 bytes in row-major order: cell (row r, column c) is byte 5r + c, row 0 is the top row and column 0 is B. The centre cell (r = 2, c = 2, byte 12) is the free square and must be 0. Every other cell must hold a number from its column’s range, and no number may appear twice. A card that breaks these rules is answered 95 and nothing is taken.
Request body
| Offset | Size | Field | Description |
|---|---|---|---|
| 0–15 | 16 | Challenge | 12 random bytes followed by their big-endian CRC32. |
| 16–40 | 25 | card | The bingo card, laid out as above. |
| 41–56 | 16 | entry_locker_key | The locker key the client gave its core when it stored the coins (/api/transactions/locker/put-no-sum). Exactly two groups joined by one dash (GROUP-GROUP, at most 16 characters in all), from ABCDEFGHJKMNPQRSTUVWXYZ23456789, padded with NUL bytes at the end. Upper case only, and none of the characters that can be confused (0, 1, I, L, O). The core builds the locker from the first two groups only, so a third group is refused. Use a new key for every play. |
| 57–88 | 32 | reserved | Reserved for future use. Send zeros. The server ignores these bytes today, so a later client can use them without changing the length. |
| 89–90 | 2 | Terminator | 3E 3E. |
Response body
Statuses 247, 248 and 249 carry this body. All integers are big-endian. Errors return the header only.
| Offset | Size | Field | Description |
|---|---|---|---|
| 0–3 | 4 | round_id | The round this play counted in. On a 248 it is the new round whose pot the coins joined. |
| 4–11 | 8 | entry_units | What this play added to the pot, in units of 10−8 CC. |
| 12–15 | 4 | payout_cc | Whole CloudCoins won. Set on 247 only, otherwise 0. It can be 0 even on a 247 when the pot was too small to round up to a whole coin. |
| 16–31 | 16 | payout_locker_key | The locker holding the winnings, XXXXXXX-XXXXXXXX in the same alphabet as the entry key. Set on 247 when payout_cc > 0, otherwise all zeros. |
| 32–33 | 2 | fields_present | Bit mask of the optional fields below. Bit n set means field n is filled in. A clear bit means “not supplied”, never zero. Always 0 today. |
| 34–35 | 2 | call_number | Bit 0. Balls called this game: 1 at the first ball, one more each minute, back to 1 after a win. |
| 36–39 | 4 | players | Bit 1. Players in this round. |
| 40–47 | 8 | pot_units | Bit 2. The pot after this play, in units of 10−8 CC. |
| 48 | 1 | balls_on_card | Bit 3. How many called balls are on the player’s card. |
| 49 | 1 | chat_flags | Bit 4. Bit 0 set: someone wants to chat with this player. |
| 50–54 | 5 | chat_mailbox | Bit 4. That person’s mailbox: denomination (1) + serial number (4). |
| 55–95 | 41 | reserved | Zeros. |
| 96–97 | 2 | Terminator | 3E 3E. |
The optional fields are reserved so they can be turned on later without changing the layout. None is filled in yet. A client should read a field only when its bit in fields_present is set, so clients written today keep working when a field is turned on.
Status codes
| Code | Symbol | Meaning |
|---|---|---|
| 247 | STATUS_BINGO_WIN | Bingo, you win. The body carries the payout locker. |
| 248 | STATUS_BINGO_LOSE | Bingo, you lose. Someone won within the last minute. Your coins went into the next pot. |
| 249 | STATUS_NO_BINGO | No bingo yet. Your coins are in the pot. |
| 95 | ERROR_BINGO_BAD_CARD | The card breaks the rules above. Nothing was taken. |
| 96 | ERROR_BINGO_LOCKER_EMPTY | The locker key is malformed, or the locker is empty or worth less than 1 CC. Normally nothing is taken. If the locker’s value fell below 1 CC between the server’s peek and its download, the downloaded coins go into the pot, but the play does not count. |
| 18 | ERROR_WRONG_RAIDA | This RAIDA does not host the game. Send to RAIDA 3. |
| 16 | ERROR_INVALID_PACKET_LENGTH | The body is not 91 bytes. |
| 218 | ERROR_TCP_REQUIRED | Sent over UDP. Use TCP. |
| 251 | ERROR_SERVER_BUSY | Too many plays in progress (on the server, or two already from your IP address), the same locker key is already being processed, or the rate limit was reached. Retry with the same locker key. |
| 252 | ERROR_INTERNAL | Server-side failure. Also returned when an earlier attempt with this key was interrupted mid-download and the locker is now empty: the coins may have reached the server, and the operator has a log entry to reconcile it. |
| 253 | ERROR_NETWORK | The server could not reach its core, or the download failed or timed out. Retry with the same locker key: the server checks again whether the coins are still in the locker. |
How a client should use it
- At game start, generate a random card that follows the rules above.
- Every minute: make a new locker key, store at least 1 CC from the Default wallet in it through the local core (
/api/transactions/locker/put-no-sum?locker_key=K&amount=1), then send BINGO_PLAY with the card and K to RAIDA 3 over TCP. - Retries are safe. The server remembers every entry key and answers a repeat with exactly the reply it gave the first time. After a timeout or a lost connection, send the same request again with the same key. Never make a new locker for a retry. This is how a winner who lost the 247 reply gets the payout key again.
- On 247, download the payout locker into the Default wallet (
/api/locker/download). The server makes the payout locker in the background right after it answers, so the locker can still be empty for a few seconds, or longer if the server’s core is briefly unavailable. Keep retrying the download until it succeeds. - Presentation is up to the client. The reference game shows a white cloud descending on the player’s avatar with gold coins raining down on 247 (“The Gods have provided N CloudCoins!”), an earthquake on 248, and nothing on 249.