Skip to content

💰 Currency / PublicAPI

🎯 Purpose

The PublicAPI folder contains the supported runtime-facing surface of the Currency system.

This is the layer that gameplay code, tools, and external systems are expected to use. It provides safe entry points without exposing internal implementation details.

⚠️ Important Notes

  • This is the supported dependency surface for runtime usage
  • Internal implementation details are not exposed
  • Behaviour depends on the composed service stack
  • Optional capabilities (audit, batching, escrow, etc.) may not be present

🧩 What Lives Here

Audit

  • Read audit history
  • Subscribe to audit events when supported

Batching

  • Group multiple operations into a single emitted batch when supported

Helpers

  • Awaiters (async and coroutine helpers)
  • Factories (supported composition entry points)
  • Service extensions (reason/sourceId overloads, previews, helpers)
  • Transfer policy providers

Resolution

  • Resolve the active ICurrencyService for a given context

Transactions

  • CurrencyTxn — best-effort transactional builder
  • CurrencyHoldTxn — escrow-based transaction helper
  • CurrencyPurchase — affordability and spend/grant helpers

ValueObjects

  • CostBundle
  • CostLine

🧠 Usage Guidance

Mental model

  • Abstractions define contracts
  • Internal implements behaviour
  • PublicAPI defines supported usage

Consumers should interact with Currency through this layer for common workflows.

⚠️ Important Notes

  • Behaviour may vary depending on available capabilities
  • Some helpers act as fallbacks when capabilities are not present
  • Advanced behaviour (authority, escrow, idempotency) is controlled through composition

🚫 Internal Use Only

This folder is the public runtime surface.

Do not:

  • Depend on internal implementation types
  • Bypass this layer for common workflows

🧹 Safe to Remove

This folder should not be removed.

It contains the supported runtime API surface for Currency.

  • Abstractions — core contracts
  • Internal — implementation details
  • Bootstrap — service composition and publishing
  • UnityIntegration — scene/runtime wiring