This is a theme-first shippable docs shell inspired by that “cute‑but‑dark occult” vibe. Effects are modular, toggleable, and performance-safe. Logic comes later.
CoinFlip is designed around explicit bias + explicit fees, plus hard exposure caps so the pool can’t be drained in one streak. This page is theme-first; the terminal bot + pool adapters plug in next.
Your bot reads liquidity, fee rate, edge, and max payout fraction from a pool adapter. Today it can be mock data; later you swap in on‑chain or backend adapters.
getPoolInfo() → liquidity, fees, edge, caps safe max bet auto‑calculated from pool liquidity quotes always computed the same way
Before any flip, users see: fee, bet-after-fee, win return, win profit, loss on lose, and safety locks. The UI never hides the math.
bet = user wager (1 / 5 / 10) fee = bet × feeRate betAfterFee = bet − fee winProfit = betAfterFee × m winReturn = betAfterFee + winProfit loseLoss = bet
Let L be pool liquidity and α be max payout fraction. Then max payout is:
maxPayout = L × α maxBet = maxPayout / ((1−feeRate) × (1+m))
The “safe ladder” can also require liquidity for N consecutive wins (optional strict mode).
This live tester runs locally using preset pool profiles + disclosed odds. Later you’ll wire the same UI to your pool adapter + receipts engine — but the quote math and safety gating remain identical.
Select a pool, then press Quote / Flip.
The pool can’t be allowed to die. The bot uses hard caps + circuit breakers + conservative solvency checks.
The UI offers $1/$5/$10, but the bot enforces what’s actually safe. If liquidity drops, higher bets lock automatically.
enabled(bet) if: winProfit ≤ L×α AND poolBalance ≥ winProfit×(1+buffer)
If you want extra safety, require enough liquidity to survive N consecutive player wins before enabling a bet.
need = N × winProfit × (1+buffer) poolBalance must exceed need
Pause flips if adapter fails, liquidity drops too fast, oracle is stale, or proof receipts fail verification.
pause if: adapter_error pool_drop_rate > threshold oracle_stale receipts_invalid
Proof prevents hidden manipulation of outcomes. Bias is intentional and disclosed; randomness is verifiable.
Server generates a secret seed, publishes its hash before flips start.
commit = SHA256(serverSeed) publish(commit)
After an epoch closes, server reveals the seed. Anyone verifies the hash matches.
verify SHA256(serverSeed) == commit
Use HMAC of serverSeed and clientSeed+nonce, parity determines Heads/Tails.
digest = HMAC_SHA256(serverSeed, `${clientSeed}:${nonce}`)
firstByte = hexToByte(digest[0..1])
outcome = (firstByte % 2 == 0) ? heads : tails
Reference commands. Your shipped terminal bot should mirror these behaviors.
coinflip status coinflip quote --bet 1 --side heads coinflip quote --bet 5 --side tails coinflip flip --bet 10 --side heads --client-seed "myseed" coinflip reveal