v0 state

version

// bumps on every admin write, see Version

arenas

// arena id -> \*arena, with its lobby and its round

results

// arena id -> encoded result, see results.gno

closed

The whole state of the realm. Everything is unexported and nothing below is ever returned by reference: the trees are /p/ types with mutator methods, so handing one out would be handing out write access to the realm.

refundDelay

// seconds after a game's time limit before anyone may refund it

escrowed

// ugnot owed to players: the stakes of every lobby and running game, and their unclaimed winnings

claims

// player address -> encoded credits

earnings

// player address -> encoded totals, allocated on a first settled game

winners

// the top players by winnings

webPath

// "/r/g1t2kg2vtr3fukg43eujkn6x53gfdyakhngt4sfd/gnofly/arena/v0", used to build links in Render

defaultRefundDelay

// seconds

init.11

bootstrap

bootstrap (re)creates the initial state. The tests call it to start from a clean slate.

Version

Version returns a counter that bumps on every admin write: the refund delay. Player and referee actions do not bump it.

now

now returns the block time in Unix seconds.

webPathOf

webPathOf turns "gno.land/r/..." into "/r/...".

itoa

claimCredit

claimCredit is what one game owes one player.

creditsOf

credit

credit owes amount to a player for the game of an arena. The coins are already in the realm: they stay in the escrow until claimed.

Claim

Claim sends the caller everything the realm owes them from settled games, and returns the amount in ugnot. It panics when there is nothing to claim.

Claimable

Claimable returns what a player can claim, in ugnot.

ClaimsJSON

ClaimsJSON returns what a player can claim, game by game, oldest first: { "address": "g1...", "total": 19000000, "games": [ { "id": "...", "amount": 19000000 } ] } The output has no whitespace. An address with nothing to claim returns the same shape with a zero total and no game.

topSize

topSize is how many players the list of top winners holds.

totals

totals is what the realm remembers about one player.

totalsOf

totalsOf returns the totals of a player, zero for a player who never finished a round.

creditRound

creditRound records a settled round for each of its players: one more round played, and what they were paid above their stake, if anything.

ranking

ranking is the list of top winners: the players who won the most, best first, at most topSize lines and one line per player. With equal winnings, the player who got there first stays ahead. It is the ranking of the game realm. It is kept sorted at write time, so reading it never has to look at every player. Winnings only going up is what makes that exact: a player outside the list can only enter it through raise. The two slices are parallel: slices of plain values are one stored object each, where a slice of structs would be one object per line.

spliceAddrs

spliceInts

spliceInts is spliceAddrs for a column of numbers.

errSpoofedRealm

Errors are values created once, at package init: a panic with one of them costs no allocation. Messages that need a value are built at the call.

errNotOwner

Errors are values created once, at package init: a panic with one of them costs no allocation. Messages that need a value are built at the call.

errNotAdmin

Errors are values created once, at package init: a panic with one of them costs no allocation. Messages that need a value are built at the call.

errNotReferee

Errors are values created once, at package init: a panic with one of them costs no allocation. Messages that need a value are built at the call.

errInvalidSpec

Errors are values created once, at package init: a panic with one of them costs no allocation. Messages that need a value are built at the call.

errInvalidMode

Errors are values created once, at package init: a panic with one of them costs no allocation. Messages that need a value are built at the call.

errInvalidStake

Errors are values created once, at package init: a panic with one of them costs no allocation. Messages that need a value are built at the call.

errInvalidSeats

Errors are values created once, at package init: a panic with one of them costs no allocation. Messages that need a value are built at the call.

errInvalidLives

Errors are values created once, at package init: a panic with one of them costs no allocation. Messages that need a value are built at the call.

errInvalidSeconds

Errors are values created once, at package init: a panic with one of them costs no allocation. Messages that need a value are built at the call.

errInvalidKillTarget

Errors are values created once, at package init: a panic with one of them costs no allocation. Messages that need a value are built at the call.

errRoyaleTarget

Errors are values created once, at package init: a panic with one of them costs no allocation. Messages that need a value are built at the call.

errInvalidAddress

Errors are values created once, at package init: a panic with one of them costs no allocation. Messages that need a value are built at the call.

errInvalidRefundDelay

Errors are values created once, at package init: a panic with one of them costs no allocation. Messages that need a value are built at the call.

