Formance Ledger Documentation

Formance Ledger is a programmable financial core ledger designed for money-moving applications. It provides:

• Atomic multi-postings transactions system: Ensures complex financial movements are processed reliably.
• Account-based modeling: Manages balances and ownership of assets.
• Programmability: Uses numscript, a built-in Domain Specific Language (DSL), to model financial transactions.
• Storage: Uses PostgreSQL as the primary transactional storage layer and includes mechanisms to ship logs to replica data stores for OLAP-optimized querying.

It is suitable for user balance holding apps, digital asset exchanges, payment systems, and loan management systems.

When retrieving balances, you can use two different pagination strategies:

1. Cursor-based pagination (Cursor): Use this for navigating through pages. Set Cursor to the value of next to get the next page, or previous to get the previous page. Note that when using Cursor, no other parameters (like PageSize or After) can be set. The maximum page size is 1000.
2. Address-based pagination (After): Use the After parameter to return accounts appearing after a specific address in descending order.

Many list-based API endpoints in the Ledger V2 API use a cursor-based pagination pattern. Responses include a cursor object that manages the state of the iteration.

To navigate through paginated results, check the hasMore boolean. If true, use the next string value in subsequent requests to fetch the next page. The previous string can be used to navigate backwards if supported by the endpoint.

{
  "cursor": {
    "pageSize": 15,
    "hasMore": false,
    "previous": "YXVsdCBhbmQgYSBtYXhpbXVtIG1heF9yZXN1bHRzLol=",
    "next": "aW0gdmVuaWFtLCBxdWlzIG5vc3RydWQ=",
    "data": [
      {
        "driver": "string",
        "config": {},
        "id": "string",
        "createdAt": "2019-08-24T14:15:22Z"
      }
    ]
  }
}

Because V2LogDataDeleteMetadataTargetID is a union type, you must use the Type field to discriminate between the active variant. Once the type is identified, you can safely access the corresponding field (Str for strings or Bigint for big integers).

switch v2LogDataDeleteMetadataTargetID.Type {
	case components.V2LogDataDeleteMetadataTargetIDTypeStr:
		// v2LogDataDeleteMetadataTargetID.Str is populated
	case components.V2LogDataDeleteMetadataTargetIDTypeBigint:
		// v2LogDataDeleteMetadataTargetID.Bigint is populated
}

To navigate through large lists of accounts, use the Cursor field.

Important Constraints:

• When using Cursor, the maximum PageSize is restricted to 15.
• To fetch the next page, set Cursor to the value of next provided in the previous response.
• To fetch the previous page, set Cursor to the value of previous provided in the previous response.
• No other parameters (such as Sort or PageSize) can be set when Cursor is provided.

The V2LogData object represents the payload of a log entry. Because it is a union type, its internal structure depends on the value of the Type field. You must check the Type to know which specific data variant is populated.

Supported log types and their corresponding data structures:

• NEW_TRANSACTION: Uses V2LogDataNewTransaction
• SET_METADATA: Uses V2LogDataSetMetadata
• REVERTED_TRANSACTION: Uses V2LogDataRevertedTransaction
• DELETE_METADATA: Uses V2LogDataDeleteMetadata
• INSERTED_SCHEMA: Uses V2LogDataInsertedSchema

The Formance Machine Instruction Set is a low-level set of operations used to define transactional logic within the ledger. It includes instructions for state management (loading addresses, getting balances), stack manipulation (IPUSH, MPUSH, RPUSH), arithmetic (IADD, ISUB, etc.), and transaction lifecycle management (TXSTART, SEND, COMMIT).

INIT
LOAD address
BEGIN
BALANCE asset, address
IPUSH value
MPUSH value
RPUSH value
GET register
SET register
IADD
ISUB
IMUL
MADD
MSUB
RMUL
RDD
RSUB
TXSTART size
TXEND
SEND source, destination, value
FLUSH
COMMIT
ABORT