doc.gno

 1// v0 - Unaudited: This is an initial version that has not yet been formally audited.
 2// Use in production at your own risk.
 3//
 4// Package arena holds the paid games of gnofly, a multiplayer plane game. A
 5// player pays an entry price in ugnot to join a game, the realm keeps the
 6// stakes until the game is over, then credits them by a rule it applies
 7// itself. Winners take what they are owed with Claim.
 8//
 9// Games are created off chain, by the game server at a player's request, and
10// described by a spec (see spec.gno): mode, entry price, seats, lives, game
11// time and kill target. The realm only stores a game once someone paid for
12// it, and forgets it when it is over or its lobby empties: no game nobody
13// played is ever left on chain.
14//
15// Four kinds of callers write to it:
16//
17//   - players enter a game with their stake attached, the first one handing
18//     the realm its spec, and may leave again until it starts (Enter, Leave);
19//   - referees, the game servers, start a game with the players of its lobby,
20//     and report who died by whose hand when it is over (StartRound,
21//     SettleRound, CancelRound);
22//   - anyone can send the stakes of a game back to its players once the
23//     referee is long overdue, and close a lobby whose game never started an
24//     hour after it was created (RefundRound, ExpireLobby);
25//   - the admins of the game realm set the refund delay (SetRefundDelay).
26//
27// The realm keeps no roles of its own: the owner, the admins, the referees
28// and the treasury are those of gno.land/r/g1t2kg2vtr3fukg43eujkn6x53gfdyakhngt4sfd/gnofly/game/v0, asked at
29// the time of each call.
30//
31// The referee is trusted for facts only: who died, and by whom. What these
32// facts are worth is decided by a rule of
33// gno.land/p/g1t2kg2vtr3fukg43eujkn6x53gfdyakhngt4sfd/gnofly/arena/payout/v0, picked by the mode of the game,
34// and the realm checks what the rule returns before it sends anything.
35//
36// # Money
37//
38// The realm owes exactly the stakes of its lobbies and of its running
39// games, and the winnings not claimed yet, and counts them in one number,
40// see Escrowed. Every coin that leaves
41// goes to a player of the game it came from, or to the treasury of the game
42// realm:
43//
44//	Enter        +stake   the envelope of the call stays in the realm
45//	Leave        -stake   back to the player
46//	ExpireLobby  -stakes  back to the players of the lobby
47//	StartRound    0       stakes move from the lobby to the game
48//	SettleRound  -fee     the fee leaves, the rest is credited to the winners
49//	Claim        -owed    everything credited to the caller, every game at once
50//	CancelRound  -pot     back to the players of the game
51//	RefundRound  -pot     back to the players of the game
52//
53// A game is closed by exactly one of SettleRound, CancelRound and
54// RefundRound, once.
55//
56// What a settlement does not pay to the players is the house's cut, a fee of
57// 5% sent to the treasury of the game realm, rounding included.
58//
59// Reads are plain functions meant for vm/qeval. The ones ending in JSON
60// return a single string holding a JSON document. Render exposes the same
61// data as markdown for gnoweb.
62package arena