Bitcoin Challenges Plugin for CTFd

A CTFd plugin that enables Bitcoin rewards for challenge completions, with Lightning Network support for instant withdrawals.

Features

• Real Bitcoin rewards for solving challenges
• Instant withdrawal to Lightning address on solve
• Persistent balance system with transaction history
• Lightning Network withdrawals via LNURL
• Admin wallet management dashboard
• User profile integration with balance display
• Auto-withdraw option for users with saved Lightning address

Installation

1. Copy the plugin to CTFd plugins directory:

CTFd/plugins/bitcoin_challenges/

2. Install dependencies:

pip install breez-sdk qrcode[pil] lnurl

3. Set environment variables:

export BREEZ_API_KEY=your_api_key
export WALLET_MNEMONIC="your twelve word seed phrase"
export BITCOIN_DATA_DIR=./data/bitcoin_wallet

4. Restart CTFd

Usage

For Administrators

1. Create a new challenge and select "Bitcoin" as the challenge type
2. Set the standard point value (for scoreboard)
3. Set the Bitcoin reward amount in satoshis
4. Enable/disable Bitcoin rewards as needed

Access the admin wallet dashboard at /admin/bitcoin to:

• View wallet balance
• Fund the wallet
• Monitor withdrawals
• View transaction history

For Users

1. Solve Bitcoin challenges to earn sats
2. On successful solve, enter Lightning address to withdraw instantly
3. Or save Lightning address in Settings for quick withdrawals
4. View balance and history in Settings > Bitcoin tab

Configuration

Required Environment Variables

• BREEZ_API_KEY: Your Breez SDK API key
• WALLET_MNEMONIC: 12-word seed phrase for the wallet

Optional Environment Variables

• BITCOIN_DATA_DIR: Directory for wallet data (default: ./data/bitcoin_wallet)
• BITCOIN_MAX_WITHDRAWAL_PER_DAY: Daily withdrawal limit per user (default: 10)
• BITCOIN_MAX_WITHDRAWAL_PER_HOUR: Hourly withdrawal limit per user (default: 5)

File Structure

CTFd/plugins/bitcoin_challenges/
├── __init__.py           # Main plugin, challenge class, API routes
├── models.py             # Database models (Balance, Reward, Withdrawal)
├── balances.py           # Balance management functions
├── payments.py           # Breez SDK integration
├── errors.py             # Error handling
├── logging_config.py     # Logging configuration
├── assets/
│   ├── create.html       # Challenge creation template
│   ├── update.html       # Challenge edit template
│   ├── view.html         # Challenge view template
│   ├── bitcoin-challenge-success.js  # Withdrawal UI on solve
│   └── settings_bitcoin_tab.js       # User settings tab
└── admin/
    ├── routes.py         # Admin API routes
    └── templates/        # Admin dashboard templates

Security

• Wallet mnemonic stored only in environment variables
• Rate limiting on withdrawals
• Input validation on all endpoints
• CSRF protection on all forms
• Comprehensive audit logging