b3a8fe4496
- Config, docs, scripts, and backup manifests - Submodule refs unchanged (m = modified content in submodules) Made-with: Cursor
12 KiB
GRU M00 Diamond — Institutional Architecture Spec
Purpose: Buildable blueprint for a single “giant Token Factory” inside the GRU ERC-2535 Diamond. Each currency + a/d token family is implemented as an upgradeable facet set; the GRU Diamond contains governance + storage placeholders for IPSAS, IFRS/US GAAP, ISO-20022, i18n, and future governance levels. Hand-off for whitepaper/tech spec and Solidity engineers.
Related: GRU_M00_DIAMOND_FACET_MAP.md (single-page facet map, storage namespaces, governance levels, symbol grammar) | GRU_M00_DIAMOND_REVIEW_GAPS_AND_RECOMMENDATIONS.md (gaps and wire-ins).
GRU Diamond evolution (GRC-2535 vs M00)
GRC-2535 (in gru-docs/contracts) is the current GRU Diamond: GrcDiamond + GRCStorage + Monetary, Triangulation, Index, Bond, Audit, Governance, Access, Pause facets. M00 Diamond extends or replaces it with the Token Factory, GRUStorage (seven domains), PolicyRouter + gates, and standards placeholders. Decision: Either (1) migrate GRC → M00 (same contract, add/replace facets and extend storage with reserved GRUStorage namespaces) or (2) deploy M00 as a new Diamond and deprecate GRC for token/market flows. Document the chosen path in the deployment runbook.
Existing registries: Until M00 is deployed, UniversalAssetRegistry (smom-dbis-138) remains the source of truth for bridges and token lists. After M00 is live, migrate or mirror to GRUStorage.TokenFactoryRegistry and document the cutover.
1) Diamond Topology Overview
Core Principle
- GRU = M00 Diamond (ERC-2535)
- All c-tokens + a-tokens + d-tokens are minted/managed by facets attached to the GRU Diamond.
- Storage is centralized in shared app storage to ensure upgrades don’t break state.
- Governance is layered and expandable: policy modules are “plugged in” as facets without changing base state layout.
Key idea:
“Tokens aren’t separate systems; they are markets inside the GRU Diamond, emitted as ERC-20 instances or ledgered as internal balance sheets, governed by standards modules.”
2) Storage Layout (Permanent / Upgrade-Safe)
A) Diamond App Storage (GRUStorage)
Use placeholder storage for many future standards:
- a fixed storage struct (core)
- a namespaced storage registry for standards modules
- a policy bitmask and module pointer map
Core Storage Domains
- Governance & Roles — DAO / Council / Guardian roles; emergency pause authorities; upgrade admin / timelock address; policy controllers (per module).
- Token Factory Registry — mapping of
assetId → token addresses(c, a, d variants); mapping of symbol → assetId (canonical parsing); per-asset configuration (decimals, mint rules, chain domain, W positioning, etc.). - Accounting / Ledger — Journal entries (debits/credits); chart of accounts; cost centers / funds / projects; per-asset reserve attestations; policy metadata hashes (auditable). Standards-neutral so IFRS/USGAAP/IPSAS can be added without refactoring.
- 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; message “canonicalization” hashes; correlation IDs for settlement events.
- Internationalization (i18n) Registry — Locale packs (hash pointers); translation keys for UI/client consumption; multi-jurisdiction disclosure templates.
- Expandable Standards Registry — mapping
standardId => moduleConfig(enabled flags, version, validator contracts, policy-level constraints, data namespace pointers). Enables “turning on” IPSAS or ISO-20022 without migrating storage.
3) Facet Families (Modular + Upgradeable)
A) Core Diamond Facets (always present)
- DiamondCutFacet (upgrade)
- DiamondLoupeFacet (introspection)
- Ownership/GovernanceFacet (admin model, timelocks)
- Pause/GuardianFacet (risk controls)
B) Token Factory Facets
- AssetRegistryFacet — create/modify asset definition (ISO code, type, decimals); enforce W positional semantics; generate assetId deterministic hash.
- MarketFactoryFacet — create a “market” for a given ISO asset; emit token contracts for c (compliant base), a (asset/claim), d (debt/liability).
- MintBurnFacet — mint/burn rules; reserve gating; supply caps; emergency locks.
- InterestRateFacet (Aave-style) — index math for a/d behavior; rate model plug-ins (stable/variable); accrual triggers.
- BridgeWrapFacet — W before ISO assets (wrapped bridge); escrow proofs; bridge operators / trust model.
- DWINFacet — W after T/C (D-WIN); denomination logic; optional “windowing” rules (maturity, buckets, liquidity windows).
C) Standards / Compliance Facets (placeholders, expandable later)
- IPSASFacet — GRU ledger ↔ IPSAS reporting; fund accounting.
- IFRS/USGAAPFacet — Revenue recognition; lease/contract classification hooks; impairment / reserve adequacy reporting.
- ISO20022Facet — Message builders (pacs/camt); standard dictionary mapping per assetId; settlement event correlation.
- i18nFacet — Multi-language disclosure strings by jurisdiction; “legal label packs” versioned and signed.
- GovernanceLevelFacet — Policy levels 0..N; each level toggles KYC, transfer restrictions, message logging, accounting journal mandatory, oracle requirements, timelock durations, which standards must be enabled. Reads policy bitmask in storage and routes enforcement.
4) Governance Model (Expandable + Imposed Levels)
- Level 0: Free / devnet / sandbox rules.
- Level 1: KYC optional + audit logs.
- Level 2: KYC required + reserve proofs + ISO-20022 logging.
- Level 3: IPSAS/IFRS reporting enforced + restricted transfer sets.
- Level 4+: Sovereign/regulated regime enforcement + multi-sig + external attestors + longer timelocks.
Implementation: A PolicyRouter (facet) calls ComplianceGate.checkTransfer(...), AccountingGate.postJournal(...), MessagingGate.logISO20022(...), ReserveGate.checkBacking(...). Each gate is replaceable via facet upgrade.
5) How Currency Codes Become “Markets” Inside GRU
For each ISO-4217 code (USD, EUR, JPY, etc.):
- c<ISO><T|C> (base compliant eMoney)
- a<ISO><T|C> (asset token / claim index)
- d<ISO><T|C> (debt token / liability index)
W rules: Wrapped bridge = W before ISO (e.g. aWUSDT, dWUSDT, cWUSDT). D-WIN = W after T/C (e.g. aUSDTW, dUSDTW, cUSDTW). Enforced in AssetRegistryFacet with deterministic parsing.
6) What “Upgradeable Facet per ISO” Means (Practical)
Pattern A (recommended): One Factory, Many Assets (data-driven) — One set of facets supports unlimited assets via config records. Safer: fewer upgrades, less surface area.
Pattern B (if required): “Facet Packs” per asset family — For major markets (USD/EUR), deploy specialized facets (special rate model, compliance regime, settlement rules). Storage remains standard.
Target (locked): Pattern A as default. Pattern B only for flagship USD/EUR asset families if required.
7) Minimum Placeholder Checklist (What GRU must include now)
- AppStorage skeleton — module registry; policy bitmask; ledger/journal base structs; ISO-20022 log structs; i18n registry structs.
- GovernanceFacet — role-based access control; timelock hooks; upgrade approval workflow.
- PolicyRouterFacet — empty gates initially, but callable; emits events for auditability.
- TokenFactoryFacet — can register assets; can deploy token instances (or ledgered balances if internal accounting).
- ComplianceGateFacet (stub) — allowlist/denylist placeholder; jurisdiction tags placeholder.
- AccountingGateFacet (stub) — journal entry emission placeholder; chart of accounts placeholder.
- StandardsRegistryFacet — activate/deactivate modules; enforce “required modules for governance level X.”
8) One Key Design Decision You Should Lock
Are tokens:
- A) Separate ERC-20 contracts deployed by GRU (Aave-like)
- B) Internal ledger balances inside GRU with ERC-20 views
- C) Hybrid: ERC-20 external interface, authoritative balances in GRU ledger (tokens as thin proxies)
For DeFi compatibility, A is simplest. For sovereign accounting + ISO-20022 tight control, B is more “bank-core-like.”
Locked decision: Token model A (separate ERC-20 contracts deployed by GRU, Aave-like). For DeFi compatibility and simplest integration. B or C may be chosen later if sovereign/accounting requirements dictate.
Deployment target chain and CREATE2
- Primary chain: Chain 138 (DeFi Oracle Meta Mainnet) first; then mainnet (1), 651940 (ALL Mainnet), or other EVM chains as needed.
- CREATE2: Use CREATE2 when the same M00 Diamond address is required across chains; otherwise CREATE is acceptable for single-chain (e.g. 138-only) deployment.
- Default governance level at deployment: 0 (Free / devnet / sandbox). Set via GovernanceLevelFacet after init. For production, set to 1 or 2 (or per policy) in a separate init step.
- Runbook: GRU_M00_DIAMOND_DEPLOYMENT_RUNBOOK.md.
Appendix: PolicyRouter and gate event signatures
For auditability and indexers, PolicyRouter and gates SHOULD emit the following events (or equivalent). Implement when building the spine.
| Event | Signature (semantic) | Emitted by |
|---|---|---|
| TransferChecked | TransferChecked(address from, address to, address token, uint256 amount, bool allowed, bytes32 reason) |
PolicyRouter after ComplianceGate.checkTransfer |
| JournalPosted | JournalPosted(bytes32 journalId, bytes32 coaRef, uint256 amount, address token) |
PolicyRouter after AccountingGate.postJournal |
| MessageLogged | MessageLogged(bytes32 correlationId, bytes32 payloadHash, string msgType) |
PolicyRouter after MessagingGate.logISO20022 |
| BackingChecked | BackingChecked(bytes32 assetId, uint256 amount, bool sufficient, bytes32 attestationHash) |
PolicyRouter after ReserveGate.checkBacking |
| GovernanceLevelSet | GovernanceLevelSet(uint8 previousLevel, uint8 newLevel) |
GovernanceLevelFacet when level is updated |
Use indexed parameters where appropriate (e.g. indexed address token, indexed bytes32 correlationId) for efficient filtering. Full ABI and parameter types to be defined in the implementation.
Related documents
- GRU_M00_DIAMOND_FACET_MAP.md — Facet map, storage namespaces, governance levels 0–5, canonical symbol grammar.
- GRU_M00_DIAMOND_REVIEW_GAPS_AND_RECOMMENDATIONS.md — Missing components, wire-ins, recommendations.
- GRU_M00_DIAMOND_DOCS_REVIEW_GAPS_AND_INCONSISTENCIES.md — Docs review (gaps and inconsistencies).
- gru-docs/contracts/README.md — GRC-2535 Diamond.
- TOKEN_SCOPE_GRU.md — c/a/d and W token lists.
- VAULT_SYSTEM_MASTER_TECHNICAL_PLAN.md — Vault and M00 reference.
- GRU_M00_DIAMOND_DEPLOYMENT_RUNBOOK.md — Deploy or migrate M00; target chain, CREATE2, default governance level, testing.