Coin Flip

The classic variant. You predict a sequence of N flips and win only if every prediction matches. Payouts roughly double each extra flip (minus the house edge), so chains of five pay 31.68× but are correct only 1/32 = 3.125% of the time.

Difficulty indices +1 through +5 correspond to Win All of 1, 2, 3, 4, and 5 flips respectively. Difficulty +1 is just a single heads/tails call at about 2×.

The "safe" variant. You predict N flips and win if any prediction matches. At least one match is very likely — the odds of zero matches across N flips are just 0.5ⁿ — so the multipliers sit close to 1× but your hit rate is close to 100%.

Difficulty indices −1 through −4 correspond to Win One of 2, 3, 4, and 5 flips respectively. Harder indices (more flips) mean a higher hit probability and a smaller multiplier.

The multipliers field of a GameEntry is a [u16; 9] and cannot hold a number above 65,535. Because 31.68× in bps is 316,800, the stored values are scaled down by 100. The program multiplies them back by 100 at read time (see MULTIPLIER_SCALE in state/game_registry.rs).

Two signatures are involved in a place_bet_* transaction: yours as the player (authorising the wager transfer) and the settler's as the rent_payer (paying the lamports to allocate the BetOrder PDA). The settler partial-signs the transaction before it's handed to your wallet.

The rent_payer identity is checked on-chain against game_registry.settler. This prevents any third party from spending our rent lamports, and also binds the BetOrder to the current settler keypair so that rent rebates on settlement only go where we expect.

For users who sign in with social login (Web3Auth) and have no SOL in their wallet, the settler can be switched to full fee-payer mode. In that case the settler signs the whole transaction, pays all the fees, and you just authorise the wager transfer — never blocking new users on "go buy SOL first." This is controlled by the feePayerMode flag on the /build-place-bet endpoint.

Right after bet_confirmed, the LiveView spawns an unlinked Elixir process that calls the settler's /settle-bet endpoint. The settler signs a settle_bet transaction (passing server_seed, won, payout) and submits it. The LiveView gets back a settlement_complete message and writes the signature to Mnesia.

Nothing in the UI waits for this. You can start your next bet as soon as the flip animation finishes. If settlement crashes mid-flight, the banner described below catches it within 30 seconds.

A cluster-wide GenServer called CoinFlipBetSettler (registered as a global singleton) runs every minute. It queries Mnesia for bets with status :placed that are at least two minutes old and attempts to settle them. If the settler returns AccountNotInitialized it means the BetOrder never actually landed on-chain, and the record is marked failed so the loop stops retrying.

The settle_bet handler does three critical validations before touching any money:

1. SHA256(server_seed) == bet_order.commitment_hash — else InvalidServerSeed.
2. elapsed ≤ game_registry.bet_timeout (default 120s) — else OrderExpired.
3. payout ≤ bet_order.max_payout — else PayoutExceedsMax.

If all three pass, the program transfers the payout from the vault to the player (only when won and payout is positive), updates total_liability, house_profit, total_bets, total_volume, the player's lifetime stats, and emits a BetSettled event. The BetOrder PDA is closed and its rent (~0.002 SOL) is returned to the original rent_payer — always the settler.

When the UI detects a Pending bet older than 5 minutes, it shows a yellow banner on /play with a Reclaim button. Clicking it calls the settler's /build-reclaim-expired endpoint, which returns an unsigned transaction calling the reclaim_expired instruction. You sign it with your wallet.

On-chain, the program checks that you own the bet (has_one = player), that the bet's status is still Pending, and that the timeout has actually passed (elapsed > bet_timeout, strictly greater). If all three pass, it refunds your original wager (not the potential payout, not a fee, just the wager) and closes the BetOrder. Rent goes back to the settler.

A reclaimed bet does not increment total_bets or total_volume and doesn't touch house_profit. It only decrements total_liability and unsettled_count. An expired bet is treated as if it never happened.

We keep a local copy of the nonce in Mnesia so that opening /play is instant — we don't wait for an RPC round-trip. But on-chain is the source of truth. On init, we compute next = max(mnesia_next, onchain_next). If there's drift we log a warning.

If the on-chain program rejects a commitment with NonceMismatch, the UI re-initialises, which re-reads the on-chain nonce and tries again with a higher value.

The program allows the settler to commit for any nonce greater than or equal to player_state.nonce, not just equal. That leaves room for batching or pre-committing several future seeds in advance. The current backend does not use this — each bet gets its own fresh commitment — but the capability exists on-chain.

The LiveView deducts your local balance the instant the wallet returns bet_confirmed, before settlement lands. If the settlement transaction reverts, the local balance is refreshed from chain during the next balance sync (usually within 30 seconds). Your on-chain balance is always correct.

It does, intentionally. The settlement tx typically confirms within one slot (~400ms). Letting the animation run concurrently gives us a smoother feel without extending the wait. If settlement fails mid-animation, the UI silently swallows it and the 1-minute settler takes over.

The Elixir backend uses trunc/1 (not Float.round/1) to compute the payout it submits to settle_bet. On-chain, the program uses u64 integer arithmetic. If those two diverged, the on-chain check payout ≤ max_payout would fail. We match truncation behaviour deliberately to keep them aligned.

The first click consumes the pending commitment (the program clears pending_commitment on placement). The second click would hit NoCommitment on-chain. The UI disables the button while the first tx is in-flight as a UX belt; the program provides the suspenders.

Without one, the pool could not pay its costs and would drift to zero in expectation. Our edge is small (around 1% on Win All variants) because we care more about volume and fairness than about margin per bet.

It generated the seed. The point of the commit-reveal scheme is not that you trust the settler didn't know the seed — it's that the settler committed to one specific seed on-chain before you bet, and the program will not let it reveal a different seed later. The seed is fixed the moment submit_commitment lands.

If the authority toggles the global paused flag, submit_commitment and place_bet_* start reverting with Paused. But settle_bet and reclaim_expired still work — so any bet you have in flight can still be resolved. This is intentional.

There is no per-day cap, but the program's per-bet cap (potential_profit ≤ net_balance) means you can never drain the vault in a single bet. The max-bet formula is recomputed on every placement from the live vault balance.