# Economy Framework Guide

The economy module provides server-authoritative primitives for in-game
currencies, prices, vendors, auctions, direct trades, loot tables, simulation,
analytics, premium currency, and exploit detection.

## Currencies and Ledger

Define currencies with `defineEconomyCurrency`, including kind, display symbol,
decimal precision, premium flag, and max balance. Use `applyEconomyTransaction`
for all wallet changes. Transactions must be server authorized and produce
ledger entries with source, reason, timestamp, delta, and post-transaction
balance.

## Prices, Vendors, Auctions, and Trades

`createEconomyPriceTable` and `resolveEconomyPrice` support buy/sell prices,
dynamic multipliers, region entries, and reputation discounts.
`refreshEconomyVendorStock` and `executeVendorPurchase` manage limited stock,
refresh timers, and purchase ledger entries.

`createAuctionListing`, `placeAuctionBid`, and `buyoutAuctionListing` cover
listing, bid, buyout, expiration, and transaction fee calculation.
`createEconomyTradeSession`, `addCurrencyToTrade`, `confirmEconomyTrade`, and
`executeEconomyTrade` model direct player trading as a two-party confirmed
server operation.

## Loot and Debugging

`rollEconomyLootTable` supports guaranteed drops, weighted pools,
context-sensitive entries, and pity drops. `simulateEconomyLootDrops` runs
repeatable distribution checks for loot table debugging.

## Simulation, Analytics, and Tuning

`runEconomySimulation` models aggregate sources and sinks over playtime.
`createEconomyAnalyticsSnapshot` captures supply, velocity, average wealth,
price trends, and sink/source ratio. `createEconomyBalanceTuningConfig` and
`applyEconomyTuningConfig` apply remote-config multipliers for drop rates,
prices, and rewards without a patch.

## Premium Currency and Exploit Monitoring

Validate IAP receipts with `validatePremiumReceipt`, then grant hard currency
through `grantPremiumCurrency` so premium purchases still flow through the
ledger. `detectEconomyExploits` flags unauthorized gains, duplicate transaction
patterns, and excessive gain velocity for review.
