# SEPA Adapter Specification

## Overview

The SEPA adapter connects ChainID 138 eMoney Token Factory to the Single Euro Payments Area (SEPA) network for EUR-denominated transfers. Supports both SCT (SEPA Credit Transfer) and SCT Inst (SEPA Instant Credit Transfer).

## Architecture

```
ChainID 138 Events → SEPA Adapter → SEPA Network → Settlement Confirmation → ChainID 138
```

## Responsibilities

1. **Event Watching**: Monitor `TriggerCreated` events for SEPA rail type
2. **SEPA Message Construction**: Build ISO-20022 messages compliant with SEPA rulebook
3. **SEPA Submission**: Submit via SEPA clearing system (via bank or payment service provider)
4. **Attestation**: Submit confirmations to `SettlementOrchestrator`

## Event Monitoring

### Watched Events

- `RailTriggerRegistry.TriggerCreated` (filter: `rail == SEPA`)
- `RailTriggerRegistry.TriggerStateUpdated` (filter: `rail == SEPA`)

## SEPA Variants

### SCT (Standard Credit Transfer)

- Settlement: T+1 (next business day)
- Message: `pain.001` (initiation), `pacs.008` (interbank)
- Cut-off times apply

### SCT Inst (Instant Credit Transfer)

- Settlement: Real-time (within seconds)
- Message: `pain.001` with instant indicator
- Higher fees, 24/7 availability

## ISO-20022 Message Construction

### Outbound (pain.001 for SEPA)

```xml
<Document>
  <CstmrCdtTrfInitn>
    <GrpHdr>
      <MsgId>instructionId</MsgId>
      <CreDtTm>timestamp</CreDtTm>
      <NbOfTxs>1</NbOfTxs>
    </GrpHdr>
    <PmtInf>
      <PmtInfId>paymentInfoId</PmtInfId>
      <PmtMtd>TRF</PmtMtd>
      <BtchBookg>false</BtchBookg>
      <ReqdExctnDt>executionDate</ReqdExctnDt>
      <Dbtr>
        <Nm>debtorName</Nm>
      </Dbtr>
      <DbtrAcct>
        <Id>
          <IBAN>debtorIBAN</IBAN>
        </Id>
      </DbtrAcct>
      <DbtrAgt>
        <FinInstnId>
          <BIC>debtorBIC</BIC>
        </FinInstnId>
      </DbtrAgt>
      <CdtTrfTxInf>
        <PmtId>
          <EndToEndId>endToEndId</EndToEndId>
        </PmtId>
        <Amt>
          <InstdAmt Ccy="EUR">amount</InstdAmt>
        </Amt>
        <CdtrAgt>
          <FinInstnId>
            <BIC>creditorBIC</BIC>
          </FinInstnId>
        </CdtrAgt>
        <Cdtr>
          <Nm>creditorName</Nm>
        </Cdtr>
        <CdtrAcct>
          <Id>
            <IBAN>creditorIBAN</IBAN>
          </Id>
        </CdtrAcct>
        <RmtInf>
          <Ustrd>remittanceInfo</Ustrd>
        </RmtInf>
      </CdtTrfTxInf>
    </PmtInf>
  </CstmrCdtTrfInitn>
</Document>
```

### SCT Inst Indicator

For instant transfers, add:
```xml
<PmtTpInf>
  <SvcLvl>
    <Cd>SEPA</Cd>
  </SvcLvl>
  <CtgyPurp>
    <Cd>INST</Cd>
  </CtgyPurp>
</PmtTpInf>
```

## On-Chain Attestation Flow

1. **Submit to Rail**:
   - Call `SettlementOrchestrator.markSubmitted(triggerId, railTxRef)`
   - `railTxRef` = SEPA transaction reference

2. **Confirm Settlement**:
   - SCT: On receipt of `camt.054` (next day)
   - SCT Inst: On receipt of `camt.054` (within seconds)
   - Call `SettlementOrchestrator.confirmSettled(triggerId, railTxRef)`

3. **Handle Returns**:
   - On `pacs.004` (Payment Return):
     - Call `SettlementOrchestrator.confirmRejected(triggerId, reason)`

## Account Resolution

- `accountRefId` → SEPA account details (IBAN, BIC)
- Validate IBAN format before submission
- Support both IBAN and BIC resolution

## SEPA Rulebook Compliance

- **Amount Limits**: SCT Inst max €15,000 per transaction
- **Currency**: EUR only
- **IBAN Validation**: Must validate IBAN checksum
- **Cut-off Times**: Respect SEPA cut-off times for SCT

## Error Handling

- **Invalid IBAN**: Validate and reject before submission
- **Amount Limits**: Check SCT Inst limits
- **Cut-off Time**: Queue for next business day if past cut-off

## Security Considerations

- SEPA-compliant authentication (e.g., PSD2 Strong Customer Authentication)
- Secure storage of IBANs and credentials
- Implement SEPA security guidelines

## Testing

- Unit tests for IBAN validation
- Integration tests with SEPA test environment
- SCT vs SCT Inst flow tests