DEV Community: Elewude Okikijesu

Your wallets are a liability

Elewude Okikijesu — Thu, 27 Aug 2026 09:31:38 +0000

Your wallets are a liability

Building a Ledger, #2 of 12

Last year, first day on a wallet ledger for one of the big processors here. Vendor meeting, before anybody had opened a laptop, and somebody said the line I have not been able to unhear since:

Do not write code you will have to defend in front of the EFCC.

Everybody laughed. Nobody was joking.

It took me a while to work out what was actually being said. It was not do not commit fraud. Nobody in that room was planning to. It was narrower than that, and much more uncomfortable:

If this is ever examined, nobody reads your code. They read your rows.

Post #1 built a ledger that cannot create or destroy money. Every transaction sums to zero, enforced by the database, no exceptions. It works.

It also cannot tell you whether the money in it is yours.

The founder on the call

He is asked how much the company is holding. He runs this:

SELECT SUM(balance) FROM wallets;
-- 2,400,000,000

₦2.4 billion. He says it out loud.

That number is wrong in the most important way a number can be wrong. It is not money the company has. It is money the company owes. Every naira in a customer wallet is a debt, payable on demand, to somebody who can walk into an agent shop and ask for it. What the company actually has is whatever is sitting in the settlement bank account, and that is a completely different number.

The gap between those two numbers is what this post is about. In this market it is also the distance between a soft chair in your own office and a concrete floor in an EFCC detention facility.

Which is why it belongs in the schema on day zero, not day one.

Nobody tells you which rows to write

Fair warning before we go further: there are about thirty lines of code in this post and they are the least interesting part.

Here is the bit that never makes it into the ticket.

You get handed let users send money to each other. You write the function. Debit one wallet, credit the other, wrap it in a transaction, done before lunch. Post #1 already dealt with the part that looked hard, which was the concurrency.

What nobody mentions is that the function you just wrote will move money it does not understand. It cannot tell a customer's deposit from a promo credit. It cannot tell your revenue from somebody else's float. It does not know that one of those numbers is not yours. It moves all of them with equal confidence, the sum-to-zero check passes every single time, and the books balance the whole way down.

Then somebody asks where the money went, and the answer gets reconstructed from the rows you chose to write.

Not the code. The rows.

So the claim is this: an amount is not a fact until you know what kind of account it sits on. Post #1 gave us numbers that always conserve. This post gives those numbers meaning.

What is −5,000?

Start with a puzzle, because it is the whole problem in one line.

An account in your ledger is sitting at −5,000. Is that a bug?

You cannot answer that. Neither can your database.

If it is a customer wallet, it is a serious bug, because a customer cannot owe you money they never borrowed.

If it is your fee revenue account, it is completely normal. That is what revenue looks like from the inside.

If it is your settlement account, you have an emergency, because you are claiming to hold cash you do not have.

Same number. Three different worlds. Signed integers carry magnitude and direction. They carry no meaning at all.

So the invariant from post #1 proves nothing was destroyed. It does not prove anything is right. To get closer to right, the ledger has to know what kind of thing each account is.

Five kinds of account

Every account answers one question: does this represent something you have, something you owe, or something that moved?

There are five answers. The machinery underneath them is about 500 years old, and the five-way split on top has been stable for most of the modern era.

Asset. Something you have or are owed. Your settlement account. Cash in an ATM. Money a merchant owes you.

Liability. Something you owe. Customer wallets go here. Tax withheld and not yet remitted. Merchant payouts you have not sent.

Equity. What is left for the owners after liabilities. Share capital, retained earnings.

Revenue. Money earned. Transaction fees, subscription income.

Expense. Money spent. Promo credits, provider costs, fraud losses.

Assets and expenses are things you hold or consumed. Liabilities, equity and revenue are things you owe or earned. That split produces the equation everything hangs on:

Assets = Liabilities + Equity + (Revenue − Expenses)

Now go back to −5,000. It is only answerable because the account has a kind. That is the entire mechanism.

Your wallets are a liability

This is the one that matters, and it is not an accounting technicality. If you hold a mobile money licence in Nigeria, it is written into your licence conditions.

What the regulator actually says

Under the CBN's July 2021 Guidelines, operators settle all obligations into settlement accounts at deposit money banks and keep separate accounts for their other business. Those settlement accounts are opened as nominee accounts on behalf of customers, and section 9(c) governs them with four conditions [1]:

The account shall not be interest bearing.
No right of set-off.
Debits only for settlement-related transactions.
No bank charges of any kind.

Section 9(d) then adds a separate prohibition: the account cannot be used as collateral for loans, under any guise.

Read those as an engineer rather than a lawyer. No right of set-off means you cannot take what customers owe you out of the pool. Debits only for settlement means money may not leave that account for any other reason, including yours. No collateral means you cannot borrow against it.

The regulator is saying, in legal language, that this is not your money.

Then comes the line that should make anyone building a ledger sit up. Section 9(e) requires that the settlement account balance always equal the total unspent balance of every e-money holder [1].

That is Assets = Liabilities. One asset account, one class of liability, mandated by law, checkable with a query.

The accounting equation is not a nice-to-have here. It is a licence condition.

(One caveat, because it matters if you build savings: those funds are an explicit exception. They go into a separate pool and get invested in Nigerian Treasury Bills, and section 10.1.3(a) caps fees and charges for managing that investment at 10% of the interest income it earns. Read section 10 properly before you model any of it.)

Why those conditions exist

Every one of them is there because somebody did the opposite.

The pool account is the largest number in the company and it sits there looking spendable. When payroll is due and revenue is thin, the distance between we are holding ₦2.4 billion and we have ₦2.4 billion is the distance between a going concern and that concrete floor. In this market it is not hypothetical. It is a recurring news story, and it is what that vendor meeting was actually about.

A schema will not stop a determined founder. But a ledger where customer float is typed as a liability, sitting next to a settlement asset that is supposed to match it, makes the gap visible on day one rather than on the day somebody comes asking.

