Double Entry Ledger Fintech Expert

Double-Entry Ledger & FinTech Core Accounting Expert (2026 Edition)

English | Bahasa Indonesia

English

Orchestration & Integration

• Payment Gateways & Settlement: doku-payment-gateway, payment-gateway-expert, saas-billing, agentic-m2m-settlement, agentic-micro-economy-architect
• Database & Concurrency Locks: database-orm-expert, supabase-security-expert
• Formal Verification & Security: formal-spec-z3-verifier, zero-trust-secret-vault, anti-slop
• Lifecycle & Governance: brainstorming, zero-to-prod-orchestrator, session-memory-manager

Description

Mission-critical financial engineering guide for designing immutable Double-Entry Accounting Ledgers. Never track money using a mutable users.balance = users.balance - 100 column alone. Covers append-only journal entries, zero-sum balanced postings ($\sum \text{Debits} = \sum \text{Credits}$), two-phase pending/posted escrow holds, TigerBeetle high-throughput financial accounting, integer minor-unit arithmetic (BIGINT), and daily webhook-to-ledger reconciliation.

Trigger Conditions

• Building digital wallets, marketplace escrow systems, split payouts, or M2M agent clearing houses.
• Recording payment gateway webhooks (DOKU SNAP BI, Stripe, Xendit) into an auditable internal ledger.
• Implementing two-phase authorization holds (pending balance vs available balance).
• Preventing floating-point rounding bugs (0.1 + 0.2 !== 0.3) and race-condition double-spends.

Core Ledger Invariants

Core Implementation Patterns

1. PostgreSQL Immutable Double-Entry DDL Schema

sqlCopy code
CREATE TABLE IF NOT EXISTS ledger_accounts (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  tenant_id UUID NOT NULL,
  code VARCHAR(64) NOT NULL,
  name VARCHAR(128) NOT NULL,
  normal_balance VARCHAR(6) NOT NULL CHECK (normal_balance IN ('DEBIT', 'CREDIT')),
  currency CHAR(3) NOT NULL DEFAULT 'IDR',
  posted_balance_minor BIGINT NOT NULL DEFAULT 0,
  pending_hold_minor BIGINT NOT NULL DEFAULT 0,
  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
  UNIQUE (tenant_id, code)
);

CREATE INDEX IF NOT EXISTS idx_ledger_accounts_tenant ON ledger_accounts(tenant_id);

