Skip to content

💰 Abstractions / Services

🎯 Purpose

The Services folder defines the core service contracts and optional capability interfaces for the Currency system.

These interfaces describe how currency can be queried, mutated, and extended. They do not define how any behaviour is implemented.

🧠 Usage Guidance

Service abstractions are intended to:

  • Define the core currency service contract
  • Expose optional capability interfaces (audit metadata, batching, exchange)
  • Provide a stable integration surface for gameplay systems and tools
  • Keep behaviour implementation separate from contracts

🧩 What Lives Here

ICurrencyService

  • The primary contract for currency operations

  • Supports:

  • wallet creation (EnsureWallet)

  • querying (GetBalance)

  • mutation:

    • Credit
    • Debit
    • Transfer
    • SetBalance
    • change notification (OnWalletChanged)

IAuditAwareCurrencyService

  • Optional capability for services that support:

  • reason

  • sourceId
  • Allows audit metadata to flow through operations
  • Not part of the base contract by design

ICurrencyBatchEvents

  • Optional capability for batch notifications

  • Emits grouped wallet changes via:

  • OnWalletBatchChanged

ICurrencyExchange

  • Public seam for currency conversion logic

  • Supports:

  • TryQuote (non-mutating)

  • TryExchange (mutating, implementation-defined behaviour)

⚠️ Important Notes

  • ICurrencyService defines the primary contract for balance queries and mutation
  • Optional capabilities are exposed via interfaces and may not be present
  • No assumptions should be made about composition order or behaviour
  • Behaviour (caps, escrow, authority, idempotency, etc.) depends on the composed service stack
  • Audit metadata is intentionally separated from the base service interface
  • Atomicity beyond a single operation is not provided by the contract

🧠 Usage Guidance

Mental model

  • ICurrencyService is the core contract
  • Other capabilities decorate, observe, or compose around it
  • Consumers should depend only on required capabilities

Optional capabilities:

  • Audit → IAuditAwareCurrencyService
  • Batching → ICurrencyBatchEvents
  • Exchange → ICurrencyExchange

Not all services implement all capabilities.

🚫 Internal Use Only

This folder defines contracts only.

Do not:

  • Add implementation logic
  • Depend on concrete service implementations
  • Assume optional capabilities are always available

🧹 Safe to Remove

This folder should not be removed if any Currency system is in use.

All integrations and higher-level systems depend on these contracts.

  • Abstractions / Primitives — core value types
  • PublicAPI — supported helpers and workflows built on these contracts
  • Internal — implementation details and decorators (not for direct use)