proxmox/docs/04-configuration/naming-conventions/04_REGISTRY_AND_JSON_FIELDS.md

Registry and JSON fields

Last updated: 2026-03-31
Purpose: Recommended fields for token and bridge registries so UTRNF-style roles, GRU layers, and cross-chain identity are machine-readable. This complements symbols documented in 01_UTRNF_REFERENCE.md and DBIS mapping in 02_DBIS_NAMESPACE_AND_UTRNF_MAPPING.md.

Schema and examples: schemas/token-registry-entry.schema.json, examples/ — validated by bash scripts/validation/validate-naming-convention-registry-examples.sh when check-jsonschema is installed.

---

1. Core identity fields

Field	Type	Description
chainId	number	EIP-155 style chain ID.
address	string (0x…)	Checksum or lowercase consistent with consumer; document casing rule.
symbol	string	Human display symbol (e.g. cUSDC, lpPairName).
name	string	ERC-20 name or display name.
decimals	number	Token decimals.

Composite primary key for on-chain instances: (chainId, address).

---

2. Underlying and UTRNF-oriented fields

Field	Type	Description
underlying	string	Underlying ticker or logical asset (e.g. USDC, XAU).
utrnfRole	string	Optional UTRNF classification: asset, variable_debt, stable_debt, yield, liquidity, synthetic, reserve, wrapped, incentive, collateral (locked lending-style collateral — generic UTRNF), or none / not_applicable.
tokenRole	string	DBIS-oriented role: e.g. gru_compliant_base, gru_wrapped, dex_lp, vault_share, bridge_receipt, utility.
gruAssetClass	string	Optional refinement for GRU tooling (align with GRU_STANDARDS_PROFILE.md).

Use tokenRole for ecosystem-specific meaning; use utrnfRole when the instrument aligns with UTRNF grammar. DBIS c* compliant base money should use tokenRole: gru_compliant_base and typically utrnfRole: not_applicable (or none). Reserve utrnfRole: collateral for contracts that are actually UTRNF-style collateral tokens, not for cUSDC / cUSDT on Chain 138.

---

3. GRU versioning (aligns with c* V2 plan)

Field	Type	Description
assetId	string	Stable id for the asset family. May be a 0x-prefixed 32-byte hex (bytes32), a namespaced opaque string (e.g. keccak256:GRU:cUSDC as a convention label — not necessarily an on-chain hash unless your registry defines it that way), or another stable key. Align with GRU_C_STAR_V2_STANDARDS_MATRIX_AND_IMPLEMENTATION_PLAN.md (keccak256("GRU:cUSDC") style in prose = logical id; store the encoding your tooling actually uses).
assetVersionId	string	Version-specific id (e.g. V1 vs V2 cUSDC).
forwardCanonical	boolean	Whether this deployment is the active canonical target for routing.
legacyAliases	array	Optional list of superseded (chainId, address) or symbols.

See GRU_C_STAR_V2_STANDARDS_MATRIX_AND_IMPLEMENTATION_PLAN.md (asset identity and versioning).

---

4. GRU monetary layer (optional)

Field	Type	Description
gruLayer	string	M00, M0, M1, or na when not applicable to the contract.

Use for policy and reporting; do not overload ERC-20 symbol with layer codes unless explicitly standardized.

---

5. Bridge and cross-chain fields

Field	Type	Description
originChainId	number	Chain where underlying is locked or where message originates.
wrappedFrom	string	Address or logical id on origin chain.
bridgeKind	string	e.g. ccip, lock_mint, native_deposit.
ccipLane	string	Optional lane or selector label for operators.

---

6. Lending-style triad (optional, UTRNF-shaped)

When a reserve exposes Aave-like tokens:

{
  "underlying": "USDC",
  "assetToken": "aUSDC",
  "variableDebtToken": "vdUSDC",
  "stableDebtToken": "sdUSDC",
  "decimals": 6,
  "chainId": 138
}

This mirrors 01_UTRNF_REFERENCE.md section 12. Only use when those contracts exist; do not invent symbols for GRU c* unless deployed.

---

7. Repository consumers

Consumer	Location
Master contract and deployment inventory	config/smart-contracts-master.json — structure evolves with project needs; add optional metadata fields when agreed.
DBIS institutional JSON	config/dbis-institutional/README.md, schemas under config/dbis-institutional/schemas/.
Token lists	token-lists/lists/*.tokenlist.json, explorer / MetaMask dual-chain lists (see EXPLORER_TOKEN_LIST_CROSSCHECK.md).
Multichain mapper	config/token-mapping-multichain.json

---

8. Example: GRU compliant base on Chain 138

{
  "chainId": 138,
  "address": "0xf22258f57794CC8E06237084b353Ab30fFfa640b",
  "symbol": "cUSDC",
  "decimals": 6,
  "underlying": "USDC",
  "tokenRole": "gru_compliant_base",
  "utrnfRole": "not_applicable",
  "assetId": "keccak256:GRU:cUSDC",
  "forwardCanonical": true
}

Addresses and forwardCanonical must match project canon at time of publication; verify against EXPLORER_TOKEN_LIST_CROSSCHECK.md. The assetId string here is a documentation convention label; production registries may store bytes32 or another normalized form — see the assetId row in §3 above.

---

9. Validation

• Schema: schemas/token-registry-entry.schema.json (JSON Schema 2020-12).
• Examples: examples/gru-cusdc-chain138.example.json, examples/utrnf-lending-triad.example.json, examples/utrnf-collateral-placeholder.example.json (illustrative UTRNF collateral — not Chain 138 c*).
• Command: bash scripts/validation/validate-naming-convention-registry-examples.sh
  Uses check-jsonschema when installed (pip install check-jsonschema). With SCHEMA_STRICT=1, exits non-zero if the tool is missing. Wired into scripts/validation/validate-config-files.sh when strict schema checks run.