English for TigerBeetle Developers
Vocabulary for developers building on TigerBeetle — double-entry accounting, ledgers, debits and credits, linked events, and deterministic simulation testing — for teams discussing financial transaction databases in English.
TigerBeetle is a distributed database purpose-built for financial transactions, designed around double-entry accounting rather than general-purpose rows and columns. Its vocabulary comes from two worlds at once — accounting terms like “debit” and “ledger,” and distributed-systems terms like “deterministic simulation” — so teams evaluating it need fluency in both to talk about it accurately. Here’s the English for design discussions and code reviews.
Double-Entry Accounting Fundamentals
Double-entry accounting — a bookkeeping model where every transaction records two matching entries — a debit on one account and a credit on another — so the books always balance by construction. “We modeled the wallet transfer as double-entry accounting instead of a single balance update, so a bug can never silently create or destroy money.”
Debit and credit — the two sides of every transfer; a debit reduces one account’s available balance while the corresponding credit increases another’s, and TigerBeetle enforces that they always sum to zero. “The transfer failed validation because the debit and credit accounts referenced two different currencies — TigerBeetle won’t let that balance mismatch through.”
Ledger — a logical grouping of accounts and transfers that share the same currency or business domain, used to keep unrelated balances isolated from each other. “We split rewards points and cash balances into separate ledgers, since mixing their arithmetic in one ledger made reconciliation harder to reason about.”
Accounts and Transfers
Account
An account in TigerBeetle is a balance-holding record — like a user’s wallet or a merchant’s payable balance — identified by a 128-bit ID for global uniqueness across a distributed cluster.
“Every user gets one account per currency, created up front, so a transfer never has to implicitly create a missing account mid-transaction.”
Transfer
A transfer is the atomic operation that moves value between two accounts, recording a debit on one and a credit on the other in a single, immutable entry.
“Once a transfer is posted, we don’t edit it — if a refund is needed, we create a new transfer in the opposite direction instead of mutating history.”
Linked Events
Linked events let you chain multiple transfers so they either all succeed or all fail together, giving you atomicity across operations that would otherwise be separate calls.
“We used linked events to chain the fee deduction and the merchant payout — if the payout fails, the fee deduction rolls back with it.”
Two-Phase Transfer
A two-phase transfer reserves funds first (pending) and finalizes them later (post or void), useful for holds like a hotel deposit or a pre-authorization.
“We modeled the card pre-authorization as a two-phase transfer — the funds are held as pending until the merchant either posts or voids the charge.”
Reliability and Testing
Deterministic simulation testing — running the entire distributed system inside a simulated network with injected faults (dropped packets, clock skew, crashes) so bugs are reproducible from a single seed instead of being flaky and environment-dependent.
“The simulation found a rare replica-recovery bug in under an hour of simulated time — that would have taken months to surface in production traffic.”
Consensus protocol (Viewstamped Replication) — the algorithm TigerBeetle’s replicas use to agree on the order of transfers even if some nodes crash or the network partitions.
“We don’t need an external coordinator for failover — the consensus protocol handles leader election and replica agreement internally.”
Explaining TigerBeetle to a Team
| Situation | Phrase |
|---|---|
| Justifying it over a general-purpose DB | ”Once we needed atomic, auditable money movement at high throughput, a purpose-built accounting database beat rolling our own balance logic on Postgres.” |
| Explaining a modeling decision | ”We’re using linked events for the fee-plus-payout flow so a partial failure can’t leave the fee deducted without the payout completing.” |
| Describing a reliability guarantee | ”Deterministic simulation testing caught that edge case before it ever touched real transfers — that’s the main reason we trust the failover logic.” |
| Discussing a hold/capture flow | ”The pre-authorization is a two-phase transfer — the hold and the final charge are two distinct, auditable steps, not one opaque update.” |
Common Mistakes
- Saying “balance update” when you mean transfer — TigerBeetle has no direct balance mutation; every change to a balance happens through an immutable, double-entry transfer.
- Treating a two-phase transfer as optional bookkeeping — for holds and pre-authorizations, skipping the pending state removes the audit trail of “reserved but not yet captured.”
- Assuming linked events behave like a database transaction wrapper in the traditional sense — they chain specific transfers atomically, not arbitrary application logic.
Practice Exercise
- Explain, in two sentences, why double-entry accounting makes bugs harder to hide than a single mutable balance column.
- Write a short PR description for adding a two-phase transfer to model a pre-authorization-and-capture flow.
- Draft a message explaining to a non-fintech engineer why deterministic simulation testing matters for a financial ledger’s reliability.