docs: UTRNF naming conventions (01–02), c* V2 transport verify extras

- Add naming-conventions/ with UTRNF reference and DBIS namespace mapping
- Index from 04-configuration README and MASTER_INDEX
- check-cstar-v2-transport-stack: CompliantWrappedToken + JurisdictionalGovernance suites
- gitignore: config/production/dbis-identity-public-did-secrets.env

Made-with: Cursor
This commit is contained in:
defiQUG
2026-03-31 22:41:23 -07:00
parent 748c1c9e14
commit 5c69993ce9
7 changed files with 400 additions and 0 deletions

3
.gitignore vendored
View File

@@ -9,6 +9,9 @@ node_modules/
package-lock.json
yarn.lock
# DBIS identity package — never commit real secrets (example only is tracked)
config/production/dbis-identity-public-did-secrets.env
# Environment files
.env
.env.local

View File

@@ -15,6 +15,7 @@ This directory contains setup and configuration guides.
- **[MCP_SETUP.md](MCP_SETUP.md)** ⭐⭐ - MCP Server configuration for Claude Desktop
- **[WORMHOLE_AI_RESOURCES_LLM_PLAYBOOK.md](WORMHOLE_AI_RESOURCES_LLM_PLAYBOOK.md)** — Wormhole AI doc bundles: URLs, tier ladder, Chain 138 vs Wormhole boundary, mirror script, MCP
- **[WORMHOLE_AI_RESOURCES_RAG.md](WORMHOLE_AI_RESOURCES_RAG.md)** — RAG / chunking strategy for `llms-full.jsonl` (category-first)
- **[naming-conventions/](naming-conventions/)** — UTRNF / GRU / Chain 138 symbol and registry naming reference (`01_UTRNF_REFERENCE.md`)
- **[ENV_STANDARDIZATION.md](ENV_STANDARDIZATION.md)** ⭐⭐ - Environment variable standardization
- **[CREDENTIALS_CONFIGURED.md](CREDENTIALS_CONFIGURED.md)** ⭐ - Credentials configuration guide
- **[SECRETS_KEYS_CONFIGURATION.md](SECRETS_KEYS_CONFIGURATION.md)** ⭐⭐ - Secrets and keys management

View File

