d-bis/gru_emoney_token-factory
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial project setup: Add contracts, API definitions, tests, and documentation

Browse Source 
- 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
This commit is contained in:
defiQUG
2025-12-12 10:59:41 -08:00
parent 26b5aaf932
commit 651ff4f7eb
281 changed files with 24813 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

141
docs/adapters/FedwireAdapter.md Normal file
View File

@@ -0,0 +1,141 @@
# 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

152
docs/adapters/RTGSAdapter.md Normal file
View File

@@ -0,0 +1,152 @@
# RTGS Adapter Specification
## Overview
The RTGS (Real-Time Gross Settlement) adapter provides a generic framework for connecting to RTGS systems across different jurisdictions. RTGS systems settle payments individually and in real-time, making them suitable for high-value, time-critical transfers.
## Architecture
```
ChainID 138 Events → RTGS Adapter → RTGS System (Jurisdiction-Specific) → Settlement Confirmation → ChainID 138
```
## Responsibilities
1. **Event Watching**: Monitor `TriggerCreated` events for RTGS rail type
2. **RTGS Message Construction**: Build jurisdiction-specific messages (often ISO-20022 based)
3. **RTGS Submission**: Submit via RTGS API (varies by jurisdiction)
4. **Attestation**: Submit confirmations to `SettlementOrchestrator`
## Event Monitoring
### Watched Events
- `RailTriggerRegistry.TriggerCreated` (filter: `rail == RTGS`)
- `RailTriggerRegistry.TriggerStateUpdated` (filter: `rail == RTGS`)
## RTGS Systems by Jurisdiction
### Examples
- **US**: Fedwire (covered by FedwireAdapter)
- **UK**: CHAPS (Clearing House Automated Payment System)
- **Canada**: LVTS (Large Value Transfer System)
- **Australia**: RITS (Reserve Bank Information and Transfer System)
- **Japan**: BOJ-NET (Bank of Japan Financial Network System)
- **India**: RTGS (Reserve Bank of India)
## Generic RTGS Message Structure
Most RTGS systems use ISO-20022 or similar structures:
### Outbound (pacs.008 or jurisdiction-specific)
```xml
<Document>
<FIToFICstmrCdtTrf>
<GrpHdr>
<MsgId>instructionId</MsgId>
<CreDtTm>timestamp</CreDtTm>
</GrpHdr>
<CdtTrfTxInf>
<PmtId>
<EndToEndId>endToEndId</EndToEndId>
<TxId>instructionId</TxId>
</PmtId>
<Amt>
<InstdAmt Ccy="XXX">amount</InstdAmt>
</Amt>
<CdtrAgt>
<FinInstnId>
<!-- Jurisdiction-specific identifier -->
</FinInstnId>
</CdtrAgt>
<Cdtr>
<Nm>recipientName</Nm>
</Cdtr>
<CdtrAcct>
<Id>
<!-- Jurisdiction-specific account identifier -->
</Id>
</CdtrAcct>
</CdtTrfTxInf>
</FIToFICstmrCdtTrf>
</Document>
```
## Jurisdiction-Specific Considerations
### CHAPS (UK)
- Currency: GBP
- Message: ISO-20022 or CHAPS-specific format
- Settlement: Real-time during business hours
- Account: Sort code + account number
### LVTS (Canada)
- Currency: CAD
- Message: ISO-20022
- Settlement: Real-time
- Account: Transit number + account number
### RITS (Australia)
- Currency: AUD
- Message: ISO-20022
- Settlement: Real-time
- Account: BSB + account number
## On-Chain Attestation Flow
1. **Submit to Rail**:
- Call `SettlementOrchestrator.markSubmitted(triggerId, railTxRef)`
- `railTxRef` = RTGS transaction reference (format varies by jurisdiction)
2. **Confirm Settlement**:
- RTGS systems typically provide immediate confirmation
- On receipt of confirmation:
- Call `SettlementOrchestrator.confirmSettled(triggerId, railTxRef)`
3. **Handle Rejections**:
- RTGS systems may reject due to:
- Insufficient funds
- Invalid account
- System limits
- Call `SettlementOrchestrator.confirmRejected(triggerId, reason)`
## Account Resolution
- `accountRefId` → RTGS account details (format varies by jurisdiction)
- Maintain jurisdiction-specific account identifier mappings
## RTGS Characteristics
- **Real-Time**: Settlements occur immediately
- **Gross Settlement**: Each transaction settled individually
- **High Value**: Typically used for large-value transfers
- **Business Hours**: Most RTGS systems operate during business hours only
## Error Handling
- **Network Errors**: Retry with exponential backoff
- **Invalid Account**: Validate before submission
- **System Limits**: Check RTGS system limits
- **Business Hours**: Queue if outside operating hours
## Security Considerations
- RTGS systems typically require strong authentication
- Secure storage of credentials and account identifiers
- Implement jurisdiction-specific security requirements
## Testing
- Unit tests for jurisdiction-specific message formats
- Integration tests with RTGS test environments
- Jurisdiction-specific flow tests
## Implementation Notes
This adapter should be implemented as a base class with jurisdiction-specific subclasses, or use a plugin architecture to support multiple RTGS systems.

