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

Alltra inbound gold exception

The generic bridged rule above uses the origin financial chain designator in position 3. For the specific Chain 138 -> ALL Mainnet (651940) gold corridor, the repo uses an explicit ALL Mainnet naming exception:

Flow leg	XAUC	XAUT
Source-side wrapped leg	cWXAUC	cWXAUT
Bridge-minted ALL Mainnet wrapped leg	cWAXAUC	cWAXAUT
Unwrapped ALL Mainnet native leg	cAXAUC	cAXAUT

This exception is intentional and should be interpreted from the pair mapping + chainId + contract address, not by applying the generic 7-character bridged rule blindly.

---

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