Layered Accounting

The Three Layer Model

Twisp utilizes a layered model of accounting to distinguish transactions between three important categories:

1. The settled layer is for transactions that have fully settled.
2. The pending layer includes holds and pending transactions which have been authorized but not yet settled.
3. The encumbrance layer contains expected, planned, and scheduled future transactions.

By segmenting transactions in this way, it provides the data integrity needed for more accurate and useful balance calculations and funds flow modelling. It also unlocks features to support a variety of use cases without adding complexity.

For example, we can use the pending layer to verify that an account will have enough funds after the holds and pending transactions have cleared. With the encumbrance layer, we can add transactions scheduled in the future and goals or budgeting tools to set money aside in an account.

Without explicit layers, chaos reigns. Many DIY ledgers that we've seen lack the concept of layers, or only apply the concept partially. This can make it incredibly difficult to reason about the state of a ledger or perform basic accounting operations like cash reconciliation.

Layered Balances

Each account can have a different aggregate balance in each layer depending on how transactions have been posted.

To calculate the account balance for a layer, we sum all entries on that layer:

Where $b(l)$ is the balance for a layer and $e_l$ is the set of all entries on that layer.

All accounts and account sets a debit balance (sum of debit entries), credit balance (sum of credit entries), and normal balance. Learn more about balances in Balances.

Layers in Practice

To demonstrate how layers work in practice, let's consider an account set that has entries posted to its sub-accounts across all three layers. We'll follow the state changes to the account set and its balance as additional entries are written. For simplicity's sake, we'll assume that all amounts are in USD.

At first, the only entry is on the settled layer.

Because this entry is on the settled layer, the balance for that layer reflects the amount of that entry.

The pending and encumbrance layers have no entries, so they are currently at $0.

Let's see how things change when entries on the pending layer are written. In this case, the entries are modeling a basic "hold-settle" pattern: a hold is placed on the pending layer, and then settled to the settled layer and cleared from the pending layer.

Notice that the entries on the pending layer only affected the pending-layer balance. The settled balance was only changed by the additional settled-layer entry.

Let's see how the balances change with a few more entries across all layers:

Again, notice that the layered balances are only aggregating entries from their layer.

Calculating an Available Balance

While keeping separate balances for each layer is useful for tracking the current, planned, and predicted state of accounts, it is also possible to calculate a balance across layers.

The available balance is a special balance that rolls up the balances of the other layer balances. If we show the available balance from the example above, this totaling is clearly visible.

We can query the available balance with a configuration option to roll up balances:

• across all layers,
• over the settled and pending layers,
• or just the settled layer (at which point it is equivalent to the settled balance).

One way to think of the available balance is as a function that takes a layer and sums some or all of the other layer balances depending on which layer is provided.

Where $a(l)$ is the available balance at a given layer, $b(l)$ is the balance for a layer, and $S, P, E$ represent the Settled, Pending, and Encumbrance layers.