Programmable Ledger and Payment Rule Processing

This programmable ledger case study looks at ordered writes, versioned rules and a history that can be checked.

Payment splits can be written as versioned programs, and this programmable ledger loads each one when a transaction is recorded. It runs each program beside direct account postings. That lets an application state the exact allocation it intends, rather than leaving it to guesswork.

One service owns write ordering, storage and the repeated-request reply.

The challenge

A retry may reach a different node after the cluster changes leader, yet it still needs the earlier result. Each node must also agree on the program's decision. Incoming and outgoing amounts then have to balance before any storage change is written.

What we built

Programs can be supplied inside a request or picked from a versioned library on the server. They express splits and multi-stage distributions. The ledger supports asset types and reversals, and every transaction reference it records stays unique. Account types restrict which operations can run.

Indexed views expose the accounts and transactions, along with logs and running volumes for each. A read-consistency choice sets the freshness an application needs.

Prepare the read set, then order the write

Followers forward their writes to the leader. A Raft group fixes the order of those writes, and each node applies them through a deterministic state machine.

Before a proposal joins that order, admission finds and loads the records it will need. Execution may then read only those declared keys. A stale proposal is rejected when its prepared position no longer matches the actual log position. That agreement must survive later changes to either step.

Save retry decisions with their expiry

Each request arrives with its own hash, which the state machine checks against the result stored under its retry key. Matching hashes return the recorded result. When the hashes differ, the caller gets a conflict instead, and any recorded failure is kept.

Expiry comes from the committed policy at write time and is stored with the outcome. Nodes never read local settings to decide it. A transaction reference stays unique within a ledger, so it outlives the shorter retry key.

Check conservation before storage changes

The ledger stores volumes as unsigned 256-bit integers. Before it writes anything, the engine checks that the total input and output changes agree. It then saves the volumes, the log and the audit record in one storage batch. Hash-linked audit entries chain the records together. Replay checks then support a later look back into the stored projections when needed.

Operators manage the storage, snapshots and backups. All ledgers share one write-ordering group, so they also share its capacity. Customer-facing accounting and reporting stay in the surrounding product.

Project success

An application can select a payment rule version and inspect the allocation it produced. The retry key stays valid for a time. While that key is valid, a repeated request recovers its own recorded success or failure. Ordered logs and replay checks reveal the outcome. At no point does inspecting it rerun the payment as a brand-new operation.

Technology stack

Language and services

Go, gRPC, chi

Consensus

etcd Raft

Embedded storage

Pebble LSM

Component wiring

Uber fx

Integrity hashing

BLAKE3, XXH3