ledger-rs/doc/accounts.md

Accounts

Overview

An account is a versioned entity that owns postings. Balance is never stored — it is always computed from postings for a given (account, asset) pair. The ledger balance sums non-Inactive postings (Active + PendingInactive); the available balance sums only Active postings (excluding those reserved for an in-flight transfer). balance() returns the ledger balance.

Structure

Field	Type	Description
id	AccountId(i64)	Stable identity, assigned at creation
version	u64	Starts at 1, increments on every mutation
policy	AccountPolicy	Balance floor rule (see below)
flags	AccountFlags	Lifecycle flags (FROZEN, CLOSED) + user-defined (USER_0–USER_7)
book	BookId	Book this account belongs to
user_data	UserData	Fixed 28 bytes: u128 + u64 + u32 for external refs
metadata	Metadata	BTreeMap<String, Vec<u8>> for free-form data

Policies

Each account has a policy that controls what balance constraints apply:

Policy	Balance floor	Negative postings	CAS guard
NoOverdraft	>= 0	No	No
CappedOverdraft { floor }	>= floor	Yes (down to floor)	Yes
UncappedOverdraft	None	Yes (unbounded)	No
SystemAccount	None	Yes	No
ExternalAccount	None	Yes	No

An overdraft is represented as a negative posting (an offset position) assigned to the account to cover a shortfall. When an account's positive postings are insufficient for a debit, the resolve step consumes them all and creates a negative posting for the remainder. NoOverdraft accounts forbid this; validation rejects any transfer that would create a negative posting on a NoOverdraft account. CappedOverdraft's floor bounds how negative the balance may go; UncappedOverdraft, SystemAccount, and ExternalAccount are unbounded.

CappedOverdraft accounts emit CAS (Compare-And-Swap) guards during validation to prevent write-skew — two concurrent transfers could each pass validation independently but together push the balance below the floor. The guards are enforced atomically inside commit_transfer (the commit aborts with a retryable conflict if a guarded balance changed since validation).

Lifecycle

Accounts follow a three-state lifecycle controlled by flags:

Created (v1) → Frozen (v2) → Unfrozen (v3) → Closed (v4)
                  ↑               │
                  └───────────────┘

Operation	Precondition	Effect
freeze(id)	Not closed	Sets FROZEN flag, increments version
unfreeze(id)	Frozen	Clears FROZEN flag, increments version
close(id)	Zero active postings	Sets CLOSED flag, increments version

• Frozen accounts reject all transfers (both debits and credits).
• Closed accounts reject all transfers and cannot be reopened.
• Closing requires zero active postings for all assets.

Append-Only Versioning

Accounts are never modified in place. Each mutation appends a new version:

Version 1: { policy: NoOverdraft, flags: ∅ }         ← created
Version 2: { policy: NoOverdraft, flags: FROZEN }     ← frozen
Version 3: { policy: NoOverdraft, flags: ∅ }         ← unfrozen

The store enforces version_new == version_current + 1, preventing gaps or overwrites. The full history is queryable via account_history(id).

Snapshot Pinning

Transfers can carry AccountSnapshotId values — pairs of (AccountId, snapshot_hash) recording which account version the transfer was validated against.

During validation, if snapshots are present, the current account state is hashed and compared. A mismatch produces AccountVersionMismatch, preventing TOCTOU races where an account is mutated between load and apply.

The saga commit() path auto-populates snapshots when none are provided.

Balance Computation

Balance for an (account, asset) pair is computed as:

balance(account, asset) = sum(p.value for p in postings
                              where p.owner == account
                              and   p.asset == asset
                              and   p.status != Inactive)

There is no stored balance field. This eliminates drift between the balance and the underlying postings.

Account Types in Practice

Regular user accounts (NoOverdraft)

Hold positive postings only. Cannot go negative. Used for end-user wallets, merchant accounts, etc.

System accounts (SystemAccount)

Operational accounts representing issuance, sink, revenue, COGS, fees, or internal balancing. Can hold negative postings (offset positions — e.g. a liability when the account is the deposit counterparty). Used as the counterparty in deposits — the system account takes on a negative balance to offset the value credited elsewhere.

External accounts (ExternalAccount)

Boundary accounts representing the outside world (banks, payment processors). They represent value entering and leaving the ledger boundary, and like system accounts they can hold negative postings (offset positions).

Credit accounts (CappedOverdraft)

Accounts with a negative floor (e.g. credit lines). The floor is the maximum allowed overdraft. When the account's positive postings are insufficient for a debit, a negative posting is created to cover the shortfall, down to the floor. Write-skew prevention via CAS guards (enforced inside commit_transfer) ensures concurrent transfers respect the floor.