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
142 lines
3.8 KiB
Markdown
142 lines
3.8 KiB
Markdown
# SWIFT Adapter Specification
|
|
|
|
## Overview
|
|
|
|
The SWIFT adapter connects ChainID 138 eMoney Token Factory to the SWIFT network for international wire transfers. The adapter supports both SWIFT MT (Message Type) and ISO-20022 MX formats, normalizing all messages to ISO-20022 canonical format.
|
|
|
|
## Architecture
|
|
|
|
```
|
|
ChainID 138 Events → SWIFT Adapter → SWIFT Network (MT/MX) → Settlement Confirmation → ChainID 138
|
|
```
|
|
|
|
## Responsibilities
|
|
|
|
1. **Event Watching**: Monitor `TriggerCreated` events for SWIFT rail type
|
|
2. **Format Normalization**: Convert MT messages to ISO-20022 MX format
|
|
3. **SWIFT Submission**: Submit via SWIFT API (SWIFT gpi, Alliance Access, etc.)
|
|
4. **Attestation**: Submit confirmations to `SettlementOrchestrator`
|
|
|
|
## Event Monitoring
|
|
|
|
### Watched Events
|
|
|
|
- `RailTriggerRegistry.TriggerCreated` (filter: `rail == SWIFT`)
|
|
- `RailTriggerRegistry.TriggerStateUpdated` (filter: `rail == SWIFT`)
|
|
|
|
## Message Format Support
|
|
|
|
### SWIFT MT Messages
|
|
|
|
- **MT103**: Single Customer Credit Transfer
|
|
- **MT202**: General Financial Institution Transfer
|
|
- **MT900**: Confirmation of Debit
|
|
- **MT910**: Confirmation of Credit
|
|
- **MT192**: Request for Cancellation
|
|
|
|
### ISO-20022 MX Messages (Preferred)
|
|
|
|
- **pacs.008**: FIToFICustomerCreditTransfer
|
|
- **pacs.009**: FinancialInstitutionCreditTransfer
|
|
- **pacs.002**: Payment Status Report
|
|
- **camt.054**: BankToCustomerDebitCreditNotification
|
|
- **camt.056**: FIToFIPaymentCancellationRequest
|
|
|
|
## MT to MX Conversion
|
|
|
|
### MT103 → pacs.008
|
|
|
|
Key field mappings:
|
|
- Field 20 (Transaction Reference) → `PmtId.TxId`
|
|
- Field 32A (Value Date, Currency, Amount) → `Amt.InstdAmt`
|
|
- Field 50 (Ordering Customer) → `Dbtr`
|
|
- Field 59 (Beneficiary) → `Cdtr`
|
|
- Field 57A (Account With Institution) → `CdtrAgt`
|
|
|
|
## ISO-20022 Message Construction
|
|
|
|
### Outbound (pacs.008)
|
|
|
|
Similar structure to Fedwire, but with BIC codes:
|
|
|
|
```xml
|
|
<Document>
|
|
<FIToFICstmrCdtTrf>
|
|
<GrpHdr>
|
|
<MsgId>instructionId</MsgId>
|
|
<CreDtTm>timestamp</CreDtTm>
|
|
</GrpHdr>
|
|
<CdtTrfTxInf>
|
|
<PmtId>
|
|
<EndToEndId>endToEndId</EndToEndId>
|
|
<TxId>instructionId</TxId>
|
|
</PmtId>
|
|
<Amt>
|
|
<InstdAmt Ccy="EUR">amount</InstdAmt>
|
|
</Amt>
|
|
<CdtrAgt>
|
|
<FinInstnId>
|
|
<BICFI>BICCODE</BICFI>
|
|
</FinInstnId>
|
|
</CdtrAgt>
|
|
<Cdtr>
|
|
<Nm>recipientName</Nm>
|
|
<PstlAdr>
|
|
<Ctry>XX</Ctry>
|
|
</PstlAdr>
|
|
</Cdtr>
|
|
<CdtrAcct>
|
|
<Id>
|
|
<IBAN>IBAN</IBAN>
|
|
</Id>
|
|
</CdtrAcct>
|
|
</CdtTrfTxInf>
|
|
</FIToFICstmrCdtTrf>
|
|
</Document>
|
|
```
|
|
|
|
## On-Chain Attestation Flow
|
|
|
|
1. **Submit to Rail**:
|
|
- Call `SettlementOrchestrator.markSubmitted(triggerId, railTxRef)`
|
|
- `railTxRef` = SWIFT UETR (Unique End-to-End Transaction Reference) or MT reference
|
|
|
|
2. **Confirm Settlement**:
|
|
- On receipt of `camt.054` or `pacs.002` with status "ACSC":
|
|
- Call `SettlementOrchestrator.confirmSettled(triggerId, railTxRef)`
|
|
|
|
3. **Handle Rejections**:
|
|
- On MT192 or rejection status:
|
|
- Call `SettlementOrchestrator.confirmRejected(triggerId, reason)`
|
|
|
|
## SWIFT gpi Integration
|
|
|
|
If using SWIFT gpi (Global Payments Innovation):
|
|
- Track payment status via gpi Tracker API
|
|
- Use UETR for end-to-end tracking
|
|
- Implement gpi status callbacks
|
|
|
|
## Account Resolution
|
|
|
|
- `accountRefId` → SWIFT account details (BIC, IBAN, or account number)
|
|
- Support multiple account identifier formats
|
|
|
|
## Error Handling
|
|
|
|
- **Network Errors**: Retry with exponential backoff
|
|
- **Invalid BIC/IBAN**: Validate before submission
|
|
- **Timeout**: SWIFT typically 1-5 business days
|
|
|
|
## Security Considerations
|
|
|
|
- SWIFT PKI certificates for authentication
|
|
- Secure storage of BIC codes and credentials
|
|
- Implement SWIFT security best practices
|
|
|
|
## Testing
|
|
|
|
- Unit tests for MT/MX conversion
|
|
- Integration tests with SWIFT test environment
|
|
- gpi tracker integration tests
|
|
|