getting-started-with-ash-double-entry.md

Getting Started with Ash Double Entry

Ash Double Entry is implemented as a set of Ash resource extensions. You build the resources yourself, and the extensions add the attributes, relationships, actions and validations required for them to constitute a double entry system.

What is Double Entry Accounting?

Double entry is a accounting principle that ensures every financial transaction is recorded in at least two accounts, maintaining the accounting equation of Assets = Liabilities + Equity. This means that every transaction has a debit (or money going out) and a credit (or money coming in), recorded in dedicated debit and credit accounts (hence the name "double entry"). The total debits must always equal the total credits, ensuring that books always balance and allowing for errors to be quickly detected.

Implementation in AshDoubleEntry

AshDoubleEntry implements double entry accounting through three core resources:

1. AshDoubleEntry.Account DSL, which represents accounts in your ledger (such as bank accounts, revenue accounts, expense accounts, etc.).
2. AshDoubleEntry.Transfer DSL, which represents transactions between accounts, always linking a from_account and to_account with an amount.
3. AshDoubleEntry.Balance DSL, which tracks the balance of each account at the point of each transfer for recordkeeping.

What makes it special?

1. Account balances are updated automatically as transfers are introduced.
2. Arbitrary custom validations and behavior by virtue of modifying your own resources.
3. Transactions can be entered in the past, and all future balances are updated (and therefore validated).

Setup

Setup AshMoney

Follow the setup guide for AshMoney, located here. If you are using with AshPostgres, be sure to include the :ex_money_sql dependency in your mix.exs.

Add the dependency

{:ash_double_entry, "~> 1.0.3"}

Define your account resource

Example

defmodule YourApp.Ledger.Account do
  use Ash.Resource,
    domain: YourApp.Ledger,
    data_layer: AshPostgres.DataLayer,
    extensions: [AshDoubleEntry.Account]

  postgres do
    table "accounts"
    repo YourApp.Repo
  end

  account do
    # configure the other resources it will interact with
    transfer_resource YourApp.Ledger.Transfer
    balance_resource YourApp.Ledger.Balance
    # accept custom attributes in the autogenerated `open` create action
    open_action_accept [:account_number]
  end

  attributes do
    # Add custom attributes
    attribute :account_number, :string do
      allow_nil? false
    end
  end
end

What does this extension do?

• Adds the following attributes:
  • :id, a :uuid primary key
  • :currency, a :string representing the currency of the account.
  • :inserted_at, a :utc_datetime_usec timestamp
  • :identifier, a :string and a unique identifier for the account
• Adds the following actions:
  • A primary read called :read, unless a primary read action already exists.
  • A create action called open, that accepts identifier, currency, and the attributes in open_action_accept
  • A read action called :lock_accounts that can be used to lock a list of accounts while in a transaction(for data layers that support it)
• Adds a has_many relationship called balances, referring to all related balances of an account
• Adds an aggregate called balance, referring to the latest balance as a decimal for that account
• Adds the following calculations:
• A balance_as_of_ulid calculation that takes an argument called ulid, which corresponds to a transfer id and returns the balance.
• A balance_as_of calculation that takes a utc_datetime_usec and returns the balance as of that datetime.
• Adds an identity called unique_identifier that ensures identifier is unique.

Define your transfer resource

Example

defmodule YourApp.Ledger.Transfer do
  use Ash.Resource,
    domain: YourApp.Ledger,
    data_layer: AshPostgres.DataLayer,
    extensions: [AshDoubleEntry.Transfer]

  postgres do
    table "transfers"
    repo YourApp.Repo
  end

  transfer do
    # configure the other resources it will interact with
    account_resource YourApp.Ledger.Account
    balance_resource YourApp.Ledger.Balance

    # you only need this if you are using `postgres`
    # and so cannot add the `references` block shown below

    # destroy_balances? true
  end
end

What does this extension do?

