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](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`   |

### 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](../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