Skip to content

💰 Currency / Abstractions

🎯 Purpose

The Abstractions folder defines the core public contracts and primitives of the Currency system.

Everything here defines what is contractually available, not how it is implemented.

This is the foundation layer that all other Currency components build on.

🧠 Usage Guidance

Abstractions are intended to:

  • Define a minimal, stable API surface
  • Allow other systems to integrate without depending on implementations
  • Provide deterministic, data-oriented primitives
  • Enable composition (caps, audit, escrow, authority, etc.) around a single contract

This folder contains no runtime behaviour or implementation logic.

🧩 What Lives Here

Primitives

  • CurrencyId — canonical currency key
  • Money — integer minor-unit amount (no floats)
  • CurrencyDelta — post-change snapshot
  • CurOpCode, CurOpResult — operation outcomes

Services

  • ICurrencyService — core contract
  • IAuditAwareCurrencyService — optional audit metadata support
  • ICurrencyBatchEvents — optional batch event surface
  • ICurrencyExchange — exchange/conversion seam

Audit

  • CurrencyAuditEntry, CurOpKind
  • ICurrencyAuditReader, ICurrencyAuditEvents (optional capabilities)

Escrow

  • ICurrencyEscrow, ICurrencyEscrowReadOnly
  • EscrowOpCode, EscrowOpResult, EscrowHoldInfo

Policies

  • CurrencyCapRule, CapMode
  • ITransferPolicyProvider

⚠️ Important Notes

  • No implementation logic exists in this folder
  • No internal dependencies should be introduced
  • This surface is intended to remain stable across versions
  • Optional features (audit, escrow, batching, etc.) are exposed via capability interfaces
  • Behaviour depends on the composed service stack

🧠 Usage Guidance

Mental model

  • Abstractions define the contract
  • Internal implements behaviour
  • PublicAPI exposes supported usage

Everything else in the system builds around these contracts.

Ownership model

Currency is tracked:

  • Per owner
  • Per currency

Where the owner is a Unity GameObject.

This supports:

  • Scene-based ownership
  • Prefab-driven systems
  • Runtime entity mapping

Non-Unity ownership should be adapted via a wrapper or proxy.

🚫 Internal Use Only

This folder defines contracts only.

Do not:

  • Add implementation logic
  • Depend on Internal or runtime layers
  • Extend behaviour here beyond interface definitions

🧹 Safe to Remove

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

Other systems and integrations depend on these contracts.

  • PublicAPI — supported helpers and workflows
  • Internal — implementation details
  • Bootstrap — service composition and publishing
  • UnityIntegration — scene/runtime wiring