Trait LazyBalance

pub trait LazyBalance: VirtualNMap<Self::Balance, SnapShotStorage, Key = (Self::Id, Self::Variant, Self::Time), Value = Self::SnapShot, Query = Option<Self::SnapShot>>
where
    Self: Sized,
{
    type Asset: Asset;
    type Rational: Fractional;
    type Time: Time;
    type Variant: Delimited + RuntimeEnum + Default;
    type Id: Delimited;
    type Subject: Delimited + Directive + Default;
    type Balance: LazyBalanceComponent<Self, BalanceAsset, BalanceRational, BalanceTime, Context<Self>, BalanceAddon>;
    type SnapShot: LazyBalanceComponent<Self, SnapShotAsset, SnapShotRational, SnapShotTime, Context<Self>, SnapShotAddon>;
    type Receipt: LazyBalanceComponent<Self, ReceiptAsset, ReceiptRational, ReceiptTime, Context<Self>, ReceiptAddon>;
    type Limits: LazyBalanceLimits<Self>;
    type Input<'a>: LazyBalanceInput<'a, Self::Balance, Self::Variant, Self::Id, Self::Asset, Self::Receipt, Self>;
    type Output<'a>: LazyBalanceOutput<'a, Self::Asset, Self::Receipt, Self::SnapShot, Self::Time, Self::Limits, Self>;
    type BalanceFamily<'a>: LazyBalanceRoot<Self::Input<'a>, <Self::BalanceContext as ModelContext>::Context, Self::Output<'a>>;
    type BalanceContext: ModelContext<Context: LazyBalanceContext>;

    // Provided methods
    fn can_deposit<'a>(input: Self::Input<'a>) -> Self::Output<'a> { ... }
    fn can_withdraw<'a>(input: Self::Input<'a>) -> Self::Output<'a> { ... }
    fn can_mint<'a>(input: Self::Input<'a>) -> Self::Output<'a> { ... }
    fn can_reap<'a>(input: Self::Input<'a>) -> Self::Output<'a> { ... }
    fn deposit<'a>(input: Self::Input<'a>) -> Self::Output<'a> { ... }
    fn withdraw<'a>(input: Self::Input<'a>) -> Self::Output<'a> { ... }
    fn mint<'a>(input: Self::Input<'a>) -> Self::Output<'a> { ... }
    fn reap<'a>(input: Self::Input<'a>) -> Self::Output<'a> { ... }
    fn drain<'a>(input: Self::Input<'a>) -> Self::Output<'a> { ... }
    fn total_value<'a>(input: Self::Input<'a>) -> Self::Output<'a> { ... }
    fn receipt_active_value<'a>(input: Self::Input<'a>) -> Self::Output<'a> { ... }
    fn has_deposits<'a>(input: Self::Input<'a>) -> Self::Output<'a> { ... }
    fn receipt_deposit_value<'a>(input: Self::Input<'a>) -> Self::Output<'a> { ... }
    fn deposit_limits<'a>(input: Self::Input<'a>) -> Self::Output<'a> { ... }
    fn mint_limits<'a>(input: Self::Input<'a>) -> Self::Output<'a> { ... }
    fn reap_limits<'a>(input: Self::Input<'a>) -> Self::Output<'a> { ... }
}

A composable, plugin-driven balance system with lazy receipt-based accounting.

LazyBalance defines a generic balance abstraction where value is managed through deposits, receipts, and deferred redemption semantics.

The system integrates with the plugin framework to express all behavior (validation, mutation, and queries) as pluggable operations resolved at compile time.

Core Semantics

The defining property of LazyBalance is its lazy propagation model:

• Balance updates (e.g. mint, reap) are applied immediately to the underlying balance state.
• Issued receipts are not eagerly updated when such changes occur.
• Instead, the effect of these updates is deferred and applied at the time of receipt redemption (withdraw).

In other words:

Deposits -> Issue Receipts
Balance Mutations -> Affect Global State Only
Withdrawals -> Resolve Final Value Lazily

This allows the system to:

• avoid costly updates across all outstanding receipts
• maintain correctness through deferred evaluation
• support dynamic balance adjustments without recomputation overhead

Conceptual Model

The system is composed of three primary components:

• Balance

  • Canonical mutable state
  • Receives all direct updates (deposit, mint, reap, drain)

• Receipt

  • Represents a claim issued at deposit time
  • Encodes entitlement, not fixed value
  • Final value is determined lazily at withdrawal

