🎰 Blackjack on Celo - Farcaster Mini App

A full-featured Blackjack game built as a Farcaster mini-app with Celo blockchain integration. Play in Free Mode with virtual credits or On-Chain Mode where games are recorded on Celo Mainnet.

🎮 Live Demo: blackjack-farcaster.vercel.app ⛓️ Contract: 0x6cb9971850767026feBCb4801c0b8a946F28C9Ec (Celo Mainnet)

✨ Features

Free Play Mode

🎮 Start with 1000 virtual credits
💰 Win credits: +10 for win, +15 for blackjack, -10 for loss
📊 Track your stats locally
🔄 Reset anytime to start fresh

On-Chain Mode

⛓️ Games recorded on Celo blockchain
📈 Permanent statistics tracking
🎯 Win/loss streaks
🔐 Provably fair randomness (block.prevrandao)
💸 No real money - just for fun!
🔄 Auto-switching to Celo network
⚡ Optimistic UI updates for fast gameplay
💪 Reliable transactions (120s timeout, explicit gas limits)

Game Features

♠️ Standard Blackjack rules
🃏 Dealer hits on 16, stands on 17+
🎴 Ace counts as 1 or 11 (smart calculation)
🎨 Beautiful mobile-first UI with Solo-Jackpot visual signature
🌈 Glassmorphism design with gray gradients and yellow accents
📱 Optimized for Farcaster mobile experience (compact layout, no scrolling)
👛 Connected wallet display with address
🔁 One-click "PLAY AGAIN" button for on-chain games
🎯 Realistic card symbols (♠️♥️♦️♣️) with PNG assets

🏗️ Tech Stack

Frontend: Next.js 14 (App Router), React 18, TypeScript
Styling: Tailwind CSS, Framer Motion
Blockchain: Wagmi v2, Viem, Celo
Farcaster: @farcaster/miniapp-sdk
Smart Contract: Solidity 0.8.20, Hardhat

🚀 Quick Start

Prerequisites

Node.js 18+
npm or yarn
MetaMask or compatible Web3 wallet
CELO tokens for on-chain mode

Installation

Clone the repository:

git clone <your-repo-url>
cd blackjack-farcaster

Install dependencies:
```
npm install
```

Set up environment variables:

cp .env.example .env.local

Add the following to .env.local:

NEXT_PUBLIC_URL=http://localhost:3000
NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID=your_project_id_here

Get your WalletConnect Project ID from WalletConnect Cloud

Run the development server:
```
npm run dev
```
Open http://localhost:3000

📝 Smart Contract

Current Deployment

The contract is already deployed on Celo Mainnet:

Address: 0x6cb9971850767026feBCb4801c0b8a946F28C9Ec
Explorer: View on CeloScan
Network: Celo (Chain ID: 42220)

Deploy Your Own Contract

If you want to deploy your own version:

For Testnet (Alfajores):

# Get testnet CELO from https://faucet.celo.org/alfajores
npx hardhat run scripts/deploy.ts --network alfajores

For Mainnet:

npx hardhat run scripts/deploy.ts --network celo

Update Contract Address: After deployment, update lib/contract-abi.ts:

export const CONTRACT_ADDRESS = "0xYourDeployedAddress" as `0x${string}`;

🎮 How to Play

Free Mode

Click "Free Play" mode
Click "NEW GAME" to deal cards
Click "HIT" to draw another card or "STAND" to end your turn
Dealer plays automatically
Win credits and track your stats!

On-Chain Mode

Connect your wallet
Switch to "On-Chain" mode
Click "PLAY ON-CHAIN" to record a game on Celo
Each game costs minimal gas (< $0.01)
Stats are permanently stored on-chain

🎯 Game Rules

Blackjack: 21 with 2 cards = instant win (unless dealer also has 21)
Win: Beat dealer without busting (going over 21)
Push: Tie with dealer
Bust: Go over 21 = automatic loss
Dealer: Hits on 16 or less, stands on 17+
Ace: Counts as 11 or 1 (whichever is better)

📂 Project Structure

