bea1903ac9
Some checks failed
Deploy to Phoenix / deploy (push) Has been cancelled
Co-authored-by: Cursor <cursoragent@cursor.com>
83 lines
4.6 KiB
Markdown
83 lines
4.6 KiB
Markdown
# ISO-20022 and E-Money (GRU Multi-Chain)
|
||
|
||
**Last Updated:** 2026-01-31
|
||
**Document Version:** 1.0
|
||
**Status:** Active Documentation
|
||
|
||
---
|
||
|
||
This document describes ISO-20022 metadata support and E-Money hooks for GRU base money tokens. All transfers, mints, burns, and cross-chain actions must be mappable to ISO-20022 semantics where applicable.
|
||
|
||
## 1. ISO-20022 Canonical Message (Extended)
|
||
|
||
The [IISO20022Router.CanonicalMessage](../../../smom-dbis-138/contracts/emoney/interfaces/IISO20022Router.sol) struct includes:
|
||
|
||
| Field | Purpose |
|
||
|-------|---------|
|
||
| msgType | pacs.008, pain.001, camt.054, etc. |
|
||
| instructionId | InstrId – unique reference |
|
||
| endToEndId | EndToEndId (optional) |
|
||
| msgId | MsgId (optional) |
|
||
| uetr | UETR (optional) |
|
||
| accountRefId | Account reference |
|
||
| counterpartyRefId | Counterparty reference |
|
||
| debtorId | Debtor identifier (optional) |
|
||
| creditorId | Creditor identifier (optional) |
|
||
| purpose | Purpose / remittance info (optional) |
|
||
| settlementMethod | Settlement method (optional) |
|
||
| categoryPurpose | Category purpose (optional) |
|
||
| token | Token address |
|
||
| amount | Amount |
|
||
| currencyCode | Currency code |
|
||
| payloadHash | Hash of off-chain payload |
|
||
|
||
All transfer, mint, burn, and cross-chain entry points (e.g. BridgeVault, UniversalCCIPBridge, AlltraCustomBridge) should carry or reference these fields where applicable – e.g. via event parameters or a dedicated metadata field so that off-chain systems can map to ISO-20022.
|
||
|
||
## 2. E-Money Requirements (Base Money)
|
||
|
||
Base money tokens (GRU-M1: cUSDC, cUSDT, cEURC, etc.) must satisfy:
|
||
|
||
- **Par redeemability:** 1 unit of token = 1 unit of underlying; redeemable at par.
|
||
- **Safeguarded reserves:** Reserves held in segregated form; attestation via ReserveOracle or equivalent.
|
||
- **No yield on base money:** Base money tokens do not accrue interest (yield is on asset tokens, e.g. acUSDC).
|
||
- **Transaction monitoring hooks:** ComplianceGuard / PolicyManager / ComplianceRegistry enforce allowlists, KYT, and circuit breakers.
|
||
|
||
## 3. Where E-Money Hooks Are Enforced
|
||
|
||
| Requirement | Contract / component | Notes |
|
||
|-------------|----------------------|--------|
|
||
| Par redeemability | Token implementation (CompliantUSDC, ISO4217WToken) | Mint/burn 1:1; no rebase on base money. |
|
||
| Safeguarded reserves | ReserveOracle (iso4217w), StablecoinReserveVault, PolicyManager | Attestation and reserve checks before mint. |
|
||
| No yield on base money | Token implementation, Vault/DepositToken separation | Base money = c*; yield only on ac* (DepositToken). |
|
||
| Transaction monitoring | ComplianceGuard (iso4217w), ComplianceRegistry (emoney), PolicyManager | Allowlists, KYT integration, circuit breakers. |
|
||
|
||
## 4. ComplianceGuard and TokenRegistry (iso4217w)
|
||
|
||
- **ComplianceGuard:** Validates mint/burn/transfer against policy (allowlists, caps, KYC).
|
||
- **TokenRegistry:** Registers tokens and links to ComplianceGuard and reserve attestation.
|
||
- Use these for all GRU-M1 tokens so that transfers and mints are gated and mappable to ISO-20022 metadata (e.g. debtor/creditor, purpose) where required.
|
||
|
||
## 5. PolicyManager and ComplianceRegistry (emoney)
|
||
|
||
- **PolicyManager:** Central policy (e.g. per-token rules, circuit breakers).
|
||
- **ComplianceRegistry:** Marks entities (e.g. BridgeVault138) as compliant for transfers.
|
||
- Wire base money transfers and bridge lock/unlock through these so that transaction monitoring and E-Money safeguards are applied.
|
||
|
||
## 6. Reserve Attestation
|
||
|
||
- **ReserveOracle** (iso4217w): Provides reserve attestation for W tokens.
|
||
- **StablecoinReserveVault / ReserveSystem:** Hold and attest reserves for stablecoins.
|
||
- Base money mints should require a valid reserve attestation (or equivalent check) before minting; document the exact hook (e.g. MintController + ReserveOracle) in the tokenization docs.
|
||
|
||
## 7. Summary
|
||
|
||
- **ISO-20022:** CanonicalMessage extended with MsgId, UETR, debtorId, creditorId, purpose, settlementMethod, categoryPurpose. Use in submitInbound/submitOutbound and in events for transfer/mint/burn/cross-chain so that off-chain systems can map to ISO-20022.
|
||
- **E-Money:** Par redeemability, safeguarded reserves, no yield on base money, transaction monitoring – enforced in ComplianceGuard, TokenRegistry, PolicyManager, ComplianceRegistry, and ReserveOracle as above.
|
||
|
||
## 8. Related: GRU M1 Listing & Dry-Run
|
||
|
||
For CMC and CoinGecko listing preparation, dominance simulation, peg stress-tests, and dry-run procedures, see:
|
||
|
||
- **[GRU M1 Master Implementation Plan](../gru-m1/GRU_M1_MASTER_IMPLEMENTATION_PLAN.md)** — End-to-end listing framework
|
||
- **[GRU M1 Listing Dry-Run Runbook](GRU_M1_LISTING_DRY_RUN_RUNBOOK.md)** — Procedural runbook for dry-runs
|