OPENKNITv0.2.0Builder
All catalogue entries

03 / 07 Module catalogue detail

Wallet

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

Browse category: Financial

Open the builder Browse all modules

Choose the modules you want after opening the builder.

01 / Module overview

What this module does

Flexible ledger for multi-currency accounting and balances.

Documented capabilities

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

Configuration highlights

  • Flyway migrations under the wallet schema

  • Command/event-style balance mutation handlers

  • No public HTTP controller yet, intended as internal infrastructure

02 / Implementation record

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.

Core flow source: backend/modules/wallet/AGENTS.md

Continue exploring

TransactionAI moduleOCR module