All posts

Field notes

Why escrow belongs in the database, not the app layer

AO
Aaron Ontoyin
2 min read

Money movement that can only be described in application code is money movement that can be bypassed. Here is how we push exactly-once escrow down to where it cannot be argued with.

Most platforms that move money describe the rules in application code. A service checks a balance, decides a transfer is allowed, and writes two rows. It works — until a retry fires twice, a deploy races a request, or a well-meaning script updates a row by hand. The rules were only ever a suggestion, because the layer that enforced them was the same layer that could be bypassed.

On Nnarksup, escrow is the substrate. It has to hold under adversarial conditions, so we moved the guarantees down to where they cannot be argued with: the database.

Append-only, by construction

Ledger entries are written once and never overwritten. There is no UPDATE path on a settled ledger row — history accumulates instead of being edited in place. When a milestone locks funds, that is a new entry. When it releases them, that is another. The past is not a mutable field; it is a record.

This is enforced at the database level, not in a service that "promises" to behave. A privileged path that quietly rewrites a balance simply does not exist, so the audit trail is tamper-evident because of how the system is built.

Exactly-once money movement

The dangerous class of bug in payments is the double-move: the same release applied twice because a request was retried. We make each money movement idempotent at the point it is committed. A release either happens once and is recorded, or it is rejected — there is no in-between where a retry silently duplicates it.

That property is worth more than any amount of careful application code, because it holds even when the application misbehaves.

Reconciled to real custody

A ledger is only trustworthy if it corresponds to money that actually exists. Escrow balances on Nnarksup tie back to funds held at partner banks and payment institutions. The ledger is not a number in a field we control; it reflects real custodied money that reconciles. Nnarksup never touches the money itself — it instructs the custodian and records the truth.

Why this matters to you

You never see any of this. What you see is a deal that behaves the same way every time: funds lock against a milestone, they release only when delivery is proven, and every party looks at the same immutable history. The boring reliability is the product. The database is where we earned it.