Files

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

- 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

2025-12-12 10:59:41 -08:00

3.5 KiB

Raw Permalink Blame History

ISO-20022 Mapping Handbook

This document provides detailed guidance on ISO-20022 message processing and mapping to canonical formats.

Message Type Overview

Message Type	Direction	Purpose	Trigger Action
`pain.001`	Outbound	Customer Credit Transfer Initiation	`validateAndLock()` → `markSubmitted()`
`pacs.008`	Outbound	FIToFICustomerCreditTransfer	`validateAndLock()` → `markSubmitted()`
`pacs.009`	Outbound	FinancialInstitutionCreditTransfer	`validateAndLock()` → `markSubmitted()`
`camt.054`	Inbound	BankToCustomerDebitCreditNotification	`confirmSettled()` (mint tokens)
`pacs.002`	Inbound	Payment Status Report	`confirmSettled()` or `confirmRejected()`
`pacs.004`	Return	Payment Return	`confirmRejected()` (release escrow)
`camt.056`	Cancellation	FIToFIPaymentCancellationRequest	`confirmCancelled()` (release escrow)

Field Mapping

pain.001 Mapping

instructionId: Document/CstmrCdtTrfInitn/PmtInf/CdtTrfTxInf/PmtId/InstrId
endToEndId: Document/CstmrCdtTrfInitn/PmtInf/CdtTrfTxInf/PmtId/EndToEndId
amount: Document/CstmrCdtTrfInitn/PmtInf/CdtTrfTxInf/Amt/InstdAmt
currency: Document/CstmrCdtTrfInitn/PmtInf/CdtTrfTxInf/Amt/InstdAmt/@Ccy
debtorAccount: Document/CstmrCdtTrfInitn/PmtInf/DbtrAcct/Id/Othr/Id
creditorAccount: Document/CstmrCdtTrfInitn/PmtInf/CdtTrfTxInf/CdtrAcct/Id/Othr/Id

pacs.008 Mapping

instructionId: Document/FIToFICstmrCdtTrf/GrpHdr/MsgId
endToEndId: Document/FIToFICstmrCdtTrf/CdtTrfTxInf/PmtId/EndToEndId
amount: Document/FIToFICstmrCdtTrf/CdtTrfTxInf/IntrBkSttlmAmt
currency: Document/FIToFICstmrCdtTrf/CdtTrfTxInf/IntrBkSttlmAmt/@Ccy

pacs.002 Status Mapping

Status Code	Meaning	Action
`ACSC`	AcceptedSettlementCompleted	`confirmSettled()`
`RJCT`	Rejected	`confirmRejected()`
`PNDG`	Pending	Wait for final status
`CANC`	Cancelled	`confirmCancelled()`

Processing Flow

Outbound Flow

Client submits pain.001 or pacs.008 via /v1/iso/outbound
ISO Router normalizes message to canonical format
Orchestrator creates trigger in CREATED state
Orchestrator validates and locks funds (VALIDATED state)
Adapter submits to rail (SUBMITTED_TO_RAIL state)
Trigger moves to PENDING state
Rail adapter receives pacs.002 or camt.054
Orchestrator confirms settled/rejected (SETTLED/REJECTED state)

Inbound Flow

Rail adapter receives camt.054 or pacs.002
Adapter submits via /v1/iso/inbound (mTLS)
ISO Router normalizes message
Orchestrator creates trigger
For camt.054 with credit: mint tokens and confirmSettled()
For pacs.002 with RJCT: confirmRejected()

Idempotency

All ISO-20022 message submissions are idempotent by instructionId. Duplicate submissions with the same instructionId are rejected.

Payload Storage

Full ISO-20022 XML payloads stored off-chain
Only payloadHash stored on-chain in trigger
Payloads can be retrieved via API for reconciliation

Reconciliation

Use instructionId and endToEndId for end-to-end reconciliation:

GET /v1/triggers?instructionId=0x1234...
GET /v1/triggers?endToEndId=0xabcd...

Error Handling

Invalid ISO-20022 messages trigger confirmRejected() with appropriate reason codes:

Schema validation errors → CONFIG_ERROR
Missing required fields → CONFIG_ERROR
Invalid amounts → CONFIG_ERROR

3.5 KiB Raw Permalink Blame History