discord-lnbits-bot/README.md

# Discord LNbits Bot

A full-stack Dockerized membership engine that lets users purchase Discord roles via Bitcoin Lightning (LNbits). It provides:
 - A Discord bot that dynamically registers slash-commands per membership “plan”
 - A Flask web UI (port 3000) for configuring your Discord/LNbits credentials and creating/editing membership plans
 - A Postgres backend to persist plans, subscriptions, and payment logs
 - Automated expiry logic (calendar-month, rolling-days, fixed-date) with scheduled role revocation

---

## 🚀 Features

- 🔧 **One-click Docker Compose**: bot + web UI + database
- ✅ **Dynamic slash-commands** for each plan (no code changes needed)
- ⚡ **Lightning invoices** via LNbits REST API
- 🌐 **WebSocket listener** for incoming payments
- 👤 **Automatic role assignment** on payment
- ⏰ **Scheduled cleanup** of expired subscriptions
- 📊 **Persistent audit log** in Postgres (raw JSON, timestamps, statuses)

---

## 📋 Requirements

- **A Discord Bot Token** (from the [Developer Portal](https://discord.com/developers/applications))
- **LNbits Wallet Invoice Key**
- **A running LNbits instance** (e.g., [Sats.Love](https://sats.love/))
- **Docker Engine (v20+)**
- **Docker Compose (v1.29+ or the built-in docker compose)**

---

## 1️⃣ Setting Up Your Bot

### Generate a Proper Bot Invite Link

1. **Go to**: [Discord Developer Portal](https://discord.com/developers/applications)  
2. **Click New Application**
3. Go to **OAuth2 > URL Generator**  
4. **Check these Scopes**:  
   - ✅ **bot**  
   - ✅ **applications.commands** (for slash commands)  
4. **Under Bot Permissions**, check:  
   - ✅ **Manage Roles**  
   - ✅ **Send Messages**  
   - ✅ **Embed Links**  
   - ✅ **Read Message History**  
5. **Copy & paste the generated link into your browser.**  
6. **Select your Discord server** and click **Authorize**.

---

### Enable Privileged Intents

1. **Go to** [Discord Developer Portal](https://discord.com/developers/applications).  
2. **Select your bot application.**  
3. **Navigate to** `Bot` in the left sidebar.  
4. **Scroll down to** `Privileged Gateway Intents`.  
5. **Enable** the following:  
   - ✅ **Presence Intent**
   - ✅ **Server Members Intent**
   - ✅ **Message Content Intent** 
6. **Click Save Changes.**

---

### Ensure Correct Role Permissions

1. **Go to Server Settings** → `Roles`.  
2. **Drag the bot’s role ABOVE** the role it needs to assign.  
3. **Ensure the bot has these permissions**:  
   - ✅ **Manage Roles**  
   - ✅ **Read Messages**  
   - ✅ **Send Messages**  

---

## 2️⃣ Installation Guide

### 1. Install System Dependencies

```bash
sudo apt update && sudo apt upgrade -y
sudo apt install python3 python3-pip python3-venv -y
```

### 2. Clone the Repository

```bash
git clone https://code.rustysats.com/saulteafarmer/discord-lnbits-bot
cd discord-lnbits-bot
```

### 3. Copy & Edit .env

```bash
cp .env.example .env
nano .env
```

### 4. Buld & run

```bash
docker-compose up -d --build
```

### 5. Open the web UI

Visit: http://localhost:3000
 - Configure your Discord Bot Token, Guild ID, LNbits URL, LNbits Invoice Key
 - Define membership plans (command name, role ID, channel ID, price, expiry policy)

---

## 3️⃣ Find Your Discord Guild ID & Role ID

Before configuring the bot, retrieve your **Guild ID** and **Role ID**.

### 🔹 How to Find Your Guild ID (Server ID):

1. Open **Discord** → Go to **User Settings** (⚙️).  
2. Scroll down to **Advanced** → Enable **Developer Mode**.  
3. **Right-click your server name** (left sidebar) → Click **Copy ID**.  
4. **Save this ID** for later (`guild_id`).  

### 🔹 How to Find Your Role ID:

1. Open your **Discord Server**.  
2. Go to **Server Settings** → **Roles**.  
3. **Right-click on the role** you want to assign → Click **Copy ID**.  
4. **Save this ID** for later (`role_id`).  

---

## 4️⃣ Configure the Bot

Edit the `config.json` file inside the bot directory:

```bash
sudo nano config.json
```

```json
{
  "discord_token": "YOUR_DISCORD_BOT_TOKEN",
  "guild_id": "YOUR_GUILD_ID",
  "role_id": "YOUR_ROLE_ID",
  "lnbits_url": "https://sats.love",
  "lnbits_api_key": "YOUR_INVOICE_READ_KEY",
  "channelid": "YOUR_CHANNELID_FOR_PURCHASE_ROOM",
  "price": 1000,
  "command_name": "support",
  "invoicemessage": "Invoice for your purchase."
}
```

### 🔹 What Each Setting Does:

- **`discord_token`** → Your bot token from Discord Developer Portal  
- **`guild_id`** → Your Discord server ID  
- **`role_id`** → The Discord role the bot will assign  
- **`lnbits_url`** → Base URL of your LNbits instance  
- **`lnbits_api_key`** → **Invoice-only key** from LNbits (⚠️ NOT an admin key)  
- **`price`** → Price in **satoshis** (e.g., `1000` = 1000 sats)  
- **`command_name`** → Name of the command (default: `support`)  
- **`invoicemessage`** → Message to be sent with invoice  
- **`channelid`** → Discord channel where invoices and confirmations post 

---

## 5️⃣ Run the Bot

```bash
python3 discord_lnbits_bot.py
```

---

## 6️⃣ Running the Bot in the Background

```bash
nohup python3 discord_lnbits_bot.py &
```

🔹 **To stop the bot**:

```bash
pkill -f discord_lnbits_bot.py
```

---

## License

This project is **open-source** and free to use. Contributions welcome!