Fix reminder scheduling and add group features

- Fix reminder duplicate bug: use slot-only keys to prevent multiple reminders when settings change - Add New Jackpot announcement delay setting for groups (default 5 min) - Cancel unpaid purchases after draw completes (prevents payments for past rounds) - Add BotFather commands template file - Update README documentation
2025-12-08 23:49:54 +00:00
parent 13fd2b8989
commit 86e2e0a321
10 changed files with 366 additions and 51 deletions
--- a/README.md
+++ b/README.md
@@ -1,4 +1,4 @@
-# ⚡ Lightning Lottery
+# ⚡ Lightning Lotto

 A complete Bitcoin Lightning Network powered lottery system with instant payouts to Lightning Addresses.

@@ -10,24 +10,27 @@ A complete Bitcoin Lightning Network powered lottery system with instant payouts
 - 🌐 **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
+- ⏰ **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 three main components:
+The system consists of four main components:

 1. **Backend API** (Node.js + TypeScript + Express)
 2. **Frontend** (Next.js + React + TypeScript + TailwindCSS)
-3. **Database** (PostgreSQL or SQLite)
+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
@@ -36,13 +39,23 @@ The system consists of three main components:
 ### 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
+- 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

@@ -58,7 +71,8 @@ cd LightningLotto
 ```bash
 cp back_end/env.example back_end/.env
 cp front_end/env.example front_end/.env.local
-# Edit both files with your configuration
+cp telegram_bot/env.example telegram_bot/.env
+# Edit all files with your configuration
 ```

 3. Start services:
@@ -113,6 +127,22 @@ 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
@@ -138,6 +168,15 @@ ADMIN_API_KEY=your-admin-api-key
 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)
@@ -146,7 +185,16 @@ PAYOUT_MAX_ATTEMPTS_BEFORE_REDRAW=2
 NEXT_PUBLIC_API_BASE_URL=http://localhost:3000
 ```

-See `back_end/env.example` and `front_end/env.example` for all configuration options.
+#### 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

@@ -186,9 +234,39 @@ See `back_end/env.example` and `front_end/env.example` for all configuration opt

 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

-7 main tables:
+### Backend Database (7 main tables)

 - `lotteries` - Lottery configuration
 - `jackpot_cycles` - Draw cycles with status and winners
@@ -198,15 +276,23 @@ Full API documentation available at `/api-docs` (Swagger UI).
 - `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, receive Lightning invoice
+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. **Payout**: Winner's Lightning Address paid automatically
-7. **Retry/Redraw**: Failed payouts retried; new winner drawn after max attempts
+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

@@ -219,6 +305,7 @@ Full API documentation available at `/api-docs` (Swagger UI).
 - `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

@@ -233,21 +320,18 @@ Full API documentation available at `/api-docs` (Swagger UI).
 | `/dashboard/tickets` | User's ticket history |
 | `/dashboard/wins` | User's win history |

-## Testing
+## Production Deployment

-### Backend Tests
-```bash
-cd back_end
-npm test
-```
+### Systemd Services & Nginx

-### Frontend Tests
-```bash
-cd front_end
-npm test
-```
+The `setup/` folder contains production-ready configuration files:

-## Deployment
+- `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

@@ -298,11 +382,38 @@ LightningLotto/
 │       ├── components/     # React components
 │       ├── config/         # Frontend config
 │       ├── constants/      # Text strings
-│       ├── lib/            # API client and utilities
-│       └── store/          # Redux state
+│       └── 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
@@ -311,6 +422,7 @@ MIT License - see LICENSE file for details

 - 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

 ---