LightningLotto/telegram_bot/README.md

Lightning Jackpot Telegram Bot ⚡🎰

A Telegram bot for the Lightning Jackpot lottery system. Users can buy tickets, check their tickets and wins, and receive instant notifications - all through Telegram!

Features

• 🎟 Buy Tickets - Quick buttons for 1, 2, 5, 10 tickets or custom amounts
• 💸 Lightning Payments - Generate and pay Lightning invoices directly in chat
• 📱 QR Codes - Visual QR codes for easy wallet scanning
• 🔔 Real-time Updates - Automatic payment confirmation notifications
• 🧾 View Tickets - See all your ticket purchases and their status
• 🏆 Track Wins - View your winning history and payouts
• ⚡ Lightning Address - Manage your payout address

Prerequisites

• Node.js 18+
• Telegram Bot Token (from @BotFather)
• Lightning Jackpot Backend API running

Installation

1. Clone the repository and navigate to the bot directory:

   cd telegram_bot
   

2. Install dependencies:

   npm install
   

3. Create environment file:

   cp env.example .env
   

4. Configure your .env file:

   TELEGRAM_BOT_TOKEN=your_bot_token_here
   API_BASE_URL=http://localhost:3000
   FRONTEND_BASE_URL=http://localhost:3001
   

Development

Run the bot in development mode with auto-reload:

npm run dev:watch

Or run once:

npm run dev

Production

Build and run:

npm run build
npm start

Docker

Build the image:

docker build -t lightning-lotto-telegram-bot .

Run the container:

docker run -d \
  --name telegram-bot \
  -e TELEGRAM_BOT_TOKEN=your_token \
  -e API_BASE_URL=http://backend:3000 \
  -e FRONTEND_BASE_URL=http://frontend:3001 \
  lightning-lotto-telegram-bot

Commands

Command	Description
/start	Begin using the bot
/menu	Show main menu
/buy	Buy lottery tickets
/tickets	View your tickets
/wins	View your past wins
/address	Update Lightning Address
/help	Help & information

Architecture

src/
├── config/          # Configuration management
├── handlers/        # Command and callback handlers
│   ├── start.ts     # /start command
│   ├── buy.ts       # Ticket purchase flow
│   ├── tickets.ts   # View tickets
│   ├── wins.ts      # View wins
│   ├── address.ts   # Lightning address management
│   ├── help.ts      # Help command
│   └── menu.ts      # Menu handling
├── services/
│   ├── api.ts       # Backend API client
│   ├── state.ts     # User state management (Redis/in-memory)
│   ├── qr.ts        # QR code generation
│   └── logger.ts    # Logging service
├── types/           # TypeScript type definitions
├── utils/
│   ├── format.ts    # Formatting utilities
│   └── keyboards.ts # Telegram keyboard builders
└── index.ts         # Main entry point

State Management

The bot uses Redis for persistent state management when available. If Redis is not configured, it falls back to in-memory storage (not recommended for production).

User states:

• idle - Default state, browsing menu
• awaiting_lightning_address - Waiting for user to enter Lightning Address
• awaiting_ticket_amount - Waiting for custom ticket amount
• awaiting_invoice_payment - Polling for payment
• updating_address - Updating Lightning Address

Environment Variables

Variable	Description	Default
TELEGRAM_BOT_TOKEN	Telegram Bot API token	Required
API_BASE_URL	Backend API URL	http://localhost:3000
FRONTEND_BASE_URL	Frontend URL for ticket links	http://localhost:3001
REDIS_URL	Redis connection URL	Optional
MAX_TICKETS_PER_PURCHASE	Maximum tickets per purchase	100
PAYMENT_POLL_INTERVAL_MS	Payment polling interval	5000
PAYMENT_POLL_TIMEOUT_MS	Payment polling timeout	900000
LOG_LEVEL	Logging level	info

License

MIT