v4 - IA Bot (Impact Awards Bot)

 ## **Comments**
 - Inputs in orange **[example]** are optional
 - As of 2025-09-29, **Bot Administrators** refers to users with configured admin role IDs (configurable via database)
 - **give_coin_channel** refers to the configured channel ID for coin transfer notifications (configurable via database)
 - Channel and role IDs are now configurable through database settings instead of hardcoded values
 - The bot has been rebranded from "pythbot" to "IA Bot" (Impact Awards Bot)

 ## 💰 General Commands
 ---
 | **Command** | **Description** | **Command Details** |
 | --- | --- | --- |
 | /bank | Displays the user's "wallet" balance<br><br>Using the **[member]** input will show the specified member "wallet" balance<br><br>If user is **Bot Administrator** the result will be private (only visible to the user) and will show the IAs "given to others" and the "allocated wallet" balance | /bank **[member]** |
 | /richest | Displays the total of awarded IAs in the current cycle and a leaderboard of users with the highest amount of IAs in "wallet" | /richest |

 ## 🛒 Merch Shop Commands
 ---
 | **Command** | **Description** | **Command Details** |
 | --- | --- | --- |
 | /shop | Displays a list of Item-Merch available for buying and their "price" in IA coins<br><br>Shop items are now configurable through database settings | /shop |
 | /item-info | Provides a picture and "price" of the specified Item-Merch | /item-info [item_name] |
 | /buy | Adds the specified Item-Merch to the user's unclaimed Item-Merch inventory while removing the corresponding "price" from the user's "wallet" balance<br><br>Generates a unique coupon code for order tracking | /buy [item_name] |
 | /inv | Displays the user's unclaimed Item-Merch inventory<br><br>Using the **[member]** input will show the specified member inventory | /inv **[member]** |

 ## 🌧️ Rain Commands (Bot Administrators)
 ---

| **Command Group** | **Command** | **Description** | **Command Details** |
| --- | --- | --- | --- |
| /autorain | create | Set up an automated rain event with scheduled drops\\n\\nSupports multiple selection strategies (most messages, reactions, random, new members, registered users)\\n\\nAdmins auto-excluded by default; configurable exclusion roles and per-event user cooldowns\\n\\nOptional instant-first-drop; calculates duration and schedules drops automatically | /autorain create [count] [interval_hours] [criteria_str] [coins_per_drop] [channel] **[recipients_per_drop]** **[description]** **[user_reward_cooldown_hours]** **[exclude_role_1-5]** **[instant_first_drop]** |
| /autorain | list | List all active automated rain events\\n\\nShows progress, next drop times, and event details\\n\\nDisplays channel, creator, and completion status | /autorain list |
| /autorain | cancel | Cancel an active automated rain event\\n\\nOption to refund remaining coins to creator\\n\\nSupports partial rain ID matching | /autorain cancel [rain_id] **[refund]** |
| /autorain | strategies | List and explain available automated rain strategies\\n\\nShows detailed descriptions of each selection criteria\\n\\nHelps admins choose appropriate strategy for their needs | /autorain strategies |
| /autorain | trigger | Manually trigger a drop from an automated rain (Admin only)\\n\\nUseful for testing or catching up after downtime | /autorain trigger [rain_id] |

## 📝 Registration Commands

---

| **Command Group** | **Command** | **Description** | **Command Details** |
| --- | --- | --- | --- |
| /registration | setup | Set up the registration interface with interactive buttons<br><br>Creates a persistent message with buttons for Twitter linking, SOL and EVM submission (via modals) | /registration setup |
| /registration | link_twitter | Start Twitter OAuth linking flow (opens a link button) | /registration link_twitter |
| /registration | status | Check your own registration status<br><br>Shows completion status for Twitter account linking, SOL address, and EVM address | /registration status |
| /registration | details | Admin: View a user's registration details | /registration details [user] |
| /registration | edit | Admin: Open an admin modal to edit a user's registration (twitter/sol/evm) | /registration edit [user] |
| /registration | backfill | Admin: Assign registration-complete role to all eligible members in this server | /registration backfill |
| /registration | export | Admin: Export user registration data to CSV/Excel | /registration export |

## 🎮 Quest Commands (Bot Administrators)

---

| **Command** | **Description** | **Command Details** |
| --- | --- | --- |
| /quest-announce | Announce a quest/giveaway with rich embed formatting<br><br>Creates professional quest announcements with custom colors, images, and action buttons<br><br>Automatically creates discussion threads<br><br>Includes autocomplete for all fields | /quest-announce [post_title] [title] [short_description] [type_of_event] [ends] [thread_title] [color] [collaboration_with] [requirements] [button_label] [button_url] [image_url] **[mint_price]** **[spots]** **[mint_date]** **[supply]** **[network]** |
| /thread-test | Validate that the bot can create a thread in the current channel and has correct permissions | /thread-test **[message_text]** |

## 🔧 Bot Administrators (User Gated) Specific Commands

---

