Skip to content

💰 Currency / PublicAPI / Transactions

🎯 Purpose

The Transactions folder provides supported higher-level workflows for applying multiple currency operations as a single logical action.

These APIs help with staged spending, grants, transfers, and grouped multi-step flows without exposing internal implementation details.

⚠️ Important Notes

  • Transactions are workflow helpers, not a transactional system
  • Atomicity is not guaranteed
  • Rollback is best-effort only
  • Behaviour depends on the composed service stack
  • Optional capabilities (batching, audit, escrow, authority, idempotency) may affect behaviour

🧩 What Lives Here

CurrencyTxn

  • Fluent builder for staged operations:

  • credits

  • debits
  • transfers
  • set balance
  • Applies operations sequentially on Commit()
  • Attempts rollback on failure
  • May emit a single batch event when supported

CurrencyHoldTxn

  • Escrow-first transaction helper
  • Attempts to acquire holds before applying effects
  • Requires escrow capability (ICurrencyEscrow)
  • Reduces partial application scenarios

CurrencyPurchase

  • Convenience helpers for:

  • affordability checks

  • multi-currency spends
  • multi-currency grants

🧠 Usage Guidance

Mental model

  • These helpers orchestrate multiple service calls
  • They do not provide isolation or transactional guarantees
  • Execution occurs through the live composed service

Behaviour by helper:

  • CurrencyTxn — sequential execution with best-effort rollback
  • CurrencyHoldTxn — escrow-first flow when available
  • CurrencyPurchase — simplified purchase and grant helpers

When to use

Use these helpers when:

  • Grouping multiple operations into a single flow
  • Performing purchase or reward logic
  • Coordinating staged currency changes

Prefer direct ICurrencyService usage when:

  • Operations are simple
  • You control sequencing explicitly
  • No grouping or rollback behaviour is required

🧪 Diagnostics

  • Partial results may indicate failure during multi-step execution
  • Missing escrow support may affect hold-based flows
  • Unexpected outcomes often relate to service composition

🚫 Internal Use Only

These helpers are part of the public API surface.

Do not:

  • Depend on internal transaction implementations
  • Assume atomic or isolated execution

🧹 Safe to Remove

This folder may be removed if transaction helpers are not required.

Currency will continue to operate using direct service calls.

  • PublicAPI / Helpers — factories, extensions, previews
  • PublicAPI / Batching — batch event grouping
  • Abstractions — ICurrencyService, ICurrencyEscrow
  • Internal — implementation details