errUnknownArena

Errors are values created once, at package init: a panic with one of them costs no allocation. Messages that need a value are built at the call.

errNotUserCall

Errors are values created once, at package init: a panic with one of them costs no allocation. Messages that need a value are built at the call.

errEntryClosed

Errors are values created once, at package init: a panic with one of them costs no allocation. Messages that need a value are built at the call.

errNotYetCreated

Errors are values created once, at package init: a panic with one of them costs no allocation. Messages that need a value are built at the call.

errInvalidTicket

Errors are values created once, at package init: a panic with one of them costs no allocation. Messages that need a value are built at the call.

errAlreadyInLobby

Errors are values created once, at package init: a panic with one of them costs no allocation. Messages that need a value are built at the call.

errLobbyFull

Errors are values created once, at package init: a panic with one of them costs no allocation. Messages that need a value are built at the call.

errNotInLobby

Errors are values created once, at package init: a panic with one of them costs no allocation. Messages that need a value are built at the call.

errNotExpired

Errors are values created once, at package init: a panic with one of them costs no allocation. Messages that need a value are built at the call.

errRoundRunning

Errors are values created once, at package init: a panic with one of them costs no allocation. Messages that need a value are built at the call.

errTooFewPlayers

Errors are values created once, at package init: a panic with one of them costs no allocation. Messages that need a value are built at the call.

errNoRound

Errors are values created once, at package init: a panic with one of them costs no allocation. Messages that need a value are built at the call.

errRefundTooEarly

Errors are values created once, at package init: a panic with one of them costs no allocation. Messages that need a value are built at the call.

errBadSettlement

Errors are values created once, at package init: a panic with one of them costs no allocation. Messages that need a value are built at the call.

errNotConserved

Errors are values created once, at package init: a panic with one of them costs no allocation. Messages that need a value are built at the call.

errEscrow

Errors are values created once, at package init: a panic with one of them costs no allocation. Messages that need a value are built at the call.

errInsolvent

Errors are values created once, at package init: a panic with one of them costs no allocation. Messages that need a value are built at the call.

errNothingToClaim

Errors are values created once, at package init: a panic with one of them costs no allocation. Messages that need a value are built at the call.

errCorruptClaims

Errors are values created once, at package init: a panic with one of them costs no allocation. Messages that need a value are built at the call.

errCorruptResult

Errors are values created once, at package init: a panic with one of them costs no allocation. Messages that need a value are built at the call.

errCorruptEarnings

Errors are values created once, at package init: a panic with one of them costs no allocation. Messages that need a value are built at the call.

payDenom

payDenom is the only coin the realm deals in.

hold

hold records that the realm received amount in stakes.

release

release takes amount out of what the realm owes. It is called before the coins are sent, and it panics rather than let the counter go below zero.

pay

pay sends amount ugnot from the realm's own balance to an address. A RealmSend banker can spend everything the realm holds, which is why it is built here and only here, from the live cur of the crossing function (rlm), and never kept. The bank aborts the transaction if the realm does not have the coins.

assertSolvent

assertSolvent panics unless the realm holds at least what it owes.

Escrowed

Escrowed returns what the realm owes to players, in ugnot: the stakes of every lobby and of every running round. The balance of the realm's address is never below it.

ArenasJSON

ArenasJSON returns every arena someone paid into and whose game is not over, as a JSON array sorted by id: [ { "id": "3f2a...", "mode": "deathmatch", "stake": 10000000, "minSeats": 2, "maxSeats": 8, "lives": 3, "seconds": 900, "killTarget": 5, "creator": "g1...", "created": 1790950000, "nonce": "k3x9", "lobby": [ { "address": "g1...", "ticket": "9f86d0...00a08" } ], "round": { "startedAt": 1790950300, "players": [ "g1...", "g1..." ] } } ] The output has no whitespace. "round" is null until the game starts. The fields from "mode" to "nonce" are the arena's spec: the game server rebuilds the spec string, and so the id, from them.

ArenaJSON

ArenaJSON returns one arena in the shape of ArenasJSON, or null.

writeArena

ResultsJSON

