# V2 Economy Design, Balancing, And Monitoring

This guide covers `TODOS.phase-72.72.18.1.15`: the economy documentation for
design principles, balancing methodology, and monitoring. It is the operating
map for the V2 economy surface; individual runtime docs remain the source of
truth for structs, helper APIs, and feature-specific validation.

## Runtime Map

- `CurrencyDefinition.V2` owns stable currency ids, display metadata, premium
  flags, minor units, negative-balance rules, and hard caps.
- `CurrencyLedger.V2` records every currency mutation as an immutable audit
  trail with transaction ids, source ids, reasons, timestamps, and before/after
  balances.
- `ServerCurrencyAuthority.V2` is the only gameplay path that applies trusted
  currency mutations. Client-authored balance writes are rejected before ledger
  application.
- `PremiumCurrencySystem.V2` fulfills platform-verified premium currency
  receipts through `ServerCurrencyAuthority.V2` with `SourceId = platform.iap`.
- `PriceTable.V2`, vendor shops, auction house, and direct trade resolve item
  prices and player-to-player exchange while preserving currency ids and ledger
  auditability.
- `V2LootTable`, `V2LootTableDebugger`, `V2EconomySimulation`, and
  `EconomyBalanceTuning.V2` are the authoring and live-ops surfaces used before
  rewards, prices, and drop rates ship.
- `@v2/economy-analytics`, `@v2/economy-analytics-dashboard`,
  `EconomyExploitDetection.V2`, and `ServerEconomyValidation.V2` provide the
  monitoring and enforcement loop after changes are live.

## Design Principles

1. Keep the ledger server-authoritative. Economy state changes must flow through
   `ServerCurrencyAuthority.V2` and `CurrencyLedger.V2`; direct client balance
   writes, local-only spend approvals, and untrusted source ids are not valid
   economy state.
2. Use stable ids and minor units. Currency ids, item ids, and price rows must
   be stable across patches, and all currency amounts must use minor units so
   rounding never changes a spend or grant.
3. Put caps and premium rules in data. `CurrencyDefinition.V2` hard caps,
   negative-balance permissions, and premium currency flags are the rules that
   fulfillment, pricing, and display surfaces consume.
4. Make every grant and sink attributable. A transaction needs a unique
   transaction id, source id, reason, timestamp, account id, and audit tag set
   before its audit trail is acceptable for review or rollback analysis.
5. Separate earned, purchasable, and reputation economies. Soft currencies,
   premium currency, time-limited tokens, and reputation-style balances must
   have separate ids, sources, caps, and sink expectations.
6. Treat monetization as explicit fulfillment. Real-money purchases require
   store server verification, account binding, replay protection, refund
   rejection, and `platform.iap` ledger grants. Gameplay rewards must not mimic
   store receipts.
7. Prefer deterministic reward decisions. Loot and reward seeds should be
   derived from stable server context so replaying the same table, context tags,
   pity counters, and grant ids produces explainable results.
8. Balance sources and sinks before widening access. New earn rates, vendors,
   auction fees, repairs, crafting costs, rerolls, and event rewards need a
   source/sink hypothesis and monitoring threshold before they reach production.

## Balancing Methodology

1. Define the currency role and player cohort. For each proposed change, record
   whether the target is soft currency, premium currency, token, or reputation;
   identify the level bands, player segments, and item families affected.
2. Model the source/sink plan in `V2EconomySimulation`. Include quest rewards,
   match payouts, vendor sell grants, live-event grants, repairs, crafting,
   auction fees, rerolls, and repeatable vendor spends. The simulation must show
   whether the economy is stable, inflating, or deflating over the target N-hour
   window.
3. Validate reward randomness with `V2LootTableDebugger`. Use production-like
   context tags, deterministic seeds, pity counters, expected rates, and sample
   limits before a loot table or reward pool is allowed into a canary.
4. Validate prices with `PriceTable.V2`. Buy prices, sell prices, dynamic
   multipliers, regional overrides, and quantity quotes must be checked against
   `CurrencyDefinition.V2` currency ids and the expected sink/source ratio.
5. Preview live-ops edits through `EconomyBalanceTuning.V2`. Drop rates, prices,
   and rewards must publish as remote config only when validation passes and the
   preview shows `requiresClientPatch: false`.
6. Canary the smallest meaningful population. Release to a narrow segment,
   compare against baseline cohorts, and watch inflation, deflation, earn/spend
   rates, item price effectiveness, and support reports before a wider rollout.
7. Document acceptance and rollback criteria before publish. Each balance change
   needs an owner, reason, target metric movement, abort threshold, rollback
   path, and the validation commands that passed.

## Monitoring And Alerts

- `@v2/economy-analytics` tracks currency earn/spend rates, inflation tracking,
  and item price effectiveness.
- `@v2/economy-analytics-dashboard` tracks currency supply velocity, average
  player wealth by level, item price trends, and sink/source ratios.
- `EconomyExploitDetection.V2` flags impossible currency gains, item
  duplication, untrusted currency sources, and exploit velocity; ranked and
  tournament economy signals queue fair-play review and fail closed.
- `ServerEconomyValidation.V2` remains the online validation boundary for
  suspicious spend/grant requests before downstream monitoring sees them.
- Daily launch checks review supply velocity, average player wealth by level,
  active-player wealth by cohort, top source ids, top sink ids, premium currency
  fulfillment, refund/replay rejection, and item price movement.
- Weekly balance review compares modeled source/sink expectations against live
  sink/source ratios, inflation and deflation trends, economy bot behavior,
  support incidents, and exploit evidence ids.
- Alerts should fire when total supply velocity, wealth concentration, item
  price trends, or earn/spend rates exceed the documented canary threshold, or
  when impossible gains, duplicate item instances, receipt replay, or untrusted
  source ids appear in production.

## Live-Ops Change Workflow

1. Open a balance proposal with the player cohort, currency role, source/sink
   hypothesis, expected player impact, and rollback owner.
2. Run simulation, loot-table debugging, price-table validation, and
   remote-config preview in staging.
3. Record the accepted validation output, target metrics, and alert thresholds
   in the proposal before publish.
4. Ship through canary remote config, never by client patch unless the owning
   feature contract explicitly requires one.
5. Watch the economy dashboard for the first day, then include the change in the
   weekly balance review until metrics return to the normal range.
6. Roll back immediately when ledger integrity, premium purchase fulfillment,
   fair-play evidence, or hard-cap enforcement is in doubt.

## Validation Commands

Run these checks when changing economy design guidance, balancing methodology,
monitoring docs, or CI/Horde wiring:

```bash
python3 V2/ue/Tools/check-v2-economy-documentation.py
python3 V2/ue/Tools/check-v2-economy-simulation.py
python3 V2/ue/Tools/check-v2-economy-balance-tuning.py
python3 V2/ue/Tools/check-v2-economy-exploit-detection.py
python3 V2/ue/Tools/check-v2-economy-analytics.py
python3 V2/ue/Tools/check-v2-economy-analytics-dashboard.py
python3 V2/ue/Tools/check-v2-ci-workflow.py
python3 -m json.tool V2/ue/Content/V2/Gameplay/Economy/EconomyDocumentation_V2_Contract.json
python3 -m json.tool V2/ue/Build/Horde/v2-buildgraph-job.json
python3 V2/tools/validate-v2-docs.py
```