Guarantees

Ledgers enforces a set of principles, listed here.

  • Dual aspect: 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.
  • Account versioning: Each transaction will increment the lock_version of every account it writes one or more entries against.
  • 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.

Did this page help you?