Why the branch closes at 4pm

There is a reporting consequence that will feel familiar to anyone who has worked near a Nigerian bank. Operators must reconcile pool balances daily and make weekly returns to the CBN [1].

That is a trial balance, turned into a legal obligation.

It is also why the branch shuts its doors at 4pm and the banker you know still gets home at 9. The doors close so the day can be counted. Somebody has to prove that what the system says matches what the accounts actually hold, line by line, and sign it before anyone leaves.

That work does not disappear because you have Postgres instead of a branch network. It just moves. If your ledger cannot produce that number on demand, somebody on your team produces it by hand every evening, forever, and they are not enjoying it.

Reading the sign

The mechanical bit, and it is short. We keep the signed bigint from post #1. Positive means debit. Negative means credit. That is the only convention to memorise.

Combine it with the five kinds:

Kind	Increases with	Healthy balance is
Asset	debit (+)	positive
Expense	debit (+)	positive
Liability	credit (−)	negative
Equity	credit (−)	negative
Revenue	credit (−)	negative

Which produces the thing that trips everyone up:

A customer with ₦5,000 in their wallet has a raw ledger balance of −5,000.

That looks wrong. It is not. It is negative because from the company's point of view, that is a debt. The minus sign is the ledger being honest about whose money it is.

You obviously do not show a customer −5,000. So you convert. And since this rule is going to be needed in more than one place, it goes in one place:

CREATE FUNCTION natural_sign(k account_kind) RETURNS int
    LANGUAGE sql IMMUTABLE AS $$
    SELECT CASE WHEN k IN ('liability','equity','revenue') THEN -1 ELSE 1 END;
$$;

-- Anywhere you need the number a human expects:
SELECT natural_sign(a.kind) * SUM(e.amount) AS natural_balance

Two copies of a sign rule will drift, and the day they drift is the day your dashboard and your trial balance disagree about the same account. One function, IMMUTABLE so the planner can inline it.

The number in your database and the number on the customer's screen are different things, and the account kind is the function between them. Literally, in this case. That is most of what debits and credits actually buy you.

Three transactions

Watch the equation hold.

1. Customer deposits ₦5,000 by bank transfer.

Settlement account  (asset)     + 5,000    debit
Customer wallet     (liability) − 5,000    credit
                                 -------
                                       0

You have ₦5,000 more in the bank and you owe ₦5,000 more to a customer. Assets 5,000, Liabilities 5,000.

2. You charge a ₦25 fee.

Customer wallet     (liability) +    25    debit
Fee revenue         (revenue)   −    25    credit
                                 -------
                                       0

You owe slightly less, and you earned ₦25. No cash moved. The bank balance is untouched. What changed is who has a claim on it.

3. You give a ₦1,000 promo credit.

Marketing expense   (expense)   + 1,000    debit
Customer wallet     (liability) − 1,000    credit
                                 -------
                                       0

Look carefully, because this is where a balance column would quietly lie to you.

The wallet went up by ₦1,000. Your bank account did not. You now owe ₦5,975 while holding ₦5,000. That is not a bug. It is the accurate, slightly uncomfortable fact that you promised money you have not funded.

Assets      5,000
Liabilities 5,975
Revenue        25
Expenses    1,000

5,000 = 5,975 + 0 + (25 − 1,000)
5,000 = 5,000  ✓

Still balanced, and now telling you something a balance column never could: the promotion made you poorer, and by exactly ₦1,000.

That is the whole argument in one example. A deposit and a promo credit both add money to a wallet. With a balance column they are literally the same operation. In a typed ledger they are opposites. One increases an asset. The other increases an expense. One is funded. The other is a promise.

And it opens exactly the way you would expect. Growth runs a promo over the weekend. Finance hears about it on Monday. Nothing in the wallets table separates ₦40 million of promo credits from ₦40 million customers actually deposited, so the float looks healthy right up until enough people withdraw at once. By then the question is not what your database says. It is whether the settlement account can cover it.

Where money enters

Post #1 said the ledger cannot create money. Typed accounts force you to confront what that means at the edges.

A customer deposits ₦5,000. You cannot simply credit their wallet, because the entry has to come from somewhere or it will not balance. You are physically prevented from conjuring it.

That constraint is doing you a favour. Every naira entering the system has to name its counterparty, and the counterparty is a real thing in the world: the bank account the money landed in.

The `system` account

Most teams discover this and then defeat it. They create an account called system or main or bank, with no type, and post everything against it. It grows into an enormous number nobody can explain, and becomes the black hole where every unexplained naira goes to hide.

A system account is a confession that you have not modelled something.

Banks already have a name for this. It is the suspense account, and anyone who has worked in bank operations has a story about a suspense balance nobody could explain, that grew quietly for years, and was eventually written off because everyone who knew what it was had left. A system account is a suspense account you built deliberately, before you had a single customer.

What it costs

A founder told me how this played out at his company. The shape is worth walking through, because at no point did anyone have to be dishonest.

They had a system account. Customer money came in, wallets were credited, the counter-entry went to system. Provider fees went out of system. Operating costs came out of system. A promo campaign came out of system. It was the account for everything that was not a user wallet, which made it the account for everything nobody had thought about yet.

Every decision was defensible on the day it was made. The money was in the bank. The number looked fine. Nothing objected, because nothing in the system knew the difference between money they had earned and money they were holding for somebody else.

By the time a real reconciliation happened, the hole nearly took the company down. Every customer balance was correct. Every wallet showed exactly the right number. The money to honour those numbers was not there. They had been running the business on customer float for months, and the ledger reported balanced books the entire time, because it was balanced.

Sum-to-zero held on every transaction. It just could not say what kind of zero it was.

They had magnitude and direction, and no meaning.

Typed accounts would not have stopped anyone spending that money. They would have made it impossible to spend without seeing it. An operating cost posted against a liability account is a question somebody answers out loud. An operating cost posted against system is just Tuesday.