ResultsJSON returns the last closed games, newest first, at most 50: [ { "id": "3f2a...", "mode": "deathmatch", "stake": 10000000, "outcome": "settled", "players": 2, "pot": 20000000, "fee": 500000, "closedAt": 1790951000, "payouts": [ { "address": "g1...", "amount": 19500000 } ] } ]

ResultJSON

ResultJSON returns the result of one closed game in the shape of ResultsJSON, or null when the realm does not have it (still running, or too old).

writeResult

EarningsJSON

EarningsJSON returns the top winners as a JSON array, best first, at most 10 entries: [ { "address": "g1...", "won": 19000000, "rounds": 3 } ] The output has no whitespace. "won" adds up, round after round, what the player was paid above their own stake, never less than zero for a round. "rounds" is how many settled rounds they played. With equal winnings, the player who got there first stays ahead.

PlayerJSON

PlayerJSON returns one player's totals as a JSON object: { "address": "g1...", "won": 19000000, "rounds": 3 } The output has no whitespace. An unknown address returns the same shape with zero won and zero rounds.

writeTotals

writeTotals writes the totals of a player. quoted is the player's address as a JSON string literal, quotes included.

quote

quote returns s as a JSON string literal, quotes included. It is for the strings the realm did not validate. Quotes and backslashes are escaped and anything outside printable ASCII is replaced by "?", so the result is valid JSON whatever s holds.

arena

arena is one game: its spec, the players who paid and wait, and once it started, its round. It is stored from the first paid entry and deleted when its round is closed or its lobby empties.

getArena

mustArena

Enter

Enter puts the caller in the lobby of the arena that spec describes, and returns its id. The exact stake must be attached to the transaction (-send "\<stake>ugnot") and stays in the realm until the player leaves or the game is over. The first entry creates the arena, the next ones join it: the realm recomputes the id from the spec every time. An arena takes entries for an hour after it was created, and until its game starts. ticket is 64 lowercase hex characters, the SHA-256 of a secret the player's client made up: the game server gives the seat to whoever shows the secret. It must be called directly by a user (maketx call): a call relayed by another realm or by a maketx run script is refused.

Leave

Leave takes the caller out of the lobby of an arena and sends their stake back. It works until the game starts. The last player out deletes the arena: nothing is left on chain of a game nobody played.

ExpireLobby

ExpireLobby closes an arena whose game never started: every player in the lobby gets their stake back, and the arena is deleted. Anyone can call it once the arena stopped taking entries, an hour after it was created.

withAddr

withString

withString returns list with v added at the end.

withoutAddr

withoutString

withoutString returns list without the element at index at.

Render

Render returns the state of the arenas as markdown, for gnoweb: "" the open arenas and the last games played "arena/<id>" one arena: its rules, lobby and game, or its result "earnings" the top winners Everything printed here was validated against a narrow charset when it was written (see spec.gno and validate.gno), or is an address the chain gave the realm. The only caller-supplied value, the id of an arena page, is printed only if it is a valid id. Nothing needs markdown escaping.

link

link returns the gnoweb URL of a Render path of this realm.

renderHome

renderArena

renderResult

targetCell

targetCell formats a kill target: most arenas end on the clock only.

paidCell

paidCell lists who was paid what in a round, for a table cell.

renderEarnings

modeDoc

modeDoc is one sentence about the payout rule of a mode.

gnot

gnot formats an amount of ugnot in GNOT, without trailing zeros: 10000000 gives "10 GNOT", 9500000 gives "9.5 GNOT", 1 gives "0.000001 GNOT".

percent

percent formats basis points as a percentage, without trailing zeros: 500 gives "5%", 250 gives "2.5%", 1 gives "0.01%".

clock

clock formats a block time in Unix seconds, in UTC.

result

result is how a game ended, kept for readers: no payment is ever computed from it.

outcomeSettled

outcomeCancelled

outcomeRefunded

maxResults

maxResults is how many closed games the realm remembers.

decodeResult

record

record keeps the result of a closed game, and forgets the oldest one past maxResults.

resultOf

resultOf returns the result of a closed game, if the realm still has it.

indexFrom

indexFrom returns the index of the first c in s at or after i, or len(s).

digits

digits parses a non-negative decimal of at most 18 digits.

authority

authority is the set of questions this realm asks about roles.

gameRoles

gameRoles answers with the roles of the game realm.

roles

