bea1903ac9
Some checks failed
Deploy to Phoenix / deploy (push) Has been cancelled
Co-authored-by: Cursor <cursoragent@cursor.com>
4.6 KiB
4.6 KiB
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 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 — End-to-end listing framework
- GRU M1 Listing Dry-Run Runbook — Procedural runbook for dry-runs