b3a8fe4496
Some checks failed
Deploy to Phoenix / deploy (push) Has been cancelled
- Config, docs, scripts, and backup manifests - Submodule refs unchanged (m = modified content in submodules) Made-with: Cursor
169 lines
7.0 KiB
Markdown
169 lines
7.0 KiB
Markdown
# 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
|