@@ -0,0 +1,243 @@
# Universal Token Role Naming Framework (UTRNF) — reference
**Status:** Protocol-agnostic reference grammar. For DBIS-specific binding (including `c*` tokens), see [02_DBIS_NAMESPACE_AND_UTRNF_MAPPING.md](02_DBIS_NAMESPACE_AND_UTRNF_MAPPING.md).
---
## 1. Objective
Define a standardized naming and structural methodology for tokenized financial instruments representing:
- Deposited assets
- Borrowed liabilities
- Synthetic representations
- Yield-bearing positions
- Collateral instruments
- Reserve abstractions
This framework enables deterministic token discovery, automated balance classification, protocol interoperability, ledger-level accounting automation, and cross-ecosystem composability. Token identity should communicate **financial role**, not only asset type.
---
## 2. Core design principle
**Grammar:**
```text
Prefix = financial role
Symbol body = underlying asset (or pair composition for LP)
Optional suffix = variant metadata
```
**Example (illustrative):**
```text
aUSDC → asset / deposited collateralized position (typical lending)
vdUSDC → variable debt
lpUSDCETH → liquidity pool share
```
Prefixes are intentionally short for gas efficiency and readability.
---
## 3. Universal token role prefix set
| Prefix | Role | Meaning |
|--------|------|---------|
| **a** | Asset | Deposited collateral asset (interest-bearing in typical lending) |
| **vd** | Variable debt | Floating-rate liability |
| **sd** | Stable debt | Fixed-rate liability |
| **y** | Yield | Yield-bearing derivative |
| **c** | Collateral | Locked collateral token (in generic UTRNF; **not** DBIS `c*`) |
| **r** | Reserve | Protocol reserve share |
| **lp** | Liquidity position | Liquidity pool share |
| **s** | Synthetic | Synthetic asset |
| **i** | Incentive | Rewards distribution |
| **x** | Wrapped | Wrapped representation (ecosystem may also use `w`, e.g. WETH) |
---
## 4. Canonical naming format
**Primary:**
```text
<prefix><UnderlyingSymbol>
```
Examples: `aUSDC`, `vdETH`, `sdDAI`, `yBTC`, `cWETH`, `lpUSDCETH`, `sUSD`, `xETH`.
**Extended (variant):**
```text
<prefix><UnderlyingSymbol>-<Variant>
```
Examples: `aUSDC-v3`, `vdETH-isolated`, `lpUSDCETH-30bps`, `yDAI-fixed`.
---
## 5. Token role taxonomy (summary)
### 5.1 Asset tokens — `a<Asset>`
Deposited value; typically interest-bearing, redeemable for underlying, usable as collateral. Accounting: collateralized holdings.
### 5.2 Debt tokens
- **Variable:** `vd<Asset>` — floating rate, dynamic balance, liquidation-sensitive.
- **Stable:** `sd<Asset>` — predictable rate, rebalancing, risk-stabilized layer.
### 5.3 Yield tokens — `y<Asset>`
Vaults, strategy wrappers, farming derivatives.
### 5.4 Liquidity tokens — `lp<TokenA><TokenB>`
Pooled shares; optional fee tier in suffix, e.g. `lpUSDCETH-30bps`.
### 5.5 Synthetic tokens — `s<Asset>`
Price exposure without the same custody model as the spot asset.
### 5.6 Reserve and treasury — `r<Asset>`
Protocol-owned liquidity, backstops, risk buffers.
### 5.7 Wrapped — `x<Asset>` (or `w<Asset>`)
Bridged or wrapped external representation; ecosystem norms choose `x` vs `w`.
---
## 6. Metadata suffix standard
Format: `-<descriptor>`.
Common suffixes:
| Suffix | Meaning |
|--------|---------|
| v2, v3 | Protocol version |
| iso | Isolation mode |
| e | Efficiency mode |
| Nbps | Fee tier (e.g. 5bps) |
| fixed | Fixed yield |
---
## 7. Reserve-level object model (generic)
Every underlying reserve may map to:
```text
Reserve {
underlyingAsset
assetToken // often a<Underlying>
variableDebtToken // vd<Underlying>
stableDebtToken // sd<Underlying>
interestStrategy
}
```
Example triad for `USDC`: `aUSDC`, `vdUSDC`, `sdUSDC`.
---
## 8. Balance classification logic (prefix detection)
Illustrative parsing (pseudocode):
```python
if symbol.startswith("vd"):
classify("variable_debt")
elif symbol.startswith("sd"):
classify("stable_debt")
elif symbol.startswith("lp"):
classify("liquidity")
elif symbol.startswith("a"):
classify("asset")
elif symbol.startswith("y"):
classify("yield")
elif symbol.startswith("s"):
classify("synthetic")
# …extend with longest-prefix rules for multi-letter prefixes
```
**Caveat:** In DBIS, symbols beginning with `c` denote **compliant GRU money**, not UTRNF collateral. Use ecosystem-specific mapping (see doc 02) or registry fields.
---
## 9. Accounting relationships (recommended)
```text
Assets ≈ aTokens + yTokens + lpTokens (context-dependent)
Liabilities ≈ vdTokens + sdTokens
Net equity ≈ Assets Liabilities
```
Yield and debt accrual are protocol-specific; naming signals **role**, not valuation.
---
## 10. Smart contract type naming (suggested)
Align Solidity types with roles where practical: `AssetToken`, `VariableDebtToken`, `StableDebtToken`, `YieldToken`, `LiquidityToken`, `SyntheticToken`, `ReserveToken`. Instance names can mirror symbols for ABI discoverability.
---
## 11. Multichain compatibility
**Same logical name across chains; different deployment:**
- Identical display symbol (e.g. `aUSDC`) may appear on Ethereum, Arbitrum, Polygon, Chain 138, etc.
- **Authoritative differentiation:** `chainId` + **contract address** (+ optional registry version).
This supports cross-chain reconciliation, unified analytics, and bridge-safe classification when combined with bridge metadata.
---
## 12. Registry schema example
```json
{
"underlying": "USDC",
"assetToken": "aUSDC",
"variableDebtToken": "vdUSDC",
"stableDebtToken": "sdUSDC",
"decimals": 6,
"chainId": 1
}
```
Protocols should treat the registry as authoritative for mappings; symbols are a convenience layer.
---
## 13. Cross-protocol benefits
Standardized naming assists wallet auto-classification, risk aggregation, dashboards, and unified portfolio accounting. Ambiguous naming increases misclassification and UI error risk.
---
## 14. Implementation phases (reference)
Suggested rollout (not a commitment for any single repo):
1. **Phase 1 — Token role standardization:** Prefix roles, symbol rules, suffix taxonomy.
2. **Phase 2 — Contract alignment:** Contract names, ABI mappings, registry schema.
3. **Phase 3 — SDK integration:** Prefix parsing, role detection, accounting classification.
4. **Phase 4 — Governance enforcement:** Naming compliance checks before deployment.
---
## 15. Governance recommendation
Formalize in a protocol token standard (PTS): prefix registry, reserved namespaces, versioning, validation tooling, and collision review.
---
## 16. Core insight
Token names are financial metadata encoded as language. Consistent grammar reduces the need for deep contract introspection for **role** identification; **identity** still requires chain-local address and registry discipline.

