d3bf8080b6
Features: - Lightning Network payments via LNbits integration - Provably fair draws using CSPRNG - Random ticket number generation - Automatic payouts with retry/redraw logic - Nostr authentication (NIP-07) - Multiple draw cycles (hourly, daily, weekly, monthly) - PostgreSQL and SQLite database support - Real-time countdown and payment animations - Swagger API documentation - Docker support Stack: - Backend: Node.js, TypeScript, Express - Frontend: Next.js, React, TailwindCSS, Redux - Payments: LNbits
319 lines
8.7 KiB
Markdown
319 lines
8.7 KiB
Markdown
# ⚡ Lightning Lottery
|
|
|
|
A complete Bitcoin Lightning Network powered lottery system with instant payouts to Lightning Addresses.
|
|
|
|
## Features
|
|
|
|
- ⚡ **Lightning Fast**: Instant ticket purchases and payouts via Lightning Network
|
|
- 🎲 **Provably Fair**: Cryptographically secure random number generation (CSPRNG)
|
|
- 🔐 **Secure**: Transaction-based ticket issuance, idempotent operations
|
|
- 🌐 **Anonymous or Nostr**: Buy tickets anonymously or login with Nostr
|
|
- 📱 **Mobile First**: Beautiful responsive design optimized for all devices
|
|
- 🏆 **Automatic Payouts**: Winners get paid automatically to their Lightning Address
|
|
- ⏰ **Multiple Cycles**: Support for hourly, daily, weekly, and monthly draws
|
|
- 🔄 **Auto-Redraw**: If payout fails, automatically selects a new winner
|
|
- 🎰 **Random Tickets**: Ticket numbers are randomly generated, not sequential
|
|
- 📊 **Swagger Docs**: Full API documentation at `/api-docs`
|
|
|
|
## Architecture
|
|
|
|
The system consists of three main components:
|
|
|
|
1. **Backend API** (Node.js + TypeScript + Express)
|
|
2. **Frontend** (Next.js + React + TypeScript + TailwindCSS)
|
|
3. **Database** (PostgreSQL or SQLite)
|
|
|
|
### Backend
|
|
|
|
- RESTful API with comprehensive endpoints
|
|
- LNbits integration for Lightning payments
|
|
- Automated scheduler for draws and cycle generation
|
|
- JWT authentication for Nostr users
|
|
- Admin API for manual operations
|
|
- Payment monitoring with polling fallback
|
|
- Webhook support for instant payment confirmation
|
|
|
|
### Frontend
|
|
|
|
- Server-side rendered Next.js application
|
|
- Redux state management
|
|
- Real-time countdown timers
|
|
- Invoice QR code display with payment animations
|
|
- Automatic status polling
|
|
- Nostr NIP-07 authentication
|
|
- Draw animation with winner reveal
|
|
- Past winners display
|
|
|
|
## Quick Start
|
|
|
|
### Using Docker Compose (Recommended)
|
|
|
|
1. Clone the repository:
|
|
```bash
|
|
git clone <repository-url>
|
|
cd LightningLotto
|
|
```
|
|
|
|
2. Configure environment:
|
|
```bash
|
|
cp back_end/env.example back_end/.env
|
|
cp front_end/env.example front_end/.env.local
|
|
# Edit both files with your configuration
|
|
```
|
|
|
|
3. Start services:
|
|
```bash
|
|
docker-compose up -d
|
|
```
|
|
|
|
4. Access the application:
|
|
- Frontend: http://localhost:3001
|
|
- Backend API: http://localhost:3000
|
|
- API Docs: http://localhost:3000/api-docs
|
|
- Health check: http://localhost:3000/health
|
|
|
|
### Manual Setup
|
|
|
|
#### Backend
|
|
|
|
```bash
|
|
cd back_end
|
|
npm install
|
|
cp env.example .env
|
|
# Edit .env with your configuration
|
|
|
|
# For PostgreSQL:
|
|
createdb lightning_lotto
|
|
psql lightning_lotto < src/database/schema.sql
|
|
|
|
# For SQLite (default, no setup needed):
|
|
# Database file created automatically at data/lightning_lotto.db
|
|
|
|
# Run development server
|
|
npm run dev
|
|
|
|
# Or build and run production
|
|
npm run build
|
|
npm start
|
|
```
|
|
|
|
#### Frontend
|
|
|
|
```bash
|
|
cd front_end
|
|
npm install
|
|
cp env.example .env.local
|
|
# Edit .env.local
|
|
|
|
# Run development server
|
|
npm run dev
|
|
|
|
# Or build and run production
|
|
npm run build
|
|
npm start
|
|
```
|
|
|
|
## Configuration
|
|
|
|
### Required Environment Variables
|
|
|
|
#### Backend (.env)
|
|
|
|
```bash
|
|
# Database (PostgreSQL or SQLite)
|
|
DATABASE_URL=postgresql://user:pass@localhost:5432/lightning_lotto
|
|
# Or for SQLite (leave DATABASE_URL empty or use):
|
|
USE_SQLITE=true
|
|
|
|
# LNbits Configuration
|
|
LNBITS_API_BASE_URL=https://your-lnbits-instance.com
|
|
LNBITS_ADMIN_KEY=your-lnbits-admin-key
|
|
LNBITS_WEBHOOK_SECRET=your-webhook-secret
|
|
|
|
# Security
|
|
JWT_SECRET=your-jwt-secret-min-32-chars
|
|
ADMIN_API_KEY=your-admin-api-key
|
|
|
|
# Lottery Settings
|
|
DEFAULT_TICKET_PRICE_SATS=1000
|
|
DEFAULT_HOUSE_FEE_PERCENT=5
|
|
PAYOUT_MAX_ATTEMPTS_BEFORE_REDRAW=2
|
|
```
|
|
|
|
#### Frontend (.env.local)
|
|
|
|
```bash
|
|
NEXT_PUBLIC_API_BASE_URL=http://localhost:3000
|
|
```
|
|
|
|
See `back_end/env.example` and `front_end/env.example` for all configuration options.
|
|
|
|
## API Endpoints
|
|
|
|
### Public Endpoints
|
|
|
|
| Method | Endpoint | Description |
|
|
|--------|----------|-------------|
|
|
| GET | `/jackpot/next` | Get next upcoming draw |
|
|
| POST | `/jackpot/buy` | Purchase tickets |
|
|
| GET | `/jackpot/past-wins` | List past winners |
|
|
| GET | `/tickets/:id` | Check ticket status |
|
|
|
|
### User Endpoints (Nostr Auth)
|
|
|
|
| Method | Endpoint | Description |
|
|
|--------|----------|-------------|
|
|
| POST | `/auth/nostr` | Authenticate with Nostr |
|
|
| GET | `/me` | Get user profile |
|
|
| PATCH | `/me/lightning-address` | Update Lightning address |
|
|
| GET | `/me/tickets` | User's ticket history |
|
|
| GET | `/me/wins` | User's win history |
|
|
|
|
### Admin Endpoints
|
|
|
|
| Method | Endpoint | Description |
|
|
|--------|----------|-------------|
|
|
| GET | `/admin/cycles` | List all cycles |
|
|
| POST | `/admin/cycles/:id/run-draw` | Manually trigger draw |
|
|
| GET | `/admin/payouts` | List payouts |
|
|
| POST | `/admin/payouts/:id/retry` | Retry failed payout |
|
|
|
|
### Webhooks
|
|
|
|
| Method | Endpoint | Description |
|
|
|--------|----------|-------------|
|
|
| POST | `/webhooks/lnbits/payment` | LNbits payment callback |
|
|
|
|
Full API documentation available at `/api-docs` (Swagger UI).
|
|
|
|
## Database Schema
|
|
|
|
7 main tables:
|
|
|
|
- `lotteries` - Lottery configuration
|
|
- `jackpot_cycles` - Draw cycles with status and winners
|
|
- `ticket_purchases` - Purchase records with Lightning invoice info
|
|
- `tickets` - Individual tickets with random serial numbers
|
|
- `payouts` - Winner payouts with retry logic
|
|
- `users` - Nostr user accounts (optional)
|
|
- `draw_logs` - Audit trail for transparency
|
|
|
|
## How It Works
|
|
|
|
1. **Cycle Generation**: Scheduler automatically creates future draw cycles
|
|
2. **Ticket Purchase**: Users buy tickets, receive Lightning invoice
|
|
3. **Payment Processing**: LNbits webhook or polling confirms payment
|
|
4. **Ticket Issuance**: Random ticket numbers assigned in database transaction
|
|
5. **Draw Execution**: At scheduled time, winner selected using CSPRNG
|
|
6. **Payout**: Winner's Lightning Address paid automatically
|
|
7. **Retry/Redraw**: Failed payouts retried; new winner drawn after max attempts
|
|
|
|
## Security Features
|
|
|
|
- JWT tokens for user authentication
|
|
- Admin API key protection
|
|
- Webhook signature verification
|
|
- Rate limiting on all endpoints
|
|
- Idempotent payment processing
|
|
- Database transactions for atomic operations
|
|
- `crypto.randomBytes()` for winner selection
|
|
- `crypto.randomInt()` for ticket number generation
|
|
- No floating-point math (BIGINT for all sats)
|
|
|
|
## Frontend Pages
|
|
|
|
| Page | Description |
|
|
|------|-------------|
|
|
| `/` | Home page with jackpot countdown and winner display |
|
|
| `/buy` | Purchase tickets with Lightning invoice |
|
|
| `/tickets/:id` | View ticket status and draw results |
|
|
| `/past-wins` | Public list of past winners |
|
|
| `/about` | About page with how it works |
|
|
| `/dashboard` | User dashboard (Nostr login required) |
|
|
| `/dashboard/tickets` | User's ticket history |
|
|
| `/dashboard/wins` | User's win history |
|
|
|
|
## Testing
|
|
|
|
### Backend Tests
|
|
```bash
|
|
cd back_end
|
|
npm test
|
|
```
|
|
|
|
### Frontend Tests
|
|
```bash
|
|
cd front_end
|
|
npm test
|
|
```
|
|
|
|
## Deployment
|
|
|
|
### Production Considerations
|
|
|
|
1. Use strong secrets for `JWT_SECRET` and `ADMIN_API_KEY`
|
|
2. Configure proper CORS origins in backend
|
|
3. Use SSL/TLS (HTTPS) for all connections
|
|
4. Set up monitoring and logging
|
|
5. Configure database backups
|
|
6. Set up proper firewall rules
|
|
7. Consider using a CDN for frontend
|
|
8. Use PostgreSQL for production (SQLite for development)
|
|
|
|
### Scaling
|
|
|
|
- Backend is stateless and can be horizontally scaled
|
|
- Use connection pooling for database
|
|
- Consider Redis for caching
|
|
- Use message queue for high-volume webhooks
|
|
|
|
## Monitoring
|
|
|
|
Health check endpoint:
|
|
```bash
|
|
curl http://localhost:3000/health
|
|
```
|
|
|
|
Returns database and LNbits connectivity status.
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
LightningLotto/
|
|
├── back_end/
|
|
│ ├── src/
|
|
│ │ ├── config/ # Configuration and Swagger setup
|
|
│ │ ├── controllers/ # Route handlers
|
|
│ │ ├── database/ # Database wrapper and schema
|
|
│ │ ├── middleware/ # Auth and rate limiting
|
|
│ │ ├── routes/ # API routes
|
|
│ │ ├── scheduler/ # Automated jobs
|
|
│ │ ├── services/ # Business logic
|
|
│ │ ├── types/ # TypeScript types
|
|
│ │ └── utils/ # Validation helpers
|
|
│ └── data/ # SQLite database (if used)
|
|
├── front_end/
|
|
│ └── src/
|
|
│ ├── app/ # Next.js pages
|
|
│ ├── components/ # React components
|
|
│ ├── config/ # Frontend config
|
|
│ ├── constants/ # Text strings
|
|
│ ├── lib/ # API client and utilities
|
|
│ └── store/ # Redux state
|
|
└── docker-compose.yml
|
|
```
|
|
|
|
## License
|
|
|
|
MIT License - see LICENSE file for details
|
|
|
|
## Acknowledgments
|
|
|
|
- Built with [LNbits](https://lnbits.com/) for Lightning Network integration
|
|
- Uses [Nostr](https://nostr.com/) for decentralized authentication
|
|
- Inspired by the Bitcoin Lightning Network community
|
|
|
|
---
|
|
|
|
⚡ **Win Bitcoin on the Lightning Network!** ⚡
|