Control Templates - Formance Documentation

Control templates describe the relationship Reconciliation should protect. Choose the template closest to the business question, then configure its sources and per-asset tolerance.

Template	Business question	Sources
`ledger_vs_pool_drift`	Does cash held externally back the position recorded in Ledger?	One Ledger account set and one cash pool
`ledger_invariant`	Do several Ledger account groups maintain the required net relationship?	N Ledger account sets as signed terms (at least one, with no upper limit; meaningful net relationships usually use two or more)
`account_threshold`	Is a Ledger account group within its allowed balance range?	One Ledger account set
`source_parity`	Do two independent balance sources agree?	Any two Ledger account sets or cash pools

All four templates evaluate one outcome per asset. If two assets fail, Reconciliation opens two alerts so they can be handled independently.

Template catalog#

Use ledger_vs_pool_drift for the classic backing check between a dynamic Ledger account set and a cash pool.

json

{
  "templateKind": "ledger_vs_pool_drift",
  "templateSpec": {
    "ledger": "main",
    "ledgerQuery": {
      "$match": { "metadata[reconciliation.pool]": "stripe" }
    },
    "paymentsPoolID": "<POOL_ID>",
    "ledgerSign": -1,
    "tolerance": {
      "USD/2": 0,
      "EUR/2": 50
    }
  }
}

The control checks this relationship for every asset found on either side:

absolute(ledgerSign × ledger balance + pool balance) ≤ tolerance

Choose the sign from the way your Ledger represents the external position:

use -1 when the Ledger and pool balances are both naturally positive;
use +1, the default, when the Ledger balance is the negative counterpart of positive external cash.

Tolerance defaults to zero for assets not listed. This means a newly observed asset is still checked strictly instead of being silently ignored.

When migrating a legacy policy, omit ledgerSign to preserve its ledger + pool = 0 convention. Review the first evaluation's raw and signed Ledger values before scheduling the rule.

Tolerances use integer asset units and must be non-negative. They are useful when systems observe the same economic event at slightly different times or when a known rounding convention creates small residuals.

Prefer the smallest tolerance justified by the business process:

identify the expected timing or rounding difference;
express the maximum accepted amount per asset;
keep evidence and alerting enabled above that amount;
review tolerances when settlement behavior changes.

A tolerance prevents a difference from opening an alert. It is not the same as accepting an alert, which records a human decision after evidence exists.

Align sources with different timestamps#

Multi-source templates support an independent point in time for every source. First evaluate the rule once and inspect pitPerSource to discover its stable keys, such as:

json

{
  "ledger:main#0": "2026-07-20T23:59:59Z",
  "pool:01J...#0": "2026-07-20T23:30:00Z"
}

You can then replay or align the sources explicitly:

json

{
  "at": "2026-07-20T23:59:59Z",
  "sourcePITs": {
    "ledger:main#0": "2026-07-20T23:59:59Z",
    "pool:01J...#0": "2026-07-20T23:30:00Z"
  }
}

Values in sourcePITs are already effective timestamps, so the evaluation's safety margin is not subtracted from them. Unknown source keys and future timestamps are rejected.

Choose the account sets carefully#

A control is only as meaningful as its source selection. Before enabling a schedule:

run the underlying Ledger and cash-pool queries independently;
confirm that every intended account is included and no unrelated account matches;
verify sign conventions with a known-good balance;
test each configured asset;
run a known failing scenario and inspect its evidence.

Ledger metadata queries at a historical point in time require Ledger 2.4.11 or later, which is the minimum supported by this Reconciliation release.

Template

Business question

Sources

ledger_vs_pool_drift

Does cash held externally back the position recorded in Ledger?

One Ledger account set and one cash pool

ledger_invariant

Do several Ledger account groups maintain the required net relationship?

N Ledger account sets as signed terms (at least one, with no upper limit; meaningful net relationships usually use two or more)

account_threshold

Is a Ledger account group within its allowed balance range?

One Ledger account set

source_parity

Do two independent balance sources agree?

Any two Ledger account sets or cash pools

Template catalog#

Use ledger_vs_pool_drift for the classic backing check between a dynamic Ledger account set and a cash pool.

json

{
  "templateKind": "ledger_vs_pool_drift",
  "templateSpec": {
    "ledger": "main",
    "ledgerQuery": {
      "$match": { "metadata[reconciliation.pool]": "stripe" }
    },
    "paymentsPoolID": "<POOL_ID>",
    "ledgerSign": -1,
    "tolerance": {
      "USD/2": 0,
      "EUR/2": 50
    }
  }
}

The control checks this relationship for every asset found on either side:

absolute(ledgerSign × ledger balance + pool balance) ≤ tolerance

Choose the sign from the way your Ledger represents the external position:

use -1 when the Ledger and pool balances are both naturally positive;
use +1, the default, when the Ledger balance is the negative counterpart of positive external cash.

Tolerance defaults to zero for assets not listed. This means a newly observed asset is still checked strictly instead of being silently ignored.

When migrating a legacy policy, omit ledgerSign to preserve its ledger + pool = 0 convention. Review the first evaluation's raw and signed Ledger values before scheduling the rule.

Set tolerances deliberately#

Prefer the smallest tolerance justified by the business process:

identify the expected timing or rounding difference;

express the maximum accepted amount per asset;

keep evidence and alerting enabled above that amount;

review tolerances when settlement behavior changes.

A tolerance prevents a difference from opening an alert. It is not the same as accepting an alert, which records a human decision after evidence exists.

Align sources with different timestamps#

Multi-source templates support an independent point in time for every source. First evaluate the rule once and inspect pitPerSource to discover its stable keys, such as:

json

{
  "ledger:main#0": "2026-07-20T23:59:59Z",
  "pool:01J...#0": "2026-07-20T23:30:00Z"
}

You can then replay or align the sources explicitly:

json

{
  "at": "2026-07-20T23:59:59Z",
  "sourcePITs": {
    "ledger:main#0": "2026-07-20T23:59:59Z",
    "pool:01J...#0": "2026-07-20T23:30:00Z"
  }
}

Values in sourcePITs are already effective timestamps, so the evaluation's safety margin is not subtracted from them. Unknown source keys and future timestamps are rejected.

Choose the account sets carefully#

A control is only as meaningful as its source selection. Before enabling a schedule:

run the underlying Ledger and cash-pool queries independently;

confirm that every intended account is included and no unrelated account matches;

verify sign conventions with a known-good balance;

test each configured asset;

run a known failing scenario and inspect its evidence.

Ledger metadata queries at a historical point in time require Ledger 2.4.11 or later, which is the minimum supported by this Reconciliation release.