dbis_core/docs/flows/m-rtgs-settlement-flow.md

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
• GSS Settlement Flow
• Atomic Settlement Flow