| **Command** | **Description** | **Command Details** |
| --- | --- | --- |
| /give-coin | Award IAs from admin allocated wallet to a member's wallet<br><br>Right-click context menu supported (pre-fills member and link) | /give-coin [member] [reason] [amount] **[link]** |
| /transfer-coin | Transfer IAs from one admin allocation to another | /transfer-coin [from_member] [to_member] [amount] [reason] |
| /remove-coin | Remove IAs from a member wallet and return to admin allocation | /remove-coin [member] [amount] |
| /remove-item-from-user-inventory | Remove one specific item from a member's inventory | /remove-item-from-user-inventory [member] [item_name] |
| /remove-all-from-user-inventory | Remove all items from a member's inventory (special reseter permission) | /remove-all-from-user-inventory [member] |
| /remove-users-inventory | Remove all items from ALL users' inventories (special reseter permission) | /remove-users-inventory |
| /richest-download | Export leaderboard CSV (wallet balances) | /richest-download |
| /verify-multipliers | Toggle role multiplier verification mode | /verify-multipliers **[enable]** |
| /update-role-multipliers | Show server roles and guidance for DB multiplier config | /update-role-multipliers |
| sync (prefix) | Sync slash commands with Discord. Auto-run at startup if `sync_channel_command` is set; can be run manually by Bot Administrators | sync |

## 📒 Accounting & Auditing

- Give-coin channel logs: Every transfer (manual or autorain) posts a standardized embed in `give_coin_channel` with User, Amount, To (Reason/Link when applicable).
- Admin channel run logs: Each drop posts a detailed embed with strategy, progress, totals, and recipient metrics. End-of-event summary embed shows completion status, failed-drop count, and Top Winners.
- Rain channel UX: No text spam; only emoji reactions are added to winners' latest messages in the rain channel.
- Leaderboards & exports: `/richest` shows totals/leaderboard; `/richest-download` exports CSV.
- Registration exports: `/registration export` produces CSV/Excel/Markdown (Discord, Twitter, wallets, balances, multipliers).

## ⚙️ Legacy/Config Prefix Commands (Admins)

---

| **Command** | **Description** | **Command Details** |
| --- | --- | --- |
| reset_economy | Reset all wallets to a specified allocation amount<br><br>Requires special reseter permission | reset_economy [alloc_amount] |
| create | Mint coins into your allocated wallet<br><br>Requires special reseter permission | create [amount] |
| set_roles_for_economy | Update Admin roles list in database settings by role names | set_roles_for_economy <role1> <role2> ... |
| set_roles_for_community | Update Community roles list in database settings by role names | set_roles_for_community <role1> <role2> ... |
| set_min_max_number_of_coin | Set global min/max caps used by admin commands | set_min_max_number_of_coin <min> <max> |

## 🔄 Database-Driven Configuration

---

| **Setting** | **Description** | **Default Value** |
| --- | --- | --- |
| bot_name | Display name for the bot | "Impact Awards Bot" |
| community_name | Community name used in messages | "Impact Awards" |
| server_id | Discord server ID | Configurable |
| loaded_roles | Admin and community role IDs | Configurable object |
| give_coin_channel | Channel for coin transfer notifications | Configurable |
| transfer_emoji | Emoji used for coin amounts | Configurable |
| rain_emoji | Emoji used for rain drops | Configurable |
| role_multipliers | Role-based reward multipliers | Configurable object |
| shop_items | Available shop items and prices | Configurable array |
| sync_channel_command | Channel used to trigger automatic startup sync ("0" disables) | "0" |
| verify_role_multipliers | Toggle recalculation of role multipliers | false |
| send_emoji | Emoji used for send/reaction confirmations | Configurable |
| first_drop_delay_minutes | Delay used when `instant_first_drop` is enabled | 1 |
| community_url | Optional community link used in embeds | Configurable |
| automated_rains | Stored autorain configs (persistence) | Configurable array |

## 📊 Key Changes from v3

---

1. Rebranding: Complete rebrand from "Pyth Network" to "Impact Awards Bot"
2. Registration System: Comprehensive registration system with Twitter linking and wallet validation
3. Rain Commands: New community rain distribution system
4. Quest System: Professional quest/giveaway announcement system
5. Database Configuration: All settings now configurable via database instead of hardcoded
6. Enhanced Admin Tools: Role multiplier management and verification tools
7. Context Menus: Right-click message support for give-coin command
8. Improved Inventory: Enhanced shop system with coupon generation
9. Better Error Handling: Comprehensive validation and error messages
10. Automated Role Assignment: Registration completion automatically assigns roles
11. Autorain Messaging & Summaries: Three-channel messaging (rain reactions, admin embeds, give-coin embeds) and end-of-event summary embeds with Top Winners and failed-drop counts
12. Autorain Scheduling & Fairness: Admin roles auto-excluded; exclusion-based filtering; per-event user cooldowns; default first drop after full interval with optional `instant_first_drop`
13. Exports: `/richest-download` CSV; `/registration export` for identity data
14. DB-Driven Config: Emojis (transfer, rain), `sync_channel_command`, `verify_role_multipliers`, `first_drop_delay_minutes` moved to database
15. Reliability & Validation: Startup username queue + reconnect handling; TLS-ready Twitter OAuth; strict Sol/EVM address validation and sanitization

## 🛡️ Permission Structure

---

- Bot Administrators: Full access to all admin commands, configured via database role IDs
- All Server Members: Access to general commands, registration commands
- Special Reseters: Additional permission level for destructive inventory operations
- Sync Command (prefix): Restricted to Bot Administrators; also triggered automatically via `sync_channel_command` on startup

All permission levels are configurable through the database settings collection.