86e2e0a321
- Fix reminder duplicate bug: use slot-only keys to prevent multiple reminders when settings change - Add New Jackpot announcement delay setting for groups (default 5 min) - Cancel unpaid purchases after draw completes (prevents payments for past rounds) - Add BotFather commands template file - Update README documentation
431 lines
13 KiB
Markdown
431 lines
13 KiB
Markdown
# ⚡ Lightning Lotto
|
|
|
|
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
|
|
- ⏰ **Flexible Cycles**: Configurable draw intervals (minutes, hours, days, weekly, or cron)
|
|
- 🔄 **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`
|
|
- 🤖 **Telegram Bot**: Full-featured bot for buying tickets and receiving notifications
|
|
|
|
## Architecture
|
|
|
|
The system consists of four main components:
|
|
|
|
1. **Backend API** (Node.js + TypeScript + Express)
|
|
2. **Frontend** (Next.js + React + TypeScript + TailwindCSS)
|
|
3. **Telegram Bot** (Node.js + TypeScript + node-telegram-bot-api)
|
|
4. **Database** (PostgreSQL or SQLite)
|
|
|
|
### Backend
|
|
|
|
- RESTful API with comprehensive endpoints
|
|
- LNbits integration for Lightning payments
|
|
- Automated scheduler for draws and cycle generation
|
|
- Configurable cycle types (minutes, hours, days, weekly, cron)
|
|
- 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
|
|
- 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
|
|
- Fully responsive mobile-first design
|
|
|
|
### Telegram Bot
|
|
|
|
- Buy tickets directly from Telegram
|
|
- Lightning Address management (with 21Tipbot & Bittip integration)
|
|
- View tickets and wins
|
|
- Notification preferences (draw reminders, results, new jackpot alerts)
|
|
- Group support with admin controls
|
|
- Customizable reminders (up to 3 reminder slots per group)
|
|
- SQLite database for persistent user/group settings
|
|
|
|
## 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
|
|
cp telegram_bot/env.example telegram_bot/.env
|
|
# Edit all 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
|
|
```
|
|
|
|
#### Telegram Bot
|
|
|
|
```bash
|
|
cd telegram_bot
|
|
npm install
|
|
cp env.example .env
|
|
# Edit .env with your bot token and API URL
|
|
|
|
# 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
|
|
|
|
# Cycle Configuration (choose one type)
|
|
CYCLE_TYPE=hours # minutes | hours | days | weekly | cron
|
|
CYCLE_INTERVAL_MINUTES=30 # For 'minutes' type
|
|
CYCLE_INTERVAL_HOURS=1 # For 'hours' type
|
|
CYCLE_DAILY_TIME=20:00 # For 'days' type (HH:MM UTC)
|
|
CYCLE_WEEKLY_DAY=saturday # For 'weekly' type
|
|
CYCLE_WEEKLY_TIME=20:00 # For 'weekly' type (HH:MM UTC)
|
|
CYCLE_CRON_EXPRESSION=0 */6 * * * # For 'cron' type
|
|
```
|
|
|
|
#### Frontend (.env.local)
|
|
|
|
```bash
|
|
NEXT_PUBLIC_API_BASE_URL=http://localhost:3000
|
|
```
|
|
|
|
#### Telegram Bot (.env)
|
|
|
|
```bash
|
|
TELEGRAM_BOT_TOKEN=your-telegram-bot-token
|
|
API_BASE_URL=http://localhost:3000
|
|
FRONTEND_BASE_URL=http://localhost:3001
|
|
# BOT_DATABASE_PATH=./data/bot.db # Optional, defaults to ./data/bot.db
|
|
```
|
|
|
|
See `back_end/env.example`, `front_end/env.example`, and `telegram_bot/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).
|
|
|
|
## Telegram Bot Commands
|
|
|
|
### Private Chat Commands
|
|
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `/start` | Start the bot and register |
|
|
| `/lottomenu` | Show main menu |
|
|
| `/buyticket` | Buy lottery tickets |
|
|
| `/tickets` | View your tickets |
|
|
| `/wins` | View your wins |
|
|
| `/lottoaddress` | Set your Lightning Address |
|
|
| `/lottosettings` | Notification settings |
|
|
| `/lottohelp` | Show help |
|
|
|
|
### Group Commands (Admin Only)
|
|
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `/lottosettings` | Configure group lottery settings |
|
|
| `/jackpot` | Show current jackpot info |
|
|
|
|
### Group Features
|
|
|
|
- Enable/disable draw announcements
|
|
- Enable/disable new jackpot alerts
|
|
- Up to 3 customizable draw reminders
|
|
- Adjustable reminder times (minutes/hours/days)
|
|
- Auto-deleting settings messages (2 min TTL)
|
|
|
|
## Database Schema
|
|
|
|
### Backend Database (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
|
|
|
|
### Telegram Bot Database (SQLite)
|
|
|
|
- `users` - Telegram user profiles and notification preferences
|
|
- `user_purchases` - Tracks purchases per user
|
|
- `cycle_participants` - Tracks participants per cycle
|
|
- `groups` - Group settings and reminder configurations
|
|
|
|
## How It Works
|
|
|
|
1. **Cycle Generation**: Scheduler automatically creates future draw cycles
|
|
2. **Ticket Purchase**: Users buy tickets via web or Telegram, 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. **Notifications**: Telegram bot sends draw results to participants and groups
|
|
7. **Payout**: Winner's Lightning Address paid automatically
|
|
8. **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)
|
|
- Lightning Address LNURL verification
|
|
|
|
## 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 |
|
|
|
|
## Production Deployment
|
|
|
|
### Systemd Services & Nginx
|
|
|
|
The `setup/` folder contains production-ready configuration files:
|
|
|
|
- `lightning-lotto-backend.service` - Backend systemd service
|
|
- `lightning-lotto-frontend.service` - Frontend systemd service
|
|
- `lightning-lotto-telegram.service` - Telegram bot systemd service
|
|
- `nginx-lightning-lotto.conf` - Nginx reverse proxy with SSL
|
|
|
|
See `setup/README.md` for detailed deployment instructions.
|
|
|
|
### 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
|
|
├── telegram_bot/
|
|
│ ├── src/
|
|
│ │ ├── config/ # Bot configuration
|
|
│ │ ├── handlers/ # Command and callback handlers
|
|
│ │ ├── messages/ # Centralized message strings
|
|
│ │ ├── services/ # Database, API, notifications
|
|
│ │ ├── types/ # TypeScript types
|
|
│ │ └── utils/ # Keyboards, formatting
|
|
│ └── data/ # SQLite database for bot
|
|
├── setup/ # Production deployment configs
|
|
│ ├── *.service # Systemd service files
|
|
│ ├── nginx-*.conf # Nginx configuration
|
|
│ └── README.md # Deployment guide
|
|
├── App_info/ # Documentation
|
|
└── docker-compose.yml
|
|
```
|
|
|
|
## Testing
|
|
|
|
### Backend Tests
|
|
```bash
|
|
cd back_end
|
|
npm test
|
|
```
|
|
|
|
### Frontend Tests
|
|
```bash
|
|
cd front_end
|
|
npm test
|
|
```
|
|
|
|
## 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
|
|
- Telegram bot integration for mobile-first experience
|
|
- Inspired by the Bitcoin Lightning Network community
|
|
|
|
---
|
|
|
|
⚡ **Win Bitcoin on the Lightning Network!** ⚡
|