roles is the authority of this realm: the game realm, always. It is a variable for one reason. Under \`gno test\` an imported realm is initialized without a deployer, and a test of this package has no way to become the owner of the game realm, so the tests put their own answers here. Nothing outside the test files assigns it, and there is no setter.

callerOf

assertOwner

assertAdmin

assertReferee

round

round is the started game of an arena. Its players are fixed at start, and each of them has one stake in it.

StartRound

StartRound starts the game of an arena with every player of its lobby. Referee only. The lobby must hold at least minSeats players; it holds at most maxSeats, Enter sees to that. No coin moves: the stakes that were owed to the lobby are now owed to the round. It returns how many play.

SettleRound

SettleRound closes the game of an arena: it applies the rule of its mode to what happened, pays the players, and pays the fee to the treasury. Referee only. deaths is "victim:killer" entries separated by ";", in the order they happened, "victim:" when nobody shot the victim down, and the empty string when nobody died. A player dies at most as often as the arena has lives. The referee is trusted for these facts and for nothing else. The rule refuses a victim or a killer who is not a player of the round, and decides the amounts. The realm then checks them (see settle) before it pays.

settle

settle closes the game of an arena with the result of its rule. It trusts nothing about the result. Before a counter or a coin moves, checkResult verifies that only players of the round are paid and that the payouts and the fee add up to the pot, to the ugnot.

withFeeShared

withFeeShared returns payouts with fee added, shared between every player of the round, in their order: the remainder goes to the first.

checkResult

checkResult panics unless a result can be paid out of a pot: every payout goes to a player of the round, a player is paid at most once and never zero or less, the fee is not negative, and all of it adds up to the pot exactly. The built-in rules guarantee all of this. The check is here so that the realm does not depend on it: whatever a rule returns, the realm never sends more than the pot, and never to a stranger.

CancelRound

CancelRound closes the game of an arena without a result: every player gets their stake back in full. Referee only. The game server uses it for a game it cannot referee, for example one it finds running when it starts.

RefundRound

RefundRound closes the game of an arena without a result, like CancelRound, and can be called by anyone, once startedAt + seconds + RefundDelay() has passed on the block clock. It is the players' way out when the referee never settles: no stake depends on a server staying up.

refund

refund closes the game of an arena and sends every player their stake back. No fee is taken.

runningArena

runningArena returns an arena whose game is running. It panics for an unknown arena and for one whose game has not started.

minRefundDelay

Refund delay bounds, in seconds.

maxRefundDelay

Refund delay bounds, in seconds.

SetRefundDelay

SetRefundDelay sets how long after a game's time limit anyone may refund it. Admin only.

RefundDelay

RefundDelay returns the refund delay, in seconds.

joinAddrs

joinAddrs writes addresses separated by commas, for an event.

joinPayouts

joinPayouts writes payouts as "address:amount" separated by commas, for an event and for the stored results.

specVersion

Bounds of a spec, the same as the game server's.

idLen

Bounds of a spec, the same as the game server's.

minStake

// ugnot, 1 GNOT

maxStake

// ugnot, 1000 GNOT

minSeconds

// 5 minutes

maxSeconds

// 30 minutes

entryWindow

// seconds an arena takes entries after it was created

clockSkew

// seconds a server clock may run ahead of the chain

maxNonceLen

Bounds of a spec, the same as the game server's.

maxSpecLength

Bounds of a spec, the same as the game server's.

feeBps

Bounds of a spec, the same as the game server's.

spec

spec is a parsed arena spec.

idOf

idOf returns the id of a spec string.

parseSpec

parseSpec reads and checks a spec string. It panics on anything the realm would not play.

validNonce

validNonce reports whether s is 1 to 16 characters of \[a-z0-9].

validID

validID reports whether s can be an arena id: 24 lowercase hex characters.

ticketLen

// a SHA-256 in hex

validTicket

validTicket reports whether s is 64 lowercase hex characters, the SHA-256 of the secret a player's client keeps.

validAddress

validAddress reports whether addr is a valid address in its canonical, lowercase form. Bech32 can also be written in all capitals, and address.IsValid accepts that. Bech32 does not allow mixing cases, so looking at the first character is enough.

indexOfAddr

indexOfAddr returns the index of addr in list, -1 when it is not there. The lists of this realm hold at most 16 addresses.