Spin up your first ledger in minutes
Explore the Formance Ledger on GitHub to run the demo and spin up your first ledger in minutes.
Architecture, use cases, and when you actually need one
A ledger database is the financial system of record for money in motion. It's month-end close, and the sum of your internal user balances is thousands of dollars short of what your omnibus account (the single omnibus or FBO account holding funds for all of your customers) contains.
A ledger database makes reconciliation gaps structurally impossible because balances are derived from an append-only posting history so that teams can query finances at any past moment for auditable, real-time balances across customer funds and digital assets.
A ledger database is an append-only, cryptographically verifiable data store in which every state change is recorded as a new posting and balances are derived from the posting history.
Some ledger database architectures pair a journal, a sequence of blocks each cryptographically chained to the previous one, with an indexed, directly queryable current state.
A ledger database separates itself from adjacent systems by enforcing double-entry accounting and immutability while keeping the balance state queryable as a database primitive.
A relational database can be designed for append-only behavior, but that usually takes compensating infrastructure: separate journal tables, triggers, audit pipelines, and team-wide restraint from ever running UPDATE on a posting table.
An event store shares the immutable-log philosophy (double-entry accounting is, structurally, an event-sourced system). General event stores may leave ledger-specific invariants, such as balanced writes, unenforced, treat hash-chaining as optional hardening, and require event replay to rebuild the current state, with no directly exposed current-state primitive.
A ledger database is an operational system of record for money in motion because it tracks scarcity and concurrency in real time as funds move. The core ledger feeds the corporate general ledger accounting system, which closes the books at month-end and builds the record.
In a standard database schema, treating UPDATE and DELETE as routine operations can destroy the state history on which reconciliation depends unless that history is preserved separately.
When a balance is stored as a mutable field, overwriting it discards the sequence of movements that produced the number. If the balance is ever wrong, there is no way to reconstruct how it got that way, and no way to answer "what was this account's balance on March 5?" Auditors are left piecing together the state from mutable rows and backup snapshots.
State drift across services compounds the problem. When multiple services write to shared tables with no central system of record for balance state, partial failures across independently updated systems can leave records inconsistent.
A payment that commits the UPDATE balance but not the INSERT into the transaction log produces a discrepancy that is invisible until reconciliation runs, often weeks later at close.
Knight Capital Group shows what happens when financial state mutates without structural controls. On August 1, 2012, a deployment to Knight's order router missed one of eight servers. A repurposed flag on that server activated dead "Power Peg" code that had been dormant for years. Because a cumulative-quantity check had been moved, the server sent child orders continuously.
The system routed millions of erroneous orders into the market in just 45 minutes, resulting in massive unintended positions that Knight could only resolve at a loss of more than $460 million.
Despite dozens of automated warnings arriving immediately, no action was taken until the damage was done. The incident led to the SEC's first market-access enforcement action, resulting in an additional $12 million penalty for the firm.
The structural lesson here also applies to ledgers. Without storage-layer constraints on financial-state mutation, a single defective code path can move real money at machine speed.
A ledger database earns its role through storage-layer guarantees for append-only immutability, double-entry enforcement, bi-temporal modeling, and idempotency keys.
Append-only immutability means every posting is written once and never modified, with a hash chain making any retroactive edit detectable. Each transaction includes a hash computed from its own data and the previous transaction's hash, so any retroactive change to a historical record invalidates every hash after it.
A hash chain makes retroactive modifications evident because any change to a block alters the digest recorded by the following block.
Enforcing the zero-sum constraint, every debit matched by an equal credit, in the database itself, eliminates a class of balance errors that application-level validation cannot catch under concurrency.
Lost updates expose the failure mode of miscalculated finances. If an account holds $600, request A reads $600 and writes $100 after a $500 withdrawal, but request B reads $600 before A commits and writes $300 after a $300 withdrawal. B's write overwrites A.
Both requests passed their application-layer balance check. An application-level balance check can be stale by the time the transaction executes. When the constraint lives in the storage layer, a multi-row journal entry commits or fails as a single atomic unit, and no interleaving of concurrent writes can cause an unbalanced posting.
Bi-temporality tracks two independent time axes: when an event was effective in the real world, and when the system recorded it. This two-axis model matters the first time a correction arrives late.
An ACH return for a $5,000 credit posted March 3 arrives on March 8; you record it on March 8 with an effective date of March 3. Asked "what was the balance on March 5?", the ledger answers correctly, $5,000 lower than the naive view, without rewriting the original posting. Corrections follow the same rule but in reverse via a new posting, and are never mutated.
Late-arriving corrections make native bi-temporality necessary. Application-layer effective-date conventions can break down when it matters most, such as under concurrent writes or when a correction arrives after a dependent action has already run on the wrong data.
Idempotency keys enforced at the storage layer ensure that a retried request produces a single posting. Idempotency keys detect duplicate deliveries and return the stored result when the same key is reused for the same request, and the key remains valid.
Retried calls are a common production source of real-money duplication in payment systems spanning multiple rails, and double-entry still enables it. Duplicated transaction postings are clearly labeled with each posting's balance; the trial balance still ties to zero; and cash can be overstated. One common implementation is to commit a deduplication record in the same transaction as the posting it protects.
A ledger sits on one side of what we call the authorization boundary: a recording mode that logs transactions from an upstream system that are approved, and the authorizing mode that gates fund movement by rejecting postings that would violate a balance constraint. The two positions demand different guarantees.
In recording mode, the ledger is a passive, downstream system. An external payment processor or risk engine makes the authorization decision, and the ledger stores the approved transaction as an immutable record. Completeness and immutability of the history are enforced. In that setup, the ledger is typically best understood as an append-only audit log of approved operations.
In authorizing mode, the ledger gates fund movement. It reads the available balance, evaluates whether the proposed transaction violates a constraint, and either rejects it or records it, all in a single serializable operation before any real money moves.
Authorizing mode requires two-phase transfers, idempotency keys for every authorization, and balance reads from the ledger itself, since cached copies may be stale.
Mixed-mode operation is when a recording-mode ledger is leaned on as an authorization gate without authorization-grade concurrency control, which can create duplicate-spend bugs.
A check-then-act race follows a common pattern: two requests read a $10,000 balance simultaneously, both approve a $500 spend, and the wallet lands at $0 or negative. A subtler variant, write skew, appears when two transactions write different rows and each fails to observe the other's write.
Together, the two races violate a cross-row constraint that neither would violate alone, and not even snapshot isolation can prevent it. Serializable isolation with retry on serialization failure, or explicit row locking, has to be a deliberate design choice.
Ledger databases anchor three production workloads: omnibus wallet balances, regulatory reporting, and continuous reconciliation against external rails.
In an omnibus model, one external account backs thousands of individual balances that exist only in your internal records. Every deposit and withdrawal is posted as an immutable double-entry transaction, and posting history determines the authoritative user balance.
The accounts are the platform's omnibus/FBO bank boundary @platform:banks:chase:main and Alice's wallet @users:alice:wallet. Cash moves from the named bank boundary to Alice's wallet.
Crediting Alice's wallet $1000 from the platform's omnibus bank account is a single posting, expressed as intent in Numscript. In Numscript language, Formance's purpose-built language for describing financial transactions:
// WALLET_TOPUP
// Event: Alice funds her wallet; cash enters via the platform's omnibus bank account
send [USD/2 100000] (
source = @platform:banks:chase:main allowing unbounded overdraft
destination = @users:alice:wallet
)
set_tx_meta("event_type", "wallet_topup")
set_tx_meta("topup_id", "tpu001")
USD/2 100000 is 100,000 cents. The named bank boundary is allowed to run negative so that it can be reconciled against the bank statement. The posting moves $1000 from the platform bank boundary to Alice's wallet atomically, and her balance is the sum of all postings that have ever touched @users:alice:wallet.
Ledger databases also support regulatory reporting against safeguarding, reserve, and controls-evidence obligations. The UK's FCA CASS 15 regime requires internal safeguarding reconciliation at least once each reconciliation day. MiCA imposes reserve-of-assets obligations on certain token issuers, and SOC 2 Type II readiness also benefits from evidence that controls operated over an operating period.
Ledger databases also help hold a continuous reconciliation invariant against external rails. For an omnibus model, the sum of internal wallet balances should equal the funds actually held in the external omnibus account.
At the transaction level, a ledger database pairs each posting against the payment rail's settlement data, so drift is localized to a specific transaction. A ledger-centered reconciliation architecture supports transaction-level reconciliation.
You need a ledger database when your standard database has reached its limit, and the ledger is evaluated against the five properties.
Your standard database has reached its limit when any of these four things happen:
A well-structured relational database with append-only tables and application-level double-entry can serve a single-asset, single-provider system with no regulatory obligation and no multi-party reconciliation requirement.
Confirm each of these in any ledger database you evaluate, at the layer where it claims to be enforced:
The deployment model deserves the same scrutiny as the feature set. Regulated entities that require data-sovereignty controls may prefer self-hosted deployment over a cloud-only managed service.
Formance Ledger enforces the five properties at the storage layer, with both effective and recorded timestamps indexed independently and queryable. Formance also supports Enterprise Self-Hosted deployment for teams with data-sovereignty requirements, and the MIT-licensed core means the implementation is open for your engineers to read.