git clone https://github.com/ThisIsPhila/hackathon.git

⚡ MemePool - Lightning Meme Battle Arena

Where Bitcoin sats settle every meme duel.

Project Overview

MemePool is a real-time meme battle arena that lets communities decide winners with Lightning payments. Players launch duels, the challenger auto-replies with a fresh meme, and spectators zap sats through Bitnob invoices to move the scoreboard. The front-end ships with a demo-friendly mock stack, while the Next.js backend proxies Bitnob so the exact same flows work against live invoices.

Highlights:

• Lightning-native voting — every 10 sats equals one vote and settles through Bitnob.
• Downvote support — spend sats to push an opponent back down the board.
• Auto challenger + auto voters — the arena never feels empty during a demo.
• 10M sat starting balance — profiles track scalable balances for scripted walkthroughs.
• MemePool branding — updated copy, favicons, and social tags for the new identity.

👉 Drill into the rules and economy in docs/GAME-MECHANICS.md

How It Works

1. Summon a battle — Compose a meme in the arena composer and launch the duel.
2. Challenger joins — A challenger meme appears automatically in demo mode, or you can target a real opponent when wired to the API.
3. Zap votes — Spectators buy invoices in-app; 10 sats per vote with optional downvote direction.
4. Watch the pot — Real-time tallies update as Lightning payments settle.
5. Crown the winner — Completed battles highlight the champion, auto-generate banner art, and land in the leaderboard.

Tech Stack

• Frontend: Vite + React 18, TypeScript, Tailwind, shadcn/ui, TanStack Query, wagmi (wallet wiring ready).
• Payments: Bitnob Lightning API with copy-ready invoices, QR codes, countdown timers, and settlement polling.
• Backend: Next.js 14 API routes (under backend/onchainkit-app) used as a Lightning proxy plus Foundry contracts for future on-chain extensions.
• Mocks: Swappable profile, battle, and Lightning providers so hackathon demos run without external services.
• Automation: Scheduled challenger submissions and auto-vote scripts enrich the demo feed.

See the full architecture breakdown in docs/ARCHITECTURE.md.

Project Structure

hackathon/
├── README.md
├── docs/
│   ├── *.md                 # Product, setup, and presentation guides
│   └── integrations/
├── frontend/                # Vite client for the arena
│   ├── public/              # Assets (favicons, demo images)
│   └── src/                 # Components, hooks, and service adapters
├── backend/
│   └── onchainkit-app/      # Next.js API + Foundry contracts
└── vercel.json

Quick Start

1. Clone and install

git clone https://github.com/ThisIsPhila/hackathon.git
cd hackathon

# Frontend
cd frontend
npm install

# Backend proxy (optional for mocks, required for live Lightning)
cd ../backend/onchainkit-app
npm install

2. Configure environments

frontend/.env.local

VITE_MEMEPOOL_API_URL=http://localhost:3000/api # comment out to stay fully mock
VITE_USE_MOCK_BATTLES=false                     # true keeps preset duels only
VITE_USE_MOCK_PROFILES=false
VITE_USE_MOCK_LIGHTNING=false                   # true disables Bitnob calls

backend/onchainkit-app/.env.local

BITNOB_API_KEY=your_bitnob_secret_key
BITNOB_CUSTOMER_EMAIL=merchant@example.com
BITNOB_ENV=sandbox                               # production when you are ready
BITNOB_INVOICE_EXPIRY=2m                         # aligns with UI countdown
CORS_ALLOW_ORIGIN=http://localhost:5173

3. Run the stacks

# Terminal 1
cd frontend
npm run dev

# Terminal 2 (only if using live invoices)
cd backend/onchainkit-app
npm run dev

Visit http://localhost:5173 to duel. The mock data keeps the arena active even without the backend.

Demo Script (5 minutes)

1. Landing tour — Highlight MemePool branding and the live leaderboard.
2. Launch a battle — Post a meme, show the challenger response that appears in seconds.
3. Zap sats — Trigger a Lightning vote, copy the invoice, and confirm settlement in-app.
4. Show downvotes — Spend sats to reduce the opponent score and call out the live pot update.
5. Leaderboard recap — Scroll through realistic sats totals and winner banners.
6. Profile balance — Point to the persistent 10,000,000 sat balance and demo mode toggle.

Lightning + Mock Modes

• Auto challenger: Mock service schedules a reply meme 2-4 seconds after launch.
• Auto votes: Demo battles receive timed Lightning contributions so charts move without manual input.
• Invoice UX: QR codes, copy helpers, and a live expiry clock keep Lightning flows presenter-friendly.
• ServiceFactory: Toggling env flags instantly swaps between mock data and the Bitnob-backed API.

More operational details live in docs/SETUP.md.

Documentation Index

• docs/DOCUMENTATION-INDEX.md — master reference for every guide.
• docs/PRESENTATION-GUIDE.md — expanded show-and-tell script.
• docs/VERCEL-DEPLOYMENT.md — deploy the Vite client to Vercel.
• backend/onchainkit-app/README.md — Lightning proxy and contract notes.

Status

• ✅ Lightning invoices via Bitnob (sandbox + production toggles)
• ✅ Auto challenger + auto voters for demos
• ✅ Downvote logic wired to sats deductions
• ✅ MemePool branding (copy, icons, metadata)
• ✅ Balanced leaderboard data with realistic sats ranges
• 🚧 Contract integration for on-chain settlement
• 🚧 Social syndication connectors

Contributing

Pull requests and ideas welcome. Open an issue with repro steps for any Lightning or mock discrepancies.

License

MIT