Pump Lotto Backend

A real-time sweepstakes platform that monitors Solana blockchain transactions and automatically conducts fair draws every 20 minutes. This backend powers Banana Flip (pump.fun/coin/FjFt9FyxcKJE9wgMWwbJBLrEqXobnFB4zqLh3sprsD1d) and serves as the authoritative engine for the entire Pump Lotto ecosystem.

🎯 Overview

Pump Lotto Backend is a Node.js application that:

Monitors Solana blockchain for qualifying token transactions in real-time
Manages automated game cycles with configurable duration (default: 20 minutes)
Executes provably fair draws with transparent winner selection
Provides real-time updates via WebSocket connections
Serves comprehensive APIs for game state and historical data

The frontend repository is available at: pumplotto_frontend

🏗️ Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Frontend      │    │   Mobile App    │    │   Dashboard     │
│   (React)       │    │   (Flutter)     │    │   (Admin)       │
└─────────┬───────┘    └─────────┬───────┘    └─────────┬───────┘
          │                      │                      │
          └──────────────────────┼──────────────────────┘
                                 │
                    ┌─────────────▼─────────────┐
                    │   Pump Lotto Backend      │
                    │      (Node.js)            │
                    └─────────────┬─────────────┘
                                  │
          ┌───────────────────────┼───────────────────────┐
          │                       │                       │
┌─────────▼─────────┐   ┌─────────▼─────────┐   ┌─────────▼─────────┐
│   MySQL Database  │   │  Solana Network   │   │   File Storage    │
│   (Game State)    │   │   (Blockchain)    │   │    (Logs)         │
└───────────────────┘   └───────────────────┘   └───────────────────┘

Core Services

🕐 Scheduler Service: Manages game timing and lifecycle
⛓️ Solana Listener: Monitors blockchain for qualifying transactions
🎲 Draw Service: Executes fair winner selection algorithm
🎮 Game Service: Handles game state management
👥 Participant Service: Manages participant registration and validation

🚀 Quick Start

Prerequisites

Node.js 18.x or higher
MySQL 8.0 or higher
Solana token deployment on desired network

Installation

Clone the repository

git clone <repository-url>
cd pump-lotto-backend

Install dependencies
```
npm install
```

Setup database

mysql -u root -p

CREATE DATABASE banana_flip;
CREATE USER 'banana_user'@'localhost' IDENTIFIED BY 'secure_password';
GRANT ALL PRIVILEGES ON banana_flip.* TO 'banana_user'@'localhost';
FLUSH PRIVILEGES;

mysql -u banana_user -p banana_flip < database/schema.sql

Configure environment

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

Start the application

# Development
npm run dev

# Production
npm start

⚙️ Configuration

Key environment variables:

# Database
DB_HOST=localhost
DB_USER=banana_user
DB_PASSWORD=your_password
DB_NAME=banana_flip

# Solana Network
SOLANA_NETWORK=mainnet
TOKEN_MINT_ADDRESS_MAINNET=FjFt9FyxcKJE9wgMWwbJBLrEqXobnFB4zqLh3sprsD1d
MIN_SOL_AMOUNT=0.040

# Game Configuration  
GAME_DURATION_MINUTES=20
PORT=3000

See Configuration Guide for complete setup details.

📡 API Reference

REST Endpoints

`GET /api/v1/gamestate`

Returns current game state including active participants and recent winners.

`GET /api/v1/winners`

Returns paginated list of all winners with statistics.

`GET /api/v1/winners/:address/stats`

Returns win statistics for a specific wallet address.

`GET /health`

Health check endpoint for monitoring.

WebSocket Events

Server → Client

new_participant: Emitted when someone joins the current game
winner_declared: Emitted when a draw completes with winner and shortlist
new_game_started: Emitted every 20 minutes when a new game begins

See API Documentation for complete reference.

🎲 Fair Draw Algorithm

Participant Collection: Gather all unique wallet addresses from the current game
Shortlist Creation: Randomly select up to 25 unique participants using Fisher-Yates shuffle
Winner Selection: Randomly select one winner from the shortlist using cryptographically secure randomness
Transparency: All draw results are permanently stored and publicly accessible

🔧 Development

Local Development Setup

# Install dependencies
npm install

# Setup development database
mysql -u root -p < database/schema.sql

# Configure for development
cp .env.example .env
# Set SOLANA_NETWORK=devnet and GAME_DURATION_MINUTES=2

# Start with auto-reload
npm run dev

Testing

# Run health check
curl http://localhost:3000/health

# Test WebSocket connection
npm install -g wscat
wscat -c ws://localhost:3000

# Check game state
curl http://localhost:3000/api/v1/gamestate

See Development Guide for comprehensive development instructions.

🚀 Deployment

Production Deployment with PM2

# Install PM2
npm install -g pm2

# Start application
pm2 start ecosystem.config.js

# Save PM2 configuration
pm2 save
pm2 startup

Docker Deployment

# Build and run with Docker Compose
docker-compose up -d

# View logs
docker-compose logs -f app

See Deployment Guide for detailed deployment instructions.

📊 Monitoring

Health Monitoring

/health endpoint for load balancer probes
Database connection monitoring
Solana RPC connectivity checks
WebSocket connection tracking

Performance Metrics

Game cycle timing
Transaction processing rates
Database query performance
Memory and CPU usage

🔒 Security

Input Validation: All transactions validated for format and authenticity
Duplicate Prevention: Transaction signatures ensure one entry per transaction
SQL Injection Protection: Prepared statements throughout
Rate Limiting: Configurable limits on API endpoints
Secure Configuration: Environment-based secrets management

🗂️ Database Schema

Tables

games: Tracks 20-minute game cycles with timing and winner data
participants: Records all valid entries per game with SOL amounts
winners: Dedicated winner tracking for statistics and transparency

Key Features

Foreign key relationships for data integrity
Optimized indexes for query performance
JSON storage for draw shortlists
Precise decimal handling for SOL amounts

See Database Documentation for complete schema details.

📁 Documentation

API Reference - Complete REST API and WebSocket documentation
Architecture - System design and component overview
Database Schema - Database structure and relationships
Services - Service layer documentation
Configuration - Environment setup and options
Development - Local development guide
Deployment - Production deployment instructions
Troubleshooting - Common issues and solutions

🤝 Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📄 License

🆘 Support

For technical support or questions:

Check the Troubleshooting Guide
Review the relevant documentation
Create an issue in the repository
Contact the development team

Built with ❤️ for the Solana ecosystem

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
database		database
docs		docs
routes		routes
services		services
.env.example		.env.example
.gitignore		.gitignore
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
server.js		server.js

UjwalAKrishna/pumplotto_backend

Folders and files

Latest commit

History

Repository files navigation