Skip to main content
All Docs
FeaturesagentOS Block ManagerUpdated April 13, 2026

Reserve Fund — Current Reserve Balance & Source Tracking

Reserve Fund — Current Reserve Balance & Source Tracking

Available from: v0.13.7

The current reserve balance is a real-time field within the reserve fund model. It is drawn automatically from a linked reserve management account (TrueLayer, Calmony, or a manual ledger), or maintained manually via direct entry. The balance is the starting point for all year-by-year reserve fund projections, gap analysis, and scenario modelling — so keeping it accurate is essential.

Balance Source Types

Each reserve fund account has a balanceSourceType that records where its current balance value comes from.

Source TypeDescriptionReal-Time Sync
manualEntered directly or calculated from recorded transactions✗
calmonySynced from a Calmony ring-fenced client money account✓
truelayerSynced from a TrueLayer bank feed (read-only OAuth)✓
manual_ledgerCalculated from CSV-imported bank transactions✗

Accounts default to manual unless a source is explicitly linked.

Balance Freshness

The system tracks when the balance was last updated and surfaces a freshness label on every account:

LabelConditionIndicator
LiveUpdated within the last 5 minutesGreen pulse dot
RecentUpdated within the last 60 minutesBlue clock icon
StaleLast update was more than 60 minutes agoAmber warning icon
UnknownNo update timestamp recordedGrey offline icon

The Balance Source Card

The account detail view shows a dedicated Balance Source Card in place of the previous simple balance display. It provides:

  • The current balance in large format
  • Source type badge and freshness indicator
  • Linked source name, source type, and real-time sync support flag
  • Last sync timestamp with success/failure indicator and error message (if any)
  • Linked Calmony account details: status, bank name, and ring-fenced status
  • Action buttons: Sync Balance, Manual Update, Link Source / Unlink Source

The account list view also shows a source type badge alongside each account name.

Syncing the Balance

Click Sync Balance on the Balance Source Card to trigger a refresh.

  • For manual and manual_ledger accounts, the balance is recalculated from all recorded transactions.
  • For calmony and truelayer accounts, the system will call the respective API when configured. If the API is not yet configured, the balance falls back to transaction recalculation and a note is recorded against the sync.
  • If the sync fails, the existing balance is preserved and the error is displayed.

Every sync attempt is logged to the audit trail regardless of outcome.

Manually Updating the Balance

Admins can set the balance directly — for example after reconciling with a bank statement.

  1. Click Manual Update on the Balance Source Card.
  2. Enter the correct balance in pounds.
  3. Enter a mandatory reason (e.g. Reconciled with bank statement – April 2025).
  4. Click Update Balance.

The system automatically:

  • Updates currentBalancePence and sets balanceSourceType to manual.
  • Creates an adjustment transaction for the difference, recording the reason in the transaction notes.
  • Logs the change to the audit trail with the previous balance, new balance, difference, and reason.

Linking a Balance Source

To connect a TrueLayer, Calmony, or manual ledger data feed:

  1. Open the reserve fund account detail view.
  2. Click Link Source on the Balance Source Card.
  3. Select an active management account source from the dropdown. Only sources belonging to the same block are shown.
  4. Click Link Source to confirm.

The system will:

  • Set linkedManagementAccountSourceId to the selected source.
  • Derive balanceSourceType from the source type (truelayer → truelayer, calmony → calmony, others → manual_ledger).
  • Set supportsRealTimeSync to true for TrueLayer and Calmony sources.

You cannot link an inactive management account source.

Unlinking a Balance Source

To disconnect a data feed and revert to manual management:

  1. Click Unlink Source on the Balance Source Card.
  2. Confirm the prompt.

The system will:

  • Clear linkedManagementAccountSourceId.
  • Set balanceSourceType back to manual and supportsRealTimeSync to false.
  • Clear all sync state (lastSyncAt, lastSyncSuccess, lastSyncError).
  • Log the change to the audit trail.

Setting the Balance Source at Account Creation

When creating a new reserve fund account, you can set the initial Balance Source type via the dropdown in the create form. The default is Manual (transaction-based). You can link a specific data source after the account is created.

Database Migration

⚠️ A database migration is required to apply the new columns to reserveFundAccounts.

New columns added to reserve_fund_accounts:

balance_source_type   reserve_fund_balance_source  DEFAULT 'manual'
linked_management_account_source_id  text
supports_real_time_sync  boolean  NOT NULL  DEFAULT false
last_sync_at         timestamp
last_sync_success    boolean
last_sync_error      text

A new enum type is also created:

CREATE TYPE reserve_fund_balance_source AS ENUM (
  'manual',
  'calmony',
  'truelayer',
  'manual_ledger'
);

API Reference

reserveFund.getBalanceSummary

Returns the current balance with full source metadata and freshness information.

Input:

{ accountId: string }

Returns:

{
  accountId: string
  blockId: string
  blockName: string
  accountName: string

  currentBalancePence: number
  targetBalancePence: number | null
  fundingGapPence: number

  balanceSourceType: 'manual' | 'calmony' | 'truelayer' | 'manual_ledger'
  linkedManagementAccountSourceId: string | null
  linkedSource: { id, sourceType, label, isActive, connectorProvider } | null
  linkedCalmonyAccount: { id, status, label, bankName, isRingFenced } | null
  supportsRealTimeSync: boolean

  balanceUpdatedAt: Date | null
  lastSyncAt: Date | null
  lastSyncSuccess: boolean | null
  lastSyncError: string | null
  freshnessMinutes: number | null
  freshnessLabel: 'live' | 'recent' | 'stale' | 'unknown'

  availableSources: Array<{ id, sourceType, label, isActive, connectorProvider }>
}

reserveFund.syncBalance

Triggers a balance refresh from the linked source. Admin only.

Input:

{ accountId: string }

Returns:

{
  currentBalancePence: number
  previousBalancePence: number
  balanceDifferencePence: number
  syncSuccess: boolean
  syncError: string | null
  syncedAt: Date
  sourceType: string
}

reserveFund.updateBalanceManual

Manually sets the current balance. Admin only. A reason is required.

Input:

{
  accountId: string
  newBalancePence: number   // integer
  reason: string            // 1–1000 chars, recorded in audit trail
}

Returns:

{
  currentBalancePence: number
  previousBalancePence: number
  differencePence: number
}

reserveFund.linkSource

Links a management account source to the reserve fund. Admin only.

Input:

{
  accountId: string
  managementAccountSourceId: string
}

Returns the updated account record plus linkedSourceLabel and linkedSourceType.

reserveFund.unlinkSource

Removes the linked source and reverts to manual balance management. Admin only.

Input:

{ accountId: string }

Returns the updated account record.