# ⚡ 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!** ⚡