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 Group17 (Bingo)
Command Code1 (0x01)
HostRAIDA 3 only. Every other RAIDA answers 18 ERROR_WRONG_RAIDA.
Server functioncmd_bingo_play in bingo.c
Body layoutChallenge (16) + card (25) + entry locker key (16) + reserved (32) + terminator (2) = 91 bytes
TransportTCP only. The server waits for its core to download the entry locker, typically 2–10 s.
EncryptionAny type the node allows, including Type 0
AuthenticationNone. The entry locker is the payment.
CostThe full value of the entry locker, which must be at least 1 CC
Responses247 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_percent is 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.

ColumnBINGO
Numbers1–1516–3031–4546–6061–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

OffsetSizeFieldDescription
0–1516Challenge12 random bytes followed by their big-endian CRC32.
16–4025cardThe bingo card, laid out as above.
41–5616entry_locker_keyThe 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–8832reservedReserved for future use. Send zeros. The server ignores these bytes today, so a later client can use them without changing the length.
89–902Terminator3E 3E.

Response body

Statuses 247, 248 and 249 carry this body. All integers are big-endian. Errors return the header only.

OffsetSizeFieldDescription
0–34round_idThe round this play counted in. On a 248 it is the new round whose pot the coins joined.
4–118entry_unitsWhat this play added to the pot, in units of 10−8 CC.
12–154payout_ccWhole 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–3116payout_locker_keyThe 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–332fields_presentBit 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–352call_numberBit 0. Balls called this game: 1 at the first ball, one more each minute, back to 1 after a win.
36–394playersBit 1. Players in this round.
40–478pot_unitsBit 2. The pot after this play, in units of 10−8 CC.
481balls_on_cardBit 3. How many called balls are on the player’s card.
491chat_flagsBit 4. Bit 0 set: someone wants to chat with this player.
50–545chat_mailboxBit 4. That person’s mailbox: denomination (1) + serial number (4).
55–9541reservedZeros.
96–972Terminator3E 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

CodeSymbolMeaning
247STATUS_BINGO_WINBingo, you win. The body carries the payout locker.
248STATUS_BINGO_LOSEBingo, you lose. Someone won within the last minute. Your coins went into the next pot.
249STATUS_NO_BINGONo bingo yet. Your coins are in the pot.
95ERROR_BINGO_BAD_CARDThe card breaks the rules above. Nothing was taken.
96ERROR_BINGO_LOCKER_EMPTYThe 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.
18ERROR_WRONG_RAIDAThis RAIDA does not host the game. Send to RAIDA 3.
16ERROR_INVALID_PACKET_LENGTHThe body is not 91 bytes.
218ERROR_TCP_REQUIREDSent over UDP. Use TCP.
251ERROR_SERVER_BUSYToo 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.
252ERROR_INTERNALServer-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.
253ERROR_NETWORKThe 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

  1. At game start, generate a random card that follows the rules above.
  2. 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.
  3. 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.
  4. 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.
  5. 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.