diff --git a/.gitignore b/.gitignore index e09ed82..650582d 100644 --- a/.gitignore +++ b/.gitignore @@ -32,6 +32,19 @@ Thumbs.db # Local-only Cursor session / context (exclude from Gitea) .cursor/local/ +# Local Codex / IDE artifacts +.codex +.codex/ + +# Scratch and regenerated audit trees (re-run OMNL/JVMTM scripts to reproduce) +tmp/ +output/jvmtm-evidence/ +output/settlement-events/ +output/omnl-e2e-settlement-audit-*/ +output/*compliance-archive*.zip +output/omnl-e2e-settlement-audit-*.zip +output/transaction-package-HYBX-BATCH-001/ + # IDE files .vscode/ .idea/ @@ -63,6 +76,7 @@ __pycache__/ # CoinGecko/CMC token logos (generated by prepare-token-logos-512x512.sh) docs/04-configuration/coingecko/logos/*.png +token-lists/logos/*.png # Ephemeral phase markers .phase1-event-status diff --git a/config/gru-governance-supervision-profile.json b/config/gru-governance-supervision-profile.json new file mode 100644 index 0000000..64db0c8 --- /dev/null +++ b/config/gru-governance-supervision-profile.json @@ -0,0 +1,109 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "name": "GRU Governance and Supervision Profile", + "profileId": "gru-jurisdictional-storage-governance-supervision", + "version": "1.0.0", + "updated": "2026-03-31", + "notes": "Machine-readable policy profile for asset storage namespaces, jurisdiction-aware governance review, supervision metadata, and upgrade notice periods across c*, cW*, GRU base components, and tokenized assets.", + "references": { + "standardsProfile": "config/gru-standards-profile.json", + "storageGovernanceDoc": "docs/04-configuration/GRU_STORAGE_GOVERNANCE_AND_SUPERVISION_STANDARD.md", + "governanceDoc": "gru-docs/_core/04_GRU_Governance_Regulatory_Oversight.md", + "diamondSpecDoc": "docs/04-configuration/GRU_M00_DIAMOND_INSTITUTIONAL_SPEC.md" + }, + "requiredAssetMetadata": [ + "assetId", + "assetVersionId", + "governanceProfileId", + "supervisionProfileId", + "storageNamespace", + "primaryJurisdiction", + "regulatoryDisclosureURI", + "reportingURI", + "canonicalUnderlyingAsset", + "supervisionRequired", + "governmentApprovalRequired", + "minimumUpgradeNoticePeriod" + ], + "roles": { + "tokenRoles": [ + "DEFAULT_ADMIN_ROLE", + "MINTER_ROLE", + "BURNER_ROLE", + "PAUSER_ROLE", + "BRIDGE_ROLE", + "SUPPLY_ADMIN_ROLE", + "METADATA_ADMIN_ROLE", + "GOVERNANCE_ROLE", + "JURISDICTION_ADMIN_ROLE", + "REGULATOR_ROLE", + "SUPERVISOR_ROLE" + ], + "registryRoles": [ + "DEFAULT_ADMIN_ROLE", + "REGISTRAR_ROLE", + "PROPOSER_ROLE", + "VALIDATOR_ROLE", + "UPGRADER_ROLE", + "JURISDICTION_MANAGER_ROLE", + "REGULATOR_ROLE", + "SUPERVISOR_ROLE" + ], + "governanceRoles": [ + "DEFAULT_ADMIN_ROLE", + "PROPOSER_ROLE", + "EXECUTOR_ROLE", + "CANCELLER_ROLE", + "UPGRADER_ROLE", + "JURISDICTION_TAGGER_ROLE" + ] + }, + "storageNamespaces": { + "canonicalCStarPattern": "gru.storage.asset..", + "wrappedCWStarPattern": "gru.storage.transport.", + "registryPattern": "gru.storage.registry.", + "diamondNamespaces": [ + "grc.storage.monetary", + "grc.storage.index", + "grc.storage.bond", + "grc.storage.gov", + "grc.storage.audit", + "grc.storage.access", + "grc.storage.pause", + "grc.storage.triang", + "grc.storage.reentrancy" + ] + }, + "proposalPolicy": { + "jurisdictionTagRequiredForUpgradeSensitiveChanges": true, + "queueRequiresJurisdictionApprovalWhenFlagged": true, + "defaultMinimumUpgradeNoticePeriodSeconds": 604800, + "approvalSource": "UniversalAssetRegistry.jurisdictionAuthorities", + "minimumReviewData": [ + "jurisdictionId", + "reviewRequired", + "minimumNoticePeriod" + ] + }, + "jurisdictionDefaults": { + "supervisionRequiredDefault": true, + "governmentApprovalRequiredDefault": false, + "periodicReportingRecommended": true, + "primaryEvidenceFields": [ + "policyHash", + "supervisionURI", + "regulatoryDisclosureURI", + "reportingURI" + ] + }, + "implementationSurface": { + "canonicalTokens": [ + "smom-dbis-138/contracts/tokens/CompliantFiatTokenV2.sol" + ], + "wrappedTokens": [ + "smom-dbis-138/contracts/tokens/CompliantWrappedToken.sol" + ], + "registry": "smom-dbis-138/contracts/registry/UniversalAssetRegistry.sol", + "governance": "smom-dbis-138/contracts/governance/GovernanceController.sol" + } +} diff --git a/config/gru-standards-profile.json b/config/gru-standards-profile.json index acfd883..9e7cf4e 100644 --- a/config/gru-standards-profile.json +++ b/config/gru-standards-profile.json @@ -9,7 +9,9 @@ "references": { "transportOverlay": "config/gru-transport-active.json", "currencyManifest": "config/gru-iso4217-currency-manifest.json", + "governanceSupervisionProfile": "config/gru-governance-supervision-profile.json", "standardsMatrixDoc": "docs/04-configuration/GRU_C_STAR_V2_STANDARDS_MATRIX_AND_IMPLEMENTATION_PLAN.md", + "storageGovernanceDoc": "docs/04-configuration/GRU_STORAGE_GOVERNANCE_AND_SUPERVISION_STANDARD.md", "x402SupportDoc": "docs/04-configuration/CHAIN138_X402_TOKEN_SUPPORT.md", "fxOnboardingDoc": "docs/04-configuration/GRU_FX_CURRENCY_ONBOARDING_CHECKLIST.md" }, @@ -80,6 +82,14 @@ "id": "IeMoneyToken", "required": true, "repoInterface": "contracts/emoney/interfaces/IeMoneyToken.sol" + }, + { + "id": "DeterministicStorageNamespace", + "required": true + }, + { + "id": "JurisdictionAndSupervisionMetadata", + "required": true } ], "transportAndWrapperStandards": [ @@ -159,12 +169,26 @@ { "id": "ISO-20022 Canonical Message Model", "required": true + }, + { + "id": "JurisdictionalReview", + "required": true + }, + { + "id": "MinimumUpgradeNoticePeriod", + "required": true + }, + { + "id": "RegulatoryDisclosureAndReporting", + "required": true } ], "lifecycleDefaults": { "transportActiveDefault": false, "x402ReadyDefault": false, - "forwardCanonicalVersionPolicy": "one_forward_canonical_version_per_asset_family" + "forwardCanonicalVersionPolicy": "one_forward_canonical_version_per_asset_family", + "minimumUpgradeNoticePeriodSeconds": 604800, + "jurisdictionReviewRequiredForUpgradeSensitiveChanges": true }, "currentActivationExample": { "activeCanonicalCurrencyCodes": [ diff --git a/docs/04-configuration/GRU_C_STAR_V2_STANDARDS_MATRIX_AND_IMPLEMENTATION_PLAN.md b/docs/04-configuration/GRU_C_STAR_V2_STANDARDS_MATRIX_AND_IMPLEMENTATION_PLAN.md index 5b9e9d9..f716fbf 100644 --- a/docs/04-configuration/GRU_C_STAR_V2_STANDARDS_MATRIX_AND_IMPLEMENTATION_PLAN.md +++ b/docs/04-configuration/GRU_C_STAR_V2_STANDARDS_MATRIX_AND_IMPLEMENTATION_PLAN.md @@ -4,7 +4,7 @@ **Audience:** Solidity engineers, protocol architects, bridge operators, GRU governance, explorer / token-aggregation maintainers, and auditors. -**Related:** [GRU_STANDARDS_PROFILE.md](GRU_STANDARDS_PROFILE.md), [GRU_M00_DIAMOND_INSTITUTIONAL_SPEC.md](GRU_M00_DIAMOND_INSTITUTIONAL_SPEC.md), [GRU_M00_DIAMOND_FACET_MAP.md](GRU_M00_DIAMOND_FACET_MAP.md), [GRU_M00_DIAMOND_REVIEW_GAPS_AND_RECOMMENDATIONS.md](GRU_M00_DIAMOND_REVIEW_GAPS_AND_RECOMMENDATIONS.md), [CHAIN138_X402_TOKEN_SUPPORT.md](CHAIN138_X402_TOKEN_SUPPORT.md), [SMART_CONTRACTS_ISO20022_FIN_METHODOLOGY.md](SMART_CONTRACTS_ISO20022_FIN_METHODOLOGY.md), [GRU_TRANSPORT_ACTIVE_JSON.md](GRU_TRANSPORT_ACTIVE_JSON.md), [EXPLORER_TOKENS_GRU_POLICY.md](EXPLORER_TOKENS_GRU_POLICY.md). +**Related:** [naming-conventions/README.md](naming-conventions/README.md) (UTRNF reference + DBIS `c*` vs UTRNF `c` mapping: [naming-conventions/02_DBIS_NAMESPACE_AND_UTRNF_MAPPING.md](naming-conventions/02_DBIS_NAMESPACE_AND_UTRNF_MAPPING.md)), [GRU_STANDARDS_PROFILE.md](GRU_STANDARDS_PROFILE.md), [GRU_STORAGE_GOVERNANCE_AND_SUPERVISION_STANDARD.md](GRU_STORAGE_GOVERNANCE_AND_SUPERVISION_STANDARD.md), [GRU_M00_DIAMOND_INSTITUTIONAL_SPEC.md](GRU_M00_DIAMOND_INSTITUTIONAL_SPEC.md), [GRU_M00_DIAMOND_FACET_MAP.md](GRU_M00_DIAMOND_FACET_MAP.md), [GRU_M00_DIAMOND_REVIEW_GAPS_AND_RECOMMENDATIONS.md](GRU_M00_DIAMOND_REVIEW_GAPS_AND_RECOMMENDATIONS.md), [CHAIN138_X402_TOKEN_SUPPORT.md](CHAIN138_X402_TOKEN_SUPPORT.md), [SMART_CONTRACTS_ISO20022_FIN_METHODOLOGY.md](SMART_CONTRACTS_ISO20022_FIN_METHODOLOGY.md), [GRU_TRANSPORT_ACTIVE_JSON.md](GRU_TRANSPORT_ACTIVE_JSON.md), [EXPLORER_TOKENS_GRU_POLICY.md](EXPLORER_TOKENS_GRU_POLICY.md). --- @@ -114,6 +114,9 @@ The key design rule is: | EIP-1046 token metadata URI | **Optional yes** | Better metadata for wallets/explorers without changing token economics | Not present | Add as optional metadata extension | | eMoney reason-hash mint/burn interface | **Yes** | Aligns issuance/redemption with GRU/DBIS audit and reserve flows | Present only as interface | Make native to V2 token base | | Supply caps / per-period mint caps | **Yes** | Operational and reserve safety | Not standardized in base token | Add storage + role-gated setters in V2 | +| Deterministic storage namespace | **Yes** | Lets upgrades, registries, and auditors resolve the asset’s policy state without relying on a bare symbol | Missing as a shared rule | Store `storageNamespace` on each governed asset and mirror it into the registry | +| Governance / supervision profile IDs | **Yes** | Lets governance and registry flows identify which policy pack and supervision pack apply | Missing as a shared rule | Store `governanceProfileId` and `supervisionProfileId` on each governed asset | +| Jurisdiction / disclosure / reporting metadata | **Yes** | Needed for regulator handoff, supervisory evidence, and jurisdiction-specific activation | Missing as an operational metadata standard | Expose `primaryJurisdiction`, disclosure URI, reporting URI, supervision flags, and minimum notice period on asset contracts | | Jurisdiction / policy hooks | **Yes, but light** | Token should expose policy points without embedding full compliance logic | Only legal base events today | Add pre-transfer policy hook surfaces; route decisions stay above token | ### 4.2 Wrapper / vault / sidecar standards @@ -133,6 +136,8 @@ The key design rule is: | ERC-2535 Diamond | GRU M00 control plane | Modular standards/policy/governance system | Documented, not fully implemented | M00 Diamond spine | | Governance level bitmask | Governance / policy layer | Lets GRU enforce different policy packs by level 0–5 | Documented, incomplete | `GovernanceLevelFacet` + `PolicyRouterFacet` | | Standards registry | Governance / policy layer | Activates required standards and validators per asset / level | Missing | `StandardsRegistryFacet` | +| Jurisdictional proposal review | Governance / registry layer | Ensures sensitive changes can be reviewed and approved by the relevant jurisdictional authority | Missing before the registry/controller metadata patch | `UniversalAssetRegistry` + `GovernanceController` | +| Minimum upgrade notice period | Governance / registry layer | Prevents immediate sensitive upgrades where notice is mandatory | Missing before the registry/controller metadata patch | `UniversalAssetRegistry` + `GovernanceController` | | ISO-20022 canonical message model | Messaging layer | Gives institutional settlement compatibility without polluting token ABI | Documented, not fully on-chain | `ISO20022Facet` + `MessagingGateFacet` | | Reserve attestation / backing checks | Reserve layer | Required for issuance safety and reporting | Partial reserve logic exists | `ReserveGateFacet` + reserve attestation registry | | Accounting journal posting | Accounting layer | Needed for IPSAS / IFRS / internal audit traceability | Missing on-chain | `AccountingGateFacet` | diff --git a/docs/04-configuration/GRU_STANDARDS_PROFILE.md b/docs/04-configuration/GRU_STANDARDS_PROFILE.md index 417a2ea..a484e94 100644 --- a/docs/04-configuration/GRU_STANDARDS_PROFILE.md +++ b/docs/04-configuration/GRU_STANDARDS_PROFILE.md @@ -14,6 +14,7 @@ This profile is the shared standards contract between docs, configs, operators, - the payment profile for **x402** - the required base-token standards for `c* V2` - the transport / wrapper standards for `cW*` +- the required storage, governance, and supervision metadata for `c*`, `cW*`, and tokenized assets - the GRU M00 governance and policy standards - the broader asset scope: **ISO-4217 fiat currencies, approved commodities, and future monetary units** @@ -36,8 +37,12 @@ That keeps the standards profile broad while keeping the active transport overla Tracks which currencies exist and their current lifecycle state. - [`config/gru-transport-active.json`](../../config/gru-transport-active.json) Activates the currently enabled canonical tokens, compatible destination chains, and public pools. +- [`config/gru-governance-supervision-profile.json`](../../config/gru-governance-supervision-profile.json) + Captures deterministic storage namespaces, jurisdiction-review rules, supervision metadata, and upgrade notice periods. - [GRU_C_STAR_V2_STANDARDS_MATRIX_AND_IMPLEMENTATION_PLAN.md](GRU_C_STAR_V2_STANDARDS_MATRIX_AND_IMPLEMENTATION_PLAN.md) Explains the same standards in narrative form and maps them to contracts/facets. +- [GRU_STORAGE_GOVERNANCE_AND_SUPERVISION_STANDARD.md](GRU_STORAGE_GOVERNANCE_AND_SUPERVISION_STANDARD.md) + Defines the required metadata, jurisdiction-review flow, and storage namespace rules for governed assets. - [CHAIN138_X402_TOKEN_SUPPORT.md](CHAIN138_X402_TOKEN_SUPPORT.md) Records the current x402-ready token state on Chain 138. - [GRU_FX_CURRENCY_ONBOARDING_CHECKLIST.md](GRU_FX_CURRENCY_ONBOARDING_CHECKLIST.md) @@ -45,6 +50,7 @@ That keeps the standards profile broad while keeping the active transport overla ## Current intent -- **Standards scope:** x402, EIP-712, ERC-2612, ERC-3009, ERC-5267, AccessControl, Pausable, ISO-20022-aligned policy routing, and GRU M00 governance/policy facets. +- **Standards scope:** x402, EIP-712, ERC-2612, ERC-3009, ERC-5267, AccessControl, Pausable, deterministic storage namespaces, jurisdiction/supervision metadata, ISO-20022-aligned policy routing, and GRU M00 governance/policy facets. - **Asset scope:** all currencies added to the GRU manifest, not just the currently active USD lanes. - **Transport scope:** every public chain that is structurally compatible according to mapping, deployment, and bridge metadata. +- **Governance scope:** proposal tagging by jurisdiction, jurisdictional authority approval when required, and minimum upgrade notice periods that survive across asset families. diff --git a/docs/04-configuration/GRU_STORAGE_GOVERNANCE_AND_SUPERVISION_STANDARD.md b/docs/04-configuration/GRU_STORAGE_GOVERNANCE_AND_SUPERVISION_STANDARD.md new file mode 100644 index 0000000..3dd3e33 --- /dev/null +++ b/docs/04-configuration/GRU_STORAGE_GOVERNANCE_AND_SUPERVISION_STANDARD.md @@ -0,0 +1,82 @@ +# GRU Storage, Governance, and Supervision Standard + +**Purpose:** Define the canonical storage and governance metadata that every future GRU monetary asset, wrapped transport asset, base component, financial instrument, and tokenized asset must carry so upgrades, expansion, and jurisdictional supervision can be handled consistently. + +**Primary machine-readable profile:** [`config/gru-governance-supervision-profile.json`](../../config/gru-governance-supervision-profile.json) + +**Current implementation surface:** [CompliantFiatTokenV2.sol](../../smom-dbis-138/contracts/tokens/CompliantFiatTokenV2.sol), [CompliantWrappedToken.sol](../../smom-dbis-138/contracts/tokens/CompliantWrappedToken.sol), [UniversalAssetRegistry.sol](../../smom-dbis-138/contracts/registry/UniversalAssetRegistry.sol), [GovernanceController.sol](../../smom-dbis-138/contracts/governance/GovernanceController.sol) + +## 1. Required asset metadata + +Every governed GRU asset should expose or be mirrored into the registry with: + +- `assetId` +- `assetVersionId` +- `governanceProfileId` +- `supervisionProfileId` +- `storageNamespace` +- `primaryJurisdiction` +- `regulatoryDisclosureURI` +- `reportingURI` +- `canonicalUnderlyingAsset` +- `supervisionRequired` +- `governmentApprovalRequired` +- `minimumUpgradeNoticePeriod` + +These fields are now implemented directly on the canonical `c* V2` and `cW*` contracts and synchronized into the universal registry. + +## 2. Storage namespace rules + +- Canonical `c*` assets use deterministic storage namespaces in the pattern `gru.storage.asset..`. +- Wrapped `cW*` transport assets use deterministic storage namespaces in the pattern `gru.storage.transport.`. +- Registry mirrors use deterministic storage namespaces in the pattern `gru.storage.registry.`. +- GRU Diamond control-plane storage continues to use deterministic facet namespaces such as `grc.storage.monetary`, `grc.storage.gov`, and related `GRCStorage` slots. + +The rule is simple: metadata and policy state must be discoverable without relying on a symbol string alone. + +## 3. Jurisdictional supervision model + +- The registry owns jurisdiction profiles and authority assignments. +- A jurisdiction profile can define whether government approval is required, whether periodic reporting is expected, and the minimum upgrade notice period. +- Authorities are assigned per jurisdiction with explicit permissions for governance approval, upgrade approval, pause authority, and reporting reception. +- Asset registration pulls governance/supervision metadata from the token when available, then applies stronger jurisdiction defaults from the registry. + +This creates one place to express supervisory expectations without hardcoding a single legal regime into every token contract. + +## 4. Governance execution model + +- Governance proposals can be tagged with a jurisdiction. +- When tagged as jurisdiction-review-sensitive, a proposal cannot be queued until at least one authorized jurisdictional authority has approved it. +- The queue delay must respect the larger of: + - the proposal’s governance-mode timelock + - the jurisdiction’s minimum upgrade notice period + +This is now enforced in the shared governance controller, so “upgradeability” is not only a proxy question but also a policy and supervision workflow question. + +## 5. Scope by asset family + +| Asset family | Storage/governance expectation | +|--------------|--------------------------------| +| Canonical `c*` | Full metadata, disclosure, reporting, jurisdiction, supervision, and upgrade notice | +| Wrapped `cW*` | Same metadata discipline, plus canonical-underlying linkage and transport identity | +| GRU base components / registries | Upgradeable controller + registry storage, jurisdiction-aware proposal review where sensitive | +| Financial instruments / tokenized assets | Registry-backed metadata, explicit jurisdiction, reporting/disclosure URIs, policy profile IDs | +| Vault and reserve sidecars | Separate storage namespace; never overload canonical money-token storage | + +## 6. Recommendations + +- Migrate future flagship monetary assets toward upgradeable implementations only when the operational migration path and jurisdictional review flow are both documented and tested. +- Require every production asset onboarding checklist to populate `regulatoryDisclosureURI` and `reportingURI`, even when the initial content is an attested placeholder. +- Keep the registry as the operational source of truth for supervision metadata until the GRU M00 Diamond standards registry fully replaces or mirrors it. +- Use jurisdiction tags on any proposal that changes mint policy, burn policy, reserve thresholds, bridge permissions, metadata, upgrade targets, or pause authorities. +- Maintain multisig or institutional signer separation between protocol admins and jurisdictional authorities. + +## 7. Verification + +The current repo verifies this standard through focused Foundry suites: + +- [CompliantFiatTokenV2.t.sol](../../smom-dbis-138/test/compliance/CompliantFiatTokenV2.t.sol) +- [CompliantWrappedTokenTest.t.sol](../../smom-dbis-138/test/compliance/CompliantWrappedTokenTest.t.sol) +- [JurisdictionalGovernance.t.sol](../../smom-dbis-138/test/integration/JurisdictionalGovernance.t.sol) + +Those suites are wired into the contract green-path verifier at [check-cstar-v2-transport-stack.sh](../../scripts/verify/check-cstar-v2-transport-stack.sh). diff --git a/docs/04-configuration/README.md b/docs/04-configuration/README.md index 2ee1a09..3475323 100644 --- a/docs/04-configuration/README.md +++ b/docs/04-configuration/README.md @@ -60,6 +60,7 @@ This directory contains setup and configuration guides. - **[PRICE_FEED_CHAIN138_METAMASK_AND_WALLETS.md](PRICE_FEED_CHAIN138_METAMASK_AND_WALLETS.md)** ⭐⭐⭐ - **Single reference** for adding Chain 138 USD prices to MetaMask and wallets: CoinGecko, CMC, Consensys outreach, on-chain oracle, Snap workaround. **Explorer tokens and GRU:** +- **[naming-conventions/README.md](naming-conventions/README.md)** — UTRNF token-role grammar, DBIS `c*` / `cW*` vs UTRNF collision matrix, bridge naming, registry JSON fields (Chain 138 + cross-chain). - **[EXPLORER_TOKENS_GRU_POLICY.md](EXPLORER_TOKENS_GRU_POLICY.md)** ⭐⭐ - Policy: all c* tokens on [explorer.d-bis.org/tokens](https://explorer.d-bis.org/tokens) must be registered as GRU; token list and registration steps. - **[C_TO_CW_MAPPER_MAPPING.md](C_TO_CW_MAPPER_MAPPING.md)** ⭐⭐ - c* → cW* mapping for mapper: symbol mapping and per-chain address mapping in `config/token-mapping-multichain.json`. @@ -89,6 +90,8 @@ This directory contains setup and configuration guides. - **[GRU_FX_CURRENCY_ONBOARDING_CHECKLIST.md](GRU_FX_CURRENCY_ONBOARDING_CHECKLIST.md)** ⭐⭐⭐ - End-to-end checklist for creating and fully attaching a new FX `c*` currency into GRU, explorer metadata, transport, reserve policy, and routing. - **[`../../config/gru-standards-profile.json`](../../config/gru-standards-profile.json)** ⭐⭐⭐ - Machine-readable source of truth for the repo-wide x402, EIP/ERC, transport, and governance standards that apply to GRU monetary assets. - **[`../../config/gru-iso4217-currency-manifest.json`](../../config/gru-iso4217-currency-manifest.json)** ⭐⭐⭐ - Machine-readable canonical manifest for the supported GRU ISO-4217 and commodity currency set, including deployment, transport, and x402 lifecycle state. +- **[GRU_STORAGE_GOVERNANCE_AND_SUPERVISION_STANDARD.md](GRU_STORAGE_GOVERNANCE_AND_SUPERVISION_STANDARD.md)** ⭐⭐⭐ - Storage namespaces, jurisdiction-aware governance review, supervision metadata, and upgrade notice periods (narrative companion to the governance supervision profile). +- **[`../../config/gru-governance-supervision-profile.json`](../../config/gru-governance-supervision-profile.json)** ⭐⭐⭐ - Machine-readable governance and supervision profile (roles, required asset metadata, references into standards profile and storage standard). - **[GRU_M00_DIAMOND_DOCS_REVIEW_GAPS_AND_INCONSISTENCIES.md](GRU_M00_DIAMOND_DOCS_REVIEW_GAPS_AND_INCONSISTENCIES.md)** ⭐⭐ - Review of all GRU M00 Diamond docs: missing refs, link consistency, terminology, and follow-up list. - **[DBIS Rail Technical Spec v1](../dbis-rail/DBIS_RAIL_TECHNICAL_SPEC_V1.md)** ⭐⭐⭐ - Bank-rail settlement and GRU mint orchestration on Chain 138: RootRegistry, ParticipantRegistry, SignerRegistry, SettlementRouter, GRU_MintController, MintAuth lifecycle, EIP-712 signer quorum (3-of-5), replay protection, and audit events. - **[DBIS Rail Rulebook v1](../dbis-rail/DBIS_RAIL_RULEBOOK_V1.md)** ⭐⭐⭐ - Operational and compliance policy: good funds matrix, finality triggers per rail (wire/ACH/cash/internal), accounting sequence and deterministic accountingRef, MintAuth preconditions, reversal and exception handling, signer revocation timing, incident controls, audit and reporting standards. 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 index 04c59c9..2515ca2 100644 --- 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 @@ -81,7 +81,7 @@ Per GRU V2 direction: ## 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). +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 in-repo [`gru-docs/`](../../../gru-docs/README.md) (e.g. formulas / executive summary) and [GRU_STANDARDS_PROFILE.md](../GRU_STANDARDS_PROFILE.md). --- diff --git a/docs/04-configuration/naming-conventions/03_BRIDGES_CROSS_CHAIN_NAMING.md b/docs/04-configuration/naming-conventions/03_BRIDGES_CROSS_CHAIN_NAMING.md new file mode 100644 index 0000000..41ac2c6 --- /dev/null +++ b/docs/04-configuration/naming-conventions/03_BRIDGES_CROSS_CHAIN_NAMING.md @@ -0,0 +1,94 @@ +# Bridges and cross-chain naming + +**Purpose:** Conventions for naming and identifying assets across chains when using CCIP, wrapped representations, and GRU `c*` / `cW*` transport. Complements [02_DBIS_NAMESPACE_AND_UTRNF_MAPPING.md](02_DBIS_NAMESPACE_AND_UTRNF_MAPPING.md). + +--- + +## 1. Primary identity key + +**Authoritative asset instance:** `(chainId, contractAddress)`. + +**Display symbol** (e.g. `cUSDC`, `WETH`) is a **secondary** key: useful for humans and analytics, but **not** sufficient for: + +- Bridge receipts vs underlying +- Same hex address on two chains with **different bytecode** +- Duplicate ERC-20s indexed by an explorer + +Always thread **chainId + address** through bridge configs, indexers, and institutional JSON. + +--- + +## 2. Logical asset vs chain-local contract + +| Concept | Description | +|---------|-------------| +| **Logical asset** | Stable identifier for “what” is being moved (e.g. USDC on GRU rail, or a specific canonical `cUSDC` family). Often `assetId` / `assetVersionId` in GRU docs. | +| **Chain-local contract** | The ERC-20 (or native) contract on a specific chain. | +| **Bridge mapping** | Directed relation: source `(chainId, addr)` → destination `(chainId, addr)` with optional mint/burn semantics. | + +Naming convention: in documentation and configs, prefer **explicit pairs** over ambiguous “the USDC on the bridge.” + +--- + +## 3. Same symbol, different address (expected) + +UTRNF multichain rule: the **same symbol** may appear on many chains; only **address and chainId** differ. DBIS adds: + +- **Canonical** Chain 138 addresses for `c*` tokens are listed in [EXPLORER_TOKEN_LIST_CROSSCHECK.md](../../11-references/EXPLORER_TOKEN_LIST_CROSSCHECK.md). +- **Non-canonical** duplicates may exist on-chain (legacy deploys); registries must mark `forwardCanonical` / block explorer surfacing per project policy. + +--- + +## 4. Same hex address, different bytecode (critical) + +Some project contracts use **consistent deploy addresses across chains** (e.g. CREATE2 or deliberate parity) while **bytecode or role** differs by chain. + +**Operational rule:** When debugging explorers (Etherscan, BscScan, etc.), **do not** assume same 0x address implies same contract. Verify **chainId**, **verified source**, and **project documentation**. + +Repository context: see [docs/07-ccip/BSCSCAN_SUPPORT_DD_0xe0E932_BSC.md](../../07-ccip/BSCSCAN_SUPPORT_DD_0xe0E932_BSC.md) and [CONTRACT_ADDRESSES_REFERENCE.md](../../11-references/CONTRACT_ADDRESSES_REFERENCE.md) for CCIP bridge addresses. + +--- + +## 5. CCIP and lane-oriented naming + +For CCIP deployments and operations: + +- **Documentation anchor:** [CCIP_DEPLOYMENT_SPEC.md](../../07-ccip/CCIP_DEPLOYMENT_SPEC.md) (Chain 138 fleet, lanes, operational naming). +- **Per-chain receiver / mint behavior:** [CCIP_138_DESTINATION_RECEIVER_BY_CHAIN_AND_TOKEN.md](../../11-references/CCIP_138_DESTINATION_RECEIVER_BY_CHAIN_AND_TOKEN.md). +- **Security / sender references:** [CCIP_SECURITY_DOCUMENTATION.md](../../07-ccip/CCIP_SECURITY_DOCUMENTATION.md), [CCIP_SENDER_CONTRACT_REFERENCE.md](../../07-ccip/CCIP_SENDER_CONTRACT_REFERENCE.md). + +**Suggested naming pattern for internal runbooks:** + +```text +CCIP___ +``` + +Use `ASSET_LOGICAL_ID` from registry (not raw symbol alone), e.g. `GRU_cUSDC_v1` vs `USDC_ethereum_mainnet`. + +--- + +## 6. Wrapped native and bridge tokens + +- **WETH9 / WETH10** on Chain 138: distinguish **symbol** from **contract** (multiple wrappers may exist). +- **Bridge-specific wrapped assets:** Prefer registry fields such as `wrappedFrom`, `originChainId`, `bridgeAdapter` ([04_REGISTRY_AND_JSON_FIELDS.md](04_REGISTRY_AND_JSON_FIELDS.md)). + +--- + +## 7. c* ↔ cW* naming + +Bridge and mapper layers should preserve: + +- **Base** compliant symbol on Chain 138 (`c*`) where canonical. +- **Mirrored** or **wrapped** symbols on external chains (`cW*`) per [C_TO_CW_MAPPER_MAPPING.md](../C_TO_CW_MAPPER_MAPPING.md). + +Do not rename canonical `c*` on Chain 138 to match foreign DEX display names without a governance/version bump and registry update. + +--- + +## 8. Checklist for new bridge assets + +1. Assign **logical asset id** and registry row (doc 04). +2. Record **each endpoint** `(chainId, address)` and **mint/burn vs lock/unlock** semantics. +3. Confirm **no collision** with non-canonical tokens on explorers. +4. Update **token lists** and **CONTRACT_ADDRESSES_REFERENCE** when the project declares a new canonical deployment. +5. Document **CCIP lane** or **custom bridge** name in `07-ccip` or deployment notes. diff --git a/docs/04-configuration/naming-conventions/04_REGISTRY_AND_JSON_FIELDS.md b/docs/04-configuration/naming-conventions/04_REGISTRY_AND_JSON_FIELDS.md new file mode 100644 index 0000000..97c6c50 --- /dev/null +++ b/docs/04-configuration/naming-conventions/04_REGISTRY_AND_JSON_FIELDS.md @@ -0,0 +1,122 @@ +# Registry and JSON fields + +**Purpose:** Recommended fields for token and bridge registries so UTRNF-style roles, GRU layers, and cross-chain identity are **machine-readable**. This complements symbols documented in [01_UTRNF_REFERENCE.md](01_UTRNF_REFERENCE.md) and DBIS mapping in [02_DBIS_NAMESPACE_AND_UTRNF_MAPPING.md](02_DBIS_NAMESPACE_AND_UTRNF_MAPPING.md). + +**Phase 1:** Documentation only; no required change to existing JSON schemas unless a workstream adopts these fields explicitly. + +--- + +## 1. Core identity fields + +| Field | Type | Description | +|-------|------|-------------| +| `chainId` | number | EIP-155 style chain ID. | +| `address` | string (`0x…`) | Checksum or lowercase consistent with consumer; document casing rule. | +| `symbol` | string | Human display symbol (e.g. `cUSDC`, `lpPairName`). | +| `name` | string | ERC-20 name or display name. | +| `decimals` | number | Token decimals. | + +**Composite primary key for on-chain instances:** `(chainId, address)`. + +--- + +## 2. Underlying and UTRNF-oriented fields + +| Field | Type | Description | +|-------|------|-------------| +| `underlying` | string | Underlying ticker or logical asset (e.g. `USDC`, `XAU`). | +| `utrnfRole` | string | Optional: `asset`, `variable_debt`, `stable_debt`, `yield`, `liquidity`, `synthetic`, `reserve`, `wrapped`, `incentive`, or `none` / `not_applicable`. | +| `tokenRole` | string | DBIS-oriented role: e.g. `gru_compliant_base`, `gru_wrapped`, `dex_lp`, `vault_share`, `bridge_receipt`, `utility`. | +| `gruAssetClass` | string | Optional refinement for GRU tooling (align with [GRU_STANDARDS_PROFILE.md](../GRU_STANDARDS_PROFILE.md)). | + +Use **`tokenRole`** for ecosystem-specific meaning; use **`utrnfRole`** when the instrument aligns with UTRNF grammar. **DBIS `c*` base money** should **not** set `utrnfRole` to `collateral` unless the contract is literally a UTRNF-style collateral token (rare in current GRU base layer). + +--- + +## 3. GRU versioning (aligns with c* V2 plan) + +| Field | Type | Description | +|-------|------|-------------| +| `assetId` | string (bytes32 hex or opaque id) | Stable id for the asset family. | +| `assetVersionId` | string | Version-specific id (e.g. V1 vs V2 `cUSDC`). | +| `forwardCanonical` | boolean | Whether this deployment is the active canonical target for routing. | +| `legacyAliases` | array | Optional list of superseded `(chainId, address)` or symbols. | + +See [GRU_C_STAR_V2_STANDARDS_MATRIX_AND_IMPLEMENTATION_PLAN.md](../GRU_C_STAR_V2_STANDARDS_MATRIX_AND_IMPLEMENTATION_PLAN.md) (asset identity and versioning). + +--- + +## 4. GRU monetary layer (optional) + +| Field | Type | Description | +|-------|------|-------------| +| `gruLayer` | string | `M00`, `M0`, `M1`, or `na` when not applicable to the contract. | + +Use for policy and reporting; do not overload ERC-20 `symbol` with layer codes unless explicitly standardized. + +--- + +## 5. Bridge and cross-chain fields + +| Field | Type | Description | +|-------|------|-------------| +| `originChainId` | number | Chain where underlying is locked or where message originates. | +| `wrappedFrom` | string | Address or logical id on origin chain. | +| `bridgeKind` | string | e.g. `ccip`, `lock_mint`, `native_deposit`. | +| `ccipLane` | string | Optional lane or selector label for operators. | + +--- + +## 6. Lending-style triad (optional, UTRNF-shaped) + +When a reserve exposes Aave-like tokens: + +```json +{ + "underlying": "USDC", + "assetToken": "aUSDC", + "variableDebtToken": "vdUSDC", + "stableDebtToken": "sdUSDC", + "decimals": 6, + "chainId": 138 +} +``` + +This mirrors [01_UTRNF_REFERENCE.md](01_UTRNF_REFERENCE.md) section 12. **Only use** when those contracts exist; do not invent symbols for GRU `c*` unless deployed. + +--- + +## 7. Repository consumers + +| Consumer | Location | +|----------|----------| +| Master contract and deployment inventory | [`config/smart-contracts-master.json`](../../../config/smart-contracts-master.json) — structure evolves with project needs; add optional metadata fields when agreed. | +| DBIS institutional JSON | [`config/dbis-institutional/README.md`](../../../config/dbis-institutional/README.md), schemas under `config/dbis-institutional/schemas/`. | +| Token lists | `token-lists/lists/*.tokenlist.json`, explorer / MetaMask dual-chain lists (see [EXPLORER_TOKEN_LIST_CROSSCHECK.md](../../11-references/EXPLORER_TOKEN_LIST_CROSSCHECK.md)). | +| Multichain mapper | [`config/token-mapping-multichain.json`](../../../config/token-mapping-multichain.json) | + +--- + +## 8. Example: GRU compliant base on Chain 138 + +```json +{ + "chainId": 138, + "address": "0xf22258f57794CC8E06237084b353Ab30fFfa640b", + "symbol": "cUSDC", + "decimals": 6, + "underlying": "USDC", + "tokenRole": "gru_compliant_base", + "utrnfRole": "not_applicable", + "assetId": "keccak256:GRU:cUSDC", + "forwardCanonical": true +} +``` + +Addresses and `forwardCanonical` must match project canon at time of publication; verify against [EXPLORER_TOKEN_LIST_CROSSCHECK.md](../../11-references/EXPLORER_TOKEN_LIST_CROSSCHECK.md). + +--- + +## 9. Validation (future) + +Optional follow-up: JSON Schema under `config/` and a small validator in `scripts/validation/` to enforce required fields for new registry entries. Not part of the initial documentation drop. diff --git a/docs/04-configuration/naming-conventions/README.md b/docs/04-configuration/naming-conventions/README.md index 17e608f..f309b14 100644 --- a/docs/04-configuration/naming-conventions/README.md +++ b/docs/04-configuration/naming-conventions/README.md @@ -10,8 +10,8 @@ |------|---------| | [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. +| [03_BRIDGES_CROSS_CHAIN_NAMING.md](03_BRIDGES_CROSS_CHAIN_NAMING.md) | Logical asset identity vs chain-local contracts; CCIP and bridge naming patterns; same hex / different bytecode cautions. | +| [04_REGISTRY_AND_JSON_FIELDS.md](04_REGISTRY_AND_JSON_FIELDS.md) | Recommended JSON fields for token and bridge registries; links to `config/smart-contracts-master.json` and DBIS institutional config. | ## When to use symbol parsing vs registry diff --git a/docs/MASTER_INDEX.md b/docs/MASTER_INDEX.md index 4624792..a95ba7a 100644 --- a/docs/MASTER_INDEX.md +++ b/docs/MASTER_INDEX.md @@ -53,11 +53,12 @@ | **Reserve provenance / funding attestation (3FR staged package)** | [`config/reserve-provenance-package/README.md`](../config/reserve-provenance-package/README.md), `scripts/validation/validate-reserve-provenance-package.sh` | — | | **DBIS institutional JSON (settlement, registry, trust/governance/policy)** | [`config/dbis-institutional/README.md`](../config/dbis-institutional/README.md), `scripts/validation/validate-dbis-institutional-schemas.sh`, `scripts/verify/sync-blockscout-address-labels-from-registry.sh` | — | | **ISO-20022 → on-chain (methodology + multi-network intake)** | [04-configuration/SMART_CONTRACTS_ISO20022_FIN_METHODOLOGY.md](04-configuration/SMART_CONTRACTS_ISO20022_FIN_METHODOLOGY.md), [04-configuration/ISO20022_INTAKE_GATEWAY_CONTRACT_MULTI_NETWORK.md](04-configuration/ISO20022_INTAKE_GATEWAY_CONTRACT_MULTI_NETWORK.md); Rail: [dbis-rail/ISO_GATEWAY_AND_RELAYER_SPEC.md](dbis-rail/ISO_GATEWAY_AND_RELAYER_SPEC.md) | — | +| **Token / bridge naming (UTRNF + DBIS / Chain 138 mapping)** | [04-configuration/naming-conventions/README.md](04-configuration/naming-conventions/README.md) | — | | **GRU c* V2 standards and implementation plan** | [04-configuration/GRU_C_STAR_V2_STANDARDS_MATRIX_AND_IMPLEMENTATION_PLAN.md](04-configuration/GRU_C_STAR_V2_STANDARDS_MATRIX_AND_IMPLEMENTATION_PLAN.md) | — | | **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 | +| **UTRNF / naming (symbols, registries)** | [04-configuration/naming-conventions/](04-configuration/naming-conventions/) (`01`–`04`) | Complements GRU `c* V2` matrix | | 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) | @@ -76,7 +77,7 @@ | **00-meta** (tasks, next steps, phases) | [00-meta/NEXT_STEPS_INDEX.md](00-meta/NEXT_STEPS_INDEX.md), [00-meta/PHASES_AND_TASKS_MASTER.md](00-meta/PHASES_AND_TASKS_MASTER.md) | | **02-architecture** | [02-architecture/](02-architecture/) — **Public sector + Phoenix catalog baseline** (Sankofa **native vs partner** marketplace: [03-deployment/SANKOFA_MARKETPLACE_SURFACES.md](03-deployment/SANKOFA_MARKETPLACE_SURFACES.md)): [02-architecture/PUBLIC_SECTOR_TENANCY_MARKETPLACE_AND_DEPLOYMENT_BASELINE.md](02-architecture/PUBLIC_SECTOR_TENANCY_MARKETPLACE_AND_DEPLOYMENT_BASELINE.md); **canonical Sankofa / Phoenix boundaries and taxonomy:** [02-architecture/SANKOFA_PHOENIX_CANONICAL_BOUNDARIES_AND_TAXONOMY.md](02-architecture/SANKOFA_PHOENIX_CANONICAL_BOUNDARIES_AND_TAXONOMY.md); **current remaining-task tracker:** [02-architecture/SANKOFA_PHOENIX_REMAINING_TASKS.md](02-architecture/SANKOFA_PHOENIX_REMAINING_TASKS.md); **Phase 4 migration runbook:** [02-architecture/SANKOFA_PHOENIX_PHASE4_MIGRATION_RUNBOOK.md](02-architecture/SANKOFA_PHOENIX_PHASE4_MIGRATION_RUNBOOK.md); **complete Sankofa / Phoenix phased execution plan:** [02-architecture/SANKOFA_PHOENIX_COMPLETE_PHASED_EXECUTION_PLAN.md](02-architecture/SANKOFA_PHOENIX_COMPLETE_PHASED_EXECUTION_PLAN.md); **non-goals (incl. catalog vs marketing §9):** [02-architecture/NON_GOALS.md](02-architecture/NON_GOALS.md); **DBIS Chain 138:** [dbis_chain_138_technical_master_plan.md](../dbis_chain_138_technical_master_plan.md), [02-architecture/DBIS_NODE_ROLE_MATRIX.md](02-architecture/DBIS_NODE_ROLE_MATRIX.md), [02-architecture/DBIS_PHASE2_PROXMOX_SOVEREIGNIZATION_ROADMAP.md](02-architecture/DBIS_PHASE2_PROXMOX_SOVEREIGNIZATION_ROADMAP.md); **DBIS web / d-bis.org institutional blueprint:** [02-architecture/DBIS_WEB_AND_INSTITUTION_MASTER_BLUEPRINT.md](02-architecture/DBIS_WEB_AND_INSTITUTION_MASTER_BLUEPRINT.md) | | **03-deployment** | [03-deployment/OPERATIONAL_RUNBOOKS.md](03-deployment/OPERATIONAL_RUNBOOKS.md), [03-deployment/DEPLOYMENT_ORDER_OF_OPERATIONS.md](03-deployment/DEPLOYMENT_ORDER_OF_OPERATIONS.md), **Public sector live checklist:** [03-deployment/PUBLIC_SECTOR_LIVE_DEPLOYMENT_CHECKLIST.md](03-deployment/PUBLIC_SECTOR_LIVE_DEPLOYMENT_CHECKLIST.md), **Proxmox VE ops template:** [03-deployment/PROXMOX_VE_OPERATIONAL_DEPLOYMENT_TEMPLATE.md](03-deployment/PROXMOX_VE_OPERATIONAL_DEPLOYMENT_TEMPLATE.md) · [`config/proxmox-operational-template.json`](config/proxmox-operational-template.json); **DBIS Phase 1–3:** [03-deployment/PHASE1_DISCOVERY_RUNBOOK.md](03-deployment/PHASE1_DISCOVERY_RUNBOOK.md), [03-deployment/DBIS_PHASE3_E2E_PRODUCTION_SIMULATION_RUNBOOK.md](03-deployment/DBIS_PHASE3_E2E_PRODUCTION_SIMULATION_RUNBOOK.md), [03-deployment/CALIPER_CHAIN138_PERF_HOOK.md](03-deployment/CALIPER_CHAIN138_PERF_HOOK.md), [03-deployment/DBIS_HYPERLEDGER_RUNTIME_STATUS.md](03-deployment/DBIS_HYPERLEDGER_RUNTIME_STATUS.md), [03-deployment/DBIS_PHASES_1_TO_3_PRODUCTION_GATE.md](03-deployment/DBIS_PHASES_1_TO_3_PRODUCTION_GATE.md), **RTGS canonical production checklist and institutional-finance layers:** [03-deployment/DBIS_RTGS_E2E_REQUIREMENTS_MATRIX.md](03-deployment/DBIS_RTGS_E2E_REQUIREMENTS_MATRIX.md), [03-deployment/DBIS_RTGS_FX_TRANSACTION_CATALOG.md](03-deployment/DBIS_RTGS_FX_TRANSACTION_CATALOG.md), [03-deployment/OMNL_DBIS_CORE_CHAIN138_SMART_VAULT_RTGS_RUNBOOK.md](03-deployment/OMNL_DBIS_CORE_CHAIN138_SMART_VAULT_RTGS_RUNBOOK.md), [03-deployment/DBIS_RTGS_DEPOSITORY_AND_CUSTODY_OPERATING_MODEL.md](03-deployment/DBIS_RTGS_DEPOSITORY_AND_CUSTODY_OPERATING_MODEL.md), [03-deployment/DBIS_RTGS_FX_AND_LIQUIDITY_OPERATING_MODEL.md](03-deployment/DBIS_RTGS_FX_AND_LIQUIDITY_OPERATING_MODEL.md), [03-deployment/DBIS_RTGS_CONTROL_PLANE_DEPLOYMENT_CHECKLIST.md](03-deployment/DBIS_RTGS_CONTROL_PLANE_DEPLOYMENT_CHECKLIST.md), [03-deployment/DBIS_RTGS_LATER_PHASE_SIDECARS_DEPLOYMENT_CHECKLIST.md](03-deployment/DBIS_RTGS_LATER_PHASE_SIDECARS_DEPLOYMENT_CHECKLIST.md), [03-deployment/DBIS_OMNL_INDONESIA_BNI_E2E_INTEGRATION_BLUEPRINT.md](03-deployment/DBIS_OMNL_INDONESIA_BNI_E2E_INTEGRATION_BLUEPRINT.md), [03-deployment/DBIS_OMNL_INDONESIA_BNI_E2E_EXECUTABLE_TASK_LIST.md](03-deployment/DBIS_OMNL_INDONESIA_BNI_E2E_EXECUTABLE_TASK_LIST.md), [03-deployment/DBIS_OMNL_INDONESIA_BNI_E2E_EXECUTION_STATUS_2026-03-29.md](03-deployment/DBIS_OMNL_INDONESIA_BNI_E2E_EXECUTION_STATUS_2026-03-29.md), [03-deployment/DBIS_RTGS_FIRST_SLICE_ARCHITECTURE.md](03-deployment/DBIS_RTGS_FIRST_SLICE_ARCHITECTURE.md), [03-deployment/DBIS_RTGS_FIRST_SLICE_DEPLOYMENT_CHECKLIST.md](03-deployment/DBIS_RTGS_FIRST_SLICE_DEPLOYMENT_CHECKLIST.md), [03-deployment/DBIS_HYBX_SIDECAR_BOUNDARY_MATRIX.md](03-deployment/DBIS_HYBX_SIDECAR_BOUNDARY_MATRIX.md), [03-deployment/DBIS_MOJALOOP_INTEGRATION_STATUS.md](03-deployment/DBIS_MOJALOOP_INTEGRATION_STATUS.md), [03-deployment/DBIS_HYPERLEDGER_IDENTITY_STACK_DECISION.md](03-deployment/DBIS_HYPERLEDGER_IDENTITY_STACK_DECISION.md), [03-deployment/DBIS_IDENTITY_COMPLETION_PACKAGE_RUNBOOK.md](03-deployment/DBIS_IDENTITY_COMPLETION_PACKAGE_RUNBOOK.md), [03-deployment/DBIS_IDENTITY_ENDORSER_HANDSHAKE_RUNBOOK.md](03-deployment/DBIS_IDENTITY_ENDORSER_HANDSHAKE_RUNBOOK.md) | -| **04-configuration** | [04-configuration/README.md](04-configuration/README.md), [04-configuration/ADDITIONAL_PATHS_AND_EXTENSIONS.md](04-configuration/ADDITIONAL_PATHS_AND_EXTENSIONS.md) (paths, registry, token-mapping, LiFi/Jumper), [04-configuration/GRU_C_STAR_V2_STANDARDS_MATRIX_AND_IMPLEMENTATION_PLAN.md](04-configuration/GRU_C_STAR_V2_STANDARDS_MATRIX_AND_IMPLEMENTATION_PLAN.md) (canonical `c* V2` standards, facet mapping, migration plan), [04-configuration/GRU_STANDARDS_PROFILE.md](04-configuration/GRU_STANDARDS_PROFILE.md) and [`../config/gru-standards-profile.json`](../config/gru-standards-profile.json) (machine-readable x402, EIP/ERC, transport, governance, and ISO-4217-plus standards profile), [04-configuration/GRU_FX_CURRENCY_ONBOARDING_CHECKLIST.md](04-configuration/GRU_FX_CURRENCY_ONBOARDING_CHECKLIST.md) (end-to-end FX currency attachment), [`../config/gru-iso4217-currency-manifest.json`](../config/gru-iso4217-currency-manifest.json) (machine-readable supported currency manifest); **info.defi-oracle.io (Chain 138 hub SPA):** [04-configuration/INFO_DEFI_ORACLE_IO_DEPLOYMENT.md](04-configuration/INFO_DEFI_ORACLE_IO_DEPLOYMENT.md), app [info-defi-oracle-138/README.md](../info-defi-oracle-138/README.md); **Chain 138 wallets:** [04-configuration/CHAIN138_WALLET_CONFIG_VALIDATION.md](04-configuration/CHAIN138_WALLET_CONFIG_VALIDATION.md); **Chain 2138 testnet wallets:** [04-configuration/CHAIN2138_WALLET_CONFIG_VALIDATION.md](04-configuration/CHAIN2138_WALLET_CONFIG_VALIDATION.md); **OMNL Indonesia / HYBX-BATCH-001:** [04-configuration/mifos-omnl-central-bank/HYBX_BATCH_001_OPERATOR_CHECKLIST.md](04-configuration/mifos-omnl-central-bank/HYBX_BATCH_001_OPERATOR_CHECKLIST.md), [04-configuration/mifos-omnl-central-bank/INDONESIA_PACKAGE_4_995_EVIDENCE_STANDARD.md](04-configuration/mifos-omnl-central-bank/INDONESIA_PACKAGE_4_995_EVIDENCE_STANDARD.md) | +| **04-configuration** | [04-configuration/README.md](04-configuration/README.md), [04-configuration/naming-conventions/README.md](04-configuration/naming-conventions/README.md) (UTRNF + DBIS token/bridge naming), [04-configuration/ADDITIONAL_PATHS_AND_EXTENSIONS.md](04-configuration/ADDITIONAL_PATHS_AND_EXTENSIONS.md) (paths, registry, token-mapping, LiFi/Jumper), [04-configuration/GRU_C_STAR_V2_STANDARDS_MATRIX_AND_IMPLEMENTATION_PLAN.md](04-configuration/GRU_C_STAR_V2_STANDARDS_MATRIX_AND_IMPLEMENTATION_PLAN.md) (canonical `c* V2` standards, facet mapping, migration plan), [04-configuration/GRU_STANDARDS_PROFILE.md](04-configuration/GRU_STANDARDS_PROFILE.md) and [`../config/gru-standards-profile.json`](../config/gru-standards-profile.json) (machine-readable x402, EIP/ERC, transport, governance, and ISO-4217-plus standards profile), [04-configuration/GRU_STORAGE_GOVERNANCE_AND_SUPERVISION_STANDARD.md](04-configuration/GRU_STORAGE_GOVERNANCE_AND_SUPERVISION_STANDARD.md) and [`../config/gru-governance-supervision-profile.json`](../config/gru-governance-supervision-profile.json) (deterministic storage namespaces, jurisdiction-aware proposal review, supervision metadata, and upgrade notice periods), [04-configuration/GRU_FX_CURRENCY_ONBOARDING_CHECKLIST.md](04-configuration/GRU_FX_CURRENCY_ONBOARDING_CHECKLIST.md) (end-to-end FX currency attachment), [`../config/gru-iso4217-currency-manifest.json`](../config/gru-iso4217-currency-manifest.json) (machine-readable supported currency manifest); **info.defi-oracle.io (Chain 138 hub SPA):** [04-configuration/INFO_DEFI_ORACLE_IO_DEPLOYMENT.md](04-configuration/INFO_DEFI_ORACLE_IO_DEPLOYMENT.md), app [info-defi-oracle-138/README.md](../info-defi-oracle-138/README.md); **Chain 138 wallets:** [04-configuration/CHAIN138_WALLET_CONFIG_VALIDATION.md](04-configuration/CHAIN138_WALLET_CONFIG_VALIDATION.md); **Chain 2138 testnet wallets:** [04-configuration/CHAIN2138_WALLET_CONFIG_VALIDATION.md](04-configuration/CHAIN2138_WALLET_CONFIG_VALIDATION.md); **OMNL Indonesia / HYBX-BATCH-001:** [04-configuration/mifos-omnl-central-bank/HYBX_BATCH_001_OPERATOR_CHECKLIST.md](04-configuration/mifos-omnl-central-bank/HYBX_BATCH_001_OPERATOR_CHECKLIST.md), [04-configuration/mifos-omnl-central-bank/INDONESIA_PACKAGE_4_995_EVIDENCE_STANDARD.md](04-configuration/mifos-omnl-central-bank/INDONESIA_PACKAGE_4_995_EVIDENCE_STANDARD.md) | | **06-besu** | [06-besu/MASTER_INDEX.md](06-besu/MASTER_INDEX.md) | | **Testnet (2138)** | [testnet/DEFI_ORACLE_META_TESTNET_2138_RUNBOOK.md](testnet/DEFI_ORACLE_META_TESTNET_2138_RUNBOOK.md), [testnet/TESTNET_DEPLOYMENT.md](testnet/TESTNET_DEPLOYMENT.md) | | **07-ccip** | [07-ccip/](07-ccip/), Truth plan: [07-ccip/TRUTH_NETWORK_BRIDGE_SPEC.md](07-ccip/TRUTH_NETWORK_BRIDGE_SPEC.md), [00-meta/CW_BRIDGE_TASK_LIST.md](00-meta/CW_BRIDGE_TASK_LIST.md) | diff --git a/docs/gru-m1/README.md b/docs/gru-m1/README.md index c197c7b..df2501a 100644 --- a/docs/gru-m1/README.md +++ b/docs/gru-m1/README.md @@ -35,8 +35,10 @@ This folder contains the **GRU M1 Master Implementation Plan** and supporting do * [CMC & CoinGecko Reporting](../../smom-dbis-138/services/token-aggregation/docs/CMC_COINGECKO_REPORTING.md) — Token aggregation report API * [GRU c* V2 Standards Matrix and Implementation Plan](../04-configuration/GRU_C_STAR_V2_STANDARDS_MATRIX_AND_IMPLEMENTATION_PLAN.md) — Canonical `c* V2` standards, x402 readiness, wrapper/vault boundaries, GRU facet mapping, and phased migration plan * [GRU Standards Profile](../04-configuration/GRU_STANDARDS_PROFILE.md) — Machine-readable standards profile for x402, base-token EIPs/ERCs, mirrored `cW*` transport, and the broader ISO-4217-plus asset scope +* [GRU Storage, Governance, and Supervision Standard](../04-configuration/GRU_STORAGE_GOVERNANCE_AND_SUPERVISION_STANDARD.md) — Required metadata, jurisdiction review, and upgrade-notice rules for `c*`, `cW*`, and related governed assets * [GRU FX Currency Onboarding Checklist](../04-configuration/GRU_FX_CURRENCY_ONBOARDING_CHECKLIST.md) — Required end-to-end steps to create, attach, and activate a new FX `c*` instrument inside the GRU ecosystem * [`config/gru-standards-profile.json`](../../config/gru-standards-profile.json) — Machine-readable standards source for GRU monetary assets, payment profiles, and transport methodology +* [`config/gru-governance-supervision-profile.json`](../../config/gru-governance-supervision-profile.json) — Machine-readable storage namespace, supervision, and jurisdiction-review profile * [`config/gru-iso4217-currency-manifest.json`](../../config/gru-iso4217-currency-manifest.json) — Machine-readable supported-currency manifest for `c*` / `cW*`, deployment state, transport activation, and x402 readiness ### References diff --git a/mlfo-gitea-avatar.svg b/mlfo-gitea-avatar.svg new file mode 100644 index 0000000..9f39717 --- /dev/null +++ b/mlfo-gitea-avatar.svg @@ -0,0 +1,35 @@ + + + + + + + + + + + + + + + + + + + + + + + + ML + diff --git a/reports/identity-completion/README.md b/reports/identity-completion/README.md new file mode 100644 index 0000000..ece36d5 --- /dev/null +++ b/reports/identity-completion/README.md @@ -0,0 +1,39 @@ +# Identity Completion Evidence Directory + +**Last updated:** 2026-03-29 + +This directory is the canonical evidence sink for the remaining Indy / Aries / AnonCreds completion work referenced by: + +- `config/production/dbis-identity-public-did-package.json` +- `docs/03-deployment/DBIS_IDENTITY_COMPLETION_PACKAGE_RUNBOOK.md` + +Expected evidence files after completion: + +- `public-did.json` +- `schema-publication.json` +- `creddef-publication.json` +- `issuance-result.json` +- `verification-result.json` + +Template files now ship under: + +- `reports/identity-completion/templates/endorser-connection.json` +- `reports/identity-completion/templates/endorser-approval.json` +- `reports/identity-completion/templates/public-did-publication.json` +- `reports/identity-completion/templates/schema-publication.json` +- `reports/identity-completion/templates/creddef-publication.json` +- `reports/identity-completion/templates/issuance-result.json` +- `reports/identity-completion/templates/verification-result.json` + +Current status: + +- runtime baseline is live on `6400` and `6500` +- package baseline is generated +- governance names and control format are now pre-frozen +- external governance designation, endorser DID, connection ID, and author promotion outputs are still missing + +Governance pre-freeze artifacts: + +- `reports/identity-completion/governance-freeze.json` +- `reports/identity-completion/dbis-namespace-reservation.json` +- `reports/identity-completion/multisig-governance-model.json` diff --git a/reports/identity-completion/dbis-namespace-reservation.json b/reports/identity-completion/dbis-namespace-reservation.json new file mode 100644 index 0000000..7f91676 --- /dev/null +++ b/reports/identity-completion/dbis-namespace-reservation.json @@ -0,0 +1,11 @@ +{ + "timestamp": "2026-03-29T00:00:00Z", + "namespace": "dbis", + "reservedAliases": [ + "dbis-root-endorser", + "dbis-omnl-endorser", + "dbis-iccc-endorser", + "dbis-ar-endorser" + ], + "status": "reserved" +} diff --git a/reports/identity-completion/governance-freeze.json b/reports/identity-completion/governance-freeze.json new file mode 100644 index 0000000..2d2062a --- /dev/null +++ b/reports/identity-completion/governance-freeze.json @@ -0,0 +1,19 @@ +{ + "timestamp": "2026-03-29T00:00:00Z", + "event": "governance-pre-freeze", + "governanceVersion": "1.0", + "targetNetwork": "dbis-local-indy-pool", + "trustScope": "sovereign-internal-first", + "endorserAlias": "dbis-root-endorser", + "operatorOwner": "DBIS Identity Operations Division", + "approvalOwner": "DBIS Governance Authority", + "changeControlRef": "DBIS-ID-GOV-2026-001", + "changeControlFormat": "DBIS-ID-GOV-YYYY-NNN", + "reservedChangeControlRefs": [ + "DBIS-ID-GOV-2026-002", + "DBIS-ID-GOV-2026-003", + "DBIS-ID-GOV-2026-004" + ], + "status": "frozen", + "notes": "Governance structure frozen prior to DID promotion and formal endorser designation." +} diff --git a/reports/identity-completion/multisig-governance-model.json b/reports/identity-completion/multisig-governance-model.json new file mode 100644 index 0000000..166621b --- /dev/null +++ b/reports/identity-completion/multisig-governance-model.json @@ -0,0 +1,23 @@ +{ + "timestamp": "2026-03-29T00:00:00Z", + "governanceVersion": "1.0", + "targetNetwork": "dbis-local-indy-pool", + "endorserAlias": "dbis-root-endorser", + "type": "procedural-multisig", + "quorum": "3-of-5", + "custodians": [ + "DBIS Governance Authority", + "DBIS Identity Operations Division", + "Independent Oversight Authority", + "OMNL Authority (future slot reserved)", + "ICCC Authority (future slot reserved)" + ], + "singleKeyDidControl": "multisig-governance-around-single-key-did", + "currentPhase": "phase-1-procedural", + "futurePhases": [ + "phase-2-hsm-custody", + "phase-3-mpc-threshold-signing" + ], + "status": "frozen", + "notes": "The root endorser DID remains a single-key Indy object. Multisig is enforced around approval and key-use governance, not inside the DID itself." +} diff --git a/reports/identity-completion/templates/creddef-publication.json b/reports/identity-completion/templates/creddef-publication.json new file mode 100644 index 0000000..b97e27f --- /dev/null +++ b/reports/identity-completion/templates/creddef-publication.json @@ -0,0 +1,10 @@ +{ + "timestamp": "", + "network": "dbis-local-indy-pool", + "schemaId": "", + "issuerDID": "", + "credentialDefinitionId": "", + "tag": "default", + "supportRevocation": false, + "txnSeqNo": "" +} diff --git a/reports/identity-completion/templates/endorser-approval.json b/reports/identity-completion/templates/endorser-approval.json new file mode 100644 index 0000000..7bc6406 --- /dev/null +++ b/reports/identity-completion/templates/endorser-approval.json @@ -0,0 +1,8 @@ +{ + "timestamp": "", + "network": "dbis-local-indy-pool", + "authorDID": "", + "endorserDID": "", + "roleGranted": "ENDORSER", + "approvalSignature": "" +} diff --git a/reports/identity-completion/templates/endorser-connection.json b/reports/identity-completion/templates/endorser-connection.json new file mode 100644 index 0000000..2f71d05 --- /dev/null +++ b/reports/identity-completion/templates/endorser-connection.json @@ -0,0 +1,8 @@ +{ + "timestamp": "", + "network": "dbis-local-indy-pool", + "authorAgent": "dbis-identity-author", + "endorserAlias": "", + "connectionId": "", + "status": "connected" +} diff --git a/reports/identity-completion/templates/issuance-result.json b/reports/identity-completion/templates/issuance-result.json new file mode 100644 index 0000000..d8c563a --- /dev/null +++ b/reports/identity-completion/templates/issuance-result.json @@ -0,0 +1,9 @@ +{ + "timestamp": "", + "network": "dbis-local-indy-pool", + "schemaId": "", + "credentialDefinitionId": "", + "issuerSystem": "complete-credential", + "holderId": "", + "status": "issued" +} diff --git a/reports/identity-completion/templates/public-did-publication.json b/reports/identity-completion/templates/public-did-publication.json new file mode 100644 index 0000000..80d74f9 --- /dev/null +++ b/reports/identity-completion/templates/public-did-publication.json @@ -0,0 +1,8 @@ +{ + "timestamp": "", + "network": "dbis-local-indy-pool", + "publicDID": "", + "verkey": "", + "txnSeqNo": "", + "status": "confirmed" +} diff --git a/reports/identity-completion/templates/schema-publication.json b/reports/identity-completion/templates/schema-publication.json new file mode 100644 index 0000000..d56ee61 --- /dev/null +++ b/reports/identity-completion/templates/schema-publication.json @@ -0,0 +1,9 @@ +{ + "timestamp": "", + "network": "dbis-local-indy-pool", + "schemaName": "InstitutionAdmission", + "version": "1.0.0", + "issuerDID": "", + "schemaId": "", + "txnSeqNo": "" +} diff --git a/reports/identity-completion/templates/verification-result.json b/reports/identity-completion/templates/verification-result.json new file mode 100644 index 0000000..cf20bf6 --- /dev/null +++ b/reports/identity-completion/templates/verification-result.json @@ -0,0 +1,8 @@ +{ + "timestamp": "", + "network": "dbis-local-indy-pool", + "verificationProfileId": "smoa-basic-admission-check", + "verifierSystem": "smoa", + "presentationExchangeId": "", + "status": "verified" +} diff --git a/scripts/validation/validate-config-files.sh b/scripts/validation/validate-config-files.sh index d98a376..4b0cfdb 100755 --- a/scripts/validation/validate-config-files.sh +++ b/scripts/validation/validate-config-files.sh @@ -51,7 +51,7 @@ check_env() { if $DRY_RUN; then echo "=== Validation (--dry-run: would check) ===" - echo " REQUIRED_FILES: ${REQUIRED_FILES:-}" + echo " REQUIRED_FILES: ${REQUIRED_FILES:-}" echo " OPTIONAL_ENV: ${OPTIONAL_ENV:-}" exit 0 fi @@ -369,6 +369,26 @@ NODE log_err "Missing config/gru-transport-active.json" ERRORS=$((ERRORS + 1)) fi + + if [[ -f "$PROJECT_ROOT/config/gru-governance-supervision-profile.json" ]]; then + log_ok "Found: config/gru-governance-supervision-profile.json" + if command -v jq &>/dev/null; then + if jq -e ' + (.profileId | type == "string") + and (.requiredAssetMetadata | type == "array") + and (.roles.tokenRoles | type == "array") + and (.roles.registryRoles | type == "array") + and (.roles.governanceRoles | type == "array") + and (.storageNamespaces | type == "object") + and (.proposalPolicy.defaultMinimumUpgradeNoticePeriodSeconds | type == "number") + ' "$PROJECT_ROOT/config/gru-governance-supervision-profile.json" &>/dev/null; then + log_ok "gru-governance-supervision-profile.json: top-level structure is valid" + else + log_err "gru-governance-supervision-profile.json: invalid top-level structure" + ERRORS=$((ERRORS + 1)) + fi + fi + fi [[ -f "$PROJECT_ROOT/config/smart-contracts-master.json" ]] && log_ok "Found: config/smart-contracts-master.json" || true # Token lists (Uniswap format): validate structure if present for list in token-lists/lists/dbis-138.tokenlist.json token-lists/lists/cronos.tokenlist.json token-lists/lists/all-mainnet.tokenlist.json; do @@ -491,13 +511,15 @@ NODE and (.canonicalChainId == $manifestChain) and (.references.transportOverlay == "config/gru-transport-active.json") and (.references.currencyManifest == "config/gru-iso4217-currency-manifest.json") + and (.references.governanceSupervisionProfile == "config/gru-governance-supervision-profile.json") + and (.references.storageGovernanceDoc == "docs/04-configuration/GRU_STORAGE_GOVERNANCE_AND_SUPERVISION_STANDARD.md") ' \ --argjson activeChain "$(jq -r '.system.canonicalChainId' "$PROJECT_ROOT/config/gru-transport-active.json")" \ --argjson manifestChain "$(jq -r '.canonicalChainId' "$PROJECT_ROOT/config/gru-iso4217-currency-manifest.json")" \ "$PROJECT_ROOT/config/gru-standards-profile.json" &>/dev/null; then - log_ok "gru-standards-profile.json: canonical-chain and reference wiring matches active overlay + currency manifest" + log_ok "gru-standards-profile.json: canonical-chain and reference wiring matches active overlay + currency manifest + governance profile" else - log_err "gru-standards-profile.json: canonical-chain or reference wiring does not match active overlay / currency manifest" + log_err "gru-standards-profile.json: canonical-chain or reference wiring does not match active overlay / currency manifest / governance profile" ERRORS=$((ERRORS + 1)) fi fi diff --git a/transaction-package-HYBX-BATCH-001.zip b/transaction-package-HYBX-BATCH-001.zip index 5df28c5..b9c625b 100644 Binary files a/transaction-package-HYBX-BATCH-001.zip and b/transaction-package-HYBX-BATCH-001.zip differ