DoubleEntryLedger.Transaction (double_entry_ledger v0.1.0)

View Source

Defines the transaction schema for the double-entry ledger system.

A transaction represents a financial event recorded in the ledger, consisting of multiple balanced entries that affect account balances. Transactions follow double-entry accounting principles, ensuring that debits equal credits for each currency involved.

Transactions can exist in one of three states:

  • :pending - Initial state, can be modified
  • :posted - Finalized state, cannot be modified
  • :archived - Historical state, cannot be modified

Each transaction belongs to a specific ledger instance and contains at least two entries to maintain the balanced equation of accounting.

The following validations are enforced:

  • Transactions must have at least 2 entries
  • All entries must belong to accounts in the same ledger instance
  • Debits must equal credits for each currency involved
  • State transitions must follow allowed paths
  • Transactions can only be created in the :pending or :posted state
  • Transactions can only be updated if they are in the :pending state
  • Transactions can only be archived from the :pending state
  • Transactions can only be posted from the :pending state
  • Transactions cannot be modified once posted or archived

Usage Details: Transactions should not be created directly. Instead, use the DoubleEntryLedger.Stores.CommandStore module to create commands that will generate transactions. The CommandWorker will handle the processing of these commands and the creation of transactions in the ledger.

Summary

Types

state()

Represents the possible states of a transaction

states()

List of all possible transaction states.

t()

The transaction struct representing a financial event in the ledger.

Functions

changeset(transaction, attrs)

Creates a changeset for a transaction with the provided attributes.

changeset(transaction, attrs, transition)

Creates a changeset for updating a pending transaction.

states()

Returns the list of all valid transaction states.

Types

state()

@type state() :: :archived | :posted | :pending

Represents the possible states of a transaction:

  • :pending - Transaction is in draft mode and can be modified
  • :posted - Transaction has been finalized and cannot be changed
  • :archived - Transaction has been archived for historical purposes

states()

@type states() :: [state()]

List of all possible transaction states.

t()

@type t() :: %DoubleEntryLedger.Transaction{
  __meta__: term(),
  entries: [DoubleEntryLedger.Entry.t()] | Ecto.Association.NotLoaded.t(),
  id: Ecto.UUID.t() | nil,
  inserted_at: DateTime.t() | nil,
  instance: DoubleEntryLedger.Instance.t() | Ecto.Association.NotLoaded.t(),
  instance_id: Ecto.UUID.t() | nil,
  journal_event_transaction_links:
    [DoubleEntryLedger.JournalEventTransactionLink.t()]
    | Ecto.Association.NotLoaded.t(),
  journal_events:
    [DoubleEntryLedger.JournalEvent.t()] | Ecto.Association.NotLoaded.t(),
  posted_at: DateTime.t() | nil,
  status: state() | nil,
  updated_at: DateTime.t() | nil
}

The transaction struct representing a financial event in the ledger.

Contains the following fields:

  • id: Unique identifier
  • instance: Associated ledger instance
  • instance_id: ID of the associated ledger instance
  • posted_at: Timestamp when the transaction was posted
  • status: Current state of the transaction
  • entries: Associated debit/credit entries
  • inserted_at: Creation timestamp
  • updated_at: Last modification timestamp

Functions

changeset(transaction, attrs)

@spec changeset(t(), map()) :: Ecto.Changeset.t()

Creates a changeset for a transaction with the provided attributes.

Performs validations to ensure the transaction follows double-entry accounting principles:

  • Has at least two entries
  • All entries belong to accounts in the same ledger instance
  • Debits equal credits for each currency involved
  • State transitions follow allowed paths

Parameters

  • transaction: The existing transaction struct
  • attrs: Map of attributes to change

Returns

An Ecto.Changeset with validations applied

changeset(transaction, attrs, transition)

@spec changeset(t(), map(), DoubleEntryLedger.Types.trx_types()) :: Ecto.Changeset.t()

Creates a changeset for updating a pending transaction.

This function is specifically for updating transactions in the :pending state, allowing for controlled transitions between states.

Parameters

  • transaction: The existing transaction struct
  • attrs: Map of attributes to change
  • transition: The transaction type being applied

Returns

An Ecto.Changeset with validations applied

states()

@spec states() :: states()

Returns the list of all valid transaction states.

Returns

A list of atoms representing the possible transaction states:

  • :pending
  • :posted
  • :archived