# V2 Currency Transaction Ledger

`CurrencyLedger.V2` records every gameplay currency change as an immutable
transaction record. It builds on `CurrencyDefinition.V2` so ledger behavior uses
the same currency ids, hard caps, and negative-balance rules as display and
authoring tools.

## Runtime Surface

- `FV2CurrencyLedgerRequest` is the requested currency change. It requires a
  transaction id, account id, currency id, amount in minor units, source id,
  human-readable reason, timestamp, and transaction type.
- `FV2CurrencyTransactionRecord` is the auditable record written after
  validation. It stores source, amount, timestamp, reason, balance before, and
  balance after in the same object.
- `FV2CurrencyTransactionLedger` is account-scoped and stores balance snapshots
  plus the immutable transaction records that produced those balances.
- `FV2CurrencyLedgerAuditTrail` filters ledger records by account and currency
  and reports opening balance, closing balance, credits, debits, and all
  matching entries.
- `FV2CurrencyLedgerValidationResult` replays the audit chain and verifies that
  balance snapshots still match the transaction history.

## Audit Rules

1. Every applied transaction must have `TransactionId`, `AccountId`,
   `CurrencyId`, `SourceId`, `Reason`, `TimestampUnixSeconds`, and
   `AmountMinorUnits`.
2. `TransactionId` values are idempotency keys. Duplicate ids are rejected
   before balance changes are applied.
3. Grants, transfer-ins, and refunds require positive amounts. Spends and
   transfer-outs require negative amounts. Adjustments can be positive or
   negative but cannot be zero.
4. The ledger resolves `CurrencyId` through the currency definition catalog.
   Unknown currencies are rejected.
5. Currencies that disallow negative balances reject insufficient-funds spends.
   Reputation-style currencies can go negative only when the definition permits
   it.
6. Hard caps from currency definitions are enforced before the transaction is
   recorded.
7. Audit trails are generated from transaction records, not from the balance
   snapshot alone.

## Validation Commands

Run these checks when touching currency ledger behavior:

```bash
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/CurrencyLedger_V2_Contract.json
python3 -m json.tool V2/ue/Build/Horde/v2-buildgraph-job.json
python3 V2/tools/validate-v2-docs.py
```