# SSU Mint Burn Flow

## Overview

The Synthetic Settlement Unit (SSU) is a stabilized cross-border settlement asset with composition: 40% currency, 30% commodity, 20% CBDC, 10% LAM. This flow documents the minting and burning processes, including composition calculation and liquidity verification.

## Prerequisites

- SSU exists or can be created (default SSU)
- Sufficient liquidity in underlying assets (for minting)
- Valid mint/burn request
- SSU service operational
- Composition service available

## Visual Flow Diagram

### Minting Flow

```
┌─────────────┐
│ Mint Request│
└──────┬──────┘
       │
       │ 1. Get/Create SSU
       ▼
┌─────────────────────────┐
│ Get or Create Default   │
│  SSU                     │
│  - Lookup active SSU     │
│  - Create if not exists  │
└──────┬──────────────────┘
       │
       │ 2. Verify Liquidity
       ▼
┌─────────────────────────┐
│ Verify Liquidity for    │
│  Minting                 │
│  - Check underlying      │
│  - Verify sufficient     │
└──────┬──────────────────┘
       │
       │ 3. Calculate Composition
       ▼
┌─────────────────────────┐
│ Calculate SSU            │
│  Composition              │
│  - 40% currency          │
│  - 30% commodity         │
│  - 20% CBDC              │
│  - 10% LAM               │
└──────┬──────────────────┘
       │
       │ 4. Create Transaction
       ▼
┌─────────────────────────┐
│ Create Mint Transaction │
│  - Transaction ID        │
│  - Amount                │
│  - Type: mint            │
└──────┬──────────────────┘
       │
       │ 5. Complete
       ▼
┌─────────────┐
│ SSU Minted  │
└─────────────┘
```

### Burning Flow

```
┌─────────────┐
│ Burn Request│
└──────┬──────┘
       │
       │ 1. Verify SSU
       ▼
┌─────────────────────────┐
│ Verify SSU Exists        │
│  - Lookup SSU by ID       │
│  - Check status: active   │
└──────┬──────────────────┘
       │
       │ 2. Create Transaction
       ▼
┌─────────────────────────┐
│ Create Burn Transaction  │
│  - Transaction ID        │
│  - Amount                │
│  - Type: burn            │
└──────┬──────────────────┘
       │
       │ 3. Complete
       ▼
┌─────────────┐
│ SSU Burned  │
└─────────────┘
```

## Step-by-Step Process

### Minting Process

#### Step 1: Get or Create Default SSU
1. Receive mint request with:
   - Amount to mint
   - Trigger bank ID (optional)
   - Transaction ID (optional)
2. Lookup default SSU:
   - Search for SSU with name: "DBIS Global SSU"
   - Filter by status: `active`
3. If SSU doesn't exist:
   - Generate SSU ID: `SSU-{uuid}`
   - Create SSU record:
     - SSU ID
     - SSU name: "DBIS Global SSU"
     - Description: "DBIS Synthetic Settlement Unit - Global settlement asset"
     - Underlying assets: empty array (initialized later)
     - Status: `active`
   - Initialize composition via composition service
4. Return SSU (existing or newly created)

**Code Reference**: `src/core/settlement/ssu/ssu-service.ts:46-208`

#### Step 2: Verify Liquidity for Minting
1. Validate mint amount:
   - Convert to Decimal
   - Verify: `amount > 0`
   - If invalid, throw error: "Mint amount must be greater than zero"
2. Verify underlying asset liquidity:
   - In production: check liquidity pools for:
     - 40% currency reserves
     - 30% commodity reserves
     - 20% CBDC reserves
     - 10% LAM reserves
   - Currently: assume liquidity available (simplified)
3. If insufficient liquidity, throw error

**Code Reference**: `src/core/settlement/ssu/ssu-service.ts:213-221`

#### Step 3: Calculate Composition
1. Call composition service to calculate current composition:
   - Pass SSU ID
   - Service calculates based on:
     - Current market values
     - Reserve availability
     - Target composition ratios
2. Composition service returns:
   - Currency percentage: 40%
   - Commodity percentage: 30%
   - CBDC percentage: 20%
   - LAM percentage: 10%
3. Store composition for this mint operation

**Code Reference**: `src/core/settlement/ssu/ssu-composition.service.ts`

#### Step 4: Create Mint Transaction
1. Call SSU transaction service to create transaction:
   - SSU ID
   - Transaction type: `mint`
   - Amount: mint amount
   - Source bank ID: trigger bank ID (if provided)
   - Settlement ID: transaction ID (if provided)
