GodlRun: How the game works

Naming is pending. The token that GodlRun runs on has not been named yet. Everywhere in this documentation set, $TOKEN is a placeholder for that not-yet-decided token name and ticker. Nothing here should be read as an announcement of a final name.

The short version

GodlRun is a "king of the hill" game built around a single on-chain slot. One address holds that slot at a time. While they hold it, the trading fees generated by $TOKEN's liquidity pool are redirected to them instead of anywhere else. Anyone can take the slot away by paying the current asking price, plus a token deposit, both of which go up a little with every flip. There is a short grace period after each flip during which the new holder cannot immediately be flipped again. If nobody takes the slot before the holder's window runs out, the price and deposit start sliding back down toward a floor, and the first person to buy in at the decayed price takes over.

There is no dice roll anywhere in this system. Every outcome is a direct, deterministic consequence of on-chain state and time. See provably-fair.md for the full argument and how to verify it yourself.

The mechanic, in order

1. Claiming an empty slot. If nobody currently holds the slot, anyone can take it by paying the floor price in ETH and depositing the floor amount of $TOKEN.
2. Holding the slot. For a fixed window after claiming, the holder receives essentially all of the newly arrived LP fees the pool generates for $TOKEN (both the ETH-leg and the token-leg). Fees accrue continuously; they are pulled from the fee source and credited to the holder as they show up.
3. Immunity. Immediately after a holder claims the slot, there is a short immunity period during which nobody can flip them, no matter how much they're willing to pay. This exists purely to stop instant re-flips.
4. Being flipped. After immunity ends, anyone can take the slot from the current holder by paying the live price (which has escalated since the last claim) and putting up the live token deposit (which has also escalated). Each successful flip bumps the price and deposit up by a fixed step for the next challenger.
5. The window ending. The holder's occupancy window lasts 12 hours (the current configured value on the live test deployment, see the note on configured values below). If nobody flips them before it ends, the price and deposit stop escalating and start decaying.
6. Decay. Once a window has expired without a flip, the price and deposit fall away linearly, second by second, back down toward the floor. They decay to the floor over a fixed decay duration and never go below it. The first person to buy in at whatever the decayed price happens to be at that moment takes the slot.

The two settlement paths: read this carefully

This is the part of the mechanic that is easy to get wrong, so it is spelled out precisely.

Path A: a challenger flips the holder WHILE their window is still active (a genuine in-window flip)

• The outgoing holder receives a 75% ETH refund of what they originally paid for the slot. The remaining 25% is retained by the protocol.
• The incoming buyer (the one doing the flipping) receives a 50% token rebate, but on the outgoing holder's deposit, not their own. Concretely: half of what the person being displaced had deposited is credited back to the person doing the displacing. The other half is absorbed permanently.
• Neither the ETH refund nor the token rebate goes back to the outgoing holder's own deposit. Their token deposit is never returned to them, in either settlement path: the only question the mechanic answers is who else benefits from it.

Path B: a challenger takes over AFTER the holder's window has already expired (an expiry takeover)

• The outgoing holder receives 0% ETH refund. They forfeit the entire amount they originally paid.
• The incoming buyer receives no token rebate at all.
• The full 100% of the ETH the outgoing holder originally paid, and the full deposit they put up, are both absorbed by the protocol.

The reasoning: the 75%/50% payouts in Path A only make economic sense because a genuine in-window flip always means the incoming buyer is paying strictly more, and depositing strictly more, than the outgoing holder did. That relationship breaks the moment a window expires and prices start decaying: a challenger can then legitimately pay less than the outgoing holder originally paid. Paying a refund out of that shrinking pool would be able to insolvently deplete funds owed to other users. So expiry is treated as a hard boundary: the holder who let their window lapse already received the full fee stream for their entire occupancy, and their entry cost was the price of that occupancy. They keep nothing back. This exact failure mode was found and fixed during development, see security.md for the full account.

There is no ambiguity about which path applies at settlement time: it is decided purely by comparing the current time against the outgoing holder's own window end, at the instant the flip transaction executes.

Current configured values (test deployment) vs. fixed constants

Some numbers in this mechanic are hard-coded into the contract and cannot be changed after deployment. Others are configurable parameters that the protocol can adjust over time. Below, values are labeled accordingly. All values here reflect the currently deployed test contract on Robinhood Chain. See contracts.md for full deployment details, including why this is a test deployment and not production.

Note on the floor price: the underlying contract's own hard-coded starting value is 0.1 ETH. The currently live test deployment was configured to 0.02 ETH at deploy time, specifically to make full-cycle testing affordable on a small test budget. The mechanic behaves identically at either value: everything scales linearly. A production deployment's floor price will be confirmed at launch and is not yet finalized; treat any value shown in a live UI as authoritative for that specific deployment, not this document.

What you are actually earning

Holding the slot entitles you to the LP trading fees for $TOKEN that accrue during your active window, paid out in both the ETH-equivalent leg and the token leg the pool generates. You withdraw whatever has been credited to you at any time via a simple claim, independent of whether you still hold the slot. See contracts.md for the exact functions involved and faq.md for common questions.