# 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)

```xml
<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.