# V2 Server Currency Authority

`ServerCurrencyAuthority.V2` is the gameplay-side gate that prevents clients
from mutating currency state directly. It complements the broader
`V2OnlineServices` server economy validator by rejecting suspicious currency
mutations before they are applied to `CurrencyLedger.V2`.

## Runtime Surface

- `FV2ServerCurrencyAuthorityPolicy` defines the server-only rules: trusted
  source ids, mutation batch size, required server-authoritative ledger flags,
  unique server request ids, client-authored rejection, and client balance
  mismatch rejection.
- `FV2ServerCurrencyMutation` wraps a `FV2CurrencyLedgerRequest` with server
  request id, server authority id, client-reported balance, client-authored
  status, and trusted-source status.
- `FV2ServerCurrencyAuthorityResult` returns the initial ledger, the committed
  ledger, applied transactions, the last ledger result, rejection evidence, and
  blocking issues.
- `ApplyServerCurrencyMutations` evaluates a batch against policy and applies
  mutations through `ApplyCurrencyLedgerTransaction` only after server authority
  checks pass.

## Authority Rules

1. Currency changes originate from the server authority, not client-side balance
   writes.
2. Every mutation must include `ServerRequestId`, `ServerAuthorityId`, and a
   ledger request marked `bServerAuthoritative`.
3. `SourceId` must be allowed by the server authority policy and the mutation
   must be marked trusted by the caller.
4. Client-authored mutations are rejected before ledger application.
5. Client-reported balance must match the server ledger result. Mismatches fail
   closed and preserve the pre-request ledger.
6. Duplicate server request ids are rejected to prevent replayed or duplicated
   mutation batches.
7. Batch application is atomic. If any mutation is rejected, no candidate ledger
   updates are committed.
8. Accepted mutations still flow through `CurrencyLedger.V2`, so currency
   definitions, caps, negative-balance rules, duplicate transaction ids, and
   audit trail fields remain authoritative.

## Validation Commands

Run these checks when touching server-authoritative currency management:

```bash
python3 V2/ue/Tools/check-v2-server-currency-authority.py
python3 V2/ue/Tools/check-v2-currency-ledger.py
python3 V2/ue/Tools/check-v2-currency-definition.py
python3 V2/ue/Tools/check-v2-ci-workflow.py
python3 -m json.tool V2/ue/Content/V2/Gameplay/Economy/ServerCurrencyAuthority_V2_Contract.json
python3 -m json.tool V2/ue/Build/Horde/v2-buildgraph-job.json
python3 V2/tools/validate-v2-docs.py
```