272 lines
8.6 KiB
Markdown
272 lines
8.6 KiB
Markdown
|
# M-RTGS Settlement Flow
|
||
|
|
|
||
|
|
## Overview
|
||
|
|
|
||
|
|
The Multi-Asset RTGS System (M-RTGS) provides instantaneous settlement (< 100ms target) for multiple asset types (fiat, CBDC, SSU, commodities, securities) in a single synchronized settlement cycle. This flow documents the priority queue management and multi-asset settlement process.
|
||
|
|
|
||
|
|
## Prerequisites
|
||
|
|
|
||
|
|
- Payment request with valid source and destination accounts
|
||
|
|
- Sufficient balance/position in source account
|
||
|
|
- Asset type supported by M-RTGS
|
||
|
|
- M-RTGS service operational
|
||
|
|
- Queue manager initialized
|
||
|
|
|
||
|
|
## Visual Flow Diagram
|
||
|
|
|
||
|
|
```
|
||
|
|
┌─────────────┐
|
||
|
|
│ Payment │
|
||
|
|
│ Request │
|
||
|
|
└──────┬──────┘
|
||
|
|
│
|
||
|
|
│ 1. Add to Queue
|
||
|
|
▼
|
||
|
|
┌─────────────────────────┐
|
||
|
|
│ Queue Manager │
|
||
|
|
│ - Calculate priority │
|
||
|
|
│ - Priority = systemic │
|
||
|
|
│ + fx_cost + │
|
||
|
|
│ liquidity + SRI │
|
||
|
|
└──────┬──────────────────┘
|
||
|
|
│
|
||
|
|
│ 2. Priority Score
|
||
|
|
▼
|
||
|
|
┌─────────────────────────┐
|
||
|
|
│ Queue Processing │
|
||
|
|
│ - Tier 1: Sovereign │
|
||
|
|
│ - Tier 2: Interbank │
|
||
|
|
│ - Tier 3: Retail │
|
||
|
|
└──────┬──────────────────┘
|
||
|
|
│
|
||
|
|
│ 3. Process Next
|
||
|
|
▼
|
||
|
|
┌─────────────────────────┐
|
||
|
|
│ Risk Monitor │
|
||
|
|
│ - Velocity check │
|
||
|
|
│ - Liquidity check │
|
||
|
|
│ - FX slip check │
|
||
|
|
└──────┬──────────────────┘
|
||
|
|
│
|
||
|
|
│ 4. Risk Cleared
|
||
|
|
▼
|
||
|
|
┌─────────────────────────┐
|
||
|
|
│ Multi-Asset Settlement │
|
||
|
|
│ - Multi-ledger sync │
|
||
|
|
│ - < 100ms target │
|
||
|
|
│ - Status tracking │
|
||
|
|
└──────┬──────────────────┘
|
||
|
|
│
|
||
|
|
│ 5. Settled
|
||
|
|
▼
|
||
|
|
┌─────────────┐
|
||
|
|
│ Settlement │
|
||
|
|
│ Complete │
|
||
|
|
└─────────────┘
|
||
|
|
```
|
||
|
|
|
||
|
|
## Step-by-Step Process
|
||
|
|
|
||
|
|
### Step 1: Payment Queue Addition
|
||
|
|
1. Receive payment request with:
|
||
|
|
- Source bank ID
|
||
|
|
- Destination bank ID
|
||
|
|
- Amount and currency
|
||
|
|
- Asset type (fiat, CBDC, SSU, commodity, security)
|
||
|
|
- Payment priority
|
||
|
|
2. Calculate priority score:
|
||
|
|
```
|
||
|
|
priority = systemic_value + fx_cost_penalty + liquidity_weight + SRI_adjustment
|
||
|
|
```
|
||
|
|
3. Determine priority tier:
|
||
|
|
- **Tier 1**: Sovereign & systemic transactions
|
||
|
|
- **Tier 2**: Interbank transactions
|
||
|
|
- **Tier 3**: Retail CBDC traffic during peak hours
|
||
|
|
4. Add payment to appropriate queue with priority score
|
||
|
|
5. Generate queue entry ID
|
||
|
|
|
||
|
|
**Code Reference**: `src/core/settlement/m-rtgs/` (queue manager service)
|
||
|
|
|
||
|
|
### Step 2: Queue Processing
|
||
|
|
1. Queue manager selects next payment based on:
|
||
|
|
- Priority tier
|
||
|
|
- Priority score within tier
|
||
|
|
- First-in-first-out for same priority
|
||
|
|
2. Lock payment entry to prevent concurrent processing
|
||
|
|
3. Verify payment still valid:
|
||
|
|
- Source account still active
|
||
|
|
- Sufficient balance available
|
||
|
|
- Destination account still active
|
||
|
|
|
||
|
|
### Step 3: Risk Monitoring
|
||
|
|
1. Check transaction velocity:
|
||
|
|
- Count transactions from source in time window
|
||
|
|
- Verify within velocity limits
|
||
|
|
2. Check liquidity congestion:
|
||
|
|
- Verify sufficient liquidity in system
|
||
|
|
- Check for liquidity bottlenecks
|
||
|
|
3. Check FX slip (if cross-currency):
|
||
|
|
- Verify FX rate stability
|
||
|
|
- Check for excessive volatility
|
||
|
|
4. Check commodity price shocks (if commodity asset):
|
||
|
|
- Verify commodity price stability
|
||
|
|
5. Check CBDC routing patterns:
|
||
|
|
- Verify no abnormal routing detected
|
||
|
|
6. If any risk check fails, flag payment and escalate
|
||
|
|
|
||
|
|
**Code Reference**: `src/core/settlement/m-rtgs/` (risk monitor service)
|
||
|
|
|
||
|
|
### Step 4: Multi-Asset Settlement Execution
|
||
|
|
1. Determine settlement method based on asset type:
|
||
|
|
- **Fiat**: Standard ledger posting
|
||
|
|
- **CBDC**: CBDC ledger posting
|
||
|
|
- **SSU**: SSU transaction service
|
||
|
|
- **Commodity**: CDT settlement service
|
||
|
|
- **Security**: Security token settlement
|
||
|
|
2. Execute multi-ledger synchronization:
|
||
|
|
- Post to source ledger
|
||
|
|
- Post to destination ledger
|
||
|
|
- Post to master ledger (if required)
|
||
|
|
3. Monitor settlement time:
|
||
|
|
- Start timer at settlement initiation
|
||
|
|
- Target: < 100ms total time
|
||
|
|
- Log if exceeds target
|
||
|
|
4. Update payment status:
|
||
|
|
- Mark as "settling" during execution
|
||
|
|
- Mark as "settled" on completion
|
||
|
|
- Record settlement timestamp
|
||
|
|
|
||
|
|
**Code Reference**:
|
||
|
|
- `src/core/settlement/m-rtgs/` (settlement service)
|
||
|
|
- `src/core/ledger/ledger.service.ts`
|
||
|
|
- `src/core/settlement/ssu/ssu-service.ts`
|
||
|
|
- `src/core/commodities/cbds/cdt-settlement.service.ts`
|
||
|
|
|
||
|
|
### Step 5: MACE Integration (if collateralized)
|
||
|
|
1. If payment requires collateral:
|
||
|
|
- Calculate required initial margin (IM):
|
||
|
|
```
|
||
|
|
IM = exposure * volatility * SRI_factor
|
||
|
|
```
|
||
|
|
- Verify collateral availability
|
||
|
|
- Allocate collateral via MACE engine
|
||
|
|
2. Update collateral positions
|
||
|
|
3. Monitor margin requirements
|
||
|
|
|
||
|
|
**Code Reference**: `src/core/settlement/m-rtgs/` (MACE integration service)
|
||
|
|
|
||
|
|
### Step 6: Settlement Confirmation
|
||
|
|
1. Verify all ledger entries posted successfully
|
||
|
|
2. Generate settlement confirmation
|
||
|
|
3. Update queue entry status
|
||
|
|
4. Release queue lock
|
||
|
|
5. Notify payment initiator
|
||
|
|
6. Log settlement event with metrics
|
||
|
|
|
||
|
|
## Error Handling
|
||
|
|
|
||
|
|
### Error: Insufficient Balance
|
||
|
|
- **Detection**: Balance check fails
|
||
|
|
- **Action**: Remove from queue, return error
|
||
|
|
- **Recovery**: Notify initiator, suggest alternative
|
||
|
|
|
||
|
|
### Error: Risk Check Failed
|
||
|
|
- **Detection**: Risk monitor flags payment
|
||
|
|
- **Action**: Hold payment, escalate to operations
|
||
|
|
- **Recovery**: Manual review, adjust risk parameters if needed
|
||
|
|
|
||
|
|
### Error: Settlement Timeout
|
||
|
|
- **Detection**: Settlement exceeds 100ms target
|
||
|
|
- **Action**: Log warning, continue processing
|
||
|
|
- **Recovery**: Investigate performance bottleneck
|
||
|
|
|
||
|
|
### Error: Multi-Ledger Sync Failure
|
||
|
|
- **Detection**: One or more ledger posts fail
|
||
|
|
- **Action**: Rollback all ledger entries
|
||
|
|
- **Recovery**: Retry settlement, escalate if persistent
|
||
|
|
|
||
|
|
### Error: Queue Lock Timeout
|
||
|
|
- **Detection**: Payment locked too long
|
||
|
|
- **Action**: Release lock, retry or fail
|
||
|
|
- **Recovery**: Investigate deadlock conditions
|
||
|
|
|
||
|
|
## Integration Points
|
||
|
|
|
||
|
|
### Related Services
|
||
|
|
- **M-RTGS Queue Manager**: `src/core/settlement/m-rtgs/` (queue manager)
|
||
|
|
- **M-RTGS Settlement Service**: `src/core/settlement/m-rtgs/` (settlement)
|
||
|
|
- **M-RTGS Risk Monitor**: `src/core/settlement/m-rtgs/` (risk monitor)
|
||
|
|
- **M-RTGS MACE Integration**: `src/core/settlement/m-rtgs/` (MACE)
|
||
|
|
- **Ledger Service**: `src/core/ledger/ledger.service.ts`
|
||
|
|
- **SSU Service**: `src/core/settlement/ssu/ssu-service.ts`
|
||
|
|
- **CDT Settlement**: `src/core/commodities/cbds/cdt-settlement.service.ts`
|
||
|
|
|
||
|
|
### API Endpoints
|
||
|
|
- `POST /api/v1/m-rtgs/queue/add` - Add payment to queue
|
||
|
|
- `GET /api/v1/m-rtgs/queue/next` - Get next payment from queue
|
||
|
|
- `POST /api/v1/m-rtgs/settle` - Execute settlement
|
||
|
|
- `POST /api/v1/m-rtgs/risk/monitor` - Risk monitoring
|
||
|
|
|
||
|
|
### Database Models
|
||
|
|
- `MrtgsQueue` - Queue entries with priority scores
|
||
|
|
- `MrtgsSettlement` - Settlement records with multi-asset support
|
||
|
|
- `MrtgsRiskAlert` - Risk monitoring alerts
|
||
|
|
|
||
|
|
## Performance Metrics
|
||
|
|
|
||
|
|
- **Queue Addition**: < 10ms target
|
||
|
|
- **Priority Calculation**: < 5ms target
|
||
|
|
- **Risk Monitoring**: < 20ms target
|
||
|
|
- **Settlement Execution**: < 100ms target (total)
|
||
|
|
- **Total End-to-End**: < 135ms target
|
||
|
|
- **Throughput**: 50,000+ payments/second
|
||
|
|
- **Availability**: 99.99% uptime target
|
||
|
|
|
||
|
|
## Security Considerations
|
||
|
|
|
||
|
|
### Access Control
|
||
|
|
- Only authorized banks can submit payments
|
||
|
|
- Queue access restricted to M-RTGS service
|
||
|
|
|
||
|
|
### Data Integrity
|
||
|
|
- Queue entries locked during processing
|
||
|
|
- Multi-ledger synchronization ensures consistency
|
||
|
|
- Settlement timestamps provide audit trail
|
||
|
|
|
||
|
|
### Risk Controls
|
||
|
|
- Real-time velocity monitoring
|
||
|
|
- Liquidity congestion detection
|
||
|
|
- FX and commodity price shock detection
|
||
|
|
|
||
|
|
## Testing Scenarios
|
||
|
|
|
||
|
|
### Happy Path
|
||
|
|
1. Valid payment request
|
||
|
|
2. Successful queue addition
|
||
|
|
3. Priority calculation correct
|
||
|
|
4. Risk checks pass
|
||
|
|
5. Settlement completes < 100ms
|
||
|
|
6. All ledgers synchronized
|
||
|
|
|
||
|
|
### Error Scenarios
|
||
|
|
1. Insufficient balance
|
||
|
|
2. Risk check failure
|
||
|
|
3. Settlement timeout
|
||
|
|
4. Multi-ledger sync failure
|
||
|
|
5. Queue lock timeout
|
||
|
|
|
||
|
|
### Edge Cases
|
||
|
|
1. Maximum priority payment
|
||
|
|
2. Minimum priority payment
|
||
|
|
3. All asset types
|
||
|
|
4. Concurrent high-priority payments
|
||
|
|
5. System under heavy load
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
**Related Flows**:
|
||
|
|
- [GPN Payment Flow](./gpn-payment-flow.md)
|
||
|
|
- [GSS Settlement Flow](./gss-settlement-flow.md)
|
||
|
|
- [Atomic Settlement Flow](./atomic-settlement-flow.md)
|
||
|
|
|