Docs · KadeGG

01 / PROTOCOL

Protocol and security model

All staked tokens are held by kade_escrow, an Anchor program deployed on Solana mainnet. The program is deliberately small: five instructions move tokens, and each is limited to a single operation. No instruction in the program transfers tokens out of escrow to any account other than the depositing player's wallet.

The accounts

Config holds the referee key, the treasury address, the rake and the exit grace period. An administrative key may rotate these values and nothing else. It has no authority over player funds.
Match is opened and closed by the referee. Settlement occurs only within an open match. Once a match is closed, every player may withdraw immediately.
Stake is one account per wallet per match. It is the authority over that wallet's escrow token accounts, one per deposited mint. Its derivation includes the player's wallet, so it can sign only through instructions that verify the player's signature or through the referee's constrained settle path.

The instructions

instruction	who signs	what it can do
`deposit`	player	Transfers tokens from the player's wallet into their escrow. The match must be open. A deposit also clears a pending exit request and re-enters the player.
`settle`	referee	Transfers tokens from a loser's escrow to a winner's escrow within the same match, less the rake, which is sent to the treasury. Rejected once the loser's exit grace period has elapsed.
`request_exit`	player	Starts the exit grace period. After it elapses, no settlement can be made against the player.
`withdraw`	player	Transfers the full escrow balance of one mint back to the player's wallet. Permitted only after the match has closed or the player's grace period has elapsed.
`reclaim_escrow`	player or referee	Closes an empty escrow token account and refunds its rent to the signer. An account holding a balance cannot be closed.

Limits on the referee

The game server authorises joins and submits settlements. It cannot call withdraw on a player's behalf, cannot transfer tokens to any address outside the program, cannot settle between two different matches, and cannot set the rake above the hard cap. These constraints are enforced by the program itself, not by operating policy.

Current parameters

rake	`2%` of every eat, capped in code at `5%`
exit grace	`30 s`, program bounds 1 s to 600 s
tokens moved with	`transfer_checked` through the token interface, so plain SPL and Token-2022 coins both work
on-chain tests	17 behavioural tests and 3 adversarial tests, run against a local validator on every program change

Liveness

Withdrawal does not depend on the availability of the website or the game server. A player can call request_exit from any Solana client, wait for the grace period to elapse, and call withdraw for each mint. The grace period exists so that a running server can still record an elimination that occurred shortly before the exit request. An unavailable server cannot extend it.

Trust assumptions

The program is upgradeable. The upgrade authority can deploy a new version of the program. That authority is currently held by the founder. Transferring it to a multisig or revoking it is planned; until then, this is the primary trust assumption.
Token-2022 transfer fees belong to the token. stonkfun.xyz coins carry a transfer fee that is charged on deposit and on every settlement. It is distributed to the token's holders exactly as on any exchange, and the amount received in escrow is net of that fee.

02 / BEST PRACTICES

Best practices

Burner wallets

A burner wallet is a keypair stored unencrypted in the browser. This allows the page to sign without an extension, and it also means any script running on the device, or anyone with access to it, can extract the key. Keep the value held in a burner below approximately 0.25 SOL, export the key from the wallet menu before funding it, and use a connected wallet for any amount that matters.

Position sizing

The entire escrow balance is at risk while a player is in the arena, in proportion to each cell that is eaten. Deposit a portion of a position rather than a position held for other reasons. The minimum seat is worth 0.02 SOL; a few dollars is sufficient for a starting cell.

Exiting

Leave the arena.
Select cash out on the keeps page. This submits request_exit.
Wait for the 30 second grace period. An elimination that occurred shortly before the request can still be settled during it.
Withdraw each mint. The page submits these transactions and reclaims the emptied escrow accounts so their rent is returned.

Do not continue playing after requesting exit. Once the grace period has elapsed the player can no longer be settled against, the referee removes them from the arena, and a new deposit is required to re-enter.

Multi-mint deposits

A player who deposits more than one mint enters as the mint with the highest value, and every mint is at risk proportionally when a cell is eaten. Depositing a single mint is recommended.

Verification

Confirm that the program id shown in the wallet prompt is HUj1wtymfjuPLk89Uh5M1iCZCtAiffW6fLqqQN4YRrCK.
Each escrow is a token account owned by the player's Stake PDA and can be inspected on any explorer. Every settlement emits a Settled event carrying the loser, the winner, the amount and the rake.
The history panel on the keeps page is derived from those program events rather than from an internal database.

Server restarts

A server deployment restarts the arena. Escrows are unaffected, but every active seat is dropped and players must rejoin. Deployments are scheduled for low-traffic periods.

03 / GAME MECHANICS

Game mechanics

Every cell carries two kinds of mass. Token mass is derived from the player's deposited bag. Food mass comes from pellets. Both contribute to on-screen size; only token mass corresponds to value on chain.

Token mass

