⚡ Bitcoin Lightning Stack

A complete Bitcoin Lightning Network infrastructure stack featuring Lightning nodes, wallet management, and Chaumian ecash minting capabilities.

🏗️ Architecture

phoenixd (Lightning Node)
    ↓
lnbits (Wallet & Account System)
    ↓
cashu-mint (Ecash Mint)

This stack provides a full Bitcoin payment infrastructure from Lightning Network connectivity down to privacy-focused ecash tokens.

🛠️ Services

phoenixd - Lightning Network Node

• Purpose: Core Lightning Network connectivity
• Port: 9740
• Technology: Kotlin-based Lightning node by ACINQ
• Features: Self-custodial Lightning payments, channel management

LNbits - Lightning Wallet & Account System

• Purpose: User-friendly Lightning wallet with account management
• Port: 5000
• Technology: Python-based Lightning wallet platform
• Features: Multi-user wallets, extensions ecosystem, API access

Cashu Nutshell - Ecash Mint

• Purpose: Privacy-focused Chaumian ecash token issuance
• Port: 3338
• Technology: Python-based Cashu protocol implementation
• Features: Private payments, offline transactions, token exchange

🚀 Quick Start

Option 1: Cloud Deployment (Coolify)

1. Deploy in Coolify using the docker-compose.yml
2. Set environment variables:
   • PHOENIXD_API_PASSWORD (from phoenixd logs)
   • LNBITS_ADMIN_KEY (from LNbits admin wallet)
   • CASHU_MINT_PRIVATE_KEY (generate with openssl rand -hex 32)

Option 2: Local Development (Podman/Docker)

# Clone repository
git clone <repo-url>
cd bitcoin-lightning-stack

# Setup environment
cp .env.example .env
echo "AUTH_SECRET_KEY=$(openssl rand -hex 32)" >> .env
echo "CASHU_MINT_PRIVATE_KEY=$(openssl rand -hex 32)" >> .env

# Start services
docker-compose up -d
# OR with Podman
podman-compose up -d

# Get Phoenix password
docker logs phoenixd | grep -i password

# Update .env with password and restart
docker-compose restart lnbits cashu-mint

📋 Prerequisites

For Cloud Deployment:

• Coolify instance or similar container orchestration platform

For Local Development:

• Docker & Docker Compose OR Podman & podman-compose
• Linux/macOS (Windows with WSL2)

🔧 Configuration

Environment Variables

# Authentication
AUTH_SECRET_KEY=your-secret-key
PHOENIXD_API_PASSWORD=phoenix-generated-password
LNBITS_ADMIN_KEY=lnbits-admin-api-key
CASHU_MINT_PRIVATE_KEY=your-mint-private-key

# Optional
MINT_CONTACT=admin@yourdomain.com

Network Chain Selection

• Mainnet (default): Real Bitcoin transactions
• Testnet: For testing with test Bitcoin

  # Change in docker-compose.yml
  command: '--agree-to-terms-of-service --http-bind-ip=0.0.0.0 --chain=testnet'

🌐 Access Points

Once deployed, access your services:

• LNbits Web Interface: http://your-domain:5000
• Cashu Mint API: http://your-domain:3338
• Phoenix API: http://your-domain:9740 (if needed)

📊 Service Dependencies

graph TD
    A[phoenixd] --> B[lnbits]
    B --> C[cashu-mint]
    A -.->|funds| D[Bitcoin Lightning Network]
    B -.->|wallet UI| E[Users & Applications]
    C -.->|ecash tokens| F[Private Payments]

Loading

• phoenixd must be healthy before lnbits starts
• lnbits must be healthy before cashu-mint starts
• All services include health checks for proper startup coordination

🔐 Security Notes

• Change default keys: Generate strong random keys for production
• Secure access: Use HTTPS/TLS in production environments
• Backup data: Persistent volumes contain wallet and node data
• Network security: Consider firewall rules for exposed ports

📝 Getting Started Guide

1. Deploy the stack using your preferred method
2. Wait for phoenixd to sync and generate credentials
3. Configure LNbits with Phoenix backend credentials
4. Set up Cashu mint with LNbits admin key
5. Create wallets in LNbits for testing
6. Test payments between services

🛠️ Development

Adding New Services

1. Add service definition to docker-compose.yml
2. Configure proper dependencies using depends_on
3. Set up health checks for startup coordination
4. Add persistent volumes if needed
5. Update this README

Local Testing

See the included Podman Setup Guide for detailed local development instructions.

📚 Documentation

• phoenixd Documentation
• LNbits Documentation
• Cashu Protocol Specs

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Test changes locally
4. Submit a pull request

📄 License

This project configuration is open source. Individual services maintain their own licenses:

• phoenixd: Apache 2.0
• LNbits: MIT
• Cashu Nutshell: MIT

⚠️ Disclaimer

This software is for educational and experimental purposes. Use at your own risk with appropriate security measures for production environments.

---

Built for the Bitcoin Lightning Network community ⚡🧡