chore: sync all changes to Gitea
Some checks failed
Deploy to Phoenix / deploy (push) Has been cancelled
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
This commit is contained in:
defiQUG
116
docs/runbooks/GRU_M00_DIAMOND_DEPLOYMENT_RUNBOOK.md
Normal file
116
docs/runbooks/GRU_M00_DIAMOND_DEPLOYMENT_RUNBOOK.md
Normal file
@@ -0,0 +1,116 @@
|
||||
# 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](../04-configuration/GRU_M00_DIAMOND_INSTITUTIONAL_SPEC.md) | [GRU_M00_DIAMOND_FACET_MAP.md](../04-configuration/GRU_M00_DIAMOND_FACET_MAP.md) | [GRU_M00_DIAMOND_REVIEW_GAPS_AND_RECOMMENDATIONS.md](../04-configuration/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](MULTI_CHAIN_EXECUTION_DETERMINISTIC_DEPLOYMENT.md) when added. |
|
||||
|
||||
**Reference:** [MULTI_CHAIN_EXECUTION_DETERMINISTIC_DEPLOYMENT.md](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](../11-references/CONTRACT_ADDRESSES_REFERENCE.md).
|
||||
|
||||
### 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](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](../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](../04-configuration/GRU_M00_DIAMOND_INSTITUTIONAL_SPEC.md#appendix-policyrouter-and-gate-event-signatures). |
|
||||
|
||||
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](../04-configuration/GRU_M00_DIAMOND_INSTITUTIONAL_SPEC.md) — §1–§8, default governance level, event signatures appendix.
|
||||
- [GRU_M00_DIAMOND_FACET_MAP.md](../04-configuration/GRU_M00_DIAMOND_FACET_MAP.md) — Facet map, governance levels 0–5.
|
||||
- [GRU_M00_DIAMOND_REVIEW_GAPS_AND_RECOMMENDATIONS.md](../04-configuration/GRU_M00_DIAMOND_REVIEW_GAPS_AND_RECOMMENDATIONS.md) — Spine checklist (§6), wire-ins.
|
||||
- [MULTI_CHAIN_EXECUTION_DETERMINISTIC_DEPLOYMENT.md](MULTI_CHAIN_EXECUTION_DETERMINISTIC_DEPLOYMENT.md) — CREATE2 factory and salts.
|
||||
- [CONTRACT_DEPLOYMENT_RUNBOOK.md](../03-deployment/CONTRACT_DEPLOYMENT_RUNBOOK.md) — General deployment and env.
|
||||
- [gru-docs/contracts/README.md](../gru-docs/contracts/README.md) — GRC-2535 Diamond (Option B migration source).
|
||||
Reference in New Issue
Block a user