dbd517b279
- Update dbis_core, cross-chain-pmm-lps, explorer-monorepo, metamask-integration, pr-workspace/chains - Omit embedded publish git dirs and empty placeholders from index Made-with: Cursor
44 lines
4.6 KiB
Markdown
44 lines
4.6 KiB
Markdown
# Naming conventions (UTRNF, GRU, Chain 138, bridges)
|
|
|
|
**Last updated:** 2026-04-01
|
|
**Purpose:** Canonical grammar for token symbols, financial roles, cross-chain identity, and registry fields across DBIS / GRU / Chain 138 and CCIP-adjacent implementations.
|
|
|
|
**Audience:** Protocol engineers, bridge operators, explorer and token-list maintainers, institutional JSON authors, and auditors.
|
|
|
|
## Documents in this directory
|
|
|
|
| File | Summary |
|
|
|------|---------|
|
|
| [01_UTRNF_REFERENCE.md](01_UTRNF_REFERENCE.md) | Universal Token Role Naming Framework (protocol-agnostic reference): prefixes, formats, taxonomy, classification logic, multichain rule, registry example, rollout phases. |
|
|
| [02_DBIS_NAMESPACE_AND_UTRNF_MAPPING.md](02_DBIS_NAMESPACE_AND_UTRNF_MAPPING.md) | **Authoritative DBIS binding:** what `c*` and `cW*` mean here vs UTRNF `c` (collateral); which UTRNF prefixes apply as-is; registry-first rules. |
|
|
| [03_BRIDGES_CROSS_CHAIN_NAMING.md](03_BRIDGES_CROSS_CHAIN_NAMING.md) | Logical asset identity vs chain-local contracts; CCIP and bridge naming patterns; same hex / different bytecode cautions. |
|
|
| [04_REGISTRY_AND_JSON_FIELDS.md](04_REGISTRY_AND_JSON_FIELDS.md) | Recommended JSON fields for token and bridge registries; links to `config/smart-contracts-master.json` and DBIS institutional config. |
|
|
| [schemas/token-registry-entry.schema.json](schemas/token-registry-entry.schema.json) | Optional JSON Schema for registry **entry** objects; [examples/](examples/) validated by `scripts/validation/validate-naming-convention-registry-examples.sh`. |
|
|
| [examples/gru-cusdc-chain138.example.json](examples/gru-cusdc-chain138.example.json) | **cUSDC V1** on 138 — PMM / liquidity canonical; `x402Ready: false`. |
|
|
| [examples/gru-cusdc-v2-chain138.example.json](examples/gru-cusdc-v2-chain138.example.json) | **cUSDC V2** on 138 — permit / ERC-3009, **x402**; coexists with V1 per [CHAIN138_X402_TOKEN_SUPPORT.md](../CHAIN138_X402_TOKEN_SUPPORT.md). |
|
|
| [examples/gru-cusdt-chain138.example.json](examples/gru-cusdt-chain138.example.json) | **cUSDT V1** — PMM / liquidity; `x402Ready: false`. |
|
|
| [examples/gru-cusdt-v2-chain138.example.json](examples/gru-cusdt-v2-chain138.example.json) | **cUSDT V2** — **x402**-capable. |
|
|
|
|
## When to use symbol parsing vs registry
|
|
|
|
- **Human display and rough discovery:** Symbols may follow the grammars in `01` and `02`.
|
|
- **Canonical identity, accounting, and compliance:** Always resolve **`(chainId, contract address)`** plus explicit **`tokenRole` / `utrnfRole` / `gruAssetClass`** from a registry (see `04`). Never infer GRU compliant money from UTRNF prefix tables alone: **`cUSDC` is not UTRNF “collateral.”**
|
|
|
|
## Related project documentation
|
|
|
|
- GRU `c*` V2 standards and layers: [GRU_C_STAR_V2_STANDARDS_MATRIX_AND_IMPLEMENTATION_PLAN.md](../GRU_C_STAR_V2_STANDARDS_MATRIX_AND_IMPLEMENTATION_PLAN.md)
|
|
- GRU M00 Diamond symbol grammar (`c` / `a` / `d`, `W` rules): [GRU_M00_DIAMOND_FACET_MAP.md](../GRU_M00_DIAMOND_FACET_MAP.md)
|
|
- Explorer GRU registration policy: [EXPLORER_TOKENS_GRU_POLICY.md](../EXPLORER_TOKENS_GRU_POLICY.md)
|
|
- GRU standards profile (machine-readable): [GRU_STANDARDS_PROFILE.md](../GRU_STANDARDS_PROFILE.md), [`config/gru-standards-profile.json`](../../../config/gru-standards-profile.json)
|
|
- Canonical Chain 138 token addresses and Explorer cross-check: [EXPLORER_TOKEN_LIST_CROSSCHECK.md](../../11-references/EXPLORER_TOKEN_LIST_CROSSCHECK.md)
|
|
- PMM pools and routing: [PMM_DEX_ROUTING_STATUS.md](../../11-references/PMM_DEX_ROUTING_STATUS.md)
|
|
- Token-aggregation API verify: `pnpm run verify:token-aggregation-api`; public report check: `SKIP_BRIDGE_ROUTES=0 bash scripts/verify/check-public-report-api.sh https://explorer.d-bis.org` (see [AGENTS.md](../../../AGENTS.md))
|
|
- Contract addresses: [CONTRACT_ADDRESSES_REFERENCE.md](../../11-references/CONTRACT_ADDRESSES_REFERENCE.md), [ADDRESS_MATRIX_AND_STATUS.md](../../11-references/ADDRESS_MATRIX_AND_STATUS.md)
|
|
- CCIP deployment and bridge docs: [docs/07-ccip/](../../07-ccip/) (e.g. [CCIP_DEPLOYMENT_SPEC.md](../../07-ccip/CCIP_DEPLOYMENT_SPEC.md))
|
|
- c* → cW* mapper config: [C_TO_CW_MAPPER_MAPPING.md](../C_TO_CW_MAPPER_MAPPING.md), `config/token-mapping-multichain.json`
|
|
- DBIS institutional JSON: [`config/dbis-institutional/README.md`](../../../config/dbis-institutional/README.md)
|
|
|
|
## Roadmap (documentation vs code)
|
|
|
|
The UTRNF reference describes a phased rollout (token roles → contract alignment → SDK → governance checks). This directory **documents** conventions for the repo; it does not mandate immediate contract or schema refactors. Prefer incremental alignment via registries and new deployments.
|