bot event system

.env.dist

@@ -1,5 +1,11 @@
-LUCKY_POT_DISCORD_TOKEN=
-LUCKY_POT_STACKCOIN_BOT_TOKEN=
-LUCKY_POT_STACKCOIN_BASE_URL=
-LUCKY_POT_TESTING_GUILD_ID=
-LUCKY_POT_DEBUG_MODE=
+LUCKYPOT_DISCORD_TOKEN=
+LUCKYPOT_STACKCOIN_API_URL=http://localhost:4000
+LUCKYPOT_STACKCOIN_API_TOKEN=
+LUCKYPOT_STACKCOIN_WS_URL=ws://localhost:4000/ws
+LUCKYPOT_DB_PATH=luckypot.db
+LUCKYPOT_TESTING_GUILD_ID=
+LUCKYPOT_DEBUG_MODE=false
+LUCKYPOT_DAILY_DRAW_HOUR=0
+LUCKYPOT_DAILY_DRAW_MINUTE=0
+# Set >0 to override daily schedule with a repeating interval (for testing)
+# LUCKYPOT_DRAW_INTERVAL_MINUTES=5

README.md

@@ -1,6 +1,41 @@
 # LuckyPot
 
-Discord bot that implements a lottery system on-top of StackCoin.
+A lottery bot for [StackCoin](https://github.com/StackCoin/StackCoin). Players
+enter a pot by paying STK, and a daily draw selects a winner who takes the
+entire pot. There's also a 5% chance of an instant win on entry.
 
-Built using [Hikari](https://www.hikari-py.dev/), and [stackcoin-python](https://github.com/StackCoin/stackcoin-python).
+## Setup
 
+```bash
+# Install dependencies
+uv sync
+
+# Copy and fill in environment variables
+cp .env.dist .env
+
+# Run the bot
+python lucky_pot.py
+```
+
+## Environment Variables
+
+All environment variables are prefixed with `LUCKYPOT_`.
+
+| Variable                    | Required | Default                                | Description                          |
+| --------------------------- | -------- | -------------------------------------- | ------------------------------------ |
+| `LUCKYPOT_DISCORD_TOKEN`    | Yes      |                                        | Discord bot token                    |
+| `LUCKYPOT_STACKCOIN_API_URL`| Yes      | `http://localhost:4000`                | StackCoin API base URL               |
+| `LUCKYPOT_STACKCOIN_API_TOKEN`| Yes    |                                        | Bot API token from StackCoin         |
+| `LUCKYPOT_STACKCOIN_WS_URL` | No      | `ws://localhost:4000/ws`               | StackCoin WebSocket URL              |
+| `LUCKYPOT_DB_PATH`          | No       | `luckypot.db`                          | SQLite database path                 |
+| `LUCKYPOT_TESTING_GUILD_ID` | No       |                                        | Restrict slash commands to one guild |
+| `LUCKYPOT_DEBUG_MODE`       | No       | `false`                                | Enable `/force-end-pot` command      |
+| `LUCKYPOT_DAILY_DRAW_HOUR`  | No       | `0`                                    | Daily draw hour (UTC)                |
+| `LUCKYPOT_DAILY_DRAW_MINUTE`| No       | `0`                                    | Daily draw minute (UTC)              |
+
+## Slash Commands
+
+- `/enter-pot` — Enter the daily lucky pot (costs 5 STK)
+- `/pot-status` — Check the current pot status and participants
+- `/pot-history` — View recent pot winners
+- `/force-end-pot` — [DEBUG] Force end the current pot with a draw