651ff4f7eb
- Add Foundry project configuration (foundry.toml, foundry.lock) - Add Solidity contracts (TokenFactory138, BridgeVault138, ComplianceRegistry, etc.) - Add API definitions (OpenAPI, GraphQL, gRPC, AsyncAPI) - Add comprehensive test suite (unit, integration, fuzz, invariants) - Add API services (REST, GraphQL, orchestrator, packet service) - Add documentation (ISO20022 mapping, runbooks, adapter guides) - Add development tools (RBC tool, Swagger UI, mock server) - Update OpenZeppelin submodules to v5.0.0
153 lines
4.3 KiB
Markdown
153 lines
4.3 KiB
Markdown
# 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.
|
|
|