Ledger Setup and Operations - Overview

Setting up and running the ledger for a given institution happens across three distinct layers, each responsible for a different part of how it actually functions: the service layer defines what's possible and enforced universally, the product layer decides how a specific product's accounts and wallets are structured and which ledger provider(s) they use, and the operator layer is where day-to-day visibility and manual intervention happen. This article walks through each layer in turn.

Service Layer: Predefined Rules

At the service level (cac-ledger-svc), the ledger exposes a catalog of predefined rules — pre-configured behavior available for immediate use without writing custom code. Each rule is a simple toggle, and some expose a single parameter (a numeric threshold); the scripting underneath is hidden from the person configuring it.

The available rules fall into a few natural groups:

Balance limits

• Minimum wallet balance limit: prevents a wallet's available balance from falling negative
• Maximum wallet balance limit: prevents a wallet's available balance from exceeding a specified limit
• Minimum wallet balance limit (advanced): the same idea with additional logic for movement states, wallet types, and fee handling
• Maximum account balance limit: prevents an account's balance from exceeding a threshold defined by account type and currency

Currency and status guards

• Currency match check: blocks a transaction if the source and target wallet currencies don't match
• Wallet currency restriction: restricts which currencies a wallet can even be created in
• A family of status-based rejections: pending, suspended, suspended-in, suspended-out, terminated, and closed: each blocking transactions against a wallet in that state unless an explicit override is present

Restriction-type guards

• Block all / block incoming / block outgoing: reject transactions against a wallet carrying that specific restriction type

Utility

• Echo movement data: surfaces key movement attributes (group ID, payment ID, execution ID, command) for visibility

Because these are toggle-driven, an institution can compose its own ledger governance — which limits apply, which wallet states block activity, which currencies are even allowed — without needing engineering involvement for the common cases.

Product Layer: Wiring Charts, Wallets, and Ledger Providers

Below the service layer, each product wires up its own ledger configuration — under Product configuration → Products → [product], on a tab named for whichever ledger provider it connects to (for example, "XYB ledger"). This is where a product's chart, wallets, and customer-group mappings actually get defined:

• Chart configuration: the chart's name, and account configuration (account reference, account tags)
• Wallet configuration: wallet name, accounting type (for example, Asset), wallet currency, and any wallet attributes, plus wallet codes broken out by currency
• Group configuration: mapping customer groups to the wallets they should use

Critically, a product isn't limited to a single ledger provider. One observed product carried both an "XYB ledger" tab and a "Fiserv adapter" tab, each independently configured — a concrete example of a single product routing through more than one connected ledger at once, rather than being locked to XYB's own ledger exclusively.

Operator Layer: Day-to-Day Ledger Operations

Once a product is live, ongoing ledger operations happen from Console, under Ledger:

• Chart management: a full, searchable list of every chart in the system (one environment alone held over 26,000), each showing its account count and creation date. New charts can be created directly or uploaded in bulk via CSV.
• Balances: balances can be searched and browsed either by chart or by group, in list or grid view, and looked up directly by account or wallet.
• Postings: a browsable history of every ledger posting, with quick shortcuts for common ranges (last 7/30/90 days, this month) and filters for currency, metadata, value date, and status. This is also where a manual journal entry can be created, posting directly between two wallets.

One detail worth getting right when reading postings: each entry has both a Type (for example, "Res. credit" or "Res. debit") and a separate Side (Debit or Credit) — these are two distinct fields, not the same concept represented twice, and a posting's type and side don't always align in the direction you might expect.

How the Layers Fit Together

The three layers are deliberately separate concerns. The service layer sets universal guardrails once, so every product built on it inherits the same baseline governance without needing to reimplement it. The product layer is where an institution's specific structure — its charts, wallets, currencies, and which external ledgers (if any) it also needs to stay in sync with — actually takes shape. The operator layer is the ongoing, day-to-day surface where that structure is monitored and, when needed, manually corrected. Together, this is what lets one ledger platform serve very different institutions and products without requiring a different system for each.