The problem BlockMafia 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

git clone <your-repo>
cd prizemafia-frame
npm install

2. Environment Setup

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

# Compile contract
npm run hardhat:compile

# Deploy to Base Sepolia
npm run hardhat:deploy

# Update .env.local with contract address

4. Run Development Server

npm run dev

5. Test Your Frame

• Use Frame Ground 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

# 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! 🎭

Challenges I 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.