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.

​
Ledger data model

A ledger exposes and contains the following resources:
AccountsTransactions
Containers for assets, see AccountsMovement of assets between accounts, see Transactions
Beneath these resources lie the immutable log of all operations performed on the ledger. This log is the primary source of truth for the ledger, and is used to construct the state of accounts and transactions. It contains entries of the following types:
  • NEW_TRANSACTION
  • SET_METADATA
One thing to keep in mind is that all the resources listed above are fully logically separated by ledger. This means that you can have e.g. two ledgers with the same account name, and they will not interfere with each other.

​
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 is main.

​
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
The main benefit of a single ledger strategy is the simplicity of it. You don’t have to worry about whether an account exists in a ledger or not, and you don’t have to resort to distributed transactions to ensure data consistency if you want at some point to perform cross-ledger transactions.

​
Getting help

Need help or have a technical question that isn’t covered in our docs? Check out our GitHub Discussions to ask questions and get help from the Formance team and community.