159
docs/adapters/SEPAAdapter.md Normal file
View File

@@ -0,0 +1,159 @@
# 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

141
docs/adapters/SWIFTAdapter.md Normal file
View File

@@ -0,0 +1,141 @@
# SWIFT Adapter Specification
## Overview
The SWIFT adapter connects ChainID 138 eMoney Token Factory to the SWIFT network for international wire transfers. The adapter supports both SWIFT MT (Message Type) and ISO-20022 MX formats, normalizing all messages to ISO-20022 canonical format.
## Architecture
```
ChainID 138 Events → SWIFT Adapter → SWIFT Network (MT/MX) → Settlement Confirmation → ChainID 138
```
## Responsibilities
1. **Event Watching**: Monitor `TriggerCreated` events for SWIFT rail type
2. **Format Normalization**: Convert MT messages to ISO-20022 MX format
3. **SWIFT Submission**: Submit via SWIFT API (SWIFT gpi, Alliance Access, etc.)
4. **Attestation**: Submit confirmations to `SettlementOrchestrator`
## Event Monitoring
### Watched Events
- `RailTriggerRegistry.TriggerCreated` (filter: `rail == SWIFT`)
- `RailTriggerRegistry.TriggerStateUpdated` (filter: `rail == SWIFT`)
## Message Format Support
### SWIFT MT Messages
- **MT103**: Single Customer Credit Transfer
- **MT202**: General Financial Institution Transfer
- **MT900**: Confirmation of Debit
- **MT910**: Confirmation of Credit
- **MT192**: Request for Cancellation
### ISO-20022 MX Messages (Preferred)
- **pacs.008**: FIToFICustomerCreditTransfer
- **pacs.009**: FinancialInstitutionCreditTransfer
- **pacs.002**: Payment Status Report
- **camt.054**: BankToCustomerDebitCreditNotification
- **camt.056**: FIToFIPaymentCancellationRequest
## MT to MX Conversion
### MT103 → pacs.008
Key field mappings:
- Field 20 (Transaction Reference) → `PmtId.TxId`
- Field 32A (Value Date, Currency, Amount) → `Amt.InstdAmt`
- Field 50 (Ordering Customer) → `Dbtr`
- Field 59 (Beneficiary) → `Cdtr`
- Field 57A (Account With Institution) → `CdtrAgt`
## ISO-20022 Message Construction
### Outbound (pacs.008)
Similar structure to Fedwire, but with BIC codes:
```xml
<Document>
<FIToFICstmrCdtTrf>
<GrpHdr>
<MsgId>instructionId</MsgId>
<CreDtTm>timestamp</CreDtTm>
</GrpHdr>
<CdtTrfTxInf>
<PmtId>
<EndToEndId>endToEndId</EndToEndId>
<TxId>instructionId</TxId>
</PmtId>
<Amt>
<InstdAmt Ccy="EUR">amount</InstdAmt>
</Amt>
<CdtrAgt>
<FinInstnId>
<BICFI>BICCODE</BICFI>
</FinInstnId>
</CdtrAgt>
<Cdtr>
<Nm>recipientName</Nm>
<PstlAdr>
<Ctry>XX</Ctry>
</PstlAdr>
</Cdtr>
<CdtrAcct>
<Id>
<IBAN>IBAN</IBAN>
</Id>
</CdtrAcct>
</CdtTrfTxInf>
</FIToFICstmrCdtTrf>
</Document>
```
## On-Chain Attestation Flow
1. **Submit to Rail**:
- Call `SettlementOrchestrator.markSubmitted(triggerId, railTxRef)`
- `railTxRef` = SWIFT UETR (Unique End-to-End Transaction Reference) or MT reference
2. **Confirm Settlement**:
- On receipt of `camt.054` or `pacs.002` with status "ACSC":
- Call `SettlementOrchestrator.confirmSettled(triggerId, railTxRef)`
3. **Handle Rejections**:
- On MT192 or rejection status:
- Call `SettlementOrchestrator.confirmRejected(triggerId, reason)`
## SWIFT gpi Integration
If using SWIFT gpi (Global Payments Innovation):
- Track payment status via gpi Tracker API
- Use UETR for end-to-end tracking
- Implement gpi status callbacks
## Account Resolution
- `accountRefId` → SWIFT account details (BIC, IBAN, or account number)
- Support multiple account identifier formats
## Error Handling
- **Network Errors**: Retry with exponential backoff
- **Invalid BIC/IBAN**: Validate before submission
- **Timeout**: SWIFT typically 1-5 business days
## Security Considerations
- SWIFT PKI certificates for authentication
- Secure storage of BIC codes and credentials
- Implement SWIFT security best practices
## Testing
- Unit tests for MT/MX conversion
- Integration tests with SWIFT test environment
- gpi tracker integration tests