It is also, eventually, an afternoon spent explaining what system means to people who do not find it funny.

Starting from nothing

Small practical problem everyone hits on day one, same answer.

Your ledger is empty. You want to record that the company started with ₦10,000,000 of capital in the bank. Debit the settlement account ₦10,000,000. What do you credit?

Nothing exists yet, and a single-sided entry gets rejected by the trigger.

The answer is equity. Equity is the account that exists so the books can start.

Settlement account  (asset)   + 10,000,000    debit
Share capital       (equity)  − 10,000,000    credit

Same pattern handles migrations, which matters more than the founding case. Moving off a legacy system with existing balances? You do not insert balances. You post an opening transaction per account against an opening-balances equity account, and from that moment every naira has a traceable origin. The migration becomes a ledger entry you can point an auditor at.

One query for the whole business

Post #1 checked one thing per transaction. Typed accounts give you a check across the entire database:

-- Every entry ever written, per currency. Must be zero.
SELECT currency, SUM(amount) AS imbalance
  FROM entries
 GROUP BY currency
HAVING SUM(amount) <> 0;

If the per-transaction trigger is doing its job, this always returns nothing. Which is the point. It returns a row only if somebody bypassed the trigger, disabled it, or wrote straight to the table. It is your tamper detector.

The typed version is the trial balance. One row per account, which is what an accountant means by the phrase:

CREATE VIEW trial_balance AS
SELECT a.id,
       a.code,
       a.kind,
       a.currency,
       COALESCE(SUM(e.amount), 0)                        AS raw_balance,
       natural_sign(a.kind) * COALESCE(SUM(e.amount), 0)  AS natural_balance
  FROM accounts a
  LEFT JOIN entries e
         ON e.account_id = a.id
        AND e.currency   = a.currency
 WHERE NOT a.is_rollup
 GROUP BY a.id, a.code, a.kind, a.currency;

Three details. It is a LEFT JOIN so accounts with no entries still show as zero, because an account silently missing from a trial balance is worse than one showing nothing. It joins on both account_id and currency, matching post #1's composite foreign key instead of relying on you remembering it exists. And it excludes rollups, because summing a parent alongside its children counts the same money twice.

Roll that up by kind and you get the equation itself:

CREATE VIEW accounting_equation AS
SELECT kind, currency, SUM(natural_balance) AS balance
  FROM trial_balance
 GROUP BY kind, currency;

Two views, not one, and the names are worth getting right. A trial balance lists every account. Grouping by kind gives you the accounting equation, which is a different report answering a different question. Call the second one a trial balance and the first accountant who opens your repo will quietly downgrade their opinion of everything else in it.

This is the number the founder should have quoted on that call. It is also, roughly, what the CBN wants reconciled every day.

Why accountants use two columns

Time to answer the title, because I have been using one signed column and real accounting systems do not.

A traditional ledger has debit and credit, both always positive, and the two must total the same:

Account	Debit	Credit
Settlement	5,000
Customer wallet		5,000

Three real advantages:

No negative numbers anywhere. You cannot fat-finger a sign, because there are no signs.

A category of mistake gets harder to express. With one signed column, +5000 and −5000 posted to the wrong two accounts passes the sum check happily. Two columns make that harder to write by accident.

It is what every finance system on earth expects. Your accountant, your auditor, your ERP import and every regulatory return assume DR/CR.

I am still using one signed column. The sum-to-zero check is one operation on one column and post #1's constraint works unchanged. Two columns need SUM(debit) = SUM(credit), a check that exactly one is non-zero per row, and decisions about nulls versus zeros. More surface for the same guarantee.

And DR/CR is a presentation format, so you can always derive it:

SELECT CASE WHEN amount > 0 THEN  amount END AS debit,
       CASE WHEN amount < 0 THEN -amount END AS credit
  FROM entries;

You cannot go the other way as cleanly.

If you are building for an organisation that already has a finance team with opinions, store DR/CR natively and save yourself the argument. The important thing is not which representation you pick. It is that the account kind is recorded, so the sign has meaning.

The schema

CREATE TYPE account_kind AS ENUM (
    'asset', 'liability', 'equity', 'revenue', 'expense'
);

An enum rather than text with a CHECK: same validation, and adding a sixth kind becomes a deliberate migration rather than a typo that silently succeeds.

Now the migration. Post #1 shipped an accounts table, so yours has rows in it, and you cannot add a NOT NULL column to a table that already has rows. The order of the next four steps matters more than it looks, and I will come back to why.

-- 1. Add the columns, nullable for now.
ALTER TABLE accounts ADD COLUMN kind      account_kind;
ALTER TABLE accounts ADD COLUMN code      text;
ALTER TABLE accounts ADD COLUMN parent_id uuid REFERENCES accounts (id);
ALTER TABLE accounts ADD COLUMN is_rollup boolean NOT NULL DEFAULT false;

CREATE INDEX accounts_parent_idx ON accounts (parent_id);

-- 2. Seed the chart of accounts FIRST, so the rollup exists
--    before anything tries to point at it.
INSERT INTO accounts (code, name, kind, currency, is_rollup) VALUES
  ('asset:settlement:gtb',      'GTB settlement account',   'asset',     'NGN', false),
  ('asset:cash:agent_float',    'Agent cash float',         'asset',     'NGN', false),
  ('liability:wallets',         'User wallets',             'liability', 'NGN', true ),
  ('liability:tax:withholding', 'Withholding tax payable',  'liability', 'NGN', false),
  ('liability:payouts:pending', 'Merchant payouts pending', 'liability', 'NGN', false),
  ('equity:opening_balances',   'Opening balances',         'equity',    'NGN', false),
  ('revenue:fees:transfer',     'Transfer fee revenue',     'revenue',   'NGN', false),
  ('expense:promotions',        'Promotional credits',      'expense',   'NGN', false),
  ('expense:provider_fees',     'Payment provider fees',    'expense',   'NGN', false);

