d3bf8080b6
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
143 lines
3.1 KiB
Markdown
143 lines
3.1 KiB
Markdown
# 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
|
|
|