LightningLotto/back_end

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:

npm install

2. Configure environment variables:

cp .env.example .env
# Edit .env with your configuration

3. Setup database:

# Create database
createdb lightning_lotto

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

Development

npm run dev

Production

npm run build
npm start

Scheduler (Optional Separate Process)

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