We assume here that the ledger service is running as part of the Formance Platform. If you are running it standalone from source, you will need to adapt the instructions accordingly.
Getting started
Hello, world
Learn how Formance Ledger works, by creating your first accounts and transactions to track money movements.
Complex transactions
Understand how to use Numscript to track complex money movements, reconcile accounts, and more in this series of focused tutorials.
Product Ledger vs General Ledger
When discussing “double-entry” accounting, two distinct concepts are often conflated:-
Transaction Model (Mathematical): Refers to the technical aspects of how transactions are recorded:
- A transaction always involves ≥2 accounts in compensating directions
- Account balances are derived from an immutable log of transactions
-
Accounting Business Rules: Refers to accounting conventions:
- Classification of accounts (assets, liabilities, equity)
- The balancing imposed by the accounting equation
- Debit/credit nomenclature and conventions
| Ledger Type | Purpose |
|---|---|
| General Ledger (GL) | Organizes financial events to produce clarity on the financial position of a business. Typically exists in an ERP (Sage) or GL-specific tool (QuickBooks). |
| Product Ledger | Provides a technological foundation for automated flow of funds. Focuses on scarcity, rivalrousness, concurrency, auditability, immutability, and performance. |
Data Immutability
The Ledger ensures immutability by chaining transaction logs with each other, similar to a blockchain mechanism. Each transaction produces a hash — a fixed-length string generated from the transaction data. Hashing works in one direction only: for a given piece of data, you’ll always get the same hash, but you can’t reverse a hash back to its original data. The first transaction comes with a hash made from its data. Each subsequent transaction produces a hash from its own data combined with the previous hash, creating a tamper-evident chain. This ensures the ledger remains a permanent, indelible, and unalterable history of transactions.Log hashing can be disabled for performance if tamper-evidence is not required for your use case. See Data isolation with buckets for configuration options.
Ledger data model
A ledger exposes and contains the following resources:| Accounts | Transactions |
|---|---|
| Containers for assets, see Accounts | Movement of assets between accounts, see Transactions |
NEW_TRANSACTIONSET_METADATA
Naming your ledger
The name of your ledger is an alphanumeric string. It is used to identify your ledger in all operations, and is also used by the storage layer to create segregated locations for your ledger data. Good names are short, descriptive, and unique and depend on both your application and your single vs multi-ledger strategy. A good generic name for a single ledger strategy ismain.
Single ledger vs multi-ledger
Formance Ledger is a multi-ledger ledger. Behind the fanciness of that statement, lies the simple meaning that you can operate multiple individual ledgers in a single instance of the Formance Ledger service. Each ledger is completely independent of the others, and can be used for different purposes. At some point, you will want to decide between a single ledger and a multi-ledger strategy. This decision is based on the opportunity for trade-offs your application has. The main benefit of a multi-ledger strategy is the leverage you get from it in term of horizontal scaling, as the locking on write is scoped by ledger. Good candidates for a multi-ledger strategy include:- Applications with multi-tenancy and no data sharing between tenants (e.g. you are a PSP and want to isolate merchants from each other)
- Applications with a high write volume and where data segregation is possible