Economy & Banking System
Relevant source files
The following files were used as context for generating this wiki page:
The Economy & Banking System provides a virtual currency framework for Discord servers. It manages user balances, currency transfers, and periodic payouts. The system operates in either a global mode, where balances persist across all servers, or a per-server mode, where each server maintains independent accounts.
Sources: redbot/cogs/economy/economy.py:108-111, redbot/core/core_commands.py:1260-1285
System Architecture
The architecture consists of the bank core module and the Economy cog. The bank module handles low-level data operations, while the Economy cog provides user-facing commands and games like slot machines.
Bank Core Module
The bank serves as the central API for all currency operations. It abstracts the storage logic, allowing other cogs to interact with user wealth without managing the underlying data.
The diagram shows the flow of a currency transaction from user input to storage updates.
Sources: redbot/core/bank.py, redbot/cogs/economy/economy.py:148-160
Configuration Scopes
The system supports two primary scopes configured via the bankset toggleglobal command:
- Global: One account per user ID across the entire bot instance.
- Server: Unique accounts per user per Discord server.
Sources: redbot/core/core_commands.py:1287-1303, redbot/cogs/economy/economy.py:302-308
Core Data Structures and Payouts
Economy Settings
The following table summarizes the configurable parameters for the economy system.
| Parameter | Type | Default | Description |
|---|---|---|---|
PAYDAY_TIME | Integer | 300 | Seconds between payday rewards. |
PAYDAY_CREDITS | Integer | 120 | Base currency amount awarded per payday. |
SLOT_MIN | Integer | 5 | Minimum bid for the slot machine. |
SLOT_MAX | Integer | 100 | Maximum bid for the slot machine. |
REGISTER_CREDITS | Integer | 0 | Starting balance for new accounts. |
Sources: redbot/cogs/economy/economy.py:113-120, redbot/core/core_commands.py:1335-1350
Payday Logic
The payday command awards currency based on a cooldown timer. If the bank is in server-specific mode, the system checks roles to determine if a user qualifies for a higher payout amount defined by rolepaydayamount.
The sequence shows the validation steps and payout determination for the payday command.
Sources: redbot/cogs/economy/economy.py:277-330, redbot/cogs/economy/economy.py:644-686
Banking Operations
Transaction Methods
The system provides several functions to manipulate user balances through the redbot.core.bank API:
get_balance(user): Retrieves current credits.set_balance(user, amount): Overwrites the current balance.deposit_credits(user, amount): Adds credits to the account.withdraw_credits(user, amount): Removes credits from the account.transfer_credits(from, to, amount): Moves credits between users.
Sources: redbot/cogs/economy/economy.py:148-275
Validation and Constraints
The system enforces a maximum balance limit (_MAX_BALANCE). If an operation would cause a user to exceed this limit, the system raises a BalanceTooHigh error. Administrators can configure this limit using bankset maxbal.
Sources: redbot/core/errors.py, redbot/core/core_commands.py:1319-1333, redbot/cogs/economy/economy.py:151-153
Slot Machine Implementation
The slot machine uses a deque to simulate physical reels. It calculates payouts based on matching symbols or specific combinations.
Payout Table
| Combination | Multiplier |
|---|---|
| 2, 2, 6 | x50 |
| Four Leaf Clovers (3) | x25 |
| Cherries (3) | x20 |
| Three Identical Symbols | x10 |
| Two Consecutive Identical | x2 |
Sources: redbot/cogs/economy/economy.py:46-81
Reel Logic
The machine generates three reels by randomly rotating a default symbol set.
@staticmethod
async def slot_machine(author, channel, bid):
default_reel = deque(cast(Iterable, SMReel))
reels = []
for i in range(3):
default_reel.rotate(random.randint(-999, 999))
new_reel = deque(default_reel, maxlen=3)
reels.append(new_reel)
Sources: redbot/cogs/economy/economy.py:532-540
Administrative Management
Administrators manage the system through the bankset and economyset command groups.
Account Pruning
To maintain database health, the system provides methods to remove accounts for users who have left the server or the bot's shared servers.
bankset prune server: Removes local accounts for users no longer in the current guild.bankset prune global: Removes global accounts for users who share no servers with the bot.
Sources: redbot/core/core_commands.py:1385-1430
Configuration Command Summary
bankset bankname: Sets the name of the bank (e.g., "The Iron Bank").bankset creditsname: Sets the currency name (e.g., "Gold").economyset slotmin/slotmax: Controls gambling limits.economyset slottime: Adjusts the cooldown between slot uses.
Sources: redbot/core/core_commands.py:1305-1317, redbot/cogs/economy/economy.py:587-630
Conclusion
The Economy & Banking System provides a robust foundation for community engagement. By separating core banking logic from specific economy features, the system ensures data integrity while allowing for flexible expansion through additional cogs and modules.