# V2 Economy Exploit Detection

`EconomyExploitDetection.V2` analyzes an account-scoped economy window for
signals that are broader than a single transaction: impossible currency gains,
duplicated item instances, and suspicious gain or transaction velocity. It
complements the online `ServerEconomyValidation.V2` anti-cheat gate by scanning
gameplay ledger and inventory state after transactions have been recorded.

## Runtime Surface

- `FV2EconomyExploitDetectionPolicy` defines thresholds for per-transaction
  currency gain, total gain per analysis window, transaction count per window,
  minimum and maximum window length, trusted currency sources, detector-family
  toggles, forensic persistence, fair-play review queueing, and ranked
  fail-closed behavior.
- `FV2EconomyExploitDetectionRequest` contains request id, account id, optional
  match id, analysis-window bounds, the account currency ledger, inventory
  containers, ranked/tournament state, and whether the ledger window is
  complete.
- `FV2EconomyExploitIssue` records typed evidence with failure tag, subject id,
  currency id, item instance id, observed value, allowed value, evidence score,
  message, and blocking status.
- `FV2EconomyExploitDetectionResult` summarizes the analyzed window with total
  currency credits, transaction count, max single grant, duplicated item ids,
  evidence id, review flags, ranked fail-closed state, and all issues.

## Detection Rules

1. Impossible currency gains compare every positive grant, transfer-in, refund,
   or positive adjustment against `MaxCurrencyGainPerTransactionMinorUnits`.
2. Currency gain velocity compares total positive currency credits within the
   analysis window against `MaxCurrencyGainPerWindowMinorUnits`.
3. Currency transaction velocity compares the number of account transactions in
   the window against `MaxCurrencyTransactionsPerWindow`.
4. Item duplication scans all occupied slots across supplied
   `FV2InventoryContainer` values and flags any `InstanceId` that appears more
   than once.
5. Duplicate currency transaction ids inside the analysis window are flagged as
   ledger replay or import corruption.
6. Currency sources must be in `TrustedCurrencySourceIds` when
   `bRequireTrustedCurrencySources` is enabled. The default allow-list matches
   server economy sources such as `server.reward`, `quest.daily`,
   `vendor.noodle_cart`, `dialogue.choice`, and `platform.iap`.
7. Missing request ids, account ids, complete ledger windows, valid window
   lengths, or matching ledger account ids fail before a report can be treated
   as clean.
8. Any exploit report receives a deterministic evidence id, persists forensic
   evidence when policy requires it, and queues fair-play review. Ranked and
   tournament requests fail closed when `bRankedModesFailClosed` is enabled.

## Relationship To Server Economy Validation

`ServerEconomyValidation.V2` is the online anti-cheat validator for incoming
transaction batches. It catches non-server-authored state, balance mismatches,
duplicate transaction ids, and per-transaction impossible gains before the batch
is trusted.

`EconomyExploitDetection.V2` runs against gameplay state over a time window. It
is the right tool for detecting economy abuse that only becomes obvious after
aggregation: repeated small grants, high transaction velocity, duplicated item
instances across containers, and suspicious source mixtures.

## Validation Commands

Run these checks when touching economy exploit detection:

```bash
python3 V2/ue/Tools/check-v2-economy-exploit-detection.py
python3 V2/ue/Tools/check-v2-currency-ledger.py
python3 V2/ue/Tools/check-v2-server-economy-validation.py
python3 V2/ue/Tools/check-v2-ci-workflow.py
python3 -m json.tool V2/ue/Content/V2/Gameplay/Economy/EconomyExploitDetection_V2_Contract.json
python3 -m json.tool V2/ue/Build/Horde/v2-buildgraph-job.json
python3 V2/tools/validate-v2-docs.py
```