-- 3. Backfill. Everything that existed before this migration was a wallet,
--    so it is a liability and it hangs off the rollup we just created.
UPDATE accounts a
   SET kind      = 'liability',
       code      = 'liability:wallets:' || a.id,
       parent_id = (SELECT id FROM accounts WHERE code = 'liability:wallets')
 WHERE a.kind IS NULL;

-- 4. Tighten.
ALTER TABLE accounts
    ALTER COLUMN kind SET NOT NULL,
    ALTER COLUMN code SET NOT NULL,
    ADD  CONSTRAINT accounts_code_unique UNIQUE (code);

Seed before backfill, not after. Do it the other way round and every migrated wallet gets a null parent_id, because the rollup it should point at does not exist yet. Nothing errors. The wallets simply never roll up, and you find out during your first reconciliation.

code gives you stable, readable identifiers. You will use them in code, in reconciliation scripts, and in conversations with your accountant, all of which go better when the thing has a name instead of a UUID.

Rollups, and why `parent_id` is there

Individual user wallets are still their own rows, all of kind liability, each with parent_id pointing at liability:wallets.

That parent is a rollup, not a posting account, and the distinction matters more than it looks. Post entries to both a wallet and its parent and you count the same money twice, so your trial balance is quietly wrong. Never post to the parent and its balance is zero, so comparing against it is meaningless.

Now, the tempting way to enforce this is to work it out from the data. An account with children is a rollup, so:

-- Do not do this.
IF EXISTS (SELECT 1 FROM accounts WHERE parent_id = NEW.account_id) THEN

That is a bug, and a nasty one. An account is postable right up until the moment it gets its first child, and then it silently stops being postable. liability:wallets accepts entries on Monday. On Tuesday the first wallet points at it. Those Monday entries are now double-counted forever, and nothing anywhere raises a complaint, because on Monday the rule genuinely did not apply.

A classification that can change when unrelated data changes is not a classification. So state it structurally, at creation, with the is_rollup column from the migration:

CREATE FUNCTION reject_posting_to_rollup() RETURNS trigger AS $$
BEGIN
    IF (SELECT is_rollup FROM accounts WHERE id = NEW.account_id) THEN
        RAISE EXCEPTION 'account % is a rollup and cannot be posted to directly',
            NEW.account_id USING ERRCODE = 'restrict_violation';
    END IF;
    RETURN NEW;
END;
$$ LANGUAGE plpgsql;

CREATE TRIGGER entries_leaf_accounts_only
    BEFORE INSERT ON entries
    FOR EACH ROW EXECUTE FUNCTION reject_posting_to_rollup();

The flag is set when the account is created and cannot drift with the data. If you want to go further, the composite foreign key trick from post #1 works here too: a UNIQUE (id, is_rollup) on accounts lets you require that every parent_id points at a row where is_rollup is true, so a wallet cannot hang off another wallet.

A rollup's balance is the sum of its children, computed on demand. Which means the sum of every user wallet is the wallet total by construction, not by luck, and comparing that against asset:settlement:gtb is the licence condition from earlier, expressed as a query.

That is post #12 in miniature.

What this does not solve

Same discipline as last time, because a rule that gets oversold gets ignored.

Typed accounts still do not mean correct. Debit expense:promotions when you meant expense:provider_fees and everything balances perfectly while your P&L is wrong. Post #1 said conservation is not accuracy. Classification is not accuracy either.

A balanced equation does not mean you are solvent. Assets equals liabilities plus equity holds even when equity is deeply negative. The ledger balances beautifully all the way into insolvency. It is an integrity check, not a health check.

Nothing here handles timing. A fee earned today and collected next month is a receivable, and this model has no concept of accrual versus cash. That is where a lot of fintech reporting goes wrong, and it deserves its own post.

The FX case is still open. Post #1's trigger groups by currency, so a multi-currency transaction must balance in each currency independently. Real FX needs balancing legs through an FX position account, and revaluation when rates move.

This chart of accounts is not portable. The invariant survives any asset. Almost nothing around it does. Yen has no minor unit, so post #1's "store everything in kobo" assumption breaks on day one. On-chain assets settle by confirmation rather than bank transfer, and confirmations can be reorganised away. What counts as settled, how many decimals you need, and who you reconcile against are decisions you make before your posting logic means anything.

And check the regulations yourself. The guidelines here are from July 2021, the CBN revises them as it sees fit, and they cover mobile money operators specifically. Hold a PSSP, switching, PSB or microfinance licence and your conditions differ. The accounting argument holds regardless. The legal detail may not.

What ships

Tag v0.2-post-02: the account_kind enum, the four-step migration, is_rollup accounts with the leaf-only posting trigger, the natural_sign function, the seeded chart of accounts, the trial_balance and accounting_equation views, and tests asserting that the whole ledger sums to zero per currency, that the equation holds after a deposit, a fee and a promo, that posting to a rollup is rejected, and that the wallet rollup equals the sum of individual wallets.

The founder on that call had one number. He should have had three: ₦2.4 billion owed to customers, whatever is actually in the settlement account, and the difference between them. If the first two are not close together, that is the only fact on the call that matters.

And it is the difference somebody else will eventually calculate, from your rows, in a room you did not choose.

Next post: splitting ₦100 three ways without losing a kobo. Money types, minor units, and why the remainder has to go somewhere on purpose.

References

[1] Central Bank of Nigeria (2021). Framework and Guidelines on Mobile Money Services in Nigeria. Settlement account conditions at section 9; savings wallets at section 10. https://www.cbn.gov.ng/Out/2021/CCD/Framework%20and%20Guidelines%20on%20Mobile%20Money%20Services%20in%20Nigeria%20-%20July%202021.pdf

#2 of 12 in Building a Ledger, a double-entry ledger engine in Go. Code: https://github.com/Helewud/kobo

balance is a summary, not a fact. In this post, I break down the 5 major failure modes of storing wallet balances in a single column and show how to enforce zero-sum invariants directly in Postgres.

