Coin Flip

Two-player USDC coin flip on Ethereum Sepolia. Player 1 picks Heads or Tails and deposits 10 USDC; player 2 joins by game number, gets the other side and deposits 10 USDC. Joining requests a random number from Chainlink VRF v2.5, and the VRF callback pays the 20 USDC pot to the winner in the same transaction.

Built on Scaffold-ETH 2 (Foundry + Next.js + wagmi + RainbowKit).

Layout

Path	What
packages/foundry/contracts/CoinFlip.sol	The game contract
packages/foundry/contracts/mocks/	MockUSDC and LocalVRFCoordinator, deployed on the local chain only
packages/foundry/test/	Unit tests (Chainlink's official VRF mock) and a Sepolia fork test
packages/foundry/script/DeployCoinFlip.s.sol	Deploy: real VRF + Circle USDC on Sepolia, mocks locally
packages/nextjs/app/page.tsx	Start / join screen
packages/nextjs/app/game/[id]/page.tsx	Game page: waiting, flipping, result, payout tx, cancel/refund/claim

Contract rules

• Buy-in is fixed at 10 USDC (10e6, 6 decimals). No house fee; the winner gets 20.
• Game numbers are sequential from 1. You cannot join your own game.
• cancelGame: player 1 gets their deposit back while nobody has joined.
• refundGame: if VRF has not answered 1 hour after joining, anyone can refund both players. A late VRF answer is then ignored.
• If a payout transfer fails (e.g. USDC has blocked the winner's address), the game still settles and the amount is credited to claimable; the winner withdraws it with claim(). The VRF callback never reverts, because Chainlink does not retry failed callbacks.
• Trust: the owner can change VRF settings and, through Chainlink's base contract, repoint the VRF coordinator, which would let a dishonest owner choose outcomes. There is no function that lets the owner move escrowed USDC.

Local development

yarn install
yarn chain        # terminal 1: local anvil chain
yarn deploy       # terminal 2: deploys CoinFlip + MockUSDC + LocalVRFCoordinator, regenerates frontend ABIs
yarn start        # terminal 3: http://localhost:3000

scaffold.config.ts must have targetNetworks: [chains.foundry] for local work. On the local chain the UI shows "Mint 100 test USDC" and, on a game that is flipping, "Answer flip (local VRF)" (local VRF requests are answered by hand). The Debug Contracts page is available locally only.

Tests:

yarn foundry:test
# Also run the fork test, which checks the VRF callback's gas with real Sepolia USDC (~108k by Foundry's gas schedule, which underprices Sepolia's storage creation; measured on Sepolia itself it is ~271k, against the 500k limit):
SEPOLIA_RPC_URL=https://ethereum-sepolia-rpc.publicnode.com yarn foundry:test

Deploying to Sepolia

You need: a deployer wallet with Sepolia ETH, and free accounts/keys from Alchemy (RPC), Etherscan (verification) and Reown (WalletConnect project ID).

1. Deployer key. yarn account:import (paste the private key; it is stored encrypted in ~/.foundry/keystores) or yarn generate for a fresh one. yarn account shows its address and balance.
2. VRF subscription. At vrf.chain.link (Sepolia), connect the same deployer wallet, create a subscription and fund it with Sepolia ETH. Budget about 0.004 ETH per flip at 10 gwei; 0.5 ETH is comfortable for a workshop. Copy the subscription ID.
3. Foundry env. In packages/foundry/.env set ALCHEMY_API_KEY, ETHERSCAN_API_KEY and VRF_SUBSCRIPTION_ID.
4. Deploy and verify.

   yarn deploy --network sepolia     # deploys CoinFlip and adds it as a consumer on your subscription
   yarn verify --network sepolia
   

   Check the subscription page on vrf.chain.link lists the new contract as a consumer.
5. Point the frontend at Sepolia. In packages/nextjs/scaffold.config.ts set targetNetworks: [chains.sepolia]. deployedContracts.ts was regenerated by the deploy; commit it.
6. Smoke test locally with yarn start and two wallets before the workshop.

Hosting on Vercel

1. Push the repo to GitHub.
2. On vercel.com, sign in with GitHub, Add New → Project, import the repo and set Root Directory to packages/nextjs.
3. Environment variables: NEXT_PUBLIC_ALCHEMY_API_KEY and NEXT_PUBLIC_WALLET_CONNECT_PROJECT_ID (your own, not the Scaffold-ETH defaults, which are shared and rate-limited).
4. Deploy. Every push to main redeploys. (Alternative from the CLI: yarn vercel --prod.)

After deploying, add the Vercel domain to the allowed origins of your Reown project and (optionally) restrict the Alchemy key to that domain.