On entry the referee records a price for each deposited mint. The bag's SOL value at those prices determines the player's token mass for the duration of the session. Price movement during the session does not change it.
1 SOL of value corresponds to 4,000 mass. Token mass is floored at 20 and capped at 20,000 regardless of bag value.
When a cell is eaten, the share of the victim's bag backing that cell is settled to the eater's escrow and is carried at the victim's entry price.

Food mass

Pellets are worth 1 mass each. The smallest map holds 900; the count scales with area.
Food mass decays at 0.4% per second.
A staked player's food mass cannot exceed 2× their token mass. Free play is uncapped, as it has no token mass.
Food mass never leaves the arena as tokens and has no on-chain value.

Size and speed

Radius is 4 + 6·√mass, so size grows sub-linearly with mass.
Speed is 520 px/s at mass 10 and scales with mass^-0.35.
Speed is proportional to cursor distance, reaching full speed at 2.5 radii from the cell, with a short momentum constant to smooth steering.

Eating

An eater must have at least 1.25× the mass of the cell it eats.
The victim's centre must lie inside the eater's radius minus 0.4× the victim's radius.
Eating transfers the victim cell's food mass and its share of the victim's bag. Losing the last cell is an elimination.
Same mint, same team. Players entered as the same mint cannot eat each other.

Split, merge, eject

split `space`	Each cell of at least `32` mass divides toward the cursor with a `780 px/s` boost, up to `16` cells. Bag share divides with the cell.
merge	Split cells may rejoin after `15 s + 20 ms × mass`. Until then they collide.
eject `W`	Ejects `12` mass of food from each cell of at least 30 mass. Only food mass can be ejected; token mass cannot leave a cell this way.

Spawning and the arena

A newly spawned cell is shielded for 5 s, during which it can neither eat nor be eaten.
The arena scales with player count: a 6,000 px side at 40 players, growing with the square root of the head count up to 30,000. Food count scales with area.
The viewport grows with the player's size, up to 4×.
The simulation runs at 60 Hz and clients receive snapshots at 30 Hz. The server is authoritative; the client sends only cursor position and split and eject inputs.

Two arenas

Free. No wallet and no deposit. Players still enter as a graduated stonkfun.xyz ticker and the same-mint rule applies. Food mass only.
Keeps. A signed wallet and a deposited bag. Every eat is settled on chain.

04 / FAIRNESS

Fairness

Price manipulation

Bags are priced at entry, not continuously. Moving a thinly traded coin during a session does not change any player's size. Size is obtained only by depositing value, which is itself at risk.

Size cap

Token mass is capped at 20,000, approximately 5 SOL of value. Additional deposits above that do not increase size. The viewport is also capped, so no player can observe the entire map.

Minimum stake

A seat requires at least 0.02 SOL of value, and a staked cell's food mass is capped at twice its token mass. A negligible deposit cannot be grown into a large cell that threatens real bags at no on-chain risk.

Spawn protection

A five second shield applies in both directions: a newly spawned cell can neither be eaten nor eat.

Client authority

The client holds no authority. It transmits cursor position and two inputs. Mass, position, eats and prices are determined on the server and confirmed on chain.

Price integrity

Entry prices are sourced from Jupiter with the trade tape as a cross-check, and a mint whose price cannot be established is refused at join. Mints with a freeze authority, a transfer hook, a permanent delegate or a non-transferable extension are refused, since such tokens could be frozen or moved while in escrow.

Settlement integrity

If the referee cannot fund the rent required to record a settlement, joins are closed and settlements are refused before submission. After every settlement attempt, successful or not, the arena state is reconciled against the escrows. On-chain state is authoritative.

Fee transparency

The rake is a value in the program's config, hard-capped at 5%, and every Settled event records the exact amount taken. No other fee is charged by the protocol.

Note that players entered as the same mint are allies by design. Coordination between holders of the same coin is expected and permitted.

05 / RULES

Rules of play

Only graduated stonkfun.xyz coins may enter. Bonding-curve coins are refused at join in both arenas. The house coin is the sole exception.
A staked seat requires a signed wallet. A keeps join carries the wallet's signature over a server-issued nonce. Free play does not sign.
The minimum stake is 0.02 SOL of value. Mints with a freeze authority, transfer hook, permanent delegate or non-transferable extension are refused.
A player enters as their most valuable mint. When several mints are deposited, all of them are at risk.
Eating requires 1.25× the victim's mass and the victim's centre inside the eater. Players entered as the same mint cannot eat each other.
Every eat is settled on chain for the eaten cell's share of the loser's bag, less a 2% rake and the token's own transfer fee.
Exit is request, grace, withdraw. During the 30 second grace period an elimination that has already occurred can still be settled. After it, no settlement can be made against the player and they are removed from the arena.
A new deposit re-enters a player. A deposit clears a pending exit request. There is no other way to re-enter.
A closed match releases every escrow. When the referee closes the match, settlement stops and every player may withdraw immediately.
Food mass has no on-chain value. Pellet mass never leaves the arena and cannot be converted to tokens.
A server restart drops every seat. Escrows are unaffected; players must rejoin.

Where this document and the program differ, the program is authoritative. Source: program/programs/kade_escrow/src/lib.rs.