Elewude Okikijesu — Tue, 25 Aug 2026 06:54:58 +0000

Elewude Okikijesu

Aug 25

Your wallet balance shouldn't be a column

#wallet #database #fintech #go

16 min read

[Boost]

Elewude Okikijesu — Tue, 25 Aug 2026 06:49:29 +0000

Elewude Okikijesu

Aug 25

Your wallet balance shouldn't be a column

#wallet #database #fintech #go

16 min read

Your wallet balance shouldn't be a column

Elewude Okikijesu — Tue, 25 Aug 2026 06:00:00 +0000

Your wallet balance shouldn't be a column

Building a Ledger, #1 of 12

An agent is standing in a shop in Ikeja. She has ₦80,000 in her wallet. She tries to send ₦5,000 to a supplier and the app spins, then times out.

Her money is there. The system just can't give it to her right now, because it is busy paying her. Somewhere in a data centre, her wallet row is locked as part of a fee posting for a transaction she has nothing to do with.

This post is about the one design decision that leads there, and how to avoid it.

This is the first post in a series where I build a working double-entry ledger in Go, one post at a time.

The line everybody writes

UPDATE wallets SET balance = balance - 5000 WHERE id = $1;

One line. Fast. Obvious.

Let me be fair to it first, because most posts on this topic are not. This exact statement is safer than people think. In Postgres, if two of these run at once, they do not lose money. The second one waits for the first to commit, then re-reads the row and applies its change to the new value. Postgres calls this the EvalPlanQual recheck, and it exists precisely to stop lost updates at the default isolation level [6].

So the one-liner survives. The problem is that almost nobody ships the one-liner, because it can't answer the question that actually matters: does this wallet have enough?

There are five things wrong with keeping a balance in a column. Only one of them can be fixed with a lock, and that fix is what causes the fifth.

Failure one: the lost update

To check the balance before spending it, you write this instead:

row := db.QueryRow("SELECT balance FROM wallets WHERE id = $1", id)
// balance = 10,000
if balance < amount {
    return ErrInsufficientFunds
}
db.Exec("UPDATE wallets SET balance = $1 WHERE id = $2", balance-amount, id)

This is the version in production at a lot of companies. It is also broken.

Balance starts at ₦10,000

Request A:  read balance    → 10,000
Request B:  read balance    → 10,000
Request A:  write 10,000 - 3,000 = 7,000
Request B:  write 10,000 - 4,000 = 6,000

Final balance: ₦6,000
Money withdrawn: ₦7,000

The user took out ₦7,000 but only ₦4,000 left their balance. You gave away ₦3,000.

The read and the write are two separate statements, so nothing connects them. Postgres has no idea the second statement depends on the first.

This is not new. It was named three decades ago as phenomenon P4, "Lost Update," in the 1995 SIGMOD paper by Berenson, Bernstein, Gray, Melton and the O'Neils [5].

Two things worth knowing about isolation levels here, because they get repeated wrong constantly:

Postgres defaults to READ COMMITTED, which allows this.
MySQL/InnoDB defaults to REPEATABLE READ, which does not. Different default, different failure mode.

If you have never explicitly thought about isolation levels, you do not know which of those you are running.

I've watched this one play out more times than I'd like. It is the most common way I have seen a young fintech lose real money, and it is usually not an accident.

This is a known attack. People go looking for it. Fire twenty withdrawal requests at the same endpoint in the same second, then check what the balance says afterwards. It costs nothing to test, it needs no stolen credentials and no insider, and when it works, it works again and again until somebody reconciles. By then the money has been cashed out.

So do not file this under "bug we should get to eventually." A balance column with a read-then-write on it is an open door, and in this market people are already checking the handle.

Now the honest part. You are already thinking: just use SELECT ... FOR UPDATE. You are right. That fixes this one.

Hold that thought. It is the only one of the five that locking solves, and in failure five, it becomes the problem.

Failure two: you cannot answer "why?"

A customer says they were debited twice. You open the database:

balance: 12,400

Now what?

That number tells you what the balance is. It says nothing about how it got there. You can't see what it was yesterday. You can't see which operations changed it. You can't tell whether there were two debits or one.

Every investigation becomes archaeology through application logs, if you kept them, and if they weren't rotated away last week.

Some teams do keep a transactions table alongside the balance. That helps, but it doesn't fix this. If the balance isn't derived from that table, the two can drift, and when they disagree you have no way to say which one is right.

This goes beyond support tickets. Handle other people's money long enough and an auditor, a regulator or a partner bank will ask you to prove a balance. "Our application wrote this number" is not proof. It's a claim.

Pat Helland said it best: "Accountants don't use erasers or they go to jail" [1]. Accounting solved this centuries ago. Nothing is erased. Mistakes are fixed by adding new entries, never by changing old ones.

An UPDATE on a balance column is an eraser.

Failure three: money can be created and destroyed

This is the one that should worry you most, and the one discussed least.

A transfer is two writes:

UPDATE wallets SET balance = balance - 5000 WHERE id = 'sender';
UPDATE wallets SET balance = balance + 5000 WHERE id = 'receiver';

Wrap it in a transaction and both succeed or both fail. Good. But think about what your schema actually knows.

It knows there are two rows. It does not know they are related. It does not know that ₦5,000 leaving one place and ₦5,000 arriving in another are two halves of one event. There is no rule anywhere saying money must be conserved.

So the day a bug writes the debit and skips the credit, whether from a bad code path, a half-completed retry, or a migration script someone ran at 2am, then ₦5,000 stops existing. Nothing notices. There is no query that says "something is wrong here," because the schema has no concept of right and wrong. It only has numbers.

Uber published a ten-year retrospective on their payments platform this year. Among the principles they say they defended for a decade is zero-sum accounting, which ensured "money was never created or destroyed" [2]. That's a property they designed for on purpose. It isn't free.

You can't have it with a balance column. There's nothing for it to be a property of.

Failure four: corruption is permanent

