Ledgers Guarantees
Ledgers enforces a set of principles, listed here.
- Balanced: For each currency within a ledger, credits will always equal debits. For each currency within a transaction, credits will always equal debits. At any given moment in time, the balance of an account is equal to the sum of its effective credit and debit entries.
- Auditable Versions: The exact entries that contribute to each
lock_version
of an account can always be queried. - Archival Instead of Deletion: Transactions cannot be deleted, only archived. Once archived, a transaction’s entries won’t count toward any account balances. Posted transactions cannot be archived.
- Ledger Isolation: Each ledger will isolate its accounting from other ledgers. We validate that transactions can only be written against accounts in the same ledger. If accounts or transactions across different ledgers refer to the same real-world entity, you can use metadata to reference the same identifier.
- Immutability: Entries cannot be changed or removed on a transaction once it is posted. Fields that do not affect balances like metadata can still be edited.
- Idempotency: Idempotency keys are supported on all POST requests to prevent creating duplicate objects, even when you’re retrying failures. When provided, we also enforce
external_id
to be unique for all transactions within a ledger. - Write Atomicity: When you create a transaction, its entries will either all succeed or all fail to be written.
- Read Committed Isolation: Reads won’t block and aren’t blocked by writes. Writes can use locking to ensure serial writes when you want to create a transaction that depends on an account balance.
Updated 5 months ago