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 payout defines how the stakes of a gnofly arena round are shared
 5// out once the round is over: a Rule turns what happened, who died and by
 6// whose hand, into who gets what.
 7//
 8// The package is pure: it holds no state, moves no coin and knows nothing
 9// about roles. A realm keeps the stakes, asks a rule for a Result and makes
10// the payments itself:
11//
12//	players, err := payout.ParsePlayers("g1aaa...,g1bbb...,g1ccc...")
13//	if err != nil {
14//		panic(err)
15//	}
16//	deaths, err := payout.ParseDeaths("g1bbb...:g1aaa...;g1ccc...:")
17//	if err != nil {
18//		panic(err)
19//	}
20//	g := payout.Game{Stake: 10000000, Lives: 3, KillTarget: 0, FeeBps: 500}
21//	res, err := payout.Lookup(payout.ModeDeathmatch).Settle(g, players, deaths)
22//
23// Two rules ship with the package, both stateless values with no field:
24//
25//   - BattleRoyale: the pot goes to the players still in at the end, or to
26//     the last one out;
27//   - Deathmatch: the pot goes to the top three by kills, 60%, 30% and 10%.
28//
29// Every rule conserves the pot. For any input a rule accepts,
30//
31//	sum(res.Payouts) + res.Fee == Stake * len(players)
32//
33// and nobody but a player of the round is ever paid. What is not paid to a
34// player is the house's cut, the fee. Amounts are rounded down, and what
35// rounding leaves over goes to the fee. A realm that pays out real coins
36// should still check both properties on the Result it gets before it sends
37// anything: that check is cheap, and it is what keeps a mistake in a rule
38// from becoming a loss.
39package payout