# 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)

```xml
<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