The balance is now wrong. How do you fix it?

You can't recompute it, because there's nothing to recompute from. The column was always the only copy of the truth. So your only option is:

UPDATE wallets SET balance = 8500 WHERE id = $1;

Which is the exact operation that caused the problem. It leaves no record. Six months later nobody knows this number was typed by hand during an incident. It looks identical to a balance earned honestly.

Corruption here isn't just possible. It's permanent and invisible.

Failure five: the hot row

Failure one was about being wrong. This one is about being unavailable.

You added SELECT ... FOR UPDATE. Correctness is fixed. Now a popular merchant starts receiving payments. Fifty credits land on one wallet in the same second.

Every one of them wants the same row. They queue behind a single lock. Throughput on that wallet is now 1 / lock_hold_time, no matter how many servers you run. Add capacity and nothing improves, because the bottleneck is one row in one table.

Note that the plain one-liner has this problem too. Locking made you correct; it did not make you fast, and nothing about a mutable balance column ever will.

Then it gets worse. Transfers lock two rows:

Transfer A→B:  lock A, then lock B
Transfer B→A:  lock B, then lock A

Both hold one lock and wait for the other. Deadlock. Postgres detects it and kills one transaction. Your user sees a failed transfer that should have worked.

The standard fix is to always acquire locks in a fixed order: sort by account ID, lock the smaller first. It works. It also requires every developer who ever touches money code to remember it, forever, including the one who joins next year and writes a batch settlement job at 2am.

The fee split: where this gets ugly

Take one POS payment of ₦20,000 through an agent network. That transaction doesn't touch two wallets. The fee gets split:

Customer            − ₦20,100
Merchant            + ₦20,000
Agent (net)         +     ₦40
Tax withheld        +      ₦5
Aggregator          +     ₦20
Platform            +     ₦25
Switch / processor  +     ₦10

The agent's gross commission is ₦45; ₦5 is withheld at source, so ₦40 reaches her wallet and ₦5 goes to a tax liability account. Seven wallets, one payment, and the numbers sum to zero.

With SELECT ... FOR UPDATE, that's seven row locks held together in one transaction. Now look at which rows. The customer and merchant change every time. But the aggregator, the platform, the switch and the tax account are in every single transaction the network processes. They are not occasionally hot. They are locked on every payment, all day.

At a few hundred payments a second, those four rows are the whole system. Run twenty application servers and nothing improves, because all twenty are waiting on the same four rows.

And then you get the agent in the shop. Her wallet is locked as part of somebody else's fee posting. She tries to send ₦5,000 to a supplier and it hangs, times out, or deadlocks against a settlement job running in the other direction.

She can't spend her money because the system is busy paying her.

That is not a throughput problem you can buy your way out of. It is the data model.

"Just use a queue"

This is where most teams land. Put transactions on a queue, partition by wallet ID, process each wallet serially. One consumer per wallet, no concurrent writes, no locks, no deadlocks.

It works. And notice what you just decided: serialise the events and apply them in order. That is a ledger. You have arrived at the right idea.

But look at where you put it.

Your system of record is now two systems. The truth about a wallet is "what Postgres says, plus whatever is still in flight in the queue." Those two things are not in the same transaction and cannot be made consistent with each other. There's a window where money has left the sender and not arrived at the receiver, and nothing in your database represents that window.

Queues also deliver at-least-once. A consumer that crashes after applying a credit but before acknowledging will apply it again, so you need idempotency keys anyway, and that is a database concern.

And ordering is only per-partition. Repartition, rebalance or scale consumers and your careful per-wallet ordering can break in ways that are painful to reproduce.

The queue is a good tool. It is a bad system of record. You've taken the most important invariant in your business and handed it to a component sitting outside your database, when it could have been native to your schema.

How the big processors actually handle it

It's tempting to settle this by quoting transaction volumes. That's the wrong lesson. The interesting thing about Stripe isn't how much they process. It's how.

Stripe's internal Ledger is an immutable, auditable log that serves as the system of record for their financial data, handling five billion events a day [4]. Adyen has described roughly fifty rows being inserted into their accounting database over the lifetime of a single payment [7].

Note what both of those are: inserts. Not updates. The scale comes from appending, because appends don't fight each other.

Now the counterexample, because it matters more than the supporting ones. Uber's Gulfstream has had immutable money orders and zero-sum accounting for a decade, and they still hit a wall. In a separate post this year they describe hot-key accounts that by 2023 needed far more than their system's limit of 3 to 4 update operations per second [3].

So append-only is not a magic word. Uber kept a stored-balance layer for reads, and that layer is where the heat landed. What appending buys you is that the write path stops conflicting. Where you keep derived balances, and how you shard them, is a separate problem you still have to solve.

Our fee split, done as a ledger, is seven INSERTs into entries inside one transaction, summing to zero. No row is exclusively locked. The platform account can receive a thousand fee entries a second while the agent spends from her wallet in the same millisecond, because those are different rows and neither blocks the other.

One caveat, so you hear it from me and not from production: those inserts do take a shared FOR KEY SHARE lock on the referenced accounts row, because that's how foreign keys work. Shared locks don't block each other, so throughput holds. But very high concurrency on the same referenced row generates multixact traffic, and that has its own costs at scale. Better trade, not zero cost.

On "correctness over efficiency"

You'll hear that fintech should always choose correctness over speed. The sentiment is right, but stated that way it hands the argument to the other side, because if correctness always wins, then locking all seven wallets is justified and the agent can just wait.

Better framing: with an append-only ledger, you are not making that trade on the write path at all. The lock-based design buys correctness by spending availability. The ledger keeps the same correctness and moves the cost somewhere much smaller.

Where a real trade does show up, it's narrower than people think, and it's about reads:

Showing a balance can be slightly stale. A dashboard 200ms behind harms nobody.
Authorising a debit cannot be stale. That read must be authoritative, or you've reinvented failure one with extra steps.

