ledger-rs

kuatia

kuatia (kuatiʼa) — Guaraní for paper, document, writing. A fitting name for a small, append-only ledger library.

Auditable, multi-asset UTXO-style ledger in Rust.

Overview

kuatia models value as postings — signed amounts owned by exactly one account. Transfers atomically consume existing postings and create new ones, enforcing per-asset conservation. This gives the same safety guarantee as double-entry bookkeeping (Σ debits = Σ credits), expressed as sum(consumed) == sum(created) per asset over signed postings. There are no mutable balance fields; an account's balance is always the sum of its active postings.

It supports journaling: a committed transfer is a journal entry, a transfer with multiple movements is a compound journal entry (one balanced event touching many accounts, and, since each asset balances independently, many assets), and the append-only transfer log is the accounting journal. Replaying that log reconstructs every balance, so the ledger is auditable by construction. See doc/journaling.md.

┌─────────────────────────────────────────────────────┐
│                   kuatia (async)                    │
│                                                     │
│  Intent layer:  TransferBuilder + commit · balance   │
│  Saga pipeline: resolve → reserve → validate → fin.  │
│  Raw pipeline:  load  →  plan  →  apply             │
│  Saga steps:    legend step adapters                 │
├─────────────────────────────────────────────────────┤
│               kuatia-core (pure)                    │
│                                                     │
│  Types:         Account · Transfer · Posting · Cent │
│  Validation:    validate_and_plan()                 │
│  Hashing:       double-SHA256, content-addressed    │
│  Selection:     greedy posting selection             │
└─────────────────────────────────────────────────────┘

Crates

Crate	Purpose
kuatia-types	Domain types — AccountId, Posting, Transfer, Cent, etc.
kuatia-core	Pure, sans-IO decision logic — validation, hashing, posting selection.
kuatia-storage	Store trait (7 sub-traits), InMemoryStore, store_tests! conformance macro.
kuatia-storage-sql	SQL-backed Store — SQLite and PostgreSQL via sqlx.
kuatia	Async resource layer — Ledger, saga commit pipeline, intent-layer API.

Quick Example

use std::sync::Arc;
use kuatia::ledger::Ledger;
use kuatia::mem_store::InMemoryStore;
use kuatia_core::*;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let ledger = Arc::new(Ledger::new(InMemoryStore::new()));

    let usd = AssetId::new(1);
    let alice = AccountId::new(1);
    let bob = AccountId::new(2);
    let bank = AccountId::new(3); // external account

    // Create accounts, deposit, pay...
    // See doc/crates.md for the full API reference.

    Ok(())
}

Documentation

• Architecture Decisions — why the ledger works the way it does
• Crate Reference — modules, types, and APIs per crate
• Accounts — account model, policies, and lifecycle
• Transfers — Movement struct, resolve algorithm, and TransferBuilder API
• Journaling — transfers as journal entries, compound and multi-asset entries, the transfer log as the journal
• Glossary — terms, book scoping, and worked examples
• Accounting Mapping — how classical double-entry concepts map onto kuatia

License

See LICENSE for details.