Pledge2Play

A Bitcoin Lightning Network gaming application where players compete in synchronous game rooms by staking satoshis.

Overview

Pledge2Play is a web-based gaming platform that leverages the Bitcoin Lightning Network for instant, low-fee micropayments. Two players join a game room, each stakes 1,000 satoshis, and the winner (determined by a random number generator) receives the full 2,000 satoshi prize via Lightning Network payment.

Features

• Lightning-Fast Payments: Instant Bitcoin transactions via Lightning Network
• Fair Gaming: Random number generation determines winners (even numbers = Player 1, odd = Player 2)
• Personal Experience: Players enter their names for a personalized gaming experience
• Real-Time Updates: Live game state updates without page refreshes
• Secure Staking: All Bitcoin transactions are handled through secure Lightning invoices
• Simple Interface: Clean, intuitive UI built with Bootstrap dark theme

How It Works

1. Create a Game: Player 1 creates a new game room with their name
2. Share the Room: Copy and share the game URL with another player
3. Join the Game: Player 2 enters their name and joins the room
4. Stake Bitcoin: Both players stake 1,000 sats via Lightning Network
5. Play: The server generates a random number to determine the winner
6. Payout: Winner receives 2,000 sats instantly to their Lightning wallet

Technology Stack

• Backend: Python Flask web framework
• Database: PostgreSQL with SQLAlchemy ORM
• Lightning Network: Lexe sidecar for Bitcoin payment processing
• Frontend: Bootstrap 5 with dark theme
• Real-time Updates: JavaScript polling for game state changes

Prerequisites

• Python 3.11+
• PostgreSQL database
• Lexe API credentials for Lightning Network access

Installation

1. Clone the repository:

git clone https://github.com/yourusername/pledge2play.git
cd pledge2play

2. Install dependencies:

pip install Flask Flask-SQLAlchemy gunicorn psycopg2-binary requests SQLAlchemy Werkzeug

3. Set up environment variables:

export DATABASE_URL="postgresql://user:password@localhost/pledge2play"
export LEXE_CLIENT_CREDENTIALS="your_base64_encoded_credentials"
export SESSION_SECRET="your_secret_key_here"

4. Initialize the database:

python -c "from app import app, db; app.app_context().push(); db.create_all()"

5. Run the application:

gunicorn --bind 0.0.0.0:5000 main:app

Configuration

Lexe Lightning Network Setup

The application uses Lexe's Lightning Network sidecar for payment processing. You'll need to:

1. Obtain Lexe API credentials
2. The sidecar binary will be automatically downloaded on first run
3. The sidecar runs on port 5393 by default

Database Configuration

The application supports both SQLite (development) and PostgreSQL (production):

• Development: Uses SQLite by default if DATABASE_URL is not set
• Production: Set DATABASE_URL to your PostgreSQL connection string

Project Structure

pledge2play/
├── app.py                 # Flask application initialization
├── models.py              # SQLAlchemy database models
├── routes.py              # Web route handlers
├── game_service.py        # Game logic and state management
├── lexe_service.py        # Lightning Network integration
├── startup.py             # Application initialization
├── templates/             # HTML templates
│   ├── base.html         # Base template
│   ├── index.html        # Home page
│   ├── create_game.html  # Game creation
│   ├── game_room.html    # Game room interface
│   └── payout.html       # Payout interface
└── static/               # Static assets
    └── style.css         # Custom styles

API Endpoints

• GET / - Home page
• POST /create - Create a new game room
• GET /game/<game_id> - Game room interface
• POST /join/<game_id> - Join an existing game
• POST /api/stake - Create Lightning invoice for staking
• GET /api/check_payment - Check invoice payment status
• POST /api/play - Execute game and determine winner
• GET /api/game_status - Get current game state
• POST /payout/<game_id> - Process winner payout

Security Considerations

• Session-based player authentication
• CSRF protection via Flask sessions
• Secure handling of Lightning Network credentials
• Input validation for all user inputs
• Protection against URL preview auto-joining

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Built with the Lexe Lightning Network API
• Powered by the Bitcoin Lightning Network
• UI framework by Bootstrap

Disclaimer

This is a demonstration application for educational purposes. Please gamble responsibly and only stake what you can afford to lose.