Under the hood

This will describe how balance checking and BeanTab work in more detail. In theory, you may skip this page and return to it once you have related questions or want to know more about the details.

Balance + Tab idea¶

Let's take Assets:MyFavouriteBank:Cash as an example.

Each asset account pairs with Equity:OpeningBalances:* (e.g. Equity:OpeningBalances:MyFavouriteBank:Cash) for the first snapshot.

Changes between snapshots are routed to companion accounts: Expenses:Unattributed:MyFavouriteBank for banks, Expenses:Unattributed:Physical:Cash for cash, and Income:MyAutomaticBroker:PnL for opaque funds whose value moves without detailed holdings (A cleaner approach for those funds is the valuation plugin below). "Routing" is done using pad directives preciding balance checks.

Liabilities work like Assets conceptually. Both count toward net worth. If unsure, start with Assets.

Native Beancount balance and pad directives are the building blocks. This guide uses extended variants via BeanTab.

Why balance-ext and pad-ext instead of standard balance and pad¶

Standard balance checks a single currency amount on the account and only produces errors on mismatch. Standard pad fills this gaps but is overly verbose for extensive use.

Extended versions of these directives allow to set defaults and reduce amount of boilerplate significantly. It's also easier to manage single entries rather than keeping balance and a corresponding pad in sync programmatically.

balance-ext adds typed checks (padded, full-padded, valuation, etc.) so one grid cell can assert balances and trigger the right follow-up logic.

pad-ext replaces stock pad: optional suppression of unused-pad errors, regex-based default pad accounts (e.g. Expenses:Unattributed:{name}), and different targets for opening vs later snapshots.

BeanTab edits these custom directives in a spreadsheet UI and depends on both plugins (see plugin order in Lazy Beancount's main.bean)..

Valuation plugin¶

For opaque funds (robo-advisor, managed portfolio) you often only know total value and cash flows, not every holding. balance + pad would book swings to Income:…:PnL like realized gains, which is misleading.

Use the valuation plugin: valuation custom directives instead of pad/balance pairs for total value over time.

In BeanTab, use balance type V / valuation, or maintain valuation entries in the ledger. The account needs a non-zero balance (transaction or pad) before the first valuation check.

Works alongside portfolio analysis when configured.