GL/DESIGN.md

General Ledger service design

Status: append-only model accepted on 2026-08-14; authority and availability policy revised on 2026-08-28.

Purpose and ownership

GL is Darano's primary financial source of truth. It records every wallet value movement as an append-only journal. Kuknos, through its Stellar-compatible interface, is the secondary settlement and verification source of truth.

GL owns its PostgreSQL database and exposes an internal gRPC API. Wallet does not write GL tables directly, and GL does not write wallet tables. In normal operation a transaction requires both GL and Kuknos. If GL is unhealthy, all value-changing transaction admission and processing halt until it recovers. If Kuknos is unavailable, an authorized operator may explicitly enable GL-only operation through an AdminPanel toggle or configuration. Kuknos must never be disabled automatically.

Non-negotiable invariants

1. Every monetary journal is double entry. Signed entries sum to zero for each asset in a journal.
2. Journals and entries are append-only. Corrections append a full reversal and a replacement; update and delete operations are not exposed.
3. Amounts cross the API as canonical decimal strings and are stored as numeric(38,18). Floating-point values are rejected at the GL boundary.
4. A source idempotency key identifies one immutable payload. Replaying the same key and payload succeeds with the original result; reusing the key for different content fails.
5. Account, asset, source transaction, correlation, actor, occurrence time, and recording time are retained on every applicable record.
6. A journal commits atomically with all its entries or not at all.
7. A financial effect is journaled only when Wallet has committed that effect. Pending and failed lifecycle events may be retained as audit events but do not create monetary entries.
8. Derived balances are rebuildable solely by ordering and summing immutable entries. Cached balances are disposable projections, never source data.

Data model

ledger_accounts

A stable account is scoped to an asset and optional owner. Initial account classes are USER_AVAILABLE, USER_FROZEN, EXTERNAL_BLOCKCHAIN, TREASURY, MARKET_CLEARING, IPG_CLEARING, and COMMISSION_REVENUE. The natural identity (class, owner_type, owner_id, asset_id) is unique.

journals

Each journal contains a generated UUID, source service, unique idempotency key, source transaction ID and tracking code, effect kind and version, optional reversal target, occurred/recorded timestamps, correlation and actor IDs, blockchain network/hash/sequence references, and JSON metadata. A canonical payload hash detects conflicting reuse of an idempotency key.

entries

Each entry contains its journal ID, line number, ledger account, asset ID, signed decimal amount, and optional description. (journal_id, line_number) is unique. Positive means credit and negative means debit. Zero entries are invalid. Database constraints and the application transaction jointly enforce precision, immutability, account/asset agreement, and per-asset balance.

transaction_events

Lifecycle observations such as CREATED, PENDING_TRX, PENDING_ADMIN, FAILED, and SUCCESSFUL are append-only events keyed idempotently by source transaction and event version. They preserve error and blockchain metadata but are separate from monetary journals.

Wallet-to-ledger mapping

Every row below balances independently per asset. Where one business operation moves two assets, the entries belong to one correlated journal containing two balanced asset groups.

Wallet effect	Debit	Credit
Internal transfer	sender USER_AVAILABLE	recipient USER_AVAILABLE
External deposit	EXTERNAL_BLOCKCHAIN	recipient USER_AVAILABLE
External withdrawal	sender USER_AVAILABLE	EXTERNAL_BLOCKCHAIN
Freeze/lock	user USER_AVAILABLE	user USER_FROZEN
Release/unlock	user USER_FROZEN	user USER_AVAILABLE
IRT/IPG deposit	IPG_CLEARING	user USER_AVAILABLE
IRT withdrawal	user USER_AVAILABLE	IPG_CLEARING
Commission	payer or originating clearing account	COMMISSION_REVENUE
Buy/ICO	buyer IRT; treasury asset inventory	TREASURY IRT; buyer asset
Sell/redeem	seller asset; TREASURY IRT	treasury asset inventory; seller IRT
Market trade	buyer quote and seller base	seller quote and buyer base

Trustline creation is non-monetary and is recorded only as a transaction event. The adapter must derive accounts from stable IDs, not display names or public keys. Before integration, each existing Wallet call site must confirm its exact counterparty and fee legs; missing information is a validation failure, not an implicit suspense posting.

Delivery and ordering

Wallet owns a durable ledger_outbox table. The wallet state change, wallet transaction update, and outbox insert occur in the same PostgreSQL transaction. A dispatcher delivers events to GL with at-least-once semantics. It retries with backoff and never drops a record; poison records are quarantined and alerted but remain replayable.

The idempotency key format is wallet:<transaction-id>:<effect-kind>:v<event-version>. A transaction hash is metadata, not an identity, because it can be absent or replaced. GL serializes posts that affect the same accounts, records both source and receipt ordering, and returns the existing journal for identical duplicates. Together, the transactional outbox and GL idempotency provide effectively-once posting.

Wallet must not synchronously dual-write its database and GL. GL/network unavailability therefore cannot lose an already committed wallet effect and does not hold a wallet database transaction open.

Operating modes and failure semantics

• NORMAL: GL and Kuknos must both be healthy. A transaction is successful only after its required GL journal and Kuknos settlement evidence exist.
• KUKNOS_DISABLED: explicitly enabled and disabled by an authorized operator through AdminPanel or configuration. GL remains mandatory and authoritative; eligible transactions may proceed without Kuknos. Every mode transition must be immutable, attributable, time-bounded where configured, and emitted via OpenTelemetry. This mode is not implemented yet.
• RECONCILE: transaction processing is paused or restricted while tooling compares GL and Kuknos and appends approved reversals/corrections. Existing ledger records are never edited or deleted.

GL failure is always fail-closed. Public readiness reports a critical state and the incident and recovery are emitted through OpenTelemetry. Kuknos failure is also fail-closed unless KUKNOS_DISABLED has been explicitly authorized.

GL rejects unbalanced journals, invalid precision, unknown account/asset combinations, duplicate line numbers, missing source identity, conflicting idempotency payloads, and invalid reversals. Identical retries are successful. If Wallet cannot write its outbox in the local transaction, that wallet transaction rolls back. If dispatch fails, Wallet records retry state without changing the committed financial result.

Internal service boundary

The first ledger.v1.GeneralLedgerService contract provides:

• AppendJournal for one atomic, idempotent balanced journal;
• AppendTransactionEvent for non-monetary lifecycle history;
• GetJournal and ListEntries for audit and replay inspection;
• GetBalance for a rebuildable account/asset projection;
• Health for readiness and database health.

Wallet depends on its own Ledger port. Its gRPC implementation translates wallet domain values to this contract; Wallet never imports GL persistence types. Deadlines, retry classification, authentication, and correlation metadata are adapter concerns.

Implementation sequence

1. Add backward-compatible ledger/v1 protobuf messages and service methods.
2. Scaffold GL with domain, application, infrastructure, and interface layers.
3. Add explicit SQL migrations and a transactional PostgreSQL repository.
4. Implement invariant validation, idempotency, queries, and reversals.
5. Add Wallet's ledger port, gRPC adapter, transactional outbox, and dispatcher.
6. Map each Wallet transaction path and add outage/replay/reconciliation tests.

Initial non-goals

• Disabling Kuknos automatically on health-check failure.
• Editing or deleting posted journals.
• Storing binary floats or using Wallet's mutable transaction table as GL.
• Sharing a database schema between Wallet and GL.
• Migrating UI, documentation-site, or DevOps repositories.