Helpers¶

🎯 Purpose¶

The Helpers folder provides supported convenience APIs that sit on top of ICurrencyService.

These helpers expose common workflows, composition entry points, and utility behaviour without expanding the core service interface or exposing internal implementation details.

⚠️ Important Notes¶

Helpers do not implement core behaviour
Behaviour depends on the composed service stack
Optional capabilities (audit, batching, escrow, etc.) may not be present
Composition is performed through CurrencyFactories

🧩 What Lives Here¶

CurrencyAwaiters¶

Async and coroutine helpers for waiting on balance conditions
Driven by OnWalletChanged when available
Fallback behaviour when conditions cannot be observed

CurrencyFactories¶

Supported entry points for composing service stacks
Enables features such as:
Audit
Caps / policy
Authority
Escrow
Idempotency
Batch events
Hides internal decorator chains

CurrencyServiceExtensions¶

Convenience extensions for ICurrencyService
Includes:
reason/sourceId overloads
preview helpers (policy-aware)
affordability helpers (CostBundle)
transfer preview helpers

TransferPolicyProviders¶

Helpers for building ITransferPolicyProvider
Provide supported ways to define transfer rules

🧠 Usage Guidance¶

Mental model¶

Helpers sit on top of the service
They compose, call, or observe existing behaviour
They do not replace service responsibilities

Examples:

Factories build service stacks
Extensions call the service with additional context
Awaiters observe changes over time

🧪 Diagnostics¶

Missing behaviour may indicate required capabilities are not composed
Unexpected results often relate to service composition order

🚫 Internal Use Only¶

These helpers are part of the public API surface.

Do not:

Depend on internal implementation types
Construct decorator chains manually

🧹 Safe to Remove¶

This folder may be removed if helper APIs are not required.

Currency will continue to operate using core service contracts.

PublicAPI / Transactions — higher-level workflows
PublicAPI / Audit — audit helpers
Abstractions — core contracts
Internal — implementation details