651ff4f7eb
- Add Foundry project configuration (foundry.toml, foundry.lock) - Add Solidity contracts (TokenFactory138, BridgeVault138, ComplianceRegistry, etc.) - Add API definitions (OpenAPI, GraphQL, gRPC, AsyncAPI) - Add comprehensive test suite (unit, integration, fuzz, invariants) - Add API services (REST, GraphQL, orchestrator, packet service) - Add documentation (ISO20022 mapping, runbooks, adapter guides) - Add development tools (RBC tool, Swagger UI, mock server) - Update OpenZeppelin submodules to v5.0.0
160 lines
4.0 KiB
Markdown
160 lines
4.0 KiB
Markdown
# 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
|
|
|