You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Manages role-based access control within a diamond.
24
+
Role-based access control for diamond contracts
25
25
</DocSubtitle>
26
26
27
27
<Callouttype="info"title="Key Features">
28
-
- Role-based access control for granular permission management.
29
-
- Support for batch granting and revoking roles.
30
-
- Extensible with other access control facets like `AccessControlPausableFacet`.
28
+
- Exposes external functions for role management and permission checking.
29
+
- Integrates with diamond storage for persistent role data.
30
+
- Supports batch operations for granting and revoking roles to multiple accounts.
31
+
- Provides functions to check role membership and enforce role requirements.
31
32
</Callout>
32
33
33
34
## Overview
34
35
35
-
The AccessControlFacet provides a robust role-based access control (RBAC) system for Compose diamonds. It allows for granular permission management by defining roles and assigning them to accounts. This facet is crucial for securing sensitive functions and orchestrating complex interactions by enforcing role requirements.
36
+
This facet implements role-based access control for Compose diamonds. It exposes external functions to manage roles and permissions, interacting with diamond storage. Developers add this facet to enforce access control policies across their diamond's functionality.
function grantUserRole(bytes32 _role, address _user) external {
506
+
IDiamond(diamondAddress).grantRole(_role, _user);
507
507
}
508
508
}`}
509
509
</ExpandableCode>
510
+
-->
510
511
511
512
## Best Practices
512
513
513
514
<Callouttype="tip"title="Best Practice">
514
-
- Initialize roles and grant them to appropriate accounts during diamond deployment.
515
-
- Use `grantRoleBatch` and `revokeRoleBatch` for efficient mass role management.
516
-
- Define clear hierarchies for roles using `setRoleAdmin` to manage administrative privileges.
515
+
- Initialize role administration and grant initial roles during diamond deployment.
516
+
- Use `grantRole` and `revokeRole` for individual account management.
517
+
- Utilize `grantRoleBatch` and `revokeRoleBatch` for efficient management of multiple accounts.
518
+
- Ensure that roles are properly defined and their admin roles are set to manage permissions effectively.
517
519
</Callout>
518
520
519
521
## Security Considerations
520
522
521
523
<Callouttype="warning"title="Security">
522
-
Ensure that role administration is properly secured. The `setRoleAdmin`, `grantRole`, and `revokeRole` functions require the caller to be the admin of the role. Reentrancy is mitigated as role modifications are atomic. Input validation is handled internally by the facet to prevent invalid role or account assignments.
524
+
All state-changing functions (`setRoleAdmin`, `grantRole`, `revokeRole`, `grantRoleBatch`, `revokeRoleBatch`, `renounceRole`) require caller authorization, typically controlled by the role's admin role. The `requireRole` function reverts with `AccessControlUnauthorizedAccount` if the caller lacks the specified role. `renounceRole` reverts with `AccessControlUnauthorizedSender` if the caller is not the account attempting to renounce the role. Follow standard Solidity security practices for input validation.
-Emits events for role changes, aiding off-chain monitoring.
32
32
</Callout>
33
33
34
34
<Callouttype="info"title="Module Usage">
@@ -37,7 +37,7 @@ This module provides internal functions for use in your custom facets. Import it
37
37
38
38
## Overview
39
39
40
-
The AccessControl module provides a robust system for managing roles and permissions, ensuring that only authorized accounts can perform specific actions. This is crucial for maintaining security and control within a Compose diamond by enabling granular access delegation and revocation.
40
+
This module provides internal functions for managing role-based access control within a diamond proxy. Facets can import and use these functions to grant, revoke, and check roles using shared diamond storage. This ensures consistent access control logic across all facets that depend on this module.
-Define roles using `bytes32` and `keccak256` for clarity and gas efficiency.
439
-
-Use `requireRole` for immediate enforcement of permissions within functions.
440
-
-Carefully manage the administration of roles using `setRoleAdmin`to prevent unintended privilege escalation.
438
+
-Call `requireRole` to enforce access control checks before executing sensitive operations.
439
+
-Ensure the diamond's storage layout is compatible with the `AccessControlStorage` struct.
440
+
-Handle `AccessControlUnauthorizedAccount` errors to provide clear feedback to users.
441
441
</Callout>
442
442
443
443
## Integration Notes
444
444
445
445
<Callouttype="success"title="Shared Storage">
446
-
The AccessControl module utilizes the diamond storage pattern, storing its state at a well-defined slot identified by `keccak256("compose.accesscontrol")`. Facets can access this state by calling the `getStorage()` function or directly interacting with the module's functions, which implicitly read from this storage slot. Ensure that the AccessControl module is correctly initialized and its storage slot is reserved to avoid conflicts with other modules.
446
+
This module utilizes diamond storage at the slot identified by `keccak256("compose.accesscontrol")`. All functions operate on the `AccessControlStorage` struct, which is implicitly managed by the diamond storage pattern. Changes to roles made through this module are immediately visible to all facets that access the same storage slot.
Control role access and pause/unpause specific roles.
24
+
Manages role pausing and unpausing within a diamond
25
25
</DocSubtitle>
26
26
27
27
<Callouttype="info"title="Key Features">
28
-
- Allows pausing and unpausing of specific roles, preventing execution of role-bound functions.
29
-
- Integrates seamlessly with existing AccessControl mechanisms.
30
-
- Provides view functions to check the current paused status of any role.
28
+
- Exposes external functions for pausing and unpausing specific roles.
29
+
- Emits `RolePaused` and `RoleUnpaused` events for state changes.
30
+
- Reverts with `AccessControlUnauthorizedAccount` if caller lacks permission to pause/unpause.
31
+
- Reverts with `AccessControlRolePaused` when a paused role is accessed.
31
32
</Callout>
32
33
33
34
## Overview
34
35
35
-
This facet provides granular control over role-based access, allowing specific roles to be temporarily paused. It integrates with the core AccessControl logic to enforce role permissions and adds a pausing mechanism for enhanced operational flexibility. Use this facet to manage temporary disruptions or maintenance periods for specific functionalities tied to roles.
36
+
This facet implements role-based pausing and unpausing for diamond functionality. It exposes external functions to control role states, ensuring operations can be temporarily halted or resumed. Developers integrate this facet to add granular control over role permissions within a diamond.
- Initialize or upgrade the diamond to include this facet to enable role pausing capabilities.
330
-
-Ensure the caller invoking `pauseRole` and `unpauseRole` has the necessary administrative privileges for the target role.
331
-
-Leverage `requireRoleNotPaused` within other facets or contract logic to dynamically enforce pausing states.
321
+
- Initialize roles and their pausing status during diamond deployment.
322
+
-Enforce `requireRoleNotPaused` checks on sensitive external or internal functions.
323
+
-Grant pausing capabilities only to authorized administrative roles.
332
324
</Callout>
333
325
334
326
## Security Considerations
335
327
336
328
<Callouttype="warning"title="Security">
337
-
The `pauseRole` and `unpauseRole` functions are restricted to the admin of the respective role, preventing unauthorized pausing. The `requireRoleNotPaused` function reverts with `AccessControlRolePaused` if the role is paused, ensuring that paused roles cannot be utilized. Ensure that any critical functions protected by roles properly call `requireRoleNotPaused` or equivalent logic to respect the paused state.
329
+
All state-changing functions (`pauseRole`, `unpauseRole`) are protected by implicit access control checks handled by the diamond proxy's dispatch mechanism and the facet's internal logic, ensuring only authorized accounts can modify role pause states. The `requireRoleNotPaused` function includes checks for both account role membership and role pause status, reverting with appropriate errors (`AccessControlUnauthorizedAccount`, `AccessControlRolePaused`) to prevent unauthorized or paused role usage.
0 commit comments