Formance Ledger

Formance Ledger is a programmable financial core ledger designed to be the accounting backbone of modern fintech applications. Built in Go and backed by PostgreSQL, it provides atomic multi-posting transactions, account-based asset modeling, and a powerful domain-specific language called Numscript that lets developers encode complex financial rules without building fragile imperative logic.

Unlike generic databases or simple accounting libraries, Formance Ledger treats money movement as a first-class concern. Every transaction is recorded as a series of postings that move assets between named accounts, with full idempotency guarantees and immutable audit logs. The ledger enforces double-entry bookkeeping at the database level, making it impossible to create money or lose track of balances — a critical requirement for regulated fintech applications.

The platform is designed to fit into a microservices architecture. It ships as a standalone binary or Docker image and can be deployed as a dedicated service behind an HTTP/REST API. It also supports a Kubernetes operator deployment mode for production workloads. A built-in replication pipeline allows ledger logs to be shipped to OLAP data stores such as ClickHouse or Elasticsearch for analytics, without compromising the transactional source of truth.

Formance Ledger is the core of the broader Formance Platform, which adds payment orchestration, webhooks, and developer tooling — but the ledger works equally well as a standalone microservice for teams building custom financial infrastructure from scratch.

What You Get

• REST API with versioned endpoints — Full HTTP/REST API (v1 and v2) with OpenAPI spec included, enabling any language or framework to interact with the ledger
• Numscript DSL — A purpose-built domain-specific language for expressing financial transactions, allocations, and balance constraints as declarative scripts rather than raw SQL
• Atomic multi-posting transactions — Create transactions with multiple source and destination account postings in a single atomic operation, with automatic balance validation
• Account-based asset modeling — Hierarchical, named accounts (e.g., users:1234, fees:gateway) allow fine-grained ownership tracking of any asset denomination
• Immutable audit log — Every transaction is appended to an immutable log with idempotency keys, making the ledger tamper-evident and audit-ready
• Chart of Accounts support — Define account schemas with metadata rules and default configurations to enforce consistency across all accounts in a ledger
• OLAP replication pipeline — Built-in log shipping to ClickHouse, Elasticsearch, HTTP endpoints, or Kafka for real-time analytics without touching the transactional database
• Multi-ledger namespacing — Create isolated ledger namespaces per tenant, product line, or environment within a single deployment
• Docker and Kubernetes deployment — Ships as a Docker image with a docker-compose quickstart and an official Kubernetes operator for production-grade deployments
• OpenTelemetry instrumentation — Built-in metrics and distributed tracing via OpenTelemetry for observability in production environments

Common Use Cases

• User wallet systems — Track per-user balances for funds held in FBO (For Benefit Of) accounts with full audit history and atomic credit/debit operations
• Payment processing pipelines — Model funds moving through acquiring, processing, fee deduction, and payout stages as a series of ledger postings with guaranteed consistency
• Digital asset platforms — Represent multiple asset denominations (USD, EUR, crypto tokens) in a single ledger with asset-aware balance queries and aggregated volume reporting
• Loan and credit management — Structure principal, interest accrual, repayments, and write-offs as named account movements with full transaction history for regulatory reporting
• Marketplace escrow and settlements — Hold funds in escrow accounts, release on conditions, and distribute to sellers and platform fees in atomic multi-posting transactions
• Subscription billing and revenue recognition — Record deferred revenue, recognize income over time, and generate accurate balance sheet entries programmatically via Numscript
• Internal transfer and treasury — Manage intercompany transfers, currency conversion entries, and treasury float with a programmable, auditable double-entry system

Under The Hood

Architecture: Formance Ledger follows a clean microservices pattern with a server process (API) and a separate worker process for background tasks such as bucket cleanup and replication pipelines. The internal package structure separates concerns clearly: the internal/ directory contains the core domain model (accounts, transactions, postings, logs), the controller layer, storage adapters, the Numscript virtual machine, and the replication subsystem. The server is built on go-chi for HTTP routing with CORS support, and uses Uber’s fx dependency injection framework for modular wiring.

Tech Stack: The project is written in Go and targets PostgreSQL as its primary transactional datastore via the uptrace/bun ORM and jackc/pgx driver. Numscript is compiled using an ANTLR-generated parser (antlr/antlr4) and executed by a custom virtual machine in internal/machine/vm/. Background message publishing uses Watermill for event-driven fan-out. Replication drivers exist for ClickHouse (ClickHouse/clickhouse-go), Elasticsearch (olivere/elastic), HTTP, Kafka via NATS (nats-io/nats.go), and stdout. OpenTelemetry (go.opentelemetry.io/otel) is wired for both metrics and tracing.

Code Quality: The codebase has strong test coverage using Ginkgo/Gomega BDD-style tests and includes generated test scaffolding via go:generate directives. Integration tests use ory/dockertest to spin up real PostgreSQL containers. The project maintains separate test files per major component (accounts, transactions, balances, moves, volumes), uses go.uber.org/mock for interface mocking, and includes a dedicated test/ directory with test server utilities. Code generation is used for storage layer mocks and driver factory boilerplate, reducing human error in repetitive patterns.

What Makes It Unique: The Numscript DSL is the standout differentiator — it allows engineers to encode financial rules (allocations, overdraft controls, asset routing) as scripts that the ledger evaluates atomically against live balances at transaction time, catching constraint violations before they reach the database. Combined with the multi-ledger namespacing, OLAP replication pipeline, and schema-level Chart of Accounts enforcement, Formance Ledger provides a level of financial modeling sophistication that generic databases or simple accounting libraries cannot match. The project maintains parallel stable release lines (v2.2, v2.3, v2.4) with frequent patch releases, indicating mature operational discipline.

Self-Hosting

Formance offers enterprise support through the Formance Platform, which wraps the open source ledger with payment orchestration, a management console, hosted cloud options, and commercial SLAs. The Kubernetes operator deployment mode — required for production use per the official documentation — is open source and available at github.com/formancehq/operator. Enterprise users get access to the Formance Cloud (managed), priority support, and integration assistance. Community support is provided through GitHub Discussions.