Initial commit

2025-12-12 15:02:56 -08:00
commit 849e6a8357
891 changed files with 167728 additions and 0 deletions
--- a/docs/flows/m-rtgs-settlement-flow.md
+++ b/docs/flows/m-rtgs-settlement-flow.md
@@ -0,0 +1,271 @@
+# 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)
+