• SnapShot

  • Time-indexed projection of balance state
  • Enables historical queries and deferred computations

This forms a claim-based accounting model:

• deposits create claims
• withdrawals resolve claims
• intermediate balance changes influence claim outcomes

Storage Model

Snapshot data is externalized via VirtualNMap using SnapShotStorage, allowing:

• efficient storage of time-indexed data
• separation of heavy state from encoded balance representation
• iteration and prefix queries over historical state

Plugin-Driven Behavior

All operations are expressed through a plugin family declare_family:

Each operation:

• is type-driven via Self::Input and Self::Output
• is resolved through the Self::BalanceFamily plugin
• may be customized by runtime configuration

Limits

Operations may expose dynamic limits (e.g. minimum, maximum, optimal) via dedicated limit queries. These limits are derived from current balance state and provide bounded inputs for safe execution.

Execution DispatchPolicy

Operations may be parameterized by a Self::Subject, which encodes qualitative behavior such as precision and fortitude, influencing how operations are evaluated and executed.

Design Properties

• Lazy evaluation: receipt value is computed at redemption time
• Efficient: avoids eager updates across all outstanding claims
• Composable: behavior is modular via plugin families
• Decoupled: storage, logic, and types evolve independently
• Type-safe: all invariants enforced at compile time

Required Associated Types

type Asset: Asset

The underlying unit of value tracked by the system.

Represents tokens, points, or any fungible asset.

type Rational: Fractional

The numeric representation used for value calculations.

Typically a fixed-point or fractional type ensuring precise arithmetic.

type Time: Time

The temporal index of the system.

A monotonically increasing counter (e.g. block number or timestamp) used for snapshotting and time-based computations.

type Variant: Delimited + RuntimeEnum + Default

Logical partition of a balance.

Allows multiple independent balance states per Id (e.g. free, locked, reserved).

type Id: Delimited

Identifier of a balance owner or entity.

Combined with Variant and Time to uniquely address balance state.

type Subject: Delimited + Directive + Default

Represents the directive / intent of an operation.

Encodes behavioral characteristics such as precision and fortitude, influencing how operations are evaluated and executed.

Passed alongside operation inputs to allow context-aware behavior (e.g. exact vs approximate, polite vs forceful execution).

type Balance: LazyBalanceComponent<Self, BalanceAsset, BalanceRational, BalanceTime, Context<Self>, BalanceAddon>

Primary mutable balance state.

Represents the canonical stored value and is modified by all state-transition operations.

type SnapShot: LazyBalanceComponent<Self, SnapShotAsset, SnapShotRational, SnapShotTime, Context<Self>, SnapShotAddon>

Time-indexed projection of balance state.

Used for historical queries and deferred computations.

type Receipt: LazyBalanceComponent<Self, ReceiptAsset, ReceiptRational, ReceiptTime, Context<Self>, ReceiptAddon>

Claim over deposited value.

Issued on deposit and consumed on withdrawal.

A receipt represents the right to redeem value from the balance. Its redeemable value may differ from its original deposit value due to balance adjustments (e.g. minting or reaping).

type Limits: LazyBalanceLimits<Self>

Abstract representation of operation limits.

Encapsulates derived values across different extents (e.g. minimum, maximum, optimal) for balance operations.

Used by limit query operations to provide safe bounded values under current conditions.

type Input<'a>: LazyBalanceInput<'a, Self::Balance, Self::Variant, Self::Id, Self::Asset, Self::Receipt, Self>

Input carrier for all operations.

Encodes operation-specific arguments while supporting both mutable and immutable access patterns.

type Output<'a>: LazyBalanceOutput<'a, Self::Asset, Self::Receipt, Self::SnapShot, Self::Time, Self::Limits, Self>

Output carrier for all operations.

Encodes operation-specific results and error handling.

type BalanceFamily<'a>: LazyBalanceRoot<Self::Input<'a>, <Self::BalanceContext as ModelContext>::Context, Self::Output<'a>>

Plugin Family implementing all LazyBalance operations.

Binds each operation discriminant (defined in LazyBalanceRoot) to a concrete plugin model, determining how validation, mutation, and query logic is executed.

Combined with the resolved context, this enables compile-time dispatch of behavior while keeping logic modular and replaceable.

type BalanceContext: ModelContext<Context: LazyBalanceContext>

Context provider for all LazyBalance operations via Self::BalanceFamily.

