gru_emoney_token-factory/docs/adapters/SWIFTAdapter.md

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:

<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