TigerBeetle Documentation

A transfer is an immutable record of a financial transaction that debits a single account and credits a single account on the same ledger.

Key guarantees:

• Immutability: Transfers cannot be modified or deleted after creation. To correct an error, you must use a correcting transfer.
• Uniqueness: There is at most one Transfer with a particular id per cluster.
• Deterministic Timeouts: Transfer timeouts are driven by the cluster's timestamp.
• Pending Resolution: A pending transfer resolves at most once.

TigerBeetle is a specialized database optimized for write-heavy OLTP (Online Transaction Processing) workloads. Key performance and architectural characteristics include:

• High Throughput: Designed to handle up to 1 million transactions per second.
• Contention Management: Provides strong consistency guarantees without using row locks, preventing performance degradation on 'hot accounts' (accounts involved in a high percentage of transactions).
• Single-Core Design: Uses a single-core architecture and specific performance optimizations to achieve high throughput without the complexity and latency of horizontal sharding.
• Complementary Use: It is intended to work alongside OLGP (Online General Purpose) databases, which are better suited for read-heavy or infrequently updated data.

A request in TigerBeetle is a message sent to the cluster that queries or updates the database state. A request consists of one or more events of the same type. For example, a single request can create multiple transfers, but it cannot mix different types (e.g., it cannot create both accounts and transfers in one request).

Key execution characteristics:

• The cluster commits an entire request atomically (all or nothing).
• Events within a request are applied in series; successive events observe the effects of previous ones.
• Each request generates exactly one reply message containing one result for every event in the request.

TigerBeetle utilizes double-entry bookkeeping and a financial accounting type system to ensure data integrity and balance.

Core Account Types:

• Asset: What is owned (can produce income or be sold).
• Liability: What is owed to others.
• Equity: Residual interest in assets after deducting liabilities.
• Income: Increases in assets or decreases in liabilities resulting in increased equity.
• Expense: Decreases in assets or increases in liabilities resulting in decreased equity.

Key Principles:

• Double-Entry: Every transaction is recorded in at least two places; funds always move from one account to another.
• Fundamental Equation: Assets - Liabilities = Equity. Transactions must maintain this balance.

A client session is a sequence of requests and replies between a client and a cluster. Key constraints include:

• In-flight Limit: A session may have at most one in-flight request. Additional requests are queued by the client and sent only after the preceding request receives a reply.
• Throughput Optimization: To maximize throughput, minimize the number of concurrent clients and batch as many events as possible per request.

TigerBeetle executes all client requests and events within a batch with the highest level of isolation: they are processed serially through the state machine. This serial execution, combined with batching, allows for optimal isolation without the overhead of locks for individual events.

Regarding durability, TigerBeetle uses an explicit storage fault model to protect against data loss and corruption. It leverages cluster-wide storage so that data is only lost if it is corrupted on all replicas; in such a catastrophic event, the system is designed to safely halt rather than operate with corrupted data.

Double-entry bookkeeping ensures that funds are always accounted for and never 'appear' from nowhere; they always move from one account to another.

In TigerBeetle, a Transfer consists of exactly one debit and one credit. For more complex scenarios involving multiple accounts, these transfers can be composed into multi-debit and multi-credit transfers.