aurorabot/shared/modules/economy/AGENTS.md

Economy Module

• All currency values are bigint. Never use Number() for arithmetic on balances -- use BigInt literals (e.g., 0n, 500n) and sql template expressions for DB updates.
• modifyUserBalance is the canonical way to change a user's balance. It checks for insufficient funds on negative amounts, logs a transaction record, and emits BALANCE_CHANGED for quest progression. Bypass it only if you have a very good reason.
• Daily rewards reset at UTC midnight, not 24h from last claim. The cooldown expiresAt is set to the next UTC 00:00:00. Streak breaks if the user misses an entire 24h window after the cooldown expired.
• Daily reward is capped at MAX_DAILY_REWARD = 500n regardless of streak/weekly bonus.
• The streak has a grace period: if a user's timer record is missing (e.g., DB migration), the code allows one "free" increment to avoid unfair resets.
• Weekly bonus triggers every 7th consecutive day (streak % 7 === 0).
• Exam system: a weekly check-in that rewards users based on XP gained since their last exam. The reward uses scaled BigInt arithmetic (* 10000 / 10000n) to avoid floating-point precision loss. Exams are locked to a specific day of the week set at registration time. Missing your exam day means zero reward -- there is no retroactive claim.
• Lootdrops use in-memory state (Maps for channel activity and cooldowns). This state is lost on restart. The DB stores only spawned/claimed drops. Claiming uses an atomic UPDATE ... WHERE claimedBy IS NULL to prevent race conditions.
• Lootdrops expire after 10 minutes and are cleaned up by a 60-second interval.