How to Verify Prior Ledger States

Introduction

Immutability is an important guarantee from a ledger. At Modern Treasury, we guarantee immutability by keeping track of the historical changes whenever a Ledger object is updated, which is backed by a series of immutable event logs. In this guide, we will walk through how to verify prior ledger states by finding the historical changes to a ledger.

Who This Guide is For

As a user who has integrated with Modern Treasury’s Ledger product, there may be situations where you need to find the prior states of a Ledger object. For example, you might need this when building a front-end UI for your end users to view the historical changes, generating an audit report, or manually investigating a production issue. Modern Treasury has made it more accessible to query the historical records.

This guide assumes that you are familiar with the core Ledger concepts and APIs, like creating a Ledger, adding Ledger Accounts, creating or updating a Ledger Transaction with Ledger Entries, and reading Account balances. If you are new to Ledgers, we highly recommend you to read the Accounting for Developers series or review the Ledgers API documentation first.

Ledger Transaction History

A Ledger Transaction and its Entries can be edited conditionally

Ledger Transactions are created to record money movement events that happened among multiple Ledger Accounts. A Ledger Transaction can be updated when the status is pending, but once it transitions to the final status posted or archived, it can no longer be changed.

For example, a transaction might be modified in pending status to reflect payments in transit or before they settle - such as in the processing window of an ACH credit. Once the transaction cleared they would be moved to posted. Throughout the life cycle of a Ledger Transaction, each modification generates a new Ledger Transaction Version with an incremental version number starting from zero.

Ledger Entries of a pending Ledger Transaction can also be updated. In order to guarantee immutability, the old Ledger Entries are discarded while new Ledger Entries are created. The Ledger Transaction Version object not only stores the top level Transaction attributes like description, status, metadata, it also captures the historical Ledger Entry values when the change happened.

Ledger Transaction update example

Past Transaction versions are used when trying to reconstruct the history of a particular money movement event that involves multiple changing Accounts. Consider a bill splitting app. A pending Transaction represents the bill when it’s first created, and users can add themselves to subsequent versions of the bill before it is posted.

Alice starts by paying for the entire bill.

Bob splits the bill with Alice.

The bill is posted.

Querying Ledger Transaction Versions

The Versions of a Ledger Transaction can be retrieved by sending a request to the List Ledger Transaction Versions endpoint:

The API response contains a list of historical values of the Ledger Transaction, sorted by version in a descending order. Each Version also includes the Ledger Entries attached to the Transaction at the time when the Version was created:

Versions can be queried by their created_at timestamps. For example, to find the Ledger Transaction changes between 9am and 6pm UTC on Oct 21st, you would add query parameters created_at[gte]=2022-10-21T09:00:00Z&created_at[lte]=2022-10-21T18:00:00Z:

Versions can also be queried by a version number range. For example, if you’d like to see what a Ledger Transaction looked like when it was first created, you would add query parameter version[eq]=0

Ledger Account Balance History

A Ledger account represents a balance tracked by the ledger. One transaction modifies at least two accounts. Each Ledger Account has a lock_version field which increments when the pending or posted balance of the Ledger Account changes. Notice that you can add Ledger Entries to a Ledger Account with the effective_at timestamp in any order, but the lock_version increases per edit, which is perpendicular to effective_at.

Querying Ledger Entries

In order to find which Ledger Entry contributed to a certain Ledger Account lock_version, you can send a request to the List Ledger Entries endpoint with ledger_account_id and ledger_account_lock_version query parameters. As mentioned earlier, in order to guarantee immutability, previous Ledger Entries are replaced with the new ones upon editing, which is why we need an extra query parameter show_deleted=true:

The API response contains the Ledger Entries of the ledger_account_lock_version:

Querying Account Balance

When a Ledger Entry with an effective_at timestamp is added to a Ledger Account, it affects the balance on and after the effective_at timestamp. For example, at 6pm UTC on Oct 1st, some Ledger Entries are added with effective_at as September 30th 6pm UTC. Then on Oct 15th, you would like see what September 30th 6pm UTC’s balances are as of now, you can send a request to the Get Ledger Account endpoint with a query parameter balances[effective_at]:

The balances in the response are the sum of all the Ledger Entries that are currently recorded in the system with effective_at less than or equal to 2022-09-30T18:00:00Z.

Conclusion

Ledger transaction versions, account lock versions and effective_at queries are powerful ways for you to reconstruct the history of your ledger. If you are interested in building a transparent and auditable data store for your financial data, take a look at Modern Treasury Ledgers and reach out if we can be helpful.