blackjack-farcaster/
├── app/                    # Next.js app router pages
│   ├── layout.tsx         # Root layout with Farcaster metadata
│   ├── page.tsx           # Main game page
│   └── globals.css        # Global styles
├── components/            # React components
│   ├── BlackjackTable.tsx # Game table UI
│   ├── CardDisplay.tsx    # Individual card display
│   ├── Hands.tsx          # Player & dealer hands
│   ├── GameControls.tsx   # HIT/STAND/NEW GAME buttons
│   ├── GameStats.tsx      # Statistics display
│   ├── GameMessage.tsx    # Game messages (win/lose/etc)
│   ├── ModeToggle.tsx     # Free/On-Chain mode toggle
│   ├── WalletConnect.tsx  # Wallet connection UI
│   ├── FarcasterShare.tsx # Share to Farcaster
│   └── providers.tsx      # Wagmi & Farcaster providers
├── contracts/             # Smart contracts
│   ├── Blackjack.sol      # Main game contract
│   └── README.md          # Contract documentation
├── hooks/                 # React hooks
│   └── useBlackjack.ts    # Core game logic hook
├── lib/                   # Utilities
│   ├── wagmi.ts           # Wagmi configuration
│   ├── farcaster.ts       # Farcaster SDK helpers
│   ├── cards.ts           # Card types & utilities
│   ├── contract-abi.ts    # Contract ABI & address
│   └── utils.ts           # General utilities
├── scripts/               # Deployment scripts
│   └── deploy.ts          # Hardhat deployment script
└── hardhat.config.ts      # Hardhat configuration

🔑 Key Files Explained

hooks/useBlackjack.ts: Contains all game logic including Ace calculation, dealer AI, and blockchain integration
contracts/Blackjack.sol: Smart contract with game simulation and stats tracking
lib/wagmi.ts: Blockchain connection config with Farcaster wallet support
components/providers.tsx: Sets up Wagmi, React Query, and Farcaster SDK

🔧 Development

Build for Production

npm run build

Lint Code

npm run lint

Compile Smart Contracts

npx hardhat compile

🌐 Deployment

Deploy to Vercel

Push to GitHub:

git add .
git commit -m "Initial commit"
git push origin master

