# 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