• Adds the following attributes
  • :id, a AshDoubleEntry.ULID primary key which is sortable based on the timestamp of the transfer.
  • :amount, a AshMoney.Types.Money representing the amount and currency of the transfer
  • :timestamp, a :utc_datetime_usec representing when the transfer occurred
  • :inserted_at, a :utc_datetime_usec timestamp
• Adds the following relationships
  • :from_account, a belongs_to relationship of the account the transfer is from
  • :to_account, a belongs_to relationship of the account the transfer is to
• Adds a :read action called :read_transfers with keyset pagination enabled. Required for streaming transfers, used for validating balances.
• Adds a change that runs on all create and update actions that reifies the balances table. It inserts a balance for the transfer, and updates any affected future balances.

Define your balance resource

Example

defmodule YourApp.Ledger.Balance do
  use Ash.Resource,
    domain: YourApp.Ledger,
    data_layer: AshPostgres.DataLayer,
    extensions: [AshDoubleEntry.Balance]

  postgres do
    table "balances"
    repo YourApp.Repo

    references do
      reference :transfer, on_delete: :delete
    end
  end

  balance do
    # configure the other resources it will interact with
    transfer_resource YourApp.Ledger.Transfer
    account_resource YourApp.Ledger.Account
  end

  actions do
    read :read do
      primary? true
      # configure keyset pagination for streaming
      pagination keyset?: true, required?: false
    end
  end
end

cascading destroys {: .warning}

If you are not using a data layer capable of automatic cascade deletion, you must add destroy_balances? true to the transfer resource! We do this with the references block in ash_postgres as shown above.

What does this extension do?

• Adds the following attributes:
  • :id, a :uuid primary key
  • :balance, the balance as a decimal of the account at the time of the related transfer
• Adds the following relationships:
  • :transfer a :belongs_to relationship, pointing to the transfer that this balance is as of.
  • :account a :belongs_to relationship, pointing to the account the balance is for
• Adds the following actions:
  • a primary read action called :read, if a priamry read action doesn't exist
  • configure primary read action to have keyset pagination enabled
  • a create action called :upsert_balance, which will create or update the relevant balance, by transfer_id and account_id
• Adds an identity that ensures that account_id and transfer_id are unique

Define an Ash domain to use them through

defmodule YourApp.Ledger do
  use Ash.Domain

  resources do
    resource YourApp.Ledger.Account
    resource YourApp.Ledger.Balance
    resource YourApp.Ledger.Transfer
  end
end

And add the domain to your config

config :your_app, ash_domains: [..., YourApp.Ledger]

Generate Migrations

mix ash_postgres.generate_migrations --name add_double_entry_ledger

Run them

mix ash_postgres.migrate

Use them

Create an account

YourApp.Ledger.Account
|> Ash.Changeset.for_create(:open, %{identifier: "account_one"})
|> Ash.create!()

Create transfers between accounts

YourApp.Ledger.Transfer
|> Ash.Changeset.for_create(:transfer, %{
  amount: Money.new!(20, :USD),
  from_account_id: account_one.id,
  to_account_id: account_two.id
})
|> Ash.create!()

Update existing transfers

YourApp.Ledger.Transfer
|> Ash.Changeset.for_create(:transfer, %{
  amount: Money.new!(:USD, 20),
  from_account_id: account_one.id,
  to_account_id: account_two.id
})
|> Ash.create!()
|> Ash.Changeset.for_update(:update, %{amount: Money.new!(:USD, 10)})
|> Ash.update!()

note {: .warning}

If config :ash, :default_actions_require_atomic? is set to true, the Transfer resource update actions must define change get_and_lock_for_update() and require_atomic? false. It's OK to add require_atomic? false because the relevant accounts are locked before updating them.

Check an account's balance

YourApp.Ledger.Account
|> YourApp.Ledger.get!(account_id, load: :balance_as_of)
|> Map.get(:balance_as_of)
# => Money.new!(20, :USD)

What else can you do?

There are tons of things you can do with your resources. You can add code interfaces to give yourself a nice functional api. You can add custom attributes, aggregates, calculations, relationships, validations, changes, all the great things built into Ash.Resource! See the docs for more: AshHq.