Keep those two apart, in your head and in your code. Conflating them is how a team "fixes" contention by reading a cached balance and quietly reintroduces overdrafts.

I'll be honest about the limit: appending makes credits free, and credits are the high-volume case. A debit that must check "does this wallet have enough?" still needs an authoritative balance, and that still needs a correctness story. That's post #6, where I benchmark three of them. But solving the high-volume half completely, with no extra infrastructure, is not a small win.

The fix: derive the balance

Every failure above comes from one decision: storing a conclusion instead of the facts that produce it.

A balance is not a fact. It's a summary. It's the answer to a question you can ask at any time, as long as you kept the inputs.

So keep the inputs. Append what happened. The balance becomes a SUM:

SELECT COALESCE(SUM(amount), 0) FROM entries WHERE account_id = $1;

Helland calls this append-only computing: record observations permanently, calculate results on demand [1].

To be precise about the claim, because "never store a balance" is too strong: you can absolutely keep a materialised balance. Uber does. What you must not do is make it the only record of truth. If it can be rebuilt by replaying entries, it's a cache and you can fix it. If it can't, it's a liability.

The schema

CREATE TABLE accounts (
    id         uuid PRIMARY KEY DEFAULT gen_random_uuid(),
    name       text NOT NULL,
    currency   char(3) NOT NULL,
    created_at timestamptz NOT NULL DEFAULT now(),
    UNIQUE (id, currency)
);

CREATE TABLE transactions (
    id          uuid PRIMARY KEY DEFAULT gen_random_uuid(),
    reference   text UNIQUE,
    description text NOT NULL DEFAULT '',
    created_at  timestamptz NOT NULL DEFAULT now()
);

CREATE TABLE entries (
    id             bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
    transaction_id uuid    NOT NULL REFERENCES transactions (id),
    account_id     uuid    NOT NULL,
    currency       char(3) NOT NULL,
    amount         bigint  NOT NULL CHECK (amount <> 0),
    created_at     timestamptz NOT NULL DEFAULT now(),
    FOREIGN KEY (account_id, currency) REFERENCES accounts (id, currency)
);

-- Balance reads: INCLUDE (amount) allows an index-only scan.
CREATE INDEX entries_account_idx
    ON entries (account_id, id) INCLUDE (amount);

-- The balance trigger below queries by transaction_id on every insert.
-- Without this index that is a sequential scan of the whole table.
CREATE INDEX entries_transaction_idx ON entries (transaction_id);

A transaction is one event: a transfer, a fee, a top-up. An entry is one side of it. A simple transfer has two entries. The POS payment above has seven.

Four decisions worth explaining:

amount is bigint, in minor units. ₦50.00 is 5000 kobo. Never a float, because floats can't represent 0.1 exactly and the errors accumulate. (Not every currency divides by 100. JPY has no minor unit, KWD has three digits, so you'll eventually want an exponent per currency. Post #3.)

amount is signed. Negative takes money out, positive puts it in, and entries in one transaction must sum to zero. Accountants say debit and credit; that's post #2. For now, signed integers are the same idea with less vocabulary.

CHECK (amount <> 0). A zero entry would satisfy the sum-to-zero rule while meaning nothing.

The composite foreign key. accounts has UNIQUE (id, currency) and entries references (account_id, currency). A naira entry physically cannot be written against a dollar account. No trigger, no application check. The database rejects it. The redundant unique index is the price, and it's worth it.

Put the invariant in the database

Entries in a transaction must sum to zero, per currency. That rule is what stops money being created or destroyed.

The tempting place to enforce it is in Go, before the insert. Do that too. Just don't let it be the only place.

Bailis and colleagues studied this in Feral Concurrency Control. Across 67 real Rails applications, they found application-level validations were over 37 times more common than database transactions [8]. Their more interesting finding is the nuance: most of those validations are accidentally safe under concurrency, but the unsafe remainder is dominated by uniqueness and aggregate checks. Sum-to-zero is exactly that kind of check. It's in the group that breaks.

CREATE OR REPLACE FUNCTION assert_transaction_balances() RETURNS trigger AS $$
DECLARE
    bad record;
BEGIN
    SELECT currency, SUM(amount) AS imbalance
      INTO bad
      FROM entries
     WHERE transaction_id = NEW.transaction_id
     GROUP BY currency
    HAVING SUM(amount) <> 0
     LIMIT 1;

    IF FOUND THEN
        RAISE EXCEPTION 'transaction % does not balance in % (off by %)',
            NEW.transaction_id, bad.currency, bad.imbalance
            USING ERRCODE = 'check_violation';
    END IF;
    RETURN NULL;
END;
$$ LANGUAGE plpgsql;

CREATE CONSTRAINT TRIGGER entries_must_balance
    AFTER INSERT ON entries
    DEFERRABLE INITIALLY DEFERRED
    FOR EACH ROW EXECUTE FUNCTION assert_transaction_balances();

Two details doing real work here.

GROUP BY currency. A naive SUM(amount) over the whole transaction sums across currencies. A transaction with −5,000 NGN and +5,000 USD sums to zero and passes, creating $50 out of naira. Grouping closes that hole. (Real FX needs balancing legs through an FX position account. Later post.)

DEFERRABLE INITIALLY DEFERRED. Without it the check fires after the first entry, when the transaction is legitimately unbalanced. Deferring to commit time means all seven entries land first and the rule is checked at the end.

One cost to be aware of: constraint triggers in Postgres must be row-level, so a seven-entry transaction runs that check seven times. It's bounded by fanout and it's cheap with the index, but it isn't free.

An unbalanced transaction is not an error your code has to handle. It's a state that cannot exist.

Make it append-only for real

Block edits:

CREATE OR REPLACE FUNCTION reject_mutation() RETURNS trigger AS $$
BEGIN
    RAISE EXCEPTION '% on % is not permitted: this table is append-only',
        TG_OP, TG_TABLE_NAME USING ERRCODE = 'restrict_violation';
END;
$$ LANGUAGE plpgsql;

