diff --git a/.gitignore b/.gitignore index 51110ec..e09ed82 100644 --- a/.gitignore +++ b/.gitignore @@ -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 diff --git a/docs/04-configuration/README.md b/docs/04-configuration/README.md index 7a0ecd4..2ee1a09 100644 --- a/docs/04-configuration/README.md +++ b/docs/04-configuration/README.md @@ -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 diff --git a/docs/04-configuration/naming-conventions/01_UTRNF_REFERENCE.md b/docs/04-configuration/naming-conventions/01_UTRNF_REFERENCE.md new file mode 100644 index 0000000..34ddfdb --- /dev/null +++ b/docs/04-configuration/naming-conventions/01_UTRNF_REFERENCE.md @@ -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 + +``` + +Examples: `aUSDC`, `vdETH`, `sdDAI`, `yBTC`, `cWETH`, `lpUSDCETH`, `sUSD`, `xETH`. + +**Extended (variant):** + +```text +- +``` + +Examples: `aUSDC-v3`, `vdETH-isolated`, `lpUSDCETH-30bps`, `yDAI-fixed`. + +--- + +## 5. Token role taxonomy (summary) + +### 5.1 Asset tokens — `a` + +Deposited value; typically interest-bearing, redeemable for underlying, usable as collateral. Accounting: collateralized holdings. + +### 5.2 Debt tokens + +- **Variable:** `vd` — floating rate, dynamic balance, liquidation-sensitive. +- **Stable:** `sd` — predictable rate, rebalancing, risk-stabilized layer. + +### 5.3 Yield tokens — `y` + +Vaults, strategy wrappers, farming derivatives. + +### 5.4 Liquidity tokens — `lp` + +Pooled shares; optional fee tier in suffix, e.g. `lpUSDCETH-30bps`. + +### 5.5 Synthetic tokens — `s` + +Price exposure without the same custody model as the spot asset. + +### 5.6 Reserve and treasury — `r` + +Protocol-owned liquidity, backstops, risk buffers. + +### 5.7 Wrapped — `x` (or `w`) + +Bridged or wrapped external representation; ecosystem norms choose `x` vs `w`. + +--- + +## 6. Metadata suffix standard + +Format: `-`. + +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 + variableDebtToken // vd + stableDebtToken // sd + 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. diff --git a/docs/04-configuration/naming-conventions/02_DBIS_NAMESPACE_AND_UTRNF_MAPPING.md b/docs/04-configuration/naming-conventions/02_DBIS_NAMESPACE_AND_UTRNF_MAPPING.md new file mode 100644 index 0000000..04c59c9 --- /dev/null +++ b/docs/04-configuration/naming-conventions/02_DBIS_NAMESPACE_AND_UTRNF_MAPPING.md @@ -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 UTRNF’s “`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*`. diff --git a/docs/04-configuration/naming-conventions/README.md b/docs/04-configuration/naming-conventions/README.md new file mode 100644 index 0000000..17e608f --- /dev/null +++ b/docs/04-configuration/naming-conventions/README.md @@ -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. diff --git a/docs/MASTER_INDEX.md b/docs/MASTER_INDEX.md index 01f4f6f..4624792 100644 --- a/docs/MASTER_INDEX.md +++ b/docs/MASTER_INDEX.md @@ -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) | diff --git a/scripts/verify/check-cstar-v2-transport-stack.sh b/scripts/verify/check-cstar-v2-transport-stack.sh index 3ed7341..0b78fbe 100644 --- a/scripts/verify/check-cstar-v2-transport-stack.sh +++ b/scripts/verify/check-cstar-v2-transport-stack.sh @@ -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 ""