2. Transaction service creates:
   - Transaction ID
   - Transaction record
   - Links to SSU
3. Update SSU balance (if tracked):
   - In production: increment SSU total supply
   - Currently: simplified (balance tracking)
4. Return transaction ID

**Code Reference**: `src/core/settlement/ssu/ssu-service.ts:57-68`

### Burning Process

#### Step 1: Verify SSU Exists
1. Receive burn request with:
   - SSU ID
   - Amount to burn
   - Reason (optional)
2. Lookup SSU by ID
3. Verify SSU exists and status is `active`
4. If not found or inactive, throw error: "SSU not found or not active"

**Code Reference**: `src/core/settlement/ssu/ssu-service.ts:74-94`

#### Step 2: Create Burn Transaction
1. Call SSU transaction service to create transaction:
   - SSU ID
   - Transaction type: `burn`
   - Amount: burn amount
2. Transaction service creates:
   - Transaction ID
   - Transaction record
   - Links to SSU
3. Update SSU balance (if tracked):
   - In production: decrement SSU total supply
   - Currently: simplified (balance tracking)
4. Return transaction ID

**Code Reference**: `src/core/settlement/ssu/ssu-service.ts:84-93`

## Error Handling

### Error: SSU Not Found
- **Detection**: SSU lookup returns null
- **Action**: Throw error "SSU not found or not active"
- **Recovery**: Verify SSU ID, create SSU if needed

### Error: SSU Inactive
- **Detection**: SSU status is not `active`
- **Action**: Throw error "SSU not found or not active"
- **Recovery**: Activate SSU, retry

### Error: Invalid Mint Amount
- **Detection**: Amount <= 0
- **Action**: Throw error "Mint amount must be greater than zero"
- **Recovery**: Correct amount, retry

### Error: Insufficient Liquidity
- **Detection**: Underlying assets don't have sufficient liquidity
- **Action**: Throw error, prevent minting
- **Recovery**: Add liquidity to pools, retry

### Error: Composition Calculation Failure
- **Detection**: Composition service returns error
- **Action**: Throw error, prevent minting
- **Recovery**: Verify composition service, retry

## Integration Points

### Related Services
- **SSU Service**: `src/core/settlement/ssu/ssu-service.ts`
- **SSU Composition Service**: `src/core/settlement/ssu/ssu-composition.service.ts`
- **SSU Transaction Service**: `src/core/settlement/ssu/ssu-transaction.service.ts`
- **Liquidity Services**: GLP, ID-SLG for liquidity verification

### API Endpoints
- `POST /api/v1/ssu/mint` - Mint SSU
- `POST /api/v1/ssu/burn` - Burn SSU
- `GET /api/v1/ssu/:ssuId` - Get SSU details
- `GET /api/v1/ssu` - List active SSUs

### Database Models
- `SyntheticSettlementUnit` - SSU records
- `SsuTransaction` - SSU transaction records
- `SsuComposition` - Composition records

## Performance Metrics

- **SSU Lookup/Creation**: < 10ms target
- **Liquidity Verification**: < 20ms target
- **Composition Calculation**: < 30ms target
- **Transaction Creation**: < 10ms target
- **Total End-to-End**: < 70ms target
- **Throughput**: 5,000+ operations/second
- **Availability**: 99.99% uptime target

## Security Considerations

### SSU Validation
- Only active SSUs can be used
- SSU ID verification prevents unauthorized access

### Liquidity Verification
- Ensures underlying assets available
- Prevents over-minting
- Maintains composition ratios

### Transaction Tracking
- All mint/burn operations logged
- Transaction IDs provide audit trail
- Links to source transactions

## Testing Scenarios

### Happy Path - Minting
1. Valid mint request
2. SSU exists or created
3. Sufficient liquidity
4. Composition calculated
5. Transaction created
6. SSU minted

### Happy Path - Burning
1. Valid burn request
2. SSU exists and active
3. Transaction created
4. SSU burned

### Error Scenarios
1. SSU not found
2. SSU inactive
3. Invalid mint amount
4. Insufficient liquidity
5. Composition calculation failure

### Edge Cases
1. Maximum mint amount
2. Minimum mint amount
3. Mint with zero amount (should fail)
4. Burn more than available
5. Concurrent mint/burn operations

---

**Related Flows**:
- [SSU Atomic Settlement Flow](./ssu-atomic-settlement-flow.md)
- [FX/SSU Integration Flow](./fx-ssu-integration-flow.md)
- [GLP Contribution Withdrawal Flow](./glp-contribution-withdrawal-flow.md)