proxmox/docs/04-configuration/ISO4217_COMPLIANT_TOKEN_MATRIX.md

ISO-4217 Compliant Token Matrix (Native + Bridged)

This matrix formalizes the symbol construction standard for compliant ISO-4217 coins/tokens across:

• Financial Chains (Native issuance) using a 6-character symbol
• Public Chains (Bridged/wrapped issuance) using a 7-character symbol where ISO shifts to positions 4–6

---

1. Character-Position Rules

A) Native Financial-Chain Symbol (6 characters)

Format: c + [FinChain] + [ISO4217] + [Type]

Position	Meaning	Allowed Values
1	Compliance prefix	c
2	Financial chain designator	See FIN_CHAIN_SET
3–5	ISO-4217 currency code	See ISO4217_SET
6	Asset type	C (coin), T (token), W (D‑WIN)

Example: cAUSDT = c + A + USD + T

B) Bridged Public-Chain Symbol (7 characters)

Format: c + W + [OriginFinChain] + [ISO4217] + [Type]

Position	Meaning	Allowed Values
1	Compliance prefix	c
2	Public wrapper class	W
3	Origin financial chain designator	See FIN_CHAIN_SET
4–6	ISO-4217 currency code	See ISO4217_SET
7	Asset type	C (coin), T (token), W (D‑WIN)

Example: cWAUSDT = c + W + A + USD + T

---

2. FIN_CHAIN_SET

Designator	Chain	Chain ID	Notes
(none)	Chain 138 (DeFi Oracle Meta Mainnet)	138	v0 only: native symbols omit designator (e.g. cUSDC, cUSDT)
X	Chain 138 (origin reference only)	138	Used only when denoting origin 138 on other chains (e.g. bridged)
A	Alltra Mainnet	651940	ALL Mainnet

Chain 138: On ChainID 138, token symbols are v0 only — the chain designator is left out. Use cUSDC, cUSDT (no X). The X designator is used only for bridged tokens on public chains when the origin is Chain 138 (e.g. cWXUSDC). Reserved designators: do not reuse. Add new chains via registry.

---

3. ISO4217_SET

Reference: ISO 4217. Supported subset for implementation:

• Fiat: USD, EUR, GBP, JPY, AUD, CHF, CAD, CNY
• Commodity: XAU (gold)
• Future: Add codes via registry; validation enforces 3 uppercase letters only (no 4-letter codes in v1)

---

4. Validation Rules

Native (len = 6)

• s[0] == 'c'
• s[1] in FIN_CHAIN_SET
• s[2:5] in ISO4217_SET (positions 2, 3, 4)
• s[5] in {'C','T','W'}

Bridged (len = 7)

• s[0] == 'c'
• s[1] == 'W'
• s[2] in FIN_CHAIN_SET (origin chain)
• s[3:6] in ISO4217_SET (positions 3, 4, 5)
• s[6] in {'C','T','W'}

---

5. v0 Symbols (Chain 138 Only)

On ChainID 138 only, compliant token symbols use the v0 form with no chain designator (the X is left out):

v0 Symbol	Identity	Type	Chain
cUSDT	ISO USD, Type T	Token	138
cUSDC	ISO USD, Type C	Coin	138

• These symbols are maintained only on Chain 138; they are not used on other chains.
• Registry maps v0 → { iso, type, originChain: 'X' } for reporting and for bridged-origin reference; on-chain on 138 the symbol stays cUSDC / cUSDT.

---

6. Chain 138: No X in Native Symbols

• On Chain 138: Native token symbols remain v0 — cUSDC, cUSDT (no X, no designator). Do not use cXUSDC or cXUSDT on Chain 138.
• X is used only when referring to Chain 138 as origin elsewhere (e.g. bridged tokens on public chains: cWXUSDC, cWXUSDT).
• Registry maps v0 → v1 identity for reporting and validation; the on-chain symbol on 138 does not change.

---

7. Case Sensitivity

• Symbols are case-sensitive.
• Compliance prefix: lowercase c.
• FinChain, ISO4217, Type: uppercase (e.g. A, USD, T).

---

8. Edge Cases

• ISO codes: 3 letters only (A–Z); no 4-letter codes in v1.
• Reserved designators: X (Chain 138), A (Alltra); do not reuse.
• Invalid examples: cAUSD (missing type), cAUSDCX (7-char without W at position 2).

---

9. Migration Strategy

• Chain 138: v0 symbols cUSDT, cUSDC are maintained only on ChainID 138; the X is left out. No on-chain symbol change on 138.
• v1 registry: Maps v0 symbol → { iso, type, originChain: 'X' } for reporting; origin X denotes Chain 138 when needed (e.g. bridged).
• New chains: Use v1 symbols with designator (e.g. cAUSDT on Alltra, cWAUSDT on public chains).
• Bridged from Chain 138: Use 7-char with origin X (e.g. cWXUSDC, cWXUSDT) on public chains only.

---

10. Matrix Examples

Native on Chain 138 (v0 only — no designator)

ISO	Coin (C)	Token (T)
USD	cUSDC	cUSDT

Native (6-char) — Other financial chains (e.g. Alltra A)

ISO	Coin (C)	Token (T)	D‑WIN (W)
USD	cAUSDC	cAUSDT	cAUSDW
EUR	cAEURC	cAEURT	cAEURW
GBP	cAGBPC	cAGBPT	cAGBPW

Bridged (7-char) — Public networks

ISO	Coin (C)	Token (T)	D‑WIN (W)
USD	cWXUSDC	cWXUSDT	cWXUSDW
USD	cWAUSDC	cWAUSDT	cWAUSDW
EUR	cWAEURC	cWAEURT	cWAEURW

---

11. Chain-Context Mapping

• Chain 138: Native symbols are v0 only (no X): cUSDC, cUSDT. No 6-char form with X is used on Chain 138.
• Other financial chains: Native symbols use 6-char with designator (e.g. Alltra cAUSDC, cAUSDT).
• Bridged symbols (7-char) live on Public chains (Ethereum, Base, Polygon, etc.); use cWXUSDC when origin is Chain 138.
• Chain specificity remains defined by chainId + contract address; the symbol encodes class + origin (except v0 on 138, which encodes class only).

---

References

• CHAIN138_TOKEN_ADDRESSES.md — v0 symbol mapping
• TOKEN_SCOPE_GRU.md — token scope
• GRU_M00_DIAMOND_FACET_MAP.md — canonical symbol grammar §5