formancehq/ledger v3: A Distributed Core Ledger on Raft and Pebble

The consistency problem addressed by formancehq/ledger v3

formancehq/ledger targets systems that must record financial movements consistently while accepting requests through more than one service node. The repository describes it as the programmable open source core ledger for fintech, which places it below customer-facing banking products and closer to the accounting engine those products call. Its intended users are backend teams that need repeatable transaction rules, retries that do not accidentally apply a posting twice, and consistent state across nodes.

The central problem is not simply storing debit and credit records. Several ledger nodes must agree on an accepted transaction, and that agreement must remain consistent when a client retries a request or sends several transactions as one batch. The repository identifies Numscript transaction scripting, idempotency keys, bulk operations, and atomic handling within a single Raft group as mechanisms for those cases. Those features make the project relevant to fintech backends that need transaction semantics rather than a generic key-value store.

The implementation is written in Go, and the module path is github.com/formancehq/ledger/v3. The repository also includes a ledgerctl command, an OpenAPI file, operational documentation, deployment documentation, tests, protobuf sources, and container build files. This layout suggests a deployable service with a supporting client and a documented interface surface. The README does not describe accounting models, balance guarantees, currency handling, or reconciliation, so those details should not be inferred from the project name alone.

One Raft group and the Pebble state-machine path

Ledger v3 uses a single Raft group to manage all ledgers and their transactions. That is the defining architectural choice. The README emphasizes the single group, and the architecture diagram shows every node running an FSM for all ledgers, with a Pebble store beneath it.

A request reaches a client-facing interface over HTTP REST, gRPC, or ledgerctl. The architecture places HTTP on port 9000 and gRPC on port 8888. Accepted state changes then pass through the cluster's Raft protocol. The FSM applies agreed changes to the local Pebble store, an LSM-tree storage engine from CockroachDB implemented as a Go package in go.mod. Because all ledger state participates in one consensus group, the design supports cluster-wide atomic operations as described by the project.

This design avoids managing an independent consensus group for each ledger, which simplifies the topology described in the README. It also creates a clear shared failure and coordination boundary. The documentation does not state the Raft snapshot policy, membership-change procedure, recovery procedure, maximum transaction size, or partitioning behavior. Those operational details must come from docs/ops/deployment.md rather than assumptions based on etcd/raft itself.

Numscript, idempotency, signing, and observability boundaries

Numscript is the project's transaction programming layer. The README states that Ledger v3 supports Numscript transaction scripting, while go.mod includes github.com/formancehq/numscript v0.2.0 with references to a compiler and virtual machine. The documentation does not include Numscript syntax, an example transaction, or rules for account creation, so a valid posting cannot be reproduced from the repository description alone.

Idempotency has a more concrete operational role. The feature list says the ledger has built-in idempotency-key support for safe retries. That is useful for clients that cannot determine whether a timed-out request reached a node before trying again. Bulk operations similarly address workloads that need several transactions in one request. The README claims atomic operations through the single Raft architecture, but it does not define the bulk payload schema or whether every bulk transaction has its own idempotency key. Those are interface questions that need answers from openapi.yml or the technical documentation.

Request signing uses Ed25519 for authenticity and integrity. The README does not document key generation, rotation, header names, verification failures, or replay handling, so the signing feature should not be treated as a complete security procedure without those details. Observability is broader: OpenTelemetry covers traces, metrics, and logs, while Pyroscope supplies profiling. Generated Grafana dashboards are also referenced by the justfile. This is a substantial telemetry surface, but it does not by itself document retention, sampling, authentication, alert thresholds, or backup monitoring.

Running the first Ledger v3 node

The README defines a source-development quick start rather than a general-purpose binary installation. It requires Go 1.27 or later, Just, and Nix with Flakes enabled. The .envrc repository file is relevant because the documented first step authorizes the directory through direnv. The README does not provide a standalone download URL, package-manager command, or release artifact installation procedure.

Authorize the repository environment the first time. The README says this is a first-time-only setup step and that it operates through direnv.

