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
142 lines
4.0 KiB
Markdown
142 lines
4.0 KiB
Markdown
# 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
|
|
|