CREATE TABLE IF NOT EXISTS ledger_journals (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  tenant_id UUID NOT NULL,
  idempotency_key VARCHAR(128) UNIQUE NOT NULL,
  reference_type VARCHAR(64) NOT NULL,
  reference_id VARCHAR(128) NOT NULL,
  description TEXT NOT NULL,
  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

CREATE TABLE IF NOT EXISTS ledger_postings (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  journal_id UUID NOT NULL REFERENCES ledger_journals(id) ON DELETE RESTRICT,
  account_id UUID NOT NULL REFERENCES ledger_accounts(id) ON DELETE RESTRICT,
  direction VARCHAR(6) NOT NULL CHECK (direction IN ('DEBIT', 'CREDIT')),
  amount_minor BIGINT NOT NULL CHECK (amount_minor > 0),
  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

CREATE INDEX IF NOT EXISTS idx_ledger_postings_journal ON ledger_postings(journal_id);
CREATE INDEX IF NOT EXISTS idx_ledger_postings_account ON ledger_postings(account_id);

2. Deadlock-Free Atomic Journal Posting Engine (TypeScript)

typescriptCopy code
// src/ledger/post-journal.ts
export interface PostingLine {
  accountId: string;
  direction: 'DEBIT' | 'CREDIT';
  amountMinor: bigint;
}

export interface JournalCommand {
  tenantId: string;
  idempotencyKey: string;
  referenceType: 'DOKU_SETTLEMENT' | 'WALLET_TRANSFER' | 'REFUND_REVERSAL';
  referenceId: string;
  description: string;
  postings: readonly PostingLine[];
}

export function validateBalancedJournal(postings: readonly PostingLine[]): void {
  if (postings.length < 2) {
    throw new Error('[Ledger] A double-entry journal requires at least 2 postings');
  }

  let totalDebits = 0n;
  let totalCredits = 0n;

  for (const line of postings) {
    if (line.amountMinor <= 0n) {
      throw new Error(`[Ledger] Posting amount for account ${line.accountId} must be > 0`);
    }
    if (line.direction === 'DEBIT') {
      totalDebits += line.amountMinor;
    } else {
      totalCredits += line.amountMinor;
    }
  }

  if (totalDebits !== totalCredits) {
    throw new Error(
      `[Ledger] Unbalanced journal rejected: debits (${totalDebits}) !== credits (${totalCredits})`
    );
  }
}

export function getCanonicalLockOrder(postings: readonly PostingLine[]): string[] {
  return [...new Set(postings.map((p) => p.accountId))].sort((a, b) => a.localeCompare(b));
}

3. Two-Phase Authorization Hold & TigerBeetle Transfer Adapter (TypeScript)

Financial workflows (escrow, pre-authorization, agent budget limits) require two-phase settlement (PENDING hold $\rightarrow$ POSTED capture or VOID release):

typescriptCopy code
// src/ledger/tigerbeetle-two-phase.ts
export interface TigerBeetleTransfer {
  id: bigint;
  debitAccountId: bigint;
  creditAccountId: bigint;
  amountMinor: bigint;
  pendingId?: bigint;
  flags: {
    pending: boolean;
    postPendingTransfer: boolean;
    voidPendingTransfer: boolean;
  };
  timeoutSeconds?: number;
}

export class TigerBeetleLedgerAdapter {
  private readonly clusterId: bigint;
  private readonly replicaAddresses: readonly string[];

  constructor(clusterId: bigint, replicaAddresses: readonly string[]) {
    this.clusterId = clusterId;
    this.replicaAddresses = replicaAddresses;
  }

  public createAuthorizationHold(params: {
    transferId: bigint;
    debitAccountId: bigint;
    creditEscrowAccountId: bigint;
    amountMinor: bigint;
    timeoutSeconds: number;
  }): TigerBeetleTransfer {
    if (params.amountMinor <= 0n) {
      throw new Error('[TigerBeetle] Hold amount must be strictly positive');
    }

    return {
      id: params.transferId,
      debitAccountId: params.debitAccountId,
      creditAccountId: params.creditEscrowAccountId,
      amountMinor: params.amountMinor,
      flags: {
        pending: true,
        postPendingTransfer: false,
        voidPendingTransfer: false,
      },
      timeoutSeconds: params.timeoutSeconds,
    };
  }

  public capturePendingHold(params: {
    transferId: bigint;
    pendingTransferId: bigint;
    captureAmountMinor: bigint;
  }): TigerBeetleTransfer {
    return {
      id: params.transferId,
      debitAccountId: 0n,
      creditAccountId: 0n,
      amountMinor: params.captureAmountMinor,
      pendingId: params.pendingTransferId,
      flags: {
        pending: false,
        postPendingTransfer: true,
        voidPendingTransfer: false,
      },
    };
  }

  public voidPendingHold(params: {
    transferId: bigint;
    pendingTransferId: bigint;
  }): TigerBeetleTransfer {
    return {
      id: params.transferId,
      debitAccountId: 0n,
      creditAccountId: 0n,
      amountMinor: 0n,
      pendingId: params.pendingTransferId,
      flags: {
        pending: false,
        postPendingTransfer: false,
        voidPendingTransfer: true,
      },
    };
  }
}

Verification Checklist

• Every financial mutation validates $\sum \text{Debits} = \sum \text{Credits}$ before committing.
• ledger_journals and ledger_postings disallow UPDATE and DELETE operations; refunds create compensating reversal journals.
• Multi-account transfers lock ledger_accounts in ascending UUID order to guarantee zero deadlocks.
• Available balance is computed as posted_balance_minor - pending_hold_minor with non-negative check constraints for customer liability accounts.

Sovereign Execution, Token Efficiency & Invariants

Bahasa Indonesia

Integrasi Orkestrasi

• Payment Gateway & Settlement: doku-payment-gateway, payment-gateway-expert, saas-billing, agentic-m2m-settlement, agentic-micro-economy-architect
• Database & Penguncian Konkurensi: database-orm-expert, supabase-security-expert
• Verifikasi Formal & Keamanan: formal-spec-z3-verifier, zero-trust-secret-vault, anti-slop
• Siklus Hidup & Tata Kelola: brainstorming, zero-to-prod-orchestrator, session-memory-manager

Deskripsi

Panduan rekayasa finansial kritis untuk merancang buku besar akuntansi Double-Entry yang tidak dapat diubah (immutable). Mencakup pencatatan jurnal append-only, keseimbangan nol ($\sum \text{Debit} = \sum \text{Kredit}$), penahanan saldo dua fase (pending/escrow holds), aritmetika integer satuan terkecil (BIGINT), dan urutan penguncian akun kanonis bebas deadlock.

4 Invarian Buku Besar (Ledger Invariants)

1. Hukum Kekekalan Saldo ($\sum \text{Debit} = \sum \text{Kredit}$): Setiap transaksi jurnal wajib memiliki minimal 2 baris posting dengan total debit sama persis dengan total kredit.
2. Imutabilitas Mutlak (Append-Only): Tabel jurnal dan posting dilarang di-UPDATE atau di-DELETE. Koreksi atau refund wajib dilakukan melalui jurnal pembalik (compensating entry).
3. Satuan Terkecil Integer (BIGINT): Dilarang menggunakan FLOAT atau DOUBLE untuk uang.
4. Urutan Kunci Kanonis: Kunci baris akun menggunakan ORDER BY id ASC FOR UPDATE untuk mencegah deadlock saat dua transfer saling bersilangan.

Daftar Periksa Verifikasi (Checklist)

• Setiap mutasi keuangan memvalidasi $\sum \text{Debit} = \sum \text{Kredit}$ sebelum komit.
• Tabel jurnal dan posting bersifat append-only dengan idempotency_key unik.
• Penguncian multi-akun selalu diurutkan berdasarkan UUID secara menaik (ASC).

Matriks Eksekusi Berdaulat, Efisiensi Token & Invarian