BlockMafia
Multiplayer Mafia game with ETH prizes.
About
The problem it solves # 🎭 PrizeMafia - Farcaster Frame Multiplayer Mafia game with ETH prizes, built as a Farcaster Frame on Base L2. ## 🎮 Game Overview - **9 Players**: Exactly 9 players per game - **Entry Fee**: 0.001 ETH (testnet) - **Roles**: 2 Mafia, 1 Doctor, 1 God, 5 Villagers - **Duration**: 3 rounds max, ~15 minutes - **Platform**: Farcaster Frames (no app needed!) ## 🏗️ Architecture - **Frontend**: Next.js + Farcaster Frames - **Backend**: Next.js API routes + Redis state - **Blockchain**: Base Sepolia testnet - **Wallet**: Privy embedded wallets - **Images**: @vercel/og dynamic generation ## 🚀 Quick Start ### 1. Clone and Install ```bash git clone <your-repo> cd prizemafia-frame npm install ``` ### 2. Environment Setup ```bash cp .env.example .env.local # Fill in your API keys: # - NEYNAR_API_KEY (Farcaster) # - UPSTASH_REDIS_URL & TOKEN (Redis) # - ALCHEMY_BASE_KEY (Base network) # - PRIVY_APP_ID & SECRET (Wallets) # - PRIVATE_KEY (Deployer wallet) ``` ### 3. Deploy Smart Contract ```bash # Compile contract npm run hardhat:compile # Deploy to Base Sepolia npm run hardhat:deploy # Update .env.local with contract address ``` ### 4. Run Development Server ```bash npm run dev ``` ### 5. Test Your Frame - Use [Frame Ground](https://frameground.app) to test locally - Share frame URL in Warpcast to test live ## 📁 Project Structure ``` src/ ├── app/api/ │ ├── frame/ # Frame endpoints │ ├── og/ # Image generation │ └── cron/ # Timer jobs ├── lib/ │ ├── game-engine.ts # Game logic │ ├── redis.ts # State management │ ├── frame-utils.ts # Frame helpers │ └── types.ts # TypeScript types ├── contracts/ │ └── SimpleMafiaEscrow.sol └── scripts/ └── deploy.ts ``` ## 🎯 Game Flow 1. **Create/Join**: Host creates game, players join via frame 2. **Payment**: Players pay 0.001 ETH entry fee (embedded wallet) 3. **Start**: Game starts when 9 players joined 4. **Roles**: Secret roles assigned via private DMs 5. **Day Phase**: 5min discussion, vote to eliminate 6. **Night Phase**: Mafia kills, Doctor saves 7. **Win**: Mafia wins if they equal villagers, else villagers win ## 🔧 API Endpoints ### Frame Routes - `GET/POST /api/frame` - Main landing - `POST /api/frame/create` - Create game - `POST /api/frame/join` - Join game - `POST /api/frame/lobby` - Lobby state - `POST /api/frame/start` - Start game - `POST /api/frame/game` - Game state ### Image Generation - `GET /api/og?type=landing` - Landing image - `GET /api/og?type=lobby&gameId=X&playerCount=5` - Lobby - `GET /api/og?type=game&phase=day&round=1&userRole=mafia` - Game ## 🛠️ Development Commands ```bash # Development npm run dev # Start dev server npm run build # Build for production npm run typecheck # TypeScript check # Smart Contracts npm run hardhat:compile # Compile contracts npm run hardhat:test # Run tests npm run hardhat:deploy # Deploy to testnet ``` ## 🚨 Important Notes ### Testnet Only This is built for Base Sepolia testnet with 0.001 ETH entry fees. **DO NOT** use on mainnet without proper audits and legal review. ### Legal Compliance Online gaming with real money requires legal compliance in many jurisdictions. Consult legal counsel before accepting real ETH. --- **Built with ❤️ by Deb** *Ready to play? Share the frame in Warpcast and let the games begin! 🎭*
How it's made
Challenges we ran into # Challenges I Ran Into Building PrizeMafia as a Farcaster Frame involved integrating real-time multiplayer logic with blockchain payments, which led to several hurdles. Here are the key ones and how I overcame them: ## 1. Managing Real-Time Game State Across Players **Hurdle:** Farcaster Frames are stateless by design, making it tricky to synchronize game phases (e.g., day/night cycles) and player actions in real-time for 9 players. Initial attempts using only API routes caused race conditions where votes or role assignments overlapped, leading to inconsistent game states. **Solution:** I implemented Redis for persistent state management, storing game data with TTL (time-to-live) for automatic cleanup. This allowed atomic updates via Redis transactions, ensuring thread-safe operations. I also added cron jobs to handle phase transitions, tested thoroughly with mock players to simulate concurrency. ## 2. Integrating Embedded Wallets for ETH Payments **Hurdle:** Using Privy for embedded wallets worked well for seamless payments, but on Base Sepolia testnet, transaction confirmations were slow, causing UI freezes during the 0.001 ETH entry fee process. Players sometimes saw "pending" states indefinitely, disrupting the lobby flow. **Solution:** I polled the blockchain using Alchemy's API for transaction receipts, with exponential backoff to avoid rate limits. Added client-side loading indicators and error handling for failed txns, redirecting users to retry. Extensive testing on testnet with multiple wallets ensured reliability. ## 3. Dynamic Image Generation for Frames **Hurdle:** Generating OG images with @vercel/og for lobby and game states was complex, especially for personalized content like player roles sent via DMs. Early versions had rendering issues on mobile Farcaster clients, with images not updating dynamically based on query params. **Solution:** I refactored the API to use conditional rendering in the OG endpoint, caching images in Vercel for performance. Debugged by logging params and testing on Frame Ground, ensuring compatibility across devices. This improved load times and visual consistency. These challenges pushed me to deepen my knowledge of serverless architectures and blockchain integrations, ultimately making the app more robust. All issues were resolved through iterative testing, documentation reviews, and community forums like Farcaster dev channels.