Core Ledger Service

Overview

The Core Ledger Service (CLS) is the heart of Kredete's financial record-keeping system. It implements a double-entry bookkeeping system that ensures all financial transactions are accurately recorded, traceable, and immutable.

Core Principles

Double-Entry Bookkeeping

Every transaction in the system results in at least two entries:

A debit entry to one account
A credit entry to another account

The fundamental equation that must always balance:

Accounting Equation

Assets = Liabilities + Equity

Or expanded: Assets + Expenses = Liabilities + Equity + Revenue

Immutability

Once a ledger entry is posted, it cannot be:

❌ Deleted
❌ Modified
❌ Backdated

Corrections are made through reversal entries that offset the original transaction.

Entry Types

Loan Disbursement

Transaction: Disbursing ₦500,000 loan to customer Reference: DISB-2026041600001 | Account | Debit (₦) | Credit (₦) | |--------------------------------|--------------|--------------| | 1200 - Loans Receivable | 500,000.00 | | | 1100 - Bank Account | | 495,000.00 | | 4200 - Processing Fee Income | | 5,000.00 | |--------------------------------|--------------|--------------| | TOTAL | 500,000.00 | 500,000.00 |

Loan Repayment

Transaction: Recording ₦55,000 loan repayment Reference: RPMT-2026051500001 | Account | Debit (₦) | Credit (₦) | |--------------------------------|--------------|--------------| | 1100 - Bank Account | 55,000.00 | | | 1200 - Loans Receivable | | 45,000.00 | | 4100 - Interest Income | | 10,000.00 | |--------------------------------|--------------|--------------| | TOTAL | 55,000.00 | 55,000.00 |

Interest Accrual

Transaction: Daily interest accrual Reference: ACCR-2026041600001 | Account | Debit (₦) | Credit (₦) | |--------------------------------|--------------|--------------| | 1210 - Accrued Interest Recv. | 416.67 | | | 4100 - Interest Income | | 416.67 | |--------------------------------|--------------|--------------| | TOTAL | 416.67 | 416.67 |

Write-Off

Transaction: Writing off uncollectible loan Reference: WOFF-2026041600001 | Account | Debit (₦) | Credit (₦) | |--------------------------------|--------------|--------------| | 1290 - Allowance for Loan Loss | 500,000.00 | | | 1200 - Loans Receivable | | 500,000.00 | |--------------------------------|--------------|--------------| | TOTAL | 500,000.00 | 500,000.00 |

Chart of Accounts

Code	Type	Account Name	Normal Balance
1000	Asset	Assets	Debit
1100	Asset	Cash and Bank	Debit
1200	Asset	Loans Receivable	Debit
1210	Asset	Accrued Interest Receivable	Debit
1290	Asset	Allowance for Loan Losses	Credit (contra)
2000	Liability	Liabilities	Credit
2100	Liability	Accounts Payable	Credit
2200	Liability	Customer Deposits	Credit
3000	Equity	Equity	Credit
3100	Equity	Share Capital	Credit
3200	Equity	Retained Earnings	Credit
4000	Revenue	Revenue	Credit
4100	Revenue	Interest Income	Credit
4200	Revenue	Processing Fee Income	Credit
5000	Expense	Expenses	Debit
5300	Expense	Provision for Bad Debts	Debit

Immutability & Hash Chain

Hash Calculation

Each entry's hash is calculated using:

def calculate_entry_hash(entry, previous_hash):
    data = f"{entry['entry_id']}" \
           f"{entry['journal_id']}" \
           f"{entry['account_id']}" \
           f"{entry['entry_type']}" \
           f"{entry['amount']}" \
           f"{entry['currency']}" \
           f"{entry['posted_at']}" \
           f"{previous_hash}"
    
    return hashlib.sha256(data.encode()).hexdigest()

Chain Verification

# Verify ledger integrity
kubectl exec -it kredete-ledger-pod -- ./bin/cli ledger verify \
  --from-date 2026-04-01 \
  --to-date 2026-04-16

# Expected output:
# Verifying ledger entries from 2026-04-01 to 2026-04-16
# Entries verified: 1,234,567
# Hash chain: ✓ Valid
# Balance check: ✓ Balanced
# Verification completed successfully

API Reference

Post Journal Entry

POST /v2/ledger/journals

{
  "journal_type": "loan_disbursement",
  "reference": "DISB-2026041600001",
  "effective_date": "2026-04-16",
  "description": "Loan disbursement for LOAN-2026-00001",
  "entries": [
    {
      "account_id": "acc_loans_receivable",
      "entry_type": "debit",
      "amount": 500000.00,
      "currency": "NGN"
    },
    {
      "account_id": "acc_bank_operating",
      "entry_type": "credit",
      "amount": 495000.00,
      "currency": "NGN"
    },
    {
      "account_id": "acc_fee_income",
      "entry_type": "credit",
      "amount": 5000.00,
      "currency": "NGN"
    }
  ]
}

Get Account Balance

GET /v2/ledger/accounts/{account_id}/balance?as_of=2026-04-16

Get Account Statement

GET /v2/ledger/accounts/{account_id}/statement?from=2026-04-01&to=2026-04-16