proxmox/docs/runbooks/MULTI_CHAIN_EXECUTION_ISO20022_EMONEY.md

# 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