Wallet

Internal balance and asset accounting module for systems that need wallet totals, balance mutations, and audited asset events.

Generate with OpenKnitBrowse other modules

What this module does

Flexible ledger for multi-currency accounting and balances.

Key capabilities

  • Per-user wallet and asset balance ownership
  • Command-driven balance changes with before/after auditing
  • Multi-currency or multi-asset accounting primitives

Core flows

  1. Ensure wallet and wallet asset existence

    • Trigger: command handling pre-hook for non-create commands.
    • Steps: resolve wallet for user, auto-create wallet asset with zero balance when missing.
    • Output: guaranteed wallet asset target for mutation command.
    • Failure/edge cases: creation failure bubbles as command failure.

  2. Add wallet asset amount

    • Trigger: AddWalletAssetCommand handled via WalletAssetEventHandler.
    • Steps: lock by user+currency, load asset, capture totalBefore, increment totalAmount, persist event row.
    • Output: increased wallet asset balance with audit trail.
    • Failure/edge cases: missing asset (auto-create in pre-hook), lock conflicts.

  3. Subtract wallet asset amount

    • Trigger: SubtractWalletAssetCommand.
    • Steps: lock by user+currency, validate funds, capture totalBefore, decrement totalAmount, persist event row.
    • Output: decreased balance with audit trail.
    • Failure/edge cases: insufficient funds -> UnappliedCommandException.

  4. Create wallet asset command

    • Trigger: CreateWalletAssetCommand.
    • Steps: find/create wallet, create asset row with zero total/hold amount, persist create event row.
    • Output: initialized asset container.
    • Failure/edge cases: duplicate asset scenarios depend on repository constraints/query behavior.

Module is included in

  • Subscription Access: Create plans, manage subscriptions, and control what users can see or use.
  • Value Ledger: Record value movements with clear entries, timestamps, and a complete audit trail.

Source paths

  • backend/modules/wallet
  • No frontend module directory is currently present for this module.