# 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](https://en.wikipedia.org/wiki/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](../11-references/CHAIN138_TOKEN_ADDRESSES.md) — v0 symbol mapping - [TOKEN_SCOPE_GRU.md](../../smom-dbis-138/docs/tokenization/TOKEN_SCOPE_GRU.md) — token scope - [GRU_M00_DIAMOND_FACET_MAP.md](GRU_M00_DIAMOND_FACET_MAP.md) — canonical symbol grammar §5