# 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

```http
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

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

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

### Get Balance

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

### Create Transfer

```http
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](./ledger-service.md#integration) for detailed integration examples.
