Economy – Adapters – Currency¶

⚠️ Implementation glue – not supported public API

This folder contains the currency integration layer for the Economy subsystem. It adapts an ICurrencyService (and optional CurrencyPolicy) into the IValueLedger abstraction used by all economy flows.

All types documented here live under: RevGaming.RevFramework.Economy.Internal.Adapters.Currency

They are implementation details. Gameplay code should depend on IValueLedger, not on the concrete adapter types defined here.

Purpose¶

Provide a consistent, policy-aware, rollback-safe bridge between the Currency module and higher-level economy services:

Shop
Crafting
Rewards

This adapter layer ensures that all money mutations:

Obey policy rules
Remain deterministic
Roll back cleanly on failure
Propagate telemetry identifiers (sourceId) consistently

Components¶

Currency-backed value ledger¶

The built-in currency adapter provides an internal implementation of IValueLedger backed by ICurrencyService.

Behaviour¶

Escrow-first design (hold → commit / release) when an escrow provider is available.
Fallback to direct debit / credit with deterministic rollback when escrow is unavailable.
All currency operations propagate sourceId for telemetry, analytics, and correlation.
Policy-aware UX preflight behaviour via LedgerPreflightMode:
Strict — UI disables if policy would modify the nominal debit (fees, rounding, clamps, caps).
PolicyApproved — UI enables if the policy approves and the wallet covers the effective debit.
Deterministic normalisation and policy evaluation ensure that CanPay() previews and authoritative Pay() / Grant() calls stay aligned.
Currency-layer results are mapped into unified EcoOpResult / EcoOpCode values.

This adapter is used internally by: - Shop flows - Crafting flows - Reward flows

Policy debit computation¶

Internal helpers compute effective debit lines when a CurrencyPolicy is present.

Responsibilities¶

Deterministically normalise incoming PriceBundle values.
Apply policy transformations to each nominal money line.
Support two validation modes:
Strict — invalid lines immediately fail the operation.
SkipInvalid — invalid lines are ignored (used for UI previews).
Produce either:
EcoOpResult.Ok with a computed list of effective debit lines, or
a specific EcoOpResult failure (invalid args, overflow, policy blocked, etc.).

These helpers exist to keep ledger behaviour and service behaviour perfectly aligned. They are not intended for direct use.

Currency result mapping¶

Currency-layer operation results are mapped into Economy results.

Mapping guarantees¶

InvalidArgs → InvalidArgs
ServiceMissing → ServiceMissing
InsufficientFunds → InsufficientFunds
Overflow → Overflow
Policy or bounds violations → PolicyBlocked
Any unknown or unmapped result → UnknownError

This guarantees that Economy services never leak currency-layer result types or require consumers to understand currency internals.

Usage¶

You normally do not construct currency adapters manually.

They are wired automatically by EconomyBootstrap when building an economy pipeline:

var (shop, rewards, crafting, ledger, store) =
    EconomyBootstrap.BuildForPlayer(player, currencyService, policy);

The returned IValueLedger is then used internally by: - Shop services - Crafting services - Reward services

If you remove the built-in currency adapter, you must supply your own implementation of IValueLedger.

Stability¶

Currency adapters are replaceable via the abstraction layer.
They are not part of the public gameplay API.
Behaviour is stable within a major version; internal structure may evolve.
Always depend on IValueLedger, never on concrete adapter types.