@@ -31,47 +31,116 @@ contract AccessManager is Initializable, UUPSUpgradeable, AccessManagerUpgradeab
3131 // return (true, getRoleAdmin(roleId), 0); // => (true, 0, 0)
3232 // }
3333
34- // Strategic roles for governance classification within the protocol:
34+ // Multisig Assignment & Rotation
35+ // ───────────────────────────────────────────────────────────────
36+ //
37+ // All operational multisigs (Admin, Pauser, Councils, Treasury signers)
38+ // are granted and managed by the Community Governance (GOV_ROLE).
39+ // Any rotation, addition, or removal of a signer or council member
40+ // must be approved by governance through a proposal, queued in the Timelock,
41+ // and executed on-chain.
42+ //
43+ // This ensures that the execution layer (multisigs) remains accountable
44+ // to the collective will of the community.
45+
46+ // Strategic roles for governance classification within the protocol
47+ // ───────────────────────────────────────────────────────────────
3548 //
3649 // Community Governance Role:
3750 // - GOV_ROLE: Represents decentralized community governance.
38- // Decisions are made through collective voting mechanisms (e.g., token-weighted, quadratic).
51+ // Decisions are made collectively through token-weighted, quadratic,
52+ // or other approved voting mechanisms, and executed via a Timelock
53+ // (e.g., 48–72 hours delay) for transparency and reaction time.
54+ //
55+ // Group / Council-Based Roles:
56+ // - ADMIN_ROLE: Managed by a multisig smart account.
57+ // Approves policy attestations, contract upgrades,
58+ // hook registrations, and moderates operational parameters.
59+ //
60+ // - SEC_ROLE: Managed by a designated security council multisig or EOA.
61+ // Authorized to pause protocol modules for monitoring, threat mitigation,
62+ // or emergency response; actions must be reported and are subject to limits.
63+ //
64+ // - TREASURER_ROLE: Managed by a treasury multisig smart account.
65+ // Executes disbursements and manages treasury flows within spending limits
66+ // and policies set by the Community Governance (GOV_ROLE).
67+ //
68+ // - CONTENT_COUNCIL_ROLE: Managed by a multisig smart account.
69+ // Participates in governance referenda and oversees content curation policies.
70+ //
71+ // - CUSTODY_COUNCIL_ROLE: Managed by a multisig smart account.
72+ // Participates in governance referenda for node/custodian validation policies.
73+ //
74+ // Individual / Contract-Based Roles:
75+ // - OPS_ROLE: Internal operational role assigned to protocol-trusted contracts,
76+ // enabling direct interaction with core modules. No human control.
77+ // - VER_ROLE: Individual role granted to trusted creators,
78+ // allowing them to upload content without conventional KYC-style verification.
79+
80+ // OPS_ROLE
81+ // ───────────────────────────────────────────────────────────────
82+ // Critical operational role used by internal protocol contracts
83+ // (e.g., Vault, Escrow) to call sensitive functions like lockFunds
84+ // and releaseFunds.
3985 //
40- // Group/Council Based Roles:
41- // - ADMIN_ROLE: Managed by a smart account or council.
42- // Handles protocol upgrades, pause mechanisms, and operational role assignments.
43- // - MOD_ROLE: Managed by a smart account or council.
44- // Approves policy submissions and moderates hook operations.
45- // - REF_ROLE: Managed by a smart account or council.
46- // Participates in governance referenda for content curation and distributor selection.
86+ // The roleAdmin of OPS_ROLE is held by the ADMIN_ROLE multisig,
87+ // which itself is controlled by Community Governance (GOV_ROLE)
88+ // via proposals + timelock and supervised by SEC_ROLE guardian.
4789 //
48- // Individual/Contract Based Roles:
49- // - OPS_ROLE: Internal operational role assigned to protocol-trusted contracts
50- // for direct module interactions. No human involvement.
51- // - VER_ROLE: Individual role assigned to trusted creators, enabling
52- // content uploads without conventional verification.
90+ // This design preserves flexibility to onboard future audited
91+ // protocol modules while preventing unilateral assignment:
92+ // any change requires a governance proposal, a timelock delay,
93+ // and transparent on-chain execution with published audit evidence.
94+ //
95+ // OPS_ROLE must never be granted to EOAs or multisigs directly.
5396
97+ // Hierarchy / Relationship Diagram
98+ // ───────────────────────────────────────────────────────────────
5499 /*
55- GOV_ROLE (Community Governance)
100+ GOV_ROLE (Community Governance)
101+ │
102+ ├── ADMIN_ROLE (Multisig Council)
103+ │ ├── OPS_ROLE (Internal Contract Role)
104+ │ └── SEC_ROLE (Security Council / Guardian)
105+ │
106+ ├── TREASURER_ROLE (Treasury Multisig under GOV policy)
56107 │
57- ├── ADMIN_ROLE (Smart Account / Council)
58- │ │
59- │ ├── MOD_ROLE (Smart Account / Council)
60- │ │
61- │ └── OPS_ROLE (Internal Contract Role)
108+ ├── CONTENT_COUNCIL_ROLE (Multisig Council)
62109 │
63- ├── REF_ROLE (Smart Account / Council)
110+ ├── CUSTODY_COUNCIL_ROLE (Multisig Council)
64111 │
65- ├ ── VER_ROLE (Individual Trusted Creator)
112+ └ ── VER_ROLE (Individual Trusted Creator)
66113 */
67114
68- _setRoleAdmin (C.VER_ROLE, C.GOV_ROLE);
69- _setRoleAdmin (C.REF_ROLE, C.GOV_ROLE);
70- _setRoleAdmin (C.MOD_ROLE, C.ADMIN_ROLE);
115+ // Proposals Lifecycle (per-domain)
116+ // ───────────────────────────────────────────────────────────────
117+ // PROPOSER (domain governor/council) EXECUTOR (domain timelock)
118+ // └─────────────── propose/schedule ───────────────┘
119+ // domain ──> domain Timelock (delay) ──> execution on domain modules
120+ //
121+ // Example:
122+ // admin-governor (only allowlisted proposers) ──> AdminTimelock ──> Admin modules
123+ //
124+ // Notes:
125+ // • Each domain has its own Governor (proposers allowlisted) and its own Timelock.
126+ // • The domain Timelock is the ONLY authority recognized by that domain’s modules
127+ // (i.e., it holds the role or is the roleAdmin for that domain).
128+ // • EXECUTOR is typically open (EXECUTOR_ROLE = address(0)); anyone can execute after delay.
129+ // • SEC_ROLE: emergency actions MAY execute directly (no timelock) with strict scope limits.
130+
131+ // Role Admin Hierarchy (as configured)
132+ // ───────────────────────────────────────────────────────────────
133+ // Admin domain controls low-level ops & security roles:
71134 _setRoleAdmin (C.OPS_ROLE, C.ADMIN_ROLE);
72- }
135+ _setRoleAdmin (C.SEC_ROLE, C.ADMIN_ROLE);
73136
74- // TODO pause protocol based on permission and roles
137+ // Governance domain controls councils & treasury/community-facing roles:
138+ _setRoleAdmin (C.VER_ROLE, C.GOV_ROLE);
139+ _setRoleAdmin (C.ADMIN_ROLE, C.GOV_ROLE); // locked role
140+ _setRoleAdmin (C.TREASURER_ROLE, C.GOV_ROLE);
141+ _setRoleAdmin (C.CUSTODY_COUNCIL_ROLE, C.GOV_ROLE);
142+ _setRoleAdmin (C.CONTENT_COUNCIL_ROLE, C.GOV_ROLE);
143+ }
75144
76145 /// @dev Authorizes the upgrade of the contract.
77146 /// @notice Only the admin can authorize the upgrade.
0 commit comments