arena/v0 package

v0 - Unaudited: This is an initial version that has not yet been formally audited. Use in production at your own risk.

Package arena holds the paid games of gnofly, a multiplayer plane game. A player pays an entry price in ugnot to join a game, the realm keeps the stakes until the game is over, then credits them by a rule it applies itself. Winners take what they are owed with Claim.

Games are created off chain, by the game server at a player's request, and described by a spec (see spec.gno): mode, entry price, seats, lives, game time and kill target. The realm only stores a game once someone paid for it, and forgets it when it is over or its lobby empties: no game nobody played is ever left on chain.

Four kinds of callers write to it:

• players enter a game with their stake attached, the first one handing the realm its spec, and may leave again until it starts (Enter, Leave);
• referees, the game servers, start a game with the players of its lobby, and report who died by whose hand when it is over (StartRound, SettleRound, CancelRound);
• anyone can send the stakes of a game back to its players once the referee is long overdue, and close a lobby whose game never started an hour after it was created (RefundRound, ExpireLobby);
• the admins of the game realm set the refund delay (SetRefundDelay).

The realm keeps no roles of its own: the owner, the admins, the referees and the treasury are those of gno.land/r/g1t2kg2vtr3fukg43eujkn6x53gfdyakhngt4sfd/gnofly/game/v0, asked at the time of each call.

The referee is trusted for facts only: who died, and by whom. What these facts are worth is decided by a rule of gno.land/p/g1t2kg2vtr3fukg43eujkn6x53gfdyakhngt4sfd/gnofly/arena/payout/v0, picked by the mode of the game, and the realm checks what the rule returns before it sends anything.

Money

The realm owes exactly the stakes of its lobbies and of its running games, and the winnings not claimed yet, and counts them in one number, see Escrowed. Every coin that leaves goes to a player of the game it came from, or to the treasury of the game realm:

1Enter        +stake   the envelope of the call stays in the realm
2Leave        -stake   back to the player
3ExpireLobby  -stakes  back to the players of the lobby
4StartRound    0       stakes move from the lobby to the game
5SettleRound  -fee     the fee leaves, the rest is credited to the winners
6Claim        -owed    everything credited to the caller, every game at once
7CancelRound  -pot     back to the players of the game
8RefundRound  -pot     back to the players of the game

A game is closed by exactly one of SettleRound, CancelRound and RefundRound, once.

What a settlement does not pay to the players is the house's cut, a fee of 5% sent to the treasury of the game realm, rounding included.

Reads are plain functions meant for vm/qeval. The ones ending in JSON return a single string holding a JSON document. Render exposes the same data as markdown for gnoweb.