💰 Currency / Persistence¶

🎯 Purpose¶

The Persistence layer provides helpers and components to save and restore wallet balances.

All persistence operates through the ICurrencyService contract and works with composed service stacks.

Persistence is optional and independent of storage technology.

⚠️ Important Notes¶

Persistence does not bypass the composed service
All mutations are applied through ICurrencyService
Behaviour depends on the composed service stack (caps, authority, idempotency, etc.)
Atomicity is not guaranteed
Rollback is best-effort only

🧩 What Lives Here¶

WalletSnapshot¶

Serializable value object representing absolute balances for a single owner.

Stores (CurrencyId, balance) pairs
Storage-agnostic
Contains data only

CurrencyPersistence¶

Static utility for capturing and restoring wallet state.

Capture¶

WalletSnapshot Capture(
    ICurrencyService svc,
    GameObject owner,
    IReadOnlyList<CurrencyId> ids);

Builds a snapshot using GetBalance
Only includes specified currency ids

Restore¶

CurOpResult Restore(
    ICurrencyService svc,
    GameObject owner,
    WalletSnapshot snapshot,
    string reason = "RestoreSnapshot",
    string sourceId = null);

Behaviour:

Applies balances using SetBalance
Uses audit-aware flows when available
Wraps operations in a batch scope when supported

Failure handling:

On failure, previously applied changes are rolled back where possible
Batch emission is cancelled

Success handling:

Emits a single batch event when supported
Returns CurOpResult.Ok()

🧠 Usage Guidance¶

Mental model¶

Persistence captures and restores state, not behaviour
Execution depends on the provided service
Service composition rules still apply

Unity integration¶

Scene-level helpers (e.g. JSON save/load components) build on this layer.

The supported persistence surface remains CurrencyPersistence.

ID selection¶

Explicit currencyIds list is used when provided
Otherwise, CurrencySet may be used
Fallback ids may be applied if neither is available

🧪 Diagnostics¶

Missing StableId values prevent save/restore for that owner
Partial snapshots only affect listed currencies
Authority restrictions may block restore operations

🚫 Not for Production Use¶

This layer provides persistence helpers only and does not include storage infrastructure.

🧹 Safe to Remove¶

This folder may be removed if persistence is not required.

Core Currency functionality does not depend on it.

Abstractions — public contracts
Core — composition and batching
Decorators — audit, idempotency, batching
Definitions — currency id selection
Exchange — optional post-load conversion