dbis_core/docs/flows/ssu-mint-burn-flow.md

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
• FX/SSU Integration Flow
• GLP Contribution Withdrawal Flow