Module assets

Source

Expand description

A collection of composable, type-driven balance models built on virtual abstractions and plugin-based execution.

§Motivation

Traditional balance systems tightly couple:

storage layout
accounting logic
and update propagation

This leads to:

costly updates across all dependent states
rigid data structures that are hard to evolve
difficulty composing new behaviors or extending models

This module addresses these limitations by:

decoupling structure, storage, and behavior
deferring computation until it is actually needed
allowing logic to be injected via plugins

§Lazy Balance Model

The primary model is LazyBalance, a receipt-based, lazily evaluated accounting system.

deposit -> issue receipt
mutate balance -> affect global state only
withdraw -> resolve receipt value lazily

In this model:

deposits create receipts (claims)
balance mutations affect global state only
receipt value is computed at withdrawal time

This avoids eagerly updating all receipts while preserving correctness.

§Design

§Virtual Architecture

All balance models are built on shared virtual primitives:

VirtualDynField -> defines structured components (asset, rational, time)
VirtualDynExtension -> enables extensibility via addons
VirtualDynBound -> provides external constraints (e.g. capacity)
VirtualNMap -> externalizes heavy or dynamic storage

These abstractions allow:

structure to remain representation-agnostic
storage to be externalized or optimized independently
components to be composed across contexts

§Plugin-Driven Execution

Behavior is defined through plugin families via:

This enables:

compile-time dispatch of operations
modular and replaceable logic
context-driven customization

Each operation (deposit, withdraw, etc.) is selected via a discriminant and resolved through the plugin family.

§Summary

This module provides a foundation for building diverse balance systems where:

accounting is lazy and efficient
structure is flexible and composable
behavior is modular and replaceable

enabling multiple accounting strategies to coexist under a unified, type-driven architecture.

Modules§

lazy_balance_model_checker 🔒: Model checker module for LazyBalance implementations.

Structs§

BalanceAddon: Discriminant for additional balance-specific extensions.
BalanceAsset: Discriminant for the asset type within LazyBalance::Balance.
BalanceExit: Represents a successful withdrawal where the lazy and manual models produce different outputs.
BalanceFailure: Represents a failure encountered during execution of an operation sequence.
BalanceModelResults: Aggregates results produced during state exploration.
BalanceRational: Discriminant for the numeric representation within LazyBalance::Balance.
BalanceState: Primary state container for executing and tracking a sequence of operations.
BalanceTime: Discriminant for the time dimension within LazyBalance::Balance.
BalanceTraps: Defines trap behavior for state exploration.
CanDeposit: Discriminant for deposit validation.
CanMint: Discriminant for mint validation.
CanReap: Discriminant for reap validation.
CanWithdraw: Discriminant for withdrawal validation.
Deposit: Discriminant for deposit execution.
DepositLimits: Discriminant for deposit limits query.
Drain: Discriminant for drain execution.
HasDeposits: Discriminant for deposit presence query.
LazyBalanceError: Discriminant for error types within the LazyBalance system.
LazyContainer: Convenience container holding the owned state required to operate on a LazyBalance instance.
LimitsAsset: Discriminant for the asset type used in operation limits.
Mint: Discriminant for mint execution.
MintLimits: Discriminant for mint limits query.
Reap: Discriminant for reap execution.
ReapLimits: Discriminant for reap limits query.
ReceiptActiveValue: Discriminant for active receipt value query.
ReceiptAddon: Discriminant for additional receipt-specific extensions.
ReceiptAsset: Discriminant for the asset type within LazyBalance::Receipt.
ReceiptDepositValue: Discriminant for receipt deposit value query.
ReceiptRational: Discriminant for the numeric representation within LazyBalance::Receipt.
ReceiptTime: Discriminant for the time dimension within LazyBalance::Receipt.
SnapShotAddon: Discriminant for additional snapshot-specific extensions.
SnapShotAsset: Discriminant for the asset type within LazyBalance::SnapShot.
SnapShotRational: Discriminant for the numeric representation within LazyBalance::SnapShot.
SnapShotStorage: Discriminant identifying the storage domain for snapshots within LazyBalance systems.
SnapShotTime: Discriminant for the time dimension within LazyBalance::SnapShot.
TotalValue: Discriminant for total balance query.
Withdraw: Discriminant for withdrawal execution.

Enums§

BalanceOp: Operation descriptor for driving both LazyBalance and ManualBalanceModel executions in a consistent manner.

Traits§

BalanceGuards: Defines validity checks for operations during state exploration.
BalanceStateHasher: Defines a primary hashing strategy for BalanceState instances.
LazyBalance: A composable, plugin-driven balance system with lazy receipt-based accounting.
LazyBalanceComponent: A abstract-container representation of a structured value participating in the lazy balance system (e.g. Balance, SnapShot, Receipt).
LazyBalanceContext: Execution context for the LazyBalance system.
LazyBalanceInput: Input contract for all LazyBalance operations.
LazyBalanceLimits
LazyBalanceMarker: Convenience trait alias for a LazyBalance implementor used in model checking and testing.
LazyBalanceModelChecker: Unified model checker interface over the lazy balance model checker module.
LazyBalanceOutput: Output contract for all LazyBalance operations.
LazyBalanceRoot: Plugin Family Root trait for LazyBalance
ManualBalanceModel: A user-indexed eager balance model over a LazyBalance system, primarily intended for testing and validation.

Type Aliases§

Context: Resolved context type for a given LazyBalance implementation.
Error: Resolved error type for a given LazyBalance implementation.

Module assetsCopy item path