b3a8fe4496
Some checks failed
Deploy to Phoenix / deploy (push) Has been cancelled
- Config, docs, scripts, and backup manifests - Submodule refs unchanged (m = modified content in submodules) Made-with: Cursor
203 lines
10 KiB
Markdown
203 lines
10 KiB
Markdown
# GRU M00 Diamond — Facet Map and Module List (Whitepaper)
|
||
|
||
**Purpose:** Single-page reference for the GRU M00 Diamond (ERC-2535) Token Factory architecture. For Solidity engineers and whitepaper authors. All c/a/d token families are implemented as upgradeable facets; storage and governance placeholders support IPSAS, IFRS/US GAAP, ISO-20022, i18n, and future governance levels.
|
||
|
||
**Token model:** **A** (locked). Separate ERC-20 contracts deployed by GRU (Aave-like). See [institutional spec §8](GRU_M00_DIAMOND_INSTITUTIONAL_SPEC.md#8-one-key-design-decision-you-should-lock). **Target pattern:** **A** (one factory, many assets); Pattern B only for flagship USD/EUR if needed. See [institutional spec §6](GRU_M00_DIAMOND_INSTITUTIONAL_SPEC.md#6-what-upgradeable-facet-per-iso-means-practical).
|
||
|
||
---
|
||
|
||
## 1. Facet Map (Mermaid)
|
||
|
||
```mermaid
|
||
flowchart TB
|
||
subgraph diamond [GRU M00 Diamond]
|
||
M00[M00 Diamond]
|
||
end
|
||
|
||
subgraph core [Core Facets]
|
||
DiamondCut[DiamondCutFacet]
|
||
DiamondLoupe[DiamondLoupeFacet]
|
||
Ownership[OwnershipFacet]
|
||
Pause[PauseFacet]
|
||
end
|
||
|
||
subgraph tokenFactory [Token Factory Facets]
|
||
AssetRegistry[AssetRegistryFacet]
|
||
MarketFactory[MarketFactoryFacet]
|
||
MintBurn[MintBurnFacet]
|
||
InterestRate[InterestRateFacet]
|
||
BridgeWrap[BridgeWrapFacet]
|
||
DWIN[DWINFacet]
|
||
end
|
||
|
||
subgraph standards [Standards and Compliance Facets]
|
||
IPSAS[IPSASFacet]
|
||
IFRS[IFRSUSGAAPFacet]
|
||
ISO20022[ISO20022Facet]
|
||
i18n[i18nFacet]
|
||
GovLevel[GovernanceLevelFacet]
|
||
end
|
||
|
||
subgraph gates [Policy Gates]
|
||
PolicyRouter[PolicyRouterFacet]
|
||
ComplianceGate[ComplianceGate]
|
||
AccountingGate[AccountingGate]
|
||
MessagingGate[MessagingGate]
|
||
ReserveGate[ReserveGate]
|
||
end
|
||
|
||
M00 --> DiamondCut
|
||
M00 --> DiamondLoupe
|
||
M00 --> Ownership
|
||
M00 --> Pause
|
||
M00 --> AssetRegistry
|
||
M00 --> MarketFactory
|
||
M00 --> MintBurn
|
||
M00 --> InterestRate
|
||
M00 --> BridgeWrap
|
||
M00 --> DWIN
|
||
M00 --> IPSAS
|
||
M00 --> IFRS
|
||
M00 --> ISO20022
|
||
M00 --> i18n
|
||
M00 --> GovLevel
|
||
M00 --> PolicyRouter
|
||
PolicyRouter --> ComplianceGate
|
||
PolicyRouter --> AccountingGate
|
||
PolicyRouter --> MessagingGate
|
||
PolicyRouter --> ReserveGate
|
||
```
|
||
|
||
---
|
||
|
||
## 2. Exact Facet Names
|
||
|
||
### 2.1 Facets by family
|
||
|
||
| Facet name | Role | Notes |
|
||
|------------|------|--------|
|
||
| **Core** | | |
|
||
| DiamondCutFacet | Upgrade mechanism | ERC-2535 diamondCut |
|
||
| DiamondLoupeFacet | Introspection | facets, facetAddress, selectors |
|
||
| OwnershipFacet | Admin / governance | Owner, timelock, upgrade approval (or use GovernanceFacet) |
|
||
| PauseFacet | Risk controls | Global and per-selector pause (GuardianFacet alias) |
|
||
| **Token Factory** | | |
|
||
| AssetRegistryFacet | Asset definitions | ISO code, type, decimals; W positional semantics; assetId hash |
|
||
| MarketFactoryFacet | Market creation | Emits c/a/d token contracts per ISO asset |
|
||
| MintBurnFacet | Supply controls | Mint/burn rules, reserve gating, supply caps, emergency locks |
|
||
| InterestRateFacet | Aave-style indices | Index math for a/d; rate model plug-ins; accrual triggers |
|
||
| BridgeWrapFacet | W-before-ISO | Wrapped bridge; escrow proofs; bridge operators |
|
||
| DWINFacet | W-after-T/C | D-WIN; denomination logic; optional windowing rules |
|
||
| **Standards / Compliance** | | |
|
||
| IPSASFacet | Public sector accounting | GRU ledger ↔ IPSAS reporting; fund accounting |
|
||
| IFRSUSGAAPFacet | IFRS / US GAAP | Revenue recognition, lease/contract hooks, impairment/reserve reporting |
|
||
| ISO20022Facet | Message builders | pacs/camt payloads; dictionary mapping; settlement correlation |
|
||
| i18nFacet | Internationalization | Locale packs, translation keys, disclosure templates |
|
||
| GovernanceLevelFacet | Policy levels | Reads policy bitmask; routes enforcement per level 0..N |
|
||
| **Minimum ship list (stubs)** | | |
|
||
| PolicyRouterFacet | Gate orchestration | Calls Compliance, Accounting, Messaging, Reserve gates |
|
||
| ComplianceGateFacet | Stub | Allowlist/denylist, jurisdiction tags placeholders |
|
||
| AccountingGateFacet | Stub | Journal entry and chart-of-accounts placeholders |
|
||
| StandardsRegistryFacet | Module activation | Activate/deactivate modules; enforce required modules per governance level |
|
||
|
||
### 2.2 Gates (used by PolicyRouter)
|
||
|
||
| Gate | Purpose |
|
||
|------|---------|
|
||
| ComplianceGate | checkTransfer (KYC/AML, sanctions, jurisdiction) |
|
||
| AccountingGate | postJournal (ledger entries, CoA) |
|
||
| MessagingGate | logISO20022 (message logging, correlation IDs) |
|
||
| ReserveGate | checkBacking (reserve proofs, attestations) |
|
||
|
||
Each gate is replaceable via facet upgrade. The **minimum ship list** (§2.1) explicitly includes ComplianceGateFacet and AccountingGateFacet stubs; MessagingGate and ReserveGate may be stubbed or implemented in a later phase.
|
||
|
||
---
|
||
|
||
## 3. Storage Namespaces (GRUStorage)
|
||
|
||
App storage is centralized in **GRUStorage** with namespaced domains so upgrades do not break state.
|
||
|
||
| Namespace / domain | Contents |
|
||
|--------------------|----------|
|
||
| Governance & roles | DAO / Council / Guardian roles; emergency pause authorities; upgrade admin; timelock address; policy controllers per module |
|
||
| Token Factory Registry | assetId → token addresses (c, a, d); symbol → assetId; per-asset config (decimals, mint rules, chain domain, W positioning) |
|
||
| Accounting / Ledger | Journal entries (debits/credits); chart of accounts; cost centers / funds / projects; per-asset reserve attestations; policy metadata hashes |
|
||
| Compliance & Identity | KYC/AML allowlists; jurisdiction tags; sanctions flags; travel rule metadata pointers; audit proof roots |
|
||
| ISO-20022 Message Vault | Message schemas registry; outbound/inbound message logs; canonicalization hashes; correlation IDs for settlement events |
|
||
| i18n Registry | Locale packs (hash pointers); translation keys for UI/clients; multi-jurisdiction disclosure templates |
|
||
| Expandable Standards Registry | standardId → moduleConfig: enabled, version, validator contracts, policy-level constraints, data namespace pointers |
|
||
|
||
---
|
||
|
||
## 4. Governance Levels (0–5)
|
||
|
||
GovernanceLevelFacet reads the policy bitmask; PolicyRouter calls the gates according to the active level. **Default at deployment:** level **0** (Free / devnet / sandbox); set via GovernanceLevelFacet after init. See [GRU_M00_DIAMOND_DEPLOYMENT_RUNBOOK.md](../runbooks/GRU_M00_DIAMOND_DEPLOYMENT_RUNBOOK.md) and institutional spec.
|
||
|
||
| Level | Name | KYC | Reserves | ISO-20022 | Accounting | Transfer restrictions | Timelock / attestors |
|
||
|-------|------|-----|----------|-----------|-------------|----------------------|----------------------|
|
||
| 0 | Free / devnet / sandbox | No | No | No | No | None | Minimal |
|
||
| 1 | KYC optional + audit | Optional | No | No | Audit logs | None | Standard |
|
||
| 2 | KYC required + proofs | Required | Reserve proofs | Logging | Journal optional | Per policy | Standard |
|
||
| 3 | IPSAS/IFRS enforced | Required | Reserve proofs | Logging | Journal mandatory | Restricted sets | Extended |
|
||
| 4 | Sovereign / regulated | Required | Attestations | Full | Full reporting | Restricted + allowlists | Multi-sig, attestors |
|
||
| 5 | Maximum compliance | Required | Full attestations | Full | Full + disclosures | Strict allowlists | Long timelocks, external attestors |
|
||
|
||
---
|
||
|
||
## 5. Canonical Symbol Grammar
|
||
|
||
Enforced in **AssetRegistryFacet** with deterministic parsing.
|
||
|
||
### 5.1 Market artifacts per ISO-4217
|
||
|
||
| Prefix | Meaning | Example |
|
||
|--------|---------|---------|
|
||
| c\<ISO>\<T\|C\> | Base compliant eMoney | cUSDC, cEURCT |
|
||
| a\<ISO>\<T\|C\> | Asset token / claim index | aUSDC, aEURCT |
|
||
| d\<ISO>\<T\|C\> | Debt token / liability index | dUSDC, dEURCT |
|
||
|
||
\<T\|C\> = issuer/type suffix (e.g. T = Tether, C = Circle-style).
|
||
|
||
### 5.2 W rules
|
||
|
||
- **W before ISO (wrapped bridge):** `W` precedes the ISO code.
|
||
Examples: `cWUSDT`, `aWUSDT`, `dWUSDT`.
|
||
- **W after T/C (D-WIN):** `W` follows the T or C suffix.
|
||
Examples: `cUSDTW`, `aUSDTW`, `dUSDTW`.
|
||
|
||
### 5.3 BNF-style summary
|
||
|
||
```
|
||
symbol := (c|a|d) iso_suffix | (c|a|d) W iso_suffix | (c|a|d) iso_suffix W
|
||
iso_suffix := <ISO4217 code><T|C> e.g. USDC, USDT, EURCT, EURCC
|
||
```
|
||
|
||
### 5.4 Examples
|
||
|
||
| Symbol | Interpretation |
|
||
|--------|----------------|
|
||
| cUSDC | Compliant base eMoney, USD (Circle-style) |
|
||
| aEURCT | Asset token, EUR (Tether) |
|
||
| dWUSDT | Debt token, wrapped USDT (bridge) |
|
||
| cUSDTW | Compliant base, USDT D-WIN (denomination/windowing) |
|
||
|
||
### 5.5 Mapping to deployed token names (a/d vs ac/vdc/sdc)
|
||
|
||
The canonical grammar uses **a** (asset) and **d** (debt). In the codebase and [TOKEN_SCOPE_GRU](../../smom-dbis-138/docs/tokenization/TOKEN_SCOPE_GRU.md), the same roles use Aave-style names: **a** ↔ **ac** (DepositToken, e.g. acUSDC, acUSDT), **d** ↔ **vdc** / **sdc** (DebtToken, e.g. vdcUSDC, sdcUSDC). The registry may store either form (aUSDC or acUSDC); both denote the same asset token type.
|
||
|
||
### 5.6 ISO-4217 Compliant Token Matrix (native / bridged)
|
||
|
||
The grammar above aligns with the [ISO4217 Compliant Token Matrix](ISO4217_COMPLIANT_TOKEN_MATRIX.md): native symbols 6-char (`c` + FinChain + ISO + Type), bridged 7-char (`c` + `W` + OriginFinChain + ISO + Type). **ChainID 138 only:** native symbols are v0 (no designator) — `cUSDC`, `cUSDT`; the X is left out. X is used only for origin reference (e.g. bridged `cWXUSDC` on other chains). Registry maps v0 → identity for reporting.
|
||
|
||
---
|
||
|
||
## Related documents
|
||
|
||
- **Full architecture spec:** [GRU_M00_DIAMOND_INSTITUTIONAL_SPEC.md](GRU_M00_DIAMOND_INSTITUTIONAL_SPEC.md) (§1–§8, token model and Pattern A locked).
|
||
- **Detailed review (gaps, wire-ins, recommendations):** [GRU_M00_DIAMOND_REVIEW_GAPS_AND_RECOMMENDATIONS.md](GRU_M00_DIAMOND_REVIEW_GAPS_AND_RECOMMENDATIONS.md).
|
||
- **Docs review (gaps and inconsistencies):** [GRU_M00_DIAMOND_DOCS_REVIEW_GAPS_AND_INCONSISTENCIES.md](GRU_M00_DIAMOND_DOCS_REVIEW_GAPS_AND_INCONSISTENCIES.md).
|
||
- **Existing Diamond (GRC-2535):** [gru-docs/contracts/README.md](../../gru-docs/contracts/README.md). The GRU docs repo is also available as a standalone clone (e.g. **GRU-Official-Docs-Monetary-Policies**); in this repo it is the submodule `gru-docs/`. See [SUBMODULE_RELATIONSHIP_MAP.md](../11-references/SUBMODULE_RELATIONSHIP_MAP.md).
|
||
- **Token scope (c/a/d, W):** [smom-dbis-138/docs/tokenization/TOKEN_SCOPE_GRU.md](../../smom-dbis-138/docs/tokenization/TOKEN_SCOPE_GRU.md).
|
||
- **ISO-4217 compliant symbol matrix (native/bridged, v0/v1):** [ISO4217_COMPLIANT_TOKEN_MATRIX.md](ISO4217_COMPLIANT_TOKEN_MATRIX.md).
|
||
- **Vault / M00 reference:** [VAULT_SYSTEM_MASTER_TECHNICAL_PLAN.md](../VAULT_SYSTEM_MASTER_TECHNICAL_PLAN.md).
|