Ledger Reference

Ledger Resources

See each of the sub-pages in this reference for details about the corresponding ledger resource. Each resource is accessible via the GraphQL API.

Axioms Governing the Twisp Ledger

This set of axioms summarizes the key behavior of a Twisp ledger.

• Accounts are a named store of value in Twisp, with each account having a balance.
  • Accounts record activity in the form of ledger entries posted to them.
  • Accounts support multiple layers and have full support for multiple journals.
  • Accounts are stored as immutable documents with all changes stored in a versioned history.
• Account sets are custom groups of accounts that aggregate balances and provide a unified interface into the entries for all accounts.
  • Account sets can contain other sets, allowing for the modeling of more complex structures for a chart of accounts.
  • A chart of accounts is a collection of account and account sets used to track money within the system.
  • Account sets belong to a single journal.
  • Account sets will materialize balances for entries posted to the account set's journal in accounts that are members of the account set or any of its descendant sets.
  • Entries can only be posted to accounts, not to account sets.
• Balances are derived from entries written to the ledger.
  • Balances are calculated for every account.
  • Querying balances reflects the current state of accounts in the ledger.
  • Accounts have a debit balance, credit balance, and normal balance on each layer (SETTLED, PENDING, and ENCUMBRANCE).
  • Balances are materialized for every combination of account, journal, layer, and currency.
  • Balance calculations are computed on write, not on read.
• Entries represent one side of a transaction in the Twisp ledger.
  • Entries always have an account, an amount (including currency), and a direction (CREDIT or DEBIT).
  • Entries can only be entered in the context of a transaction.
  • Every entry is assigned to a layer (SETTLED, PENDING, and ENCUMBRANCE) to differentiate between entries in various stages of a transaction lifecycle.
  • Posting a transaction will create at least 2 ledger entries.
• Journals are used to organize transactions within separate "books" in the Twisp ledger.
  • Every ledger contains a default journal.
  • Users can create, update, and delete additional journals as needed.
• Transactions record all accounting events in the Twisp ledger.
  • The only way to write to a ledger is through a transaction.
  • Every transaction writes two or more entries to the ledger in standard double-entry accounting practice.
  • Transactions are structured by the tran code used, ensuring that the ledger is consistent, predictable, and correct.
• Transaction codes (tran codes) define how ledger entries are written in Twisp.
  • Tran codes accept input values as parameters and write a multi-entry transaction to the ledger.
  • Params are key-value parameters specified by the transaction code and are used when posting a transaction with a specified tran code.
  • All transactions using tran codes are executed atomically, ensuring all-or-nothing commits.
  • Tran codes provide a centralized interface for defining every type of transactional activity in a system.