gru_emoney_token-factory/docs/adapters/FedwireAdapter.md

Fedwire Adapter Specification

Overview

The Fedwire adapter connects ChainID 138 eMoney Token Factory to the Federal Reserve Wire Network (Fedwire) for USD-denominated transfers. The adapter watches on-chain events and submits ISO-20022 formatted messages to Fedwire, then reports settlement status back to the chain.

Architecture

ChainID 138 Events → Fedwire Adapter → Fedwire Network → Settlement Confirmation → ChainID 138

Responsibilities

1. Event Watching: Monitor TriggerCreated events from RailTriggerRegistry for Fedwire rail type
2. Message Construction: Build ISO-20022 messages (primarily pacs.008 for outbound, camt.054 for inbound)
3. Fedwire Submission: Submit messages via Fedwire API/interface
4. Attestation: Submit settlement confirmations back to SettlementOrchestrator

Event Monitoring

Watched Events

• RailTriggerRegistry.TriggerCreated (filter: rail == FEDWIRE)
• RailTriggerRegistry.TriggerStateUpdated (filter: rail == FEDWIRE)

Event Processing

1. On TriggerCreated:

   • Extract trigger details (amount, accountRefId, instructionId, etc.)
   • Resolve accountRefId to Fedwire account details (off-chain mapping)
   • Construct ISO-20022 message
   • Submit to Fedwire

2. On state transitions:

   • Track trigger lifecycle
   • Handle cancellations/recalls if needed

Message Types

Outbound Transfers

• Primary: pacs.008 (FIToFICustomerCreditTransfer)
• Alternative: pain.001 (Customer Credit Transfer Initiation) if required by Fedwire participant

Inbound Notifications

• Primary: camt.054 (BankToCustomerDebitCreditNotification)
• Status: pacs.002 (Payment Status Report)

Returns/Reversals

• Return: pacs.004 (Payment Return)
• Cancellation: camt.056 (FIToFIPaymentCancellationRequest)

ISO-20022 Message Construction

Outbound (pacs.008)

<Document>
  <FIToFICstmrCdtTrf>
    <GrpHdr>
      <MsgId>instructionId</MsgId>
      <CreDtTm>timestamp</CreDtTm>
      <NbOfTxs>1</NbOfTxs>
    </GrpHdr>
    <CdtTrfTxInf>
      <PmtId>
        <EndToEndId>endToEndId</EndToEndId>
        <TxId>instructionId</TxId>
      </PmtId>
      <Amt>
        <InstdAmt Ccy="USD">amount</InstdAmt>
      </Amt>
      <CdtrAgt>
        <FinInstnId>
          <BICFI>recipientBIC</BICFI>
        </FinInstnId>
      </CdtrAgt>
      <Cdtr>
        <Nm>recipientName</Nm>
        <PstlAdr>
          <Ctry>US</Ctry>
        </PstlAdr>
      </Cdtr>
      <CdtrAcct>
        <Id>
          <Othr>
            <Id>recipientAccount</Id>
          </Othr>
        </Id>
      </CdtrAcct>
    </CdtTrfTxInf>
  </FIToFICstmrCdtTrf>
</Document>

On-Chain Attestation Flow

1. Submit to Rail:

   • Call SettlementOrchestrator.markSubmitted(triggerId, railTxRef)
   • railTxRef = Fedwire transaction reference

2. Confirm Settlement:

   • On receipt of camt.054 or pacs.002 with status "ACSC" (AcceptedSettlementCompleted):
     • Call SettlementOrchestrator.confirmSettled(triggerId, railTxRef)

3. Handle Rejections:

   • On receipt of rejection:
     • Call SettlementOrchestrator.confirmRejected(triggerId, reason)

4. Handle Cancellations:

   • On cancellation request:
     • Call SettlementOrchestrator.confirmCancelled(triggerId, reason)

Account Resolution

The adapter must maintain an off-chain mapping:

• accountRefId → Fedwire account details (ABA routing number, account number)
• This mapping should be stored securely and not exposed on-chain

Error Handling

• Network Errors: Retry with exponential backoff
• Invalid Messages: Log error, call confirmRejected()
• Timeout: Implement timeout handling (e.g., 24 hours for Fedwire)

Security Considerations

• API credentials must be stored securely (environment variables, secrets manager)
• All API calls should use TLS
• Implement rate limiting to prevent abuse
• Audit logs for all Fedwire interactions

Testing

• Unit tests for message construction
• Integration tests with Fedwire sandbox
• End-to-end tests with testnet deployment