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