View File

@@ -0,0 +1,113 @@
# DBIS namespace and UTRNF mapping
**Purpose:** Resolve collisions between the Universal Token Role Naming Framework ([01_UTRNF_REFERENCE.md](01_UTRNF_REFERENCE.md)) and DBIS / GRU / Chain 138 conventions. This document is **authoritative** for interpreting symbols in this repository.
---
## 1. Glossary (read this first)
| Term | Meaning in this repo |
|------|----------------------|
| **UTRNF `c` prefix** | In the generic framework: **collateral** token (locked collateral in a lending-style protocol). |
| **DBIS `c*` symbol** | **Compliant GRU settlement / e-money token** on Chain 138 (and related networks), e.g. `cUSDC`, `cUSDT`, `cXAUC`. **Not** defined as UTRNF collateral. |
| **DBIS `cW*`** | **Compliant wrapped** or public-chain / bridge-facing representation; see GRU transport and mapper docs. |
| **`tokenRole` / registry** | Machine-readable classification; overrides naive prefix parsing when present. |
**Rule:** Never classify `cUSDC`, `cUSDT`, or other DBIS `c*` tokens using UTRNFs “`c` = collateral” row. Use this mapping doc plus registry fields ([04_REGISTRY_AND_JSON_FIELDS.md](04_REGISTRY_AND_JSON_FIELDS.md)).
---
## 2. DBIS-reserved prefixes and families
### 2.1 `c` + underlying ticker (compliant base money)
- **Meaning:** Canonical compliant fiat / commodity-linked GRU tokens (V1 today; V2 evolution per [GRU_C_STAR_V2_STANDARDS_MATRIX_AND_IMPLEMENTATION_PLAN.md](../GRU_C_STAR_V2_STANDARDS_MATRIX_AND_IMPLEMENTATION_PLAN.md)).
- **Examples:** `cUSDC`, `cUSDT`, `cEURC`, `cXAUC`, `cXAUT`.
- **Canonical addresses and decimals:** [EXPLORER_TOKEN_LIST_CROSSCHECK.md](../../11-references/EXPLORER_TOKEN_LIST_CROSSCHECK.md), [ADDRESS_MATRIX_AND_STATUS.md](../../11-references/ADDRESS_MATRIX_AND_STATUS.md).
### 2.2 `cW` + suffix (compliant wrapped / bridge side)
- **Meaning:** Wrapped or mapped representation for transport and public-chain interoperability (not the same contract family as every base `c*`).
- **Configuration:** [C_TO_CW_MAPPER_MAPPING.md](../C_TO_CW_MAPPER_MAPPING.md), `config/token-mapping-multichain.json`, [GRU_TRANSPORT_ACTIVE_JSON.md](../GRU_TRANSPORT_ACTIVE_JSON.md).
### 2.3 Other common Chain 138 symbols
- **`WETH` / `WETH10`:** Wrapped native or project WETH variant; not GRU `c*`. Treat as **wrapped native** or bridge-adjacent per contract docs.
- **`LINK`:** Chainlink token on Chain 138 as deployed; role is **utility/oracle collateral**, not GRU base money.
---
## 3. UTRNF prefixes used as-is in DBIS (when applicable)
When introducing **new** instruments that are not GRU `c*` base money, the following UTRNF prefixes can align with the reference grammar **if** symbols do not conflict with reserved `c*` / `cW*` families:
| UTRNF prefix | Typical use in DBIS context |
|--------------|-----------------------------|
| **a** | Lending-style supplied asset / receipt token (if a product exposes Aave-like semantics). |
| **vd** / **sd** | Variable / stable debt receipts. |
| **y** | Vault or strategy share token. |
| **lp** | DEX or PMM liquidity share (pair composition in symbol or metadata). |
| **r** | Protocol reserve or treasury share (internal accounting). |
| **s** | Synthetic price exposure (distinct from `c*` compliant money). |
| **i** | Incentive / reward distribution token. |
| **x** | Wrapped external asset where the ecosystem chooses `x` over `w`. |
**Wrapped native:** Many ecosystems standardize on **`WETH`**, **`WBTC`**, etc. DBIS may use either UTRNF `x` or de-facto `w*` names; document the choice per deployment.
---
## 4. Collision matrix (UTRNF vs DBIS)
| UTRNF role | UTRNF prefix | DBIS collision? | Action |
|------------|--------------|-----------------|--------|
| Collateral (locked, lending) | `c` | **Yes** | **Do not** map DBIS `cUSDC` to this row. Use `gruCompliantBase` or equivalent registry field. |
| Asset (supplied) | `a` | No | Use if product introduces `a*` tokens. |
| Variable / stable debt | `vd` / `sd` | No | Use if debt tokens are deployed. |
| Liquidity | `lp` | No | Align with pool naming in docs / aggregators. |
| Synthetic | `s` | Low | Avoid ambiguous `s` symbols that look like tickers without registry context. |
| Wrapped | `x` | Low | Distinguish from `WETH10` / bridge-wrapped naming in [03_BRIDGES_CROSS_CHAIN_NAMING.md](03_BRIDGES_CROSS_CHAIN_NAMING.md). |
---
## 5. Registry-first and version-aware identity
Per GRU V2 direction:
- **Symbol alone is insufficient** during V1/V2 coexistence or duplicate ERC-20s on an explorer.
- Use **`assetId`**, **`assetVersionId`**, and **`forwardCanonical`** (or equivalent) in registries.
- Explorer and APIs may show `cUSDC`; bridges and routers must resolve **versioned canonical records**, not bare strings.
---
## 6. GRU monetary layers (M00, M0, M1)
GRU **denominations** (M00 / M0 / M1) describe **monetary policy layers**, not ERC-20 symbol prefixes. If a token is tied to a specific layer, represent that in registry metadata (e.g. `gruLayer`) rather than overloading the ticker. See [gru-docs](https://github.com/) / in-repo GRU formula docs under `gru-docs/` and [GRU_STANDARDS_PROFILE.md](../GRU_STANDARDS_PROFILE.md).
---
## 7. Diagram: UTRNF adoption vs DBIS `c*`
```mermaid
flowchart LR
subgraph utrnf [UTRNF_grammar]
a[a_prefix]
vd[vd_prefix]
lp[lp_prefix]
utrnf_c[c_as_collateral]
end
subgraph dbis [DBIS_Chain138]
cstar[c_star_compliant_money]
cw[cW_wrapped_bridge]
reg[registry_fields]
end
utrnf -->|"adopt where no conflict"| dbis
utrnf_c -.->|"do not map to cUSDT_cUSDC"| cstar
cstar --> reg
cw --> reg
```
---
## 8. Accounting hint (portfolio tools)
For **generic UTRNF** portfolios, tools may use prefix rules from doc 01. For **DBIS Chain 138**, treat **`c*`** balances as **GRU compliant cash / settlement tokens** unless a registry marks a contract as legacy or non-canonical. Debt and LP positions require contract-level roles from the relevant protocol (PMM, vaults, etc.), not inference from `c*`.

View File

@@ -0,0 +1,33 @@
# Naming conventions (UTRNF, GRU, Chain 138, bridges)
**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. |
Planned (not yet in this directory): bridges / cross-chain naming (`03`), registry JSON field guide (`04`) — see related links below until those files land.
## 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 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)
- 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.

View File

@@ -57,6 +57,7 @@
| **GRU standards profile** | [04-configuration/GRU_STANDARDS_PROFILE.md](04-configuration/GRU_STANDARDS_PROFILE.md), [`../config/gru-standards-profile.json`](../config/gru-standards-profile.json) | — |
| **GRU FX onboarding checklist** | [04-configuration/GRU_FX_CURRENCY_ONBOARDING_CHECKLIST.md](04-configuration/GRU_FX_CURRENCY_ONBOARDING_CHECKLIST.md) | — |
| **GRU ISO-4217 currency manifest** | [`../config/gru-iso4217-currency-manifest.json`](../config/gru-iso4217-currency-manifest.json) | — |
| **UTRNF / naming (symbols, registries)** | [04-configuration/naming-conventions/README.md](04-configuration/naming-conventions/README.md), [04-configuration/naming-conventions/01_UTRNF_REFERENCE.md](04-configuration/naming-conventions/01_UTRNF_REFERENCE.md), [04-configuration/naming-conventions/02_DBIS_NAMESPACE_AND_UTRNF_MAPPING.md](04-configuration/naming-conventions/02_DBIS_NAMESPACE_AND_UTRNF_MAPPING.md) | Complements GRU `c* V2` matrix; `03``04` planned |
| Operational runbooks | [03-deployment/OPERATIONAL_RUNBOOKS.md](03-deployment/OPERATIONAL_RUNBOOKS.md) | RUNBOOKS_MASTER_INDEX.md — use OPERATIONAL_RUNBOOKS as single source |
| Contract / address status | [11-references/ADDRESS_MATRIX_AND_STATUS.md](11-references/ADDRESS_MATRIX_AND_STATUS.md), [11-references/CONTRACT_ADDRESSES_REFERENCE.md](11-references/CONTRACT_ADDRESSES_REFERENCE.md), [11-references/CONTRACT_NEXT_STEPS_LIST.md](11-references/CONTRACT_NEXT_STEPS_LIST.md) (64-addr check) | CONTRACT_INVENTORY_AND_VERIFICATION (deleted) |
| **Proxmox VMIDs, LAN IPs, NPM targets** | [04-configuration/ALL_VMIDS_ENDPOINTS.md](04-configuration/ALL_VMIDS_ENDPOINTS.md) (includes **Proxmox Mail Proxy** VMID 100 / `192.168.11.32`), [`config/ip-addresses.conf`](../config/ip-addresses.conf), [11-references/NETWORK_CONFIGURATION_MASTER.md](11-references/NETWORK_CONFIGURATION_MASTER.md), [`config/proxmox-operational-template.json`](../config/proxmox-operational-template.json) | Dated inventories under `docs/archive/` (paths on disk only) |

View File

@@ -40,6 +40,9 @@ rm -f cache/solidity-files-cache.json
run forge test --match-path "test/compliance/CompliantFiatTokenV2.t.sol"
ok "CompliantFiatTokenV2 base token suite passed."
run forge test --match-path "test/compliance/CompliantWrappedTokenTest.t.sol"
ok "CompliantWrappedToken governance and transport metadata suite passed."
run forge test --match-path "test/bridge/CWReserveVerifierVaultIntegration.t.sol"
ok "Legacy reserve-verifier bridge compatibility suite passed."
@@ -49,6 +52,9 @@ ok "V2 reserve-verifier + full L1/L2 transport suite passed."
run forge test --match-path "test/bridge/CWMultiTokenBridge.t.sol"
ok "Core CWMultiTokenBridge round-trip suite passed."
run forge test --match-path "test/integration/JurisdictionalGovernance.t.sol"
ok "Jurisdictional governance and approval gating suite passed."
popd >/dev/null
log ""