Crate cala_ledger

cala-ledger

This crate provides a set of primitives for implementing an SQL-compatible double-entry accounting system. This system is engineered specifically is for dealing with money and building financial products.

Visit the website of the Cala project for more info and tutorials.

Quick Start

Here is how to initialize a ledger create a primitive template and post a transaction. This is a toy example that brings all pieces together end-to-end. Not recommended for real use.

use cala_ledger::{account::*, journal::*, tx_template::*, *};
use rust_decimal::Decimal;
use uuid::uuid;

async fn init_cala(journal_id: JournalId) -> anyhow::Result<CalaLedger, anyhow::Error> {
    let cala_config = CalaLedgerConfig::builder()
        .pg_con("postgres://user:password@localhost:5432/pg")
        // .exec_migrations(true) # commented out for execution in CI
        .build()?;
    let cala = CalaLedger::init(cala_config).await?;

    // Initialize the journal - all entities are constructed via builders
    let new_journal = NewJournal::builder()
        .id(journal_id)
        .name("Ledger")
        .build()
        .expect("Couldn't build NewJournal");
    let _ = cala.journals().create(new_journal).await;

    // Initialize an income omnibus account
    let main_account_id = uuid!("00000000-0000-0000-0000-000000000001");
    let new_account = NewAccount::builder()
        .id(main_account_id)
        .name("Income")
        .code("Income")
        .build()?;
    cala.accounts().create(new_account).await?;

    // Create the trivial 'income' template
    let params = vec![
        NewParamDefinition::builder()
            .name("sender_account_id")
            .r#type(ParamDataType::Uuid)
            .build()?,
        NewParamDefinition::builder()
            .name("units")
            .r#type(ParamDataType::Decimal)
            .build()?,
    ];

    let entries = vec![
        NewTxTemplateEntry::builder()
            .entry_type("'INCOME_DR'")
            .account_id("params.sender_account_id")
            .layer("SETTLED")
            .direction("DEBIT")
            .units("params.units")
            .currency("'BTC'")
            .build()?,
        NewTxTemplateEntry::builder()
            .entry_type("'INCOME_CR'")
            .account_id(format!("uuid('{}')", main_account_id))
            .layer("SETTLED")
            .direction("CREDIT")
            .units("params.units")
            .currency("'BTC'")
            .build()?,
    ];

    let tx_code = "GENERAL_INCOME";
    let new_template = NewTxTemplate::builder()
        .id(uuid::Uuid::new_v4())
        .code(tx_code)
        .params(params)
        .transaction(
            NewTxTemplateTransaction::builder()
                .effective("date()")
                .journal_id(format!("uuid('{}')", journal_id))
                .build()?,
        )
        .entries(entries)
        .build()?;

    cala.tx_templates().create(new_template).await?;
    Ok(cala)
}

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let journal_id = JournalId::from(uuid!("00000000-0000-0000-0000-000000000001"));
    let cala = init_cala(journal_id).await?;
    // The account that is sending to the general income account
    let sender_account_id = AccountId::new();
    let sender_account = NewAccount::builder()
        .id(sender_account_id)
        .name(format!("Sender-{}", sender_account_id))
        .code(format!("Sender-{}", sender_account_id))
        .build()?;
    cala.accounts().create(sender_account).await?;
    // Prepare the input parameters that the template requires
    let mut params = Params::new();
    params.insert("sender_account_id", sender_account_id);
    params.insert("units", Decimal::ONE);
    // Create the transaction via the template
    cala.post_transaction(TransactionId::new(), "GENERAL_INCOME", params)
        .await?;

    let account_balance = cala
        .balances()
        .find(journal_id, sender_account_id, "BTC".parse()?)
        .await?;

    let expected_balance = Decimal::new(-1, 0); // Define the expected balance
    assert_eq!(account_balance.settled(), expected_balance);
    Ok(())
}

Re-exports

pub use crate::outbox::server::OutboxServerConfig;

pub use es_entity;

pub use ledger_operation::*;

pub use primitives::*;

Modules

account

Account holds a balance in a Journal

account_set

balance

config

entry

error

instrument

Attach a span to a std::future::Future.

journal

ledger_operation

migrate

outbox

primitives

query

transaction

tx_template

velocity

Structs

CalaLedger

CalaLedgerConfig

CalaLedgerConfigBuilder

Builder for CalaLedgerConfig.

Enums

CalaLedgerConfigBuilderError

Error type for CalaLedgerConfigBuilder

Attribute Macros

instrument

Instruments a function to create and enter a tracing span every time the function is called.