CREATE TRIGGER entries_immutable
    BEFORE UPDATE OR DELETE ON entries
    FOR EACH ROW EXECUTE FUNCTION reject_mutation();

CREATE TRIGGER entries_no_truncate
    BEFORE TRUNCATE ON entries
    FOR EACH STATEMENT EXECUTE FUNCTION reject_mutation();

Note the second trigger. Row-level triggers don't fire on TRUNCATE, so without it, one statement empties your ledger.

And here is the part most posts skip. A trigger is a guardrail, not a guarantee. Whoever owns the table can run ALTER TABLE entries DISABLE TRIGGER ... and walk straight through it. If you're going to argue that application checks are one engineer with psql away from being irrelevant, and I did, above, then you have to hold your own fix to the same standard. The real control is permissions:

REVOKE UPDATE, DELETE, TRUNCATE ON entries FROM app_user;

Run migrations as a different role. And accept that even this stops at your DBA, which is why serious ledgers hash-chain their entries: you can't prevent tampering, but you can make it detectable.

Wrote a bad entry? You don't delete it. You write a reversing entry and both stay visible forever. That's post #11, and it is the eraser rule, enforced by Postgres.

What this does not solve

Being clear about the boundary, because a rule that gets oversold gets ignored:

Sum-to-zero doesn't mean correct. Debit the wrong customer, credit the right merchant: perfectly balanced, completely wrong. Conservation is not accuracy.

Internal consistency isn't external truth. Your ledger can balance to the kobo and still disagree with your partner bank. Reconciliation against the outside world is a separate discipline, and no schema gives it to you.

There are no holds yet. Card and POS flows need authorisations: money committed but not captured, an available balance distinct from a posted one. This model has no concept of a pending entry. That's coming.

Ordering by id is not ordering by commit. A transaction can take entry id 1000 and commit after one that took 1005. So "sum everything after entry N" can permanently miss in-flight rows. That's the trap in post #8's checkpointing, and it's a consequence of a decision made right here in post #1.

"But summing a million rows is slow"

Yes. Eventually.

A few thousand entries with the right index is sub-millisecond and you won't notice. A busy platform account two years in, with tens of millions of fee entries, you will.

The fix is checkpointed snapshots: store the balance as of entry N, then sum only what came after. That's post #8, and the trap above is exactly why it needs its own post.

The ordering is deliberate. Get it correct, then get it fast. The reverse is how you end up back at a mutable column with extra steps.

What ships

Tag v0.1-post-01 has the migration, the schema above, and tests proving that an unbalanced transaction is rejected, that a cross-currency "balanced" transaction is rejected, and that entries cannot be updated, deleted or truncated.

The agent in Ikeja sends her ₦5,000 and it goes through, while the platform account takes a thousand fee entries in the same second. Not because the system got faster. Because nothing in that transaction ever needed to hold her wallet still.

Next post: your wallets are a liability. Account types, why the CBN wrote one into your licence conditions, and why accountants use two columns where I used a minus sign..

References

[1] Helland, P. (2015). Immutability Changes Everything. CIDR 2015; ACM Queue 13(9). https://queue.acm.org/detail.cfm?id=2884038

[2] Uber Engineering (2026). Zero-Sum by Design: 10 Years of Uber's Payments Platform. https://www.uber.com/us/en/blog/ubers-payments-platform/

[3] Uber Engineering (2026). Building High Throughput Payment Account Processing. https://www.uber.com/en-DO/blog/high-throughput-processing/

[4] Ganelin, I. (2024). Ledger: Stripe's system for tracking and validating money movement. Stripe. https://stripe.com/blog/ledger-stripe-system-for-tracking-and-validating-money-movement

[5] Berenson, H., Bernstein, P., Gray, J., Melton, J., O'Neil, E., O'Neil, P. (1995). A Critique of ANSI SQL Isolation Levels. ACM SIGMOD.

[6] PostgreSQL Documentation. Transaction Isolation. https://www.postgresql.org/docs/current/transaction-iso.html

[7] Adyen's accounting database write volume per payment, as summarised in https://www.martinrichards.me/post/ledger_p2_scaling_double_entry_ledger_massive_psp/

[8] Bailis, P., Fekete, A., Franklin, M. J., Ghodsi, A., Hellerstein, J. M., Stoica, I. (2015). Feral Concurrency Control: An Empirical Investigation of Modern Application Integrity. ACM SIGMOD. https://doi.org/10.1145/2723372.2737784

#1 of 12 in Building a Ledger, a double-entry ledger engine in Go. Code: https://github.com/Helewud/kobo

Cover photo by Ali Mkumbwa on Unsplash

DEV Community: Elewude Okikijesu

Your wallets are a liability

Your wallets are a liability

The founder on the call

Nobody tells you which rows to write

What is −5,000?

Five kinds of account

Your wallets are a liability

What the regulator actually says

Why those conditions exist

Why the branch closes at 4pm

Reading the sign

Three transactions

Where money enters

The system account

What it costs

Starting from nothing

One query for the whole business

Why accountants use two columns

The schema

Rollups, and why parent_id is there

What this does not solve

What ships

References

balance is a summary, not a fact. In this post, I break down the 5 major failure modes of storing wallet balances in a single column and show how to enforce zero-sum invariants directly in Postgres.

Your wallet balance shouldn't be a column

[Boost]

Your wallet balance shouldn't be a column

Your wallet balance shouldn't be a column

Your wallet balance shouldn't be a column

The line everybody writes

Failure one: the lost update

Failure two: you cannot answer "why?"

Failure three: money can be created and destroyed

Failure four: corruption is permanent

Failure five: the hot row

The fee split: where this gets ugly

"Just use a queue"

How the big processors actually handle it

On "correctness over efficiency"

The fix: derive the balance

The schema

Put the invariant in the database

Make it append-only for real

What this does not solve

"But summing a million rows is slow"

What ships

References

The `system` account

Rollups, and why `parent_id` is there