Note: This post is the third chapter of a broader technical paper on How to Scale a Ledger.
A Transaction Model
Some ledger systems stop with just Accounts and Entries. We already have a way to store an immutable history of balance changes with the first two models. However, a robust ledger system should also have a Transaction model to enable atomic movement of money between Accounts and enforce double-entry rules.
Consider a simple transfer of money between two digital wallets, one owned by Alice and one by Bob. If Bob sends Alice $10, we can represent that transfer as two Entries.
bob_entry was successfully created, but
alice_entry failed to create (maybe the database was having network issues). Now the ledger is in an inconsistent state—Bob was debited money, but Alice didn’t get anything.
Transactions solve this consistency problem by allowing us to specify groups of Entries that either must all succeed or all fail. In order to guarantee atomicity, all the non-discarded Entries on a Transaction must share the status of the Transaction. This ensures that all Entries progress in status at the same time, all-or-nothing.
A Ledger API should only allow clients to directly create Transactions, not Entries. This limitation helps ensure clients don’t run into consistency problems. That means a Ledger API must manage creating Entries itself. There are three operations to implement, corresponding to the possible states of the Transaction.
Creating a Pending Transaction
This is generally the first step in the lifecycle of a Transaction. We simply need to persist the Entries.
Posting a Pending Transaction
Since Entries are immutable, when we move a Transaction from pending to posted, we need to discard and then create new Entries.
2. Create posted Entries.
Archive a Pending Transaction
Posted Transactions are immutable, and so cannot be archived. Pending Transactions can be archived, following a similar process to posting.
2. Create archived entries.
This is the third chapter of a broader technical paper with a more comprehensive overview of the importance of solid ledgering and the amount of investment it takes to get right. If you want to learn more, download the paper, or get in touch.
Read the rest of the series:
Subscribe to Journal updates
Discover product features and get primers on the payments industry.