Implements ModelContext, producing a concrete execution context whose associated Context type must satisfy LazyBalanceContext.

Since LazyBalance components (e.g. Balance, SnapShot, Receipt) are modeled as virtual structures (see VirtualDynField) and support extensibility (see VirtualDynExtension), they do not define their bounds, schemas, or error types internally.

Instead, these are supplied by the resolved context, which is required (via LazyBalanceContext) to provide:

• dynamic bounds for all core dimensions through VirtualDynBound (asset, rational, and time for balance, snapshot, and receipt)
• extension schemas via VirtualDynExtensionSchema for addon composition across components
• a unified error type via VirtualError for all operations

This enforces that all plugins in this family execute within a fully specified environment where structure, constraints, and extensibility are externally defined yet statically guaranteed.

Provided Methods

fn can_deposit<'a>(input: Self::Input<'a>) -> Self::Output<'a>

Plugin invocation pure-function for the child - CanDeposit of the plugin family - LazyBalanceRoot Returns whether a deposit is permitted.

fn can_withdraw<'a>(input: Self::Input<'a>) -> Self::Output<'a>

Plugin invocation pure-function for the child - CanWithdraw of the plugin family - LazyBalanceRoot Returns whether a withdrawal is permitted.

fn can_mint<'a>(input: Self::Input<'a>) -> Self::Output<'a>

Plugin invocation pure-function for the child - CanMint of the plugin family - LazyBalanceRoot Returns whether minting is permitted.

fn can_reap<'a>(input: Self::Input<'a>) -> Self::Output<'a>

Plugin invocation pure-function for the child - CanReap of the plugin family - LazyBalanceRoot Returns whether reaping is permitted.

fn deposit<'a>(input: Self::Input<'a>) -> Self::Output<'a>

Plugin invocation pure-function for the child - Deposit of the plugin family - LazyBalanceRoot Deposits value into the balance and issues a receipt along with depositted amount.

fn withdraw<'a>(input: Self::Input<'a>) -> Self::Output<'a>

Plugin invocation pure-function for the child - Withdraw of the plugin family - LazyBalanceRoot Withdraws value by consuming a receipt, returning withdrawed amount.

fn mint<'a>(input: Self::Input<'a>) -> Self::Output<'a>

Plugin invocation pure-function for the child - Mint of the plugin family - LazyBalanceRoot Introduces new value into the balance, returning minted amount.

fn reap<'a>(input: Self::Input<'a>) -> Self::Output<'a>

Plugin invocation pure-function for the child - Reap of the plugin family - LazyBalanceRoot Removes or adjusts value from the balance, returning reaped amount.

fn drain<'a>(input: Self::Input<'a>) -> Self::Output<'a>

Plugin invocation pure-function for the child - Drain of the plugin family - LazyBalanceRoot Clears the balance state, returning drained amount.

fn total_value<'a>(input: Self::Input<'a>) -> Self::Output<'a>

Plugin invocation pure-function for the child - TotalValue of the plugin family - LazyBalanceRoot Returns the total value of the balance.

fn receipt_active_value<'a>(input: Self::Input<'a>) -> Self::Output<'a>

Plugin invocation pure-function for the child - ReceiptActiveValue of the plugin family - LazyBalanceRoot Returns the current redeemable value of a receipt.

fn has_deposits<'a>(input: Self::Input<'a>) -> Self::Output<'a>

Plugin invocation pure-function for the child - HasDeposits of the plugin family - LazyBalanceRoot Returns whether the balance has any deposits.

fn receipt_deposit_value<'a>(input: Self::Input<'a>) -> Self::Output<'a>

Plugin invocation pure-function for the child - ReceiptDepositValue of the plugin family - LazyBalanceRoot Returns the original deposited value represented by a receipt.

fn deposit_limits<'a>(input: Self::Input<'a>) -> Self::Output<'a>

Plugin invocation pure-function for the child - DepositLimits of the plugin family - LazyBalanceRoot Returns limits for deposit operations if any, else permissive.

fn mint_limits<'a>(input: Self::Input<'a>) -> Self::Output<'a>

Plugin invocation pure-function for the child - MintLimits of the plugin family - LazyBalanceRoot Returns limits for mint operations if any, else permissive.

fn reap_limits<'a>(input: Self::Input<'a>) -> Self::Output<'a>

Plugin invocation pure-function for the child - ReapLimits of the plugin family - LazyBalanceRoot Returns limits for reap operations if any, else permissive.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors