Fighting Game · Guides & deep dives

V2 Currency Transaction Ledger

transaction id, account id, currency id, amount in minor units, source id, human-readable reason, timestamp, and transaction type.

3sections1 minread
Markdown source
On this page

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