Files

Deploy to Phoenix / deploy (push) Has been cancelled

Details

- Config, docs, scripts, and backup manifests
- Submodule refs unchanged (m = modified content in submodules)

Made-with: Cursor

2026-03-02 11:37:34 -08:00

10 KiB

Raw Blame History

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. Target pattern: A (one factory, many assets); Pattern B only for flagship USD/EUR if needed. See institutional spec §6.

1. Facet Map (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 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, 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: 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.

Full architecture spec: 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.
Docs review (gaps and inconsistencies): GRU_M00_DIAMOND_DOCS_REVIEW_GAPS_AND_INCONSISTENCIES.md.
Existing Diamond (GRC-2535): 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.
Token scope (c/a/d, W): smom-dbis-138/docs/tokenization/TOKEN_SCOPE_GRU.md.
ISO-4217 compliant symbol matrix (native/bridged, v0/v1): ISO4217_COMPLIANT_TOKEN_MATRIX.md.
Vault / M00 reference: VAULT_SYSTEM_MASTER_TECHNICAL_PLAN.md.

10 KiB Raw Blame History Unescape Escape