Michilis/LightningLotto
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit: Lightning Lottery - Bitcoin Lightning Network powered lottery

Browse Source 
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
This commit is contained in:
Michilis
2025-11-27 22:13:37 +00:00
commit d3bf8080b6
75 changed files with 18184 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

318
README.md Normal file
View File

@@ -0,0 +1,318 @@
# ⚡ 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!** ⚡