connect4 - staked Connect 4

Context

We want a real-money Connect 4 on gno.land: equal ugnot stakes, winner takes the pot minus a small house fee, fast turns, a lobby of offers open for the next N minutes, and a guarantee both players are present once a game starts.

Two platform facts shape the design:

• time.Now() is the block timestamp. It is deterministic and only advances per block; nothing executes on its own, so deadlines are enforced lazily by whichever transaction checks them.
• Presence cannot be observed on-chain. The only proof a player is there is a transaction they signed.

Decision

• Lobby of offers. Offer escrows the creator's stake with an expiry (1-60 min) and an optional reserved opponent. Accept must send exactly the same stake. Both use cur.Previous().IsUserCall() + unsafe.OriginSend().
• Presence via the move clock. Each move has 90s of block time. Accept proves the acceptor is present, Reveal the creator, and the first move the first mover. If the clock runs out with zero moves the game is void and both stakes are refunded (the absent player may be the creator who posted long ago); after at least one move, the player on turn forfeits. Anyone can call ClaimTimeout, so bystanders can settle stuck games. A late Play panics rather than settling, keeping one settlement path.
• First mover by two-sided commit-reveal. Offer takes commitment, the lowercase hex sha256(passphrase); Accept takes seedCommitment, the same for the acceptor's seed. The game then waits (Turn = 0, Play rejected) for the creator's Reveal(id, passphrase) within 90s of Accept, then the acceptor's RevealSeed(id, seed) within 90s of that. The first mover is the low bit of sha256(passphrase|seed|id|creator|acceptor). When a player commits, the other side's secret is still hidden, so neither can grind for an outcome; once revealed, a secret can't change. The only way out is not revealing, which forfeits: ClaimTimeout pays the other player as a win. A pending Accept shows only a hash, so a creator watching the mempool learns nothing it could cancel on.
• Commitments are one-use per address. A revealed secret is public, so reusing it would let the other side compute the draw. Reuse is refused per address (creator or acceptor), never globally, so nobody can block another player's offer by posting its commitment first.
• Fee is a flat 0.1 GNOT (100,000 ugnot) per decisive game (one with a winner), adjustable by the owner up to 0.5 GNOT (half the minimum stake) and snapshotted per game at Offer, so a live game's terms never change. Offer takes the highest fee the creator accepts (maxFee) and refuses a higher one, so the owner can't raise it while an offer is in flight; the cap bounds it for everyone. ActiveJSON gives the current fee, and the gnoweb offer link passes it. Draws and void games pay no fee. The lobby shows each offer's own fee. The owner (p/nt/ownable/v0) can SetFee and WithdrawFees (collected fees only, never stakes); it is whoever deploys the realm (init with an IsUserCall() previous), so the deploying multisig owns it with no address baked into the code. Ownership moves in two steps, TransferOwnership(newOwner) then AcceptOwnership() by that address, so a mistyped spelling can never strand ownership and fees.
• Address arguments must be canonical. The chain accepts four texts for one address (bech32 or bech32m, lower or upper case), but a caller's address is always lower-case bech32. An opponent or a new owner in another spelling could never match its caller, so Offer and TransferOwnership refuse it (address.gno, the check of p/samcrew/launchpad/meta/v1, copied so the realm doesn't depend on that package).
• Stale moves. Play(id, column, move) takes the move count the player saw and refuses any other. A client that re-sends a move whose outcome it could not see (a dropped response) cannot have it land on a later turn.
• Session keys. Calls signed by a tm2 account session key (gno #5307; runtime.GetSessionInfo) may Play, Reveal, RevealSeed, ClaimTimeout and Cancel only. Session allow-paths are per realm, not per function, and a session's spend limit counts gas and sent coins but not what a call forfeits: a stolen session key could otherwise Resign every live game. Offer/Accept (stakes) and the owner functions need the account's own key too.
• Cancel. The creator may cancel an open offer at any time; anyone may once it has expired, so stale offers can be cleared. The refund always goes to the creator.
• Non-payable calls reject coins. Every function other than Offer and Accept panics if coins are sent, so nothing gets stuck in the realm.
• Payouts are pushed with a RealmSend banker inside the settling tx, after state is updated. Native coin sends run no callee code.
• Leaderboards (wins, net ugnot won: the opponent's stake minus the fee) update only on Won/Draw, so void or cancelled games cannot farm stats. The two top-10 boards are kept at settlement (bump), so Render never walks every player's stats.
• An active tree holds only Open/Playing games so the lobby render cost does not grow with history, and the lobby lists at most 50 of them; clients page through ActiveJSON.

Alternatives considered

• First mover from a hash computed in Accept (block height, time, ids). Rejected: a tx can carry several messages and is atomic, so an acceptor can send [Accept, Play] and let the whole tx revert whenever the pick goes against them, then retry next block.

• Creator-only commit-reveal, with the Accept block height mixed in (the first hardened version). Rejected in review: a short private offer can only be accepted at about 12-18 heights, so a creator can grind one passphrase that moves first at all of them (about 2^18 tries).

• An acceptor seed sent in clear with Accept. Rejected: the creator sees it in the mempool and could cancel, or accept with another account, before the Accept lands whenever the draw goes against it.

• The creator picking the first mover in the offer, or a two-game match with each side moving first once: no randomness at all, but a different game.

• Matchmaking queue by stake tier: faster pairing, but no browsable lobby and it pairs people with idle players.

• Explicit "ready" handshake after accept: an extra tx per game that the first move already provides.

• Forfeit on first-move timeout: punishes an acceptor's opponent who simply posted an offer and left before it was taken; void is fairer.

• Chess-style time banks / per-game timeouts: more state and UI for little gain at this stage.

Consequences

• Clocks are only as precise as block production: a move can land a few seconds past 90s if no block was produced in between. Symmetric for both players.
• A weak secret can be brute-forced offline from its public commitment, letting the other side steer the draw. This cannot be enforced on-chain; the pages ask for openssl rand -hex 32, and Memba generates 32 random bytes for both.
• Each game needs two extra txs before the first move, Reveal and RevealSeed, each within 90s; both players must stay online until then.
• Self-play with an alt account inflates wins but costs the fee.
• A stolen session key can still play bad moves, one per turn, in the owner's live games. That is inherent to signing moves without the wallet; the client keeps sessions short and bounded.

Security review (before mainnet)

An audit against docs/resources/gno-ai-contract-review.md, the payment guidance in effective-gno.md and misc/audit-pattern-harness, then two reviews of this repository's PR, led to the two-sided draw, one-use commitments, the stale-move check, session-key refusals, the fee cap, two-step ownership, settlement-time leaderboards, the capped lobby and the deployer-owner above. Confirmed sound: the IsUserCall() + OriginSend() payment pair, no exported pointers or callbacks, Render writing only validated addresses and formatted numbers, fee < stake per game, exact refunds, and Play (until the deadline) and ClaimTimeout (after it) never overlapping. The harness's current_guard hits are the cur.IsCurrent() guard that AGENTS.md says not to write in crossing functions.

Read accessors

GameJSON(id) (with seedCommitment and revealed), ActiveJSON(offset, limit) and LeadersJSON() (the two top-10 boards) return hand-built JSON for clients (Memba's Arcade) that read over vm/qeval instead of scraping Render. Each response carries now, the block time, so clients count the 90s clock in chain time. The board is a 42-char column-major string. Strings go through strconv.Quote although every stored string is validated on write. The accessors never call statsOf, which writes on a miss.