ShaiBot/docs/ECONOMY.md

ShaiBot Cookie Economy

This manual describes the shared Cookie economy and the rules maintainers should preserve.

Source of Truth

utils/cookieEconomy.js is the shared economy utility.

Game and command modules should not perform independent ad-hoc balance mutations when the shared economy already provides the required operation.

Balances

Cookie balances live in:

items_cookies

Conceptually:

{
    userId: "...",
    cookies: 2500
}

Negative changes use an atomic balance filter so a player cannot spend more Cookies than are available.

Expected insufficient-balance failures use:

INSUFFICIENT_COOKIES

Some subsystems carry expected error identifiers in error.message, while others may also use error.code. User-facing formatters should account for the convention used by that subsystem.

Transfers

Player-to-player transfers do not require MongoDB transactions.

The safe conceptual sequence is:

atomic debit source
→ credit destination
→ compensate source if destination credit fails

A critical compensation failure must remain visible in logs.

Cooldowns

Cooldowns live in:

cooldown_cookies

Use the shared cooldown helpers, especially atomic cooldown claiming when double-clicks or simultaneous requests must not both succeed.

House Vault

ShaiBot acts as the general house Cookie vault for supported games.

Gambling losses and penalties may feed the vault, while wins, heists, and rewards may pay out from it.

House-funded features should respect their existing liquidity rules.

Cookie Collection

/cookies collect and the Crumb Saucer Bakery share utils/crumbCollect.js.

They must share:

• the same cooldown
• the same reward generation
• the same balance mutation
• the same profile tracking

Do not create separate collection behavior for the two interfaces.

PvP Stealing

Normal player-to-player stealing is separate from Vault Heist.

Detailed robbery balancing lives in:

COOKIE_LOGIC.md

The current model includes wealth scaling, victim heat, percentage-based loot, a hard per-hit cap, and an hourly victim exposure budget.

Persistent Game Settlement

For simple house games, settlement should still be protected against repeated resolution.

For lifecycle-heavy multiplayer games such as Poker, Cookie movement is separated from internal chip movement.

Poker only crosses the Cookie economy boundary for:

buy-in
cash-out / refund

Ordinary Poker betting modifies the table's internal stack state, not items_cookies.

Idempotent Operations

Recovery-sensitive economy flows can use operation IDs.

Poker temporarily stores markers such as:

appliedCookieOperations: [
    "poker_buyin:...",
    "poker_cashout:..."
]

The purpose is to prevent a retry after a crash from moving money twice.

Safe lifecycle:

apply Cookie operation once
→ persist authoritative game state
→ confirm operation is durably represented
→ remove temporary marker

Never remove a recovery marker before the surrounding state is safe.

When the final marker is removed, unset the empty field instead of leaving:

appliedCookieOperations: []

Economy Invariants

Every economy change should preserve:

No Cookie duplication.
No unexplained Cookie loss.
No duplicate debit.
No duplicate payout.
No spending below zero.

Correctness and recoverability take priority over cosmetic cleanup.