English for TigerBeetle Developers

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

1. Explain, in two sentences, why double-entry accounting makes bugs harder to hide than a single mutable balance column.
2. Write a short PR description for adding a two-phase transfer to model a pre-authorization-and-capture flow.
3. Draft a message explaining to a non-fintech engineer why deterministic simulation testing matters for a financial ledger’s reliability.

Related Resources

• English for VictoriaMetrics Developers
• English for OpenFGA Developers
• English for Xata Database Developers

Navigating the Ledger: Refining Your Financial Vocabulary

As developers working with TigerBeetle’s core – double-entry accounting, ledgers, and deterministic simulation – clear communication is absolutely critical. Misunderstandings around debits, credits, and linked events can quickly lead to errors in your data models and testing. This section focuses on refining the specific vocabulary used within our team’s discussions, moving beyond literal translations and embracing the nuances of professional English related to financial systems. We’ll look at phrasing that promotes clarity and precision when discussing transaction logic, test scenarios, and database design.

A common issue is assuming everyone understands the implications of a “debit” versus a “credit.” It’s not simply about adding or subtracting; it’s about affecting the balance sheet in a specific way. We need to consistently use terms like “increase the asset account,” “decrease liability,” and clearly articulate the logic behind each transaction. Similarly, when discussing linked events – critical for deterministic simulation – we must avoid vague statements like “this affects that.” Instead, we’ll aim for phrases like, “This event triggers a cascading effect, leading to an adjustment in the ledger balance based on rule X,” or “The subsequent event is dependent on the completion of this one, creating a tightly coupled sequence.” Furthermore, discussing the reasoning behind a test case – why a specific input produces a particular output – requires careful wording. Instead of saying “this fails because…” we should use phrases like “This failure indicates a discrepancy in the debit/credit calculation under scenario Y,” or “The simulation deviates due to an incorrect mapping between linked events.”

These small changes significantly reduce ambiguity and improve collaboration. Consider how our PR descriptions sound – they aren’t simply stating what happened, but explaining why it happened within the context of the ledger’s rules. We need to be able to clearly articulate the flow of transactions, the logic governing them, and how those rules are reflected in our database design.

Here’s an example of using tigerctl for a simulation test:

tigerctl run --simulation-test "ledger_balance_update:scenario_3" --input "initial_balance=1000, debit_amount=500, credit_amount=200"

This command demonstrates the precision required when describing a simulation test – we’re not just saying “run the test”; we’re specifying exactly what data is being used to drive the deterministic outcome and how that outcome impacts the ledger. Consistent and accurate vocabulary is key to ensuring the integrity of our system.