Configure Vercel:
- Import project in Vercel
- Add environment variables:
  - NEXT_PUBLIC_URL: Your deployed URL (e.g., https://your-app.vercel.app)
  - NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID: Your WalletConnect Project ID
- Deploy!
Update After First Deploy: After getting your Vercel URL, update NEXT_PUBLIC_URL in Vercel settings and redeploy.

Farcaster Mini App Integration

The app is fully configured for Farcaster mini-apps:

Required Assets

All PNG assets are included in /public/:

icon.png - App icon (512x512px)
og-image.png - OpenGraph image for sharing (1200x630px)
splash.png - Splash screen image

Manifest Configuration

The public/manifest.json defines the mini-app metadata with Solo-Jackpot branding.

Farcaster Redirect

The app includes a redirect configuration in next.config.mjs that points to the Farcaster hosted manifest. This is required for mini-app verification.

Metadata Setup

Farcaster metadata is configured in app/layout.tsx with:

OpenGraph tags for rich previews
fc:miniapp metadata for Farcaster integration
Launch button configuration

Deploy to Farcaster

Ensure your app is deployed and accessible via HTTPS
The manifest redirect is automatically configured
Test your mini-app in Farcaster mobile
Share your app URL in Farcaster frames!

🎨 Design - Solo-Jackpot Visual Signature

Color Scheme: Gray gradients with yellow accents (#FCFF52)
Visual Style: Glassmorphism with backdrop blur effects
Layout: Mobile-first responsive design optimized for Farcaster
Effects: Smooth animations, realistic card symbols
Typography: Clean, modern font with proper hierarchy
Accessibility: Reduced motion support, touch-friendly targets (44px minimum)
Cards: PNG assets with realistic ♠️♥️♦️♣️ symbols
Compact Mode: Optimized layout for mobile viewports with minimal scrolling

📊 Smart Contract Details

Functions

playGame(): Play a complete Blackjack game (returns result)
getStats(): Get player statistics (wins, losses, streaks, etc.)

Events

GamePlayed: Emitted after each game with full details

Randomness

Uses Ethereum's PREVRANDAO (block.prevrandao) combined with:

Block timestamp
Player address
Player's game count

Provides sufficient randomness for entertainment while being gas-efficient.

🔒 Security Notes

⚠️ This is a fun game, not a gambling platform

No real money is wagered or won
Smart contract has no withdraw/deposit functions
Randomness is suitable for games but not cryptographic security
Always verify contract address before interacting

✅ Recent Improvements

✅ Transaction Reliability: 120-second timeout with explicit gas limits (500,000)
✅ Network Auto-Switching: Automatically switches to Celo when user is on Ethereum
✅ Optimistic Updates: Fast UI feedback with 300ms delays between actions
✅ Mobile Optimization: Compact layout removes scrolling in Farcaster mobile
✅ Connected Wallet Display: Shows connected address with green indicator
✅ Play Again Button: One-click replay for on-chain games
✅ PNG Image Migration: All assets migrated from SVG to PNG for better compatibility
✅ Error Handling: Improved error messages and recovery options

🐛 Known Issues & Considerations

Contract deployment requires updating CONTRACT_ADDRESS in lib/contract-abi.ts
On-chain mode requires CELO tokens for gas (~$0.01 per game)
Stats don't sync between Free and On-Chain modes (by design)
First wallet connection may take longer on mobile

🚀 Creating a New Mini-App Based on This Project

This project serves as a great template for building Farcaster mini-apps with blockchain integration. Here's how to create your own:

1. Clone and Rename

git clone https://github.com/PhilV2dot1/blackjack-farcaster.git my-new-miniapp
cd my-new-miniapp
rm -rf .git
git init

2. Update Package.json

Change the name, description, and other metadata in package.json.

3. Modify Smart Contract

Edit contracts/YourContract.sol with your game logic
Update contract ABI and address in lib/contract-abi.ts

Deploy to Celo:

npx hardhat run scripts/deploy.ts --network celo

4. Update UI Components

Replace game logic in hooks/useBlackjack.ts (or create your own hook)
Modify components in components/ folder
Update styles to match your theme (keep Solo-Jackpot signature or create your own)

5. Update Assets

Generate new PNG images (512x512, 1200x630):

public/icon.png - Your app icon
public/og-image.png - Social sharing image
public/splash.png - Splash screen

6. Configure Farcaster

Update metadata in app/layout.tsx:
- Title, description
- Button text and action
Update public/manifest.json with your app details
Get a new Farcaster manifest URL and update redirect in next.config.mjs

7. Environment Setup

Create .env.local:

NEXT_PUBLIC_URL=your-vercel-url
NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID=your-project-id

8. Deploy

git add .
git commit -m "Initial commit for my new mini-app"
git remote add origin your-github-repo
git push -u origin master

Then deploy to Vercel and configure environment variables.

Key Files to Modify

contracts/ - Your smart contract logic
hooks/ - Game/app logic
components/ - UI components
app/layout.tsx - Metadata and SEO
public/manifest.json - Farcaster manifest
lib/contract-abi.ts - Contract interface
next.config.mjs - Farcaster redirect

🤝 Contributing

Contributions welcome! Please:

Fork the repository
Create a feature branch
Make your changes
Submit a pull request

📄 License

MIT License - see LICENSE file for details

🙏 Acknowledgments

Built for Farcaster ecosystem
Powered by Celo blockchain
Inspired by classic casino Blackjack

📞 Support

For issues or questions:

Open an issue on GitHub
Check the contracts README for deployment help
Review Celo docs for blockchain questions

**Have fun and play responsibly!

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

🎰 Blackjack on Celo - Farcaster Mini App

✨ Features

Free Play Mode

On-Chain Mode

Game Features

🏗️ Tech Stack

🚀 Quick Start

Prerequisites

Installation

📝 Smart Contract

Current Deployment

Deploy Your Own Contract

🎮 How to Play

Free Mode

On-Chain Mode

🎯 Game Rules

📂 Project Structure

🔑 Key Files Explained

🔧 Development

Build for Production

Lint Code

Compile Smart Contracts

🌐 Deployment

Deploy to Vercel

Farcaster Mini App Integration

Required Assets

Manifest Configuration

Farcaster Redirect

Metadata Setup

Deploy to Farcaster

🎨 Design - Solo-Jackpot Visual Signature

📊 Smart Contract Details

Functions

Events

Randomness

🔒 Security Notes

✅ Recent Improvements

🐛 Known Issues & Considerations

🚀 Creating a New Mini-App Based on This Project

1. Clone and Rename

2. Update Package.json

3. Modify Smart Contract

4. Update UI Components

5. Update Assets

6. Configure Farcaster

7. Environment Setup

8. Deploy

Key Files to Modify

🤝 Contributing

📄 License

🙏 Acknowledgments

📞 Support