direnv allow

After the environment is allowed, the documented command starts one node through the repository's Just automation.

just run

The architecture diagram lists HTTP on port 9000 and gRPC on port 8888 for each node. Those are the first interfaces to check when the process starts, although the README does not supply a health endpoint or an API request that can verify readiness. A successful process launch should not be confused with successful Numscript execution.

For development checks, the README and justfile expose separate targets for building, unit tests, end-to-end tests, generated protobuf code, and pre-commit checks.

just build
just test
just test-e2e
just generate-proto
just pre-commit

`just build` builds the application, `just test` runs tests, and `just test-e2e` invokes the end-to-end suite. `just generate-proto` regenerates protobuf code. The `pre-commit` recipe expands to several generation, testing, tidying, lint, and dashboard-related checks rather than acting as a single lightweight check. Contributors should therefore expect code generation and repository-wide validation to add time to the maintenance cycle.

Trade-offs in the single-group ledger design

The clearest limitation is architectural concentration. Every ledger and transaction is managed by one Raft group. The README presents this as a benefit because it simplifies operations and enables atomic operations, but the same boundary means cluster coordination is not partitioned per ledger. The documentation does not provide workload figures, cluster-size limits, or behavior under member failure, so it cannot establish whether the model meets a particular isolation or throughput requirement.

Ledger v3 is also not documented as a lightweight embedded accounting library. Running a node involves a consensus-oriented service, client interfaces, persistent Pebble storage, telemetry, and potentially cluster deployment. A team that needs only a simple local balance calculation may find that the deployment boundary is larger than necessary. Conversely, replacing the project with ordinary database transactions would not reproduce the documented Raft replication, Numscript layer, Ed25519 request signing, or ledger-specific idempotency behavior.

There is also version risk. Recent release information includes v3.0.0-beta.10, v3.0.0-rc.1, and a nightly release. These names identify prerelease or continuously produced builds, not a stable v3 tag. The repository was not archived, and the last push was on 2026-10-16. That is evidence of recent repository activity, but it does not establish compatibility or release stability. Upgrade procedures and migration notes are not present in the README.

The license is listed as unknown in the repository metadata. The repository therefore does not provide enough licensing detail in the available documentation for an adoption decision. Users must inspect the repository's actual license files and terms before redistribution or commercial deployment.

Container deployment and upgrade work in formancehq/ledger

The Dockerfile builds two Go binaries, `ledger-server` and `ledgerctl`, from the repository source. It uses a Go Alpine build stage, disables CGO, copies the server and CLI into an Alpine runtime image, installs shell completion for Bash, and sets the server as the image entrypoint. That layout is useful for teams that already build and scan container images, but the repository does not publish a prebuilt image name, tag policy, image registry, or Kubernetes manifest in the README.

The README points cluster deployment and Kubernetes users to docs/ops/deployment.md. It also identifies backup, monitoring, and CLI documentation as part of the operations section. Those subjects are exactly what an adoption review needs for a replicated ledger, and the existence of the guide is useful, but its procedures are not included in the README.

Upgrade cost appears tied to generated code and a broad validation pipeline. The justfile includes protobuf generation, RPC authentication generator tests, operator generation, dashboard generation and tests, module tidying, linting, and Go tests. Projects embedding or contributing to Ledger v3 may need to account for generated artifacts and dependent Go modules when changing interfaces. The repository's last push was on 2026-10-16, while the listed v3 release candidates and betas still call for explicit compatibility review.

Editorial conclusion

Adopt formancehq/ledger v3 when a fintech engineering team needs a programmable, replicated core ledger and can accept the operational boundary of one cluster-wide Raft group. Do not choose it solely as a stable general-purpose production dependency while v3 remains represented by beta and release candidate builds. Verify first that your Go, Just, and Nix toolchain matches the README prerequisites, then inspect the deployment guide for cluster, backup, and upgrade procedures before accepting writes.

Frequently asked questions

Official sources

1. formancehq/ledger on GitHub
2. Issues
3. Project website
4. README
5. Releases