proxmox/docs/runbooks/GRU_M00_DIAMOND_DEPLOYMENT_RUNBOOK.md

GRU M00 Diamond — Deployment and Migration Runbook

Purpose: Procedural runbook for deploying the M00 Diamond (new deployment) or migrating from GRC-2535 to M00. Covers target chain(s), CREATE2, initial facet attach, default governance level, and testing/verification.

Spec: GRU_M00_DIAMOND_INSTITUTIONAL_SPEC.md | GRU_M00_DIAMOND_FACET_MAP.md | GRU_M00_DIAMOND_REVIEW_GAPS_AND_RECOMMENDATIONS.md.

---

1. Target chain(s) and CREATE2

Item	Decision
Primary chain	Chain 138 (DeFi Oracle Meta Mainnet) first.
Additional chains	Mainnet (1), 651940 (ALL Mainnet), and other EVM chains as needed; document per chain in this runbook.
CREATE2	Use CREATE2 for M00 Diamond (and optional facet/proxy deployments) when same address across chains is required. If M00 is deployed only on 138 initially, CREATE is acceptable; switch to CREATE2 when multi-chain parity is needed.
Salt	If using CREATE2: e.g. keccak256("M00Diamond") or keccak256("GRU.M00.Diamond"). Document in MULTI_CHAIN_EXECUTION_DETERMINISTIC_DEPLOYMENT.md when added.

Reference: MULTI_CHAIN_EXECUTION_DETERMINISTIC_DEPLOYMENT.md for CREATE2 factory and contract salts.

---

2. Default governance level at deployment

• Default level at init: 0 (Free / devnet / sandbox) so that the Diamond is usable immediately without gate enforcement.
• Production: After deployment, set level via GovernanceLevelFacet (e.g. to 1 or 2) in a separate init step or upgrade. Document the chosen default per environment (devnet: 0, testnet: 1, mainnet: 2 or per policy).

---

3. Option A — Deploy M00 as a new Diamond

Use when M00 is a new contract (no migration from GRC-2535).

3.1 Prerequisites

• GRUStorage layout (or library) with reserved namespaces for all seven domains + policy bitmask + standards registry.
• Core facets: DiamondCut (or inline in Diamond), DiamondLoupe (or inline), OwnershipFacet or GovernanceFacet, PauseFacet.
• Minimum ship facets (stubs OK): PolicyRouterFacet, TokenFactoryFacet (or AssetRegistry + MarketFactory), ComplianceGateFacet, AccountingGateFacet, StandardsRegistryFacet, GovernanceLevelFacet.

3.2 Steps

1. Deploy Diamond proxy/core — Deploy the M00 Diamond contract (constructor: owner, optional version). Use CREATE2 if same address is required across chains; record address.
2. Attach core facets — diamondCut to add DiamondCutFacet (if separate), DiamondLoupeFacet (if separate), OwnershipFacet/GovernanceFacet, PauseFacet.
3. Attach minimum ship facets — diamondCut to add PolicyRouterFacet, GovernanceLevelFacet, StandardsRegistryFacet, ComplianceGateFacet (stub), AccountingGateFacet (stub), TokenFactoryFacet (or AssetRegistryFacet + MarketFactoryFacet).
4. Initialize storage — Call init on GovernanceLevelFacet (set default level to 0) and StandardsRegistryFacet (register initial modules if any). Ensure GRUStorage namespaces are initialized as required.
5. Verify — Run §6 (Testing and verification). Record Diamond address and facet list in this runbook or in CONTRACT_ADDRESSES_REFERENCE.

3.3 Env / config

• RPC_URL_138 (or target chain RPC).
• PRIVATE_KEY or deployer multisig.
• M00_OWNER or M00_UPGRADE_ADMIN (optional).
• If CREATE2: CREATE2_FACTORY_ADDRESS (see MULTI_CHAIN_EXECUTION_DETERMINISTIC_DEPLOYMENT.md).

---

4. Option B — Migrate GRC-2535 to M00

Use when upgrading the existing GrcDiamond (same contract) to M00 by adding/replacing facets and extending storage.

