Sankofa/docs/marketplace/sovereign-stack/ledger-service.md

Phoenix Ledger Service

Category: LEDGER_SERVICES
Publisher: Phoenix Cloud Services
Status: PUBLISHED
Version: 1.0.0

Overview

Phoenix Ledger Service is a sovereign-grade double-entry ledger system with virtual accounts, holds, and multi-asset support. It replaces reliance on external platforms (e.g., Tatum Virtual Accounts) with owned core primitives.

Key Features

• Double-entry accounting: Every transaction is a balanced journal entry
• Virtual account abstraction: Subaccounts for multi-currency/asset support
• Holds and reserves: Reserve funds with expiry and automatic release
• Multi-asset support: Fiat, stablecoins, tokens in unified system
• Reconciliation engine: Automated reconciliation and audit trail
• Idempotent operations: All operations idempotent via correlation_id
• State machine settlement: Clear settlement states (initiated → authorized → captured → settled → reversed)

API Endpoints

Create Journal Entry

POST /ledger/entries
Content-Type: application/json

{
  "correlationId": "tx_123456",
  "description": "Payment from user",
  "lines": [
    {
      "accountRef": "account:user_123",
      "debit": 100.00,
      "credit": 0,
      "asset": "USD"
    },
    {
      "accountRef": "account:treasury",
      "debit": 0,
      "credit": 100.00,
      "asset": "USD"
    }
  ]
}

Create Hold

POST /ledger/holds
Content-Type: application/json

{
  "accountId": "account:user_123",
  "amount": 50.00,
  "asset": "USD",
  "expiry": "2024-12-31T23:59:59Z"
}

Get Balance

GET /ledger/balances?accountId=account:user_123&asset=USD

Create Transfer

POST /ledger/transfers
Content-Type: application/json

{
  "fromAccountId": "account:user_123",
  "toAccountId": "account:user_456",
  "amount": 25.00,
  "asset": "USD",
  "correlationId": "transfer_789"
}

Data Model

Accounts

• account_id: Unique account identifier
• owner_id: User or organization ID
• type: USER, TREASURY, CLEARING
• status: ACTIVE, SUSPENDED, CLOSED

Subaccounts (Virtual Accounts)

• subaccount_id: Unique subaccount identifier
• account_id: Parent account reference
• currency/asset: Asset type (USD, USDC, etc.)
• labels: Key-value metadata

Journal Entries

• entry_id: Unique entry identifier
• timestamp: Entry timestamp
• description: Human-readable description
• correlation_id: Idempotency key

Journal Lines

• entry_id: Journal entry reference
• account_ref: Account or subaccount reference
• debit: Debit amount
• credit: Credit amount
• asset: Asset type

Pricing

• Model: Usage-based
• Free Tier: 10,000 journal entries/month
• Pricing:
  • Journal entry: $0.001
  • Hold operation: $0.0005
  • Transfer: $0.002

Compliance

• SOC 2 Type II
• PCI DSS Level 1
• GDPR compliant

SLA

• Uptime: 99.9%
• Latency: <100ms p95

Architecture

The ledger service uses PostgreSQL with:

• Partitioned journal tables by month
• Materialized views for balance calculations
• Event sourcing for audit trail
• Outbox pattern for event emission

Integration

See Integration Guide for detailed integration examples.