Docs/Use casesv0.0.1-preview

FBO sub-ledgering

Track client virtual balances and the omnibus bank position in one atomic transaction — with a reconciliation whose discrepancy is zero by construction.

On this page
  1. Two tiers, one transaction
  2. Reconciliation becomes an assertion
  3. Deposits, withdrawals, and holds
  4. Related

An FBO (for-benefit-of) arrangement holds many clients’ money in one omnibus bank account. The classic failure is drift: the sum of client virtual balances and the bank position are updated by different code paths, and reconciliation becomes the full-time job of discovering how far apart they’ve grown. TulaDB’s position–settlement mode removes the two code paths: both tiers move in one atomic transaction.

Two tiers, one transaction

Model client virtual balances on the position tier and the omnibus/bank mirror on the settlement tier of a POSITION_SETTLEMENT ledger:

F = c.create_ledger(LedgerInstance(ledger_id=0, currency=840,
        mode=LEDGER_MODE_POSITION_SETTLEMENT,
        position_tier=1, settlement_tier=2)).ledger_id

# Client A and B: a position account (virtual balance) and a
# settlement account (their share of the omnibus) each. Integer ids.
A_POS, B_POS, A_SET, B_SET, PLATFORM = 51001, 52001, 61001, 62001, 1
for acct, tier in ((A_POS,1), (B_POS,1), (A_SET,2), (B_SET,2)):
    c.create_account(AccountCreate(id=acct, ledger_id=F, currency=840, tier=tier,
                                   limit_low=-10**12, limit_high=10**12))

A client-to-client move is one call touching four accounts:

c.tiered_transfer(TieredTransferCreate(source_id=PLATFORM, ledger_id=F,
        currency=840, amount=3_000,
        dr_position_id=A_POS,  cr_position_id=B_POS,
        dr_settlement_id=A_SET, cr_settlement_id=B_SET,
        txn_id="fbo-move-1"))

The outcome: both tiers land together — position credited 3,000 and settlement credited 3,000, atomically. A limit breach on any leg rejects the whole transaction; there is no state where one tier moved and the other didn’t. That is the drift failure mode, deleted structurally.

Reconciliation becomes an assertion

Because the tiers can only move together, the per-tier totals are equal by construction — the engine can produce a per-tier reconciliation whose discrepancy must be zero, and the offline verifier re-derives it from first principles. What remains for your ops team is the external half — does the settlement tier match the actual bank statement? — which is one comparison against one number, fed by the by-ref queries or the Iceberg export.

Deposits, withdrawals, and holds

External money movements are tiered transfers between a client’s pair and the platform’s own pair (the omnibus float). Two-phase tiered operations exist too — tiered_reserve / commit / rollback mirror the hold lifecycle, so a withdrawal can hold both tiers until the bank confirms, and a reservation TTL cleans up abandoned ones.

Transfers — tiered mode · Correctness · Analytics export