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

Registry and JSON fields

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.

Phase 1: Documentation only; no required change to existing JSON schemas unless a workstream adopts these fields explicitly.

---

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: asset, variable_debt, stable_debt, yield, liquidity, synthetic, reserve, wrapped, incentive, 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* base money should not set utrnfRole to collateral unless the contract is literally a UTRNF-style collateral token (rare in current GRU base layer).

---

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

Field	Type	Description
assetId	string (bytes32 hex or opaque id)	Stable id for the asset family.
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.

---

9. Validation (future)

Optional follow-up: JSON Schema under config/ and a small validator in scripts/validation/ to enforce required fields for new registry entries. Not part of the initial documentation drop.