# Lightning Lottery Backend API

Bitcoin Lightning Network powered lottery system with automatic payouts to Lightning Addresses.

## Features

- **Public Ticket Purchasing**: Anonymous ticket purchases via Lightning invoices
- **Automated Draws**: Scheduled draws using cryptographically secure RNG
- **Instant Payouts**: Automatic payouts to Lightning Addresses
- **Nostr Authentication**: Optional user accounts via Nostr signatures
- **Multiple Cycle Types**: Hourly, daily, weekly, and monthly jackpots
- **Admin Interface**: Manual draw triggers and payout management

## Tech Stack

- **Runtime**: Node.js with TypeScript
- **Framework**: Express.js
- **Database**: PostgreSQL
- **Lightning**: LNbits integration
- **Scheduler**: node-cron

## Setup

### Prerequisites

- Node.js 18+ 
- PostgreSQL 14+
- LNbits instance

### Installation

1. Install dependencies:
```bash
npm install
```

2. Configure environment variables:
```bash
cp .env.example .env
# Edit .env with your configuration
```

3. Setup database:
```bash
# Create database
createdb lightning_lotto

# Run schema
psql lightning_lotto < src/database/schema.sql
```

### Development

```bash
npm run dev
```

### Production

```bash
npm run build
npm start
```

### Scheduler (Optional Separate Process)

```bash
npm run scheduler
```

## API Endpoints

### Public Endpoints

- `GET /jackpot/next` - Get next upcoming cycle
- `POST /jackpot/buy` - Create ticket purchase
- `GET /tickets/:id` - Get ticket status

### User Endpoints (Nostr Auth)

- `POST /auth/nostr` - Authenticate with Nostr
- `GET /me` - Get user profile
- `PATCH /me/lightning-address` - Update Lightning Address
- `GET /me/tickets` - Get user's tickets
- `GET /me/wins` - Get user's wins

### Admin Endpoints

- `GET /admin/cycles` - List all cycles
- `POST /admin/cycles/:id/run-draw` - Manually run draw
- `GET /admin/payouts` - List payouts
- `POST /admin/payouts/:id/retry` - Retry failed payout

### Webhook Endpoints

- `POST /webhooks/lnbits/payment` - LNbits payment notification

## Configuration

See `.env.example` for all configuration options.

### Required Environment Variables

- `DATABASE_URL` - PostgreSQL connection string
- `LNBITS_API_BASE_URL` - LNbits API URL
- `LNBITS_ADMIN_KEY` - LNbits admin/invoice key
- `JWT_SECRET` - Secret for JWT signing
- `ADMIN_API_KEY` - Admin endpoint authentication

## Database Schema

The system uses 7 main tables:

- `lotteries` - Lottery configuration
- `jackpot_cycles` - Draw cycles
- `ticket_purchases` - Purchase records
- `tickets` - Individual tickets
- `payouts` - Winner payouts
- `users` - Nostr user accounts
- `draw_logs` - Audit trail

## Security

- JWT tokens for user authentication
- Admin API key for admin endpoints
- Webhook signature verification
- Rate limiting on all endpoints
- Idempotent payment processing
- Transaction-based ticket issuance

## Scheduler Tasks

The scheduler runs three main tasks:

1. **Cycle Generator**: Creates future cycles (every 5 minutes)
2. **Draw Executor**: Triggers draws at scheduled times (every minute)
3. **Payout Retry**: Retries failed payouts with exponential backoff (every 10 minutes)

## License

MIT