4.1 Prerequisites

• GRC-2535 Diamond already deployed (see gru-docs/contracts/README.md).
• GRUStorage namespaces do not collide with existing GRCStorage slots; use distinct keccak256 namespaces (e.g. keccak256("gru.m00.*")).
• Upgrade authority (owner or ROLE_UPGRADE) available.

4.2 Steps

1. Propose cut — Use GovernanceFacet.proposeCut (if timelock) or direct diamondCut: add PolicyRouterFacet, GovernanceLevelFacet, StandardsRegistryFacet, ComplianceGateFacet (stub), AccountingGateFacet (stub), TokenFactoryFacet (or AssetRegistry + MarketFactory). Do not remove existing facets unless deprecating.
2. Queue and execute — If timelock: queue, wait ETA, execute. Else: execute diamondCut with init address and calldata for new storage (e.g. set governance level to 0).
3. Initialize new storage — Call GovernanceLevelFacet.setGovernanceLevel(0) (or equivalent) and any StandardsRegistryFacet init. Ensure new GRUStorage domains are written only via facet accessors to avoid overwriting GRC storage.
4. Verify — Run §6. Confirm existing GRC facets (Monetary, Bond, Index, etc.) still work and new facets are callable.

4.3 Rollback

• Keep previous facet addresses and selectors documented so a rollback cut can remove new facets and restore previous behavior if needed.

---

5. Initial facet attach order (reference)

Suggested order for first deployment (Option A):

1. Core: DiamondCut (if external), DiamondLoupe (if external), OwnershipFacet, PauseFacet.
2. Governance: GovernanceFacet (if not merged with Ownership).
3. Spine: GovernanceLevelFacet → StandardsRegistryFacet → PolicyRouterFacet → ComplianceGateFacet (stub) → AccountingGateFacet (stub) → TokenFactoryFacet (or AssetRegistry + MarketFactory).
4. Optional: AssetRegistryFacet, MarketFactoryFacet, MintBurnFacet (stubs) as needed.

Dependencies: PolicyRouterFacet and gate stubs may need GovernanceLevelFacet and GRUStorage already initialized. Run init delegatecall after the cut that adds the spine facets.

---

6. Testing and verification

After deployment or migration:

#	Check	How
1	Loupe	Call facets(), facetAddress(selector) for PolicyRouter, GovernanceLevel, ComplianceGate, AccountingGate, TokenFactory (or AssetRegistry/MarketFactory). Confirm all expected selectors are present.
2	Governance level	Call GovernanceLevelFacet.getGovernanceLevel() (or equivalent). Expect 0 (or configured default).
3	PolicyRouter	Call PolicyRouter.checkTransfer (or equivalent) with test args; expect no-op or event emission (stub).
4	Storage layout	If possible, run storage layout tests (e.g. Forge) to ensure GRUStorage slots do not overlap with existing GRCStorage or each other.
5	Upgrade	Propose and execute a no-op or small facet cut (e.g. replace a stub with same logic) to verify diamondCut and timelock (if used) work.
6	Events	Trigger a transfer or gate call and confirm expected events (e.g. TransferChecked, JournalPosted) per institutional spec appendix.

Add Forge or Hardhat tests for facet upgrade and storage consistency when the spine is implemented; reference this runbook from the test suite.

---

7. Related documents

• GRU_M00_DIAMOND_INSTITUTIONAL_SPEC.md — §1–§8, default governance level, event signatures appendix.
• GRU_M00_DIAMOND_FACET_MAP.md — Facet map, governance levels 0–5.
• GRU_M00_DIAMOND_REVIEW_GAPS_AND_RECOMMENDATIONS.md — Spine checklist (§6), wire-ins.
• MULTI_CHAIN_EXECUTION_DETERMINISTIC_DEPLOYMENT.md — CREATE2 factory and salts.
• CONTRACT_DEPLOYMENT_RUNBOOK.md — General deployment and env.
• gru-docs/contracts/README.md — GRC-2535 Diamond (Option B migration source).