Wallet, account, ledger

A wallet is not a place where money is. It is a policy applied to one or more accounts. The money, in the sense the regulator cares about, is in the safeguarding arrangement, and the claim on it is recorded in the ledger.

This is not pedantry. The moment a product manager asks for a wallet that can go negative, or a wallet shared between two users, or a wallet that holds two currencies, the distinction decides whether the answer is a configuration change or a rewrite.

Ask where a rule lives. If the rule is "this movement is arithmetically valid and conserves value", it belongs to the ledger. If the rule is "this account may not go below zero", it belongs to the account definition. If the rule is "a user under sixteen may not receive transfers from outside their family group", it belongs to the wallet.

When rules migrate downward, the ledger fills with product logic and becomes impossible to reason about. When they migrate upward, the same rule is implemented three times in three product flows and diverges within a quarter.

The simplest useful wallet already needs several accounts behind it: the settled position, reservations held against pending authorisations, and often a separate position for value that has arrived but is not yet released. Presenting one number to the user is a rendering decision made on top of those.

Getting this wrong produces the most common bug in consumer payment products: the available balance and the displayed balance disagree, and support cannot explain which is right because both are computed in different places from different definitions.

Define the derived quantities once, in the ledger layer, with names. Settled, reserved, available, pending inbound. Every surface reads those names. Nobody recomputes them locally.

A wallet can be closed. An account cannot, in any meaningful sense, because entries posted to it are permanent and its history must remain readable. A user can be deleted under data protection obligations while the movements attached to their accounts must be retained under anti money laundering obligations.

Modelling the wallet separately is what makes those two requirements compatible. The wallet is closed and the personal data attached to it is handled according to the retention policy. The accounts and entries persist, identified by keys that no longer resolve to a person for anyone without the legal basis to make that link.

Teams that made the wallet and the account the same row discover this conflict at the worst possible moment, which is when the first erasure request arrives.

An account has exactly one currency. A wallet may present several, in which case it sits above several accounts and any conversion between them is a movement with a rate, a timestamp and a spread, recorded like any other movement.

The alternative, an account holding mixed currency with a conversion applied at read time, makes every historical balance a function of a rate table that keeps changing. Balances stop being reproducible, and reproducibility was the point.

Keeping the three separate costs a few extra tables and one conversation with the product team. Merging them costs the ability to answer questions about the past, which is the ability the whole system exists to provide.

The vocabulary fight is worth having once, early, in writing.