313 lines
9.3 KiB
Markdown
313 lines
9.3 KiB
Markdown
|
# 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)
|
||
|
|
|