gru_emoney_token-factory/docs/adapters/RTGSAdapter.md

RTGS Adapter Specification

Overview

The RTGS (Real-Time Gross Settlement) adapter provides a generic framework for connecting to RTGS systems across different jurisdictions. RTGS systems settle payments individually and in real-time, making them suitable for high-value, time-critical transfers.

Architecture

ChainID 138 Events → RTGS Adapter → RTGS System (Jurisdiction-Specific) → Settlement Confirmation → ChainID 138

Responsibilities

1. Event Watching: Monitor TriggerCreated events for RTGS rail type
2. RTGS Message Construction: Build jurisdiction-specific messages (often ISO-20022 based)
3. RTGS Submission: Submit via RTGS API (varies by jurisdiction)
4. Attestation: Submit confirmations to SettlementOrchestrator

Event Monitoring

Watched Events

• RailTriggerRegistry.TriggerCreated (filter: rail == RTGS)
• RailTriggerRegistry.TriggerStateUpdated (filter: rail == RTGS)

RTGS Systems by Jurisdiction

Examples

• US: Fedwire (covered by FedwireAdapter)
• UK: CHAPS (Clearing House Automated Payment System)
• Canada: LVTS (Large Value Transfer System)
• Australia: RITS (Reserve Bank Information and Transfer System)
• Japan: BOJ-NET (Bank of Japan Financial Network System)
• India: RTGS (Reserve Bank of India)

Generic RTGS Message Structure

Most RTGS systems use ISO-20022 or similar structures:

Outbound (pacs.008 or jurisdiction-specific)

<Document>
  <FIToFICstmrCdtTrf>
    <GrpHdr>
      <MsgId>instructionId</MsgId>
      <CreDtTm>timestamp</CreDtTm>
    </GrpHdr>
    <CdtTrfTxInf>
      <PmtId>
        <EndToEndId>endToEndId</EndToEndId>
        <TxId>instructionId</TxId>
      </PmtId>
      <Amt>
        <InstdAmt Ccy="XXX">amount</InstdAmt>
      </Amt>
      <CdtrAgt>
        <FinInstnId>
          <!-- Jurisdiction-specific identifier -->
        </FinInstnId>
      </CdtrAgt>
      <Cdtr>
        <Nm>recipientName</Nm>
      </Cdtr>
      <CdtrAcct>
        <Id>
          <!-- Jurisdiction-specific account identifier -->
        </Id>
      </CdtrAcct>
    </CdtTrfTxInf>
  </FIToFICstmrCdtTrf>
</Document>

Jurisdiction-Specific Considerations

CHAPS (UK)

• Currency: GBP
• Message: ISO-20022 or CHAPS-specific format
• Settlement: Real-time during business hours
• Account: Sort code + account number

LVTS (Canada)

• Currency: CAD
• Message: ISO-20022
• Settlement: Real-time
• Account: Transit number + account number

RITS (Australia)

• Currency: AUD
• Message: ISO-20022
• Settlement: Real-time
• Account: BSB + account number

On-Chain Attestation Flow

1. Submit to Rail:

   • Call SettlementOrchestrator.markSubmitted(triggerId, railTxRef)
   • railTxRef = RTGS transaction reference (format varies by jurisdiction)

2. Confirm Settlement:

   • RTGS systems typically provide immediate confirmation
   • On receipt of confirmation:
     • Call SettlementOrchestrator.confirmSettled(triggerId, railTxRef)

3. Handle Rejections:

   • RTGS systems may reject due to:
     • Insufficient funds
     • Invalid account
     • System limits
   • Call SettlementOrchestrator.confirmRejected(triggerId, reason)

Account Resolution

• accountRefId → RTGS account details (format varies by jurisdiction)
• Maintain jurisdiction-specific account identifier mappings

RTGS Characteristics

• Real-Time: Settlements occur immediately
• Gross Settlement: Each transaction settled individually
• High Value: Typically used for large-value transfers
• Business Hours: Most RTGS systems operate during business hours only

Error Handling

• Network Errors: Retry with exponential backoff
• Invalid Account: Validate before submission
• System Limits: Check RTGS system limits
• Business Hours: Queue if outside operating hours

Security Considerations

• RTGS systems typically require strong authentication
• Secure storage of credentials and account identifiers
• Implement jurisdiction-specific security requirements

Testing

• Unit tests for jurisdiction-specific message formats
• Integration tests with RTGS test environments
• Jurisdiction-specific flow tests

Implementation Notes

This adapter should be implemented as a base class with jurisdiction-specific subclasses, or use a plugin architecture to support multiple RTGS systems.