0
# Access Control
1

2
Comprehensive permission management systems for smart contracts, including role-based access control, ownership patterns, and advanced access management with time-based operations.
3

4
## Capabilities
5

6
### Role-Based Access Control
7

8
The AccessControl system provides flexible role-based permissions where roles can be granted and revoked dynamically.
9

10
```solidity { .api }
11
/**
12
 * @dev Role-based access control mechanism
13
 */
14
abstract contract AccessControlUpgradeable {
15
    function __AccessControl_init() internal onlyInitializing;
16
    
17
    /**
18
     * @dev Returns true if account has been granted role
19
     */
20
    function hasRole(bytes32 role, address account) external view returns (bool);
21
    
22
    /**
23
     * @dev Returns the admin role that controls role
24
     */
25
    function getRoleAdmin(bytes32 role) external view returns (bytes32);
26
    
27
    /**
28
     * @dev Grants role to account. Caller must have admin role
29
     */
30
    function grantRole(bytes32 role, address account) external;
31
    
32
    /**
33
     * @dev Revokes role from account. Caller must have admin role
34
     */
35
    function revokeRole(bytes32 role, address account) external;
36
    
37
    /**
38
     * @dev Revokes role from calling account
39
     */
40
    function renounceRole(bytes32 role, address callerConfirmation) external;
41
    
42
    /**
43
     * @dev Modifier that checks that account has specific role
44
     */
45
    modifier onlyRole(bytes32 role);
46

47
    // Default admin role (0x00)
48
    bytes32 constant DEFAULT_ADMIN_ROLE = 0x00;
49
}
50

51
// Custom errors
52
error AccessControlUnauthorizedAccount(address account, bytes32 neededRole);
53
error AccessControlBadConfirmation();
54

55
// Events
56
event RoleAdminChanged(bytes32 indexed role, bytes32 indexed previousAdminRole, bytes32 indexed newAdminRole);
57
event RoleGranted(bytes32 indexed role, address indexed account, address indexed sender);
58
event RoleRevoked(bytes32 indexed role, address indexed account, address indexed sender);
59
```
60

61
**Usage Example:**
62

63
```solidity
64
import {AccessControlUpgradeable} from "@openzeppelin/contracts-upgradeable/access/AccessControlUpgradeable.sol";
65

66
contract MyContract is AccessControlUpgradeable {
67
    bytes32 public constant MINTER_ROLE = keccak256("MINTER_ROLE");
68
    bytes32 public constant PAUSER_ROLE = keccak256("PAUSER_ROLE");
69

70
    function initialize(address defaultAdmin) initializer public {
71
        __AccessControl_init();
72
        _grantRole(DEFAULT_ADMIN_ROLE, defaultAdmin);
73
    }
74

75
    function mint(address to, uint256 amount) public onlyRole(MINTER_ROLE) {
76
        // Minting logic
77
    }
78
}
79
```
80

81
### Enhanced Access Control with Default Admin Rules
82

83
Extended access control with enhanced default administration features including time delays for admin changes.
84

85
```solidity { .api }
86
/**
87
 * @dev Extension with enhanced default admin functionality
88
 */
89
abstract contract AccessControlDefaultAdminRulesUpgradeable {
90
    function __AccessControlDefaultAdminRules_init(uint48 initialDelay, address initialDefaultAdmin) internal onlyInitializing;
91
    
92
    /**
93
     * @dev Returns the current default admin
94
     */
95
    function defaultAdmin() external view returns (address);
96
    
97
    /**
98
     * @dev Returns the pending default admin and its schedule
99
     */
100
    function pendingDefaultAdmin() external view returns (address newAdmin, uint48 schedule);
101
    
102
    /**
103
     * @dev Returns the current delay for default admin changes
104
     */
105
    function defaultAdminDelay() external view returns (uint48);
106
    
107
    /**
108
     * @dev Returns the pending delay and its schedule
109
     */
110
    function pendingDefaultAdminDelay() external view returns (uint48 newDelay, uint48 schedule);
111
    
112
    /**
113
     * @dev Initiates a default admin transfer with delay
114
     */
115
    function beginDefaultAdminTransfer(address newAdmin) external;
116
    
117
    /**
118
     * @dev Accepts the pending default admin transfer
119
     */
120
    function acceptDefaultAdminTransfer() external;
121
    
122
    /**
123
     * @dev Changes the default admin delay
124
     */
125
    function changeDefaultAdminDelay(uint48 newDelay) external;
126
    
127
    /**
128
     * @dev Cancels a pending default admin delay change
129
     */
130
    function rollbackDefaultAdminDelay() external;
131
}
132
```
133

134
### Enumerable Access Control
135

136
Access control extension that allows enumeration of role members.
137

138
```solidity { .api }
139
/**
140
 * @dev Extension that allows enumerating the members of each role
141
 */
142
abstract contract AccessControlEnumerableUpgradeable {
143
    function __AccessControlEnumerable_init() internal onlyInitializing;
144
    
145
    /**
146
     * @dev Returns one of the accounts that have role. index must be between 0 and getRoleMemberCount
147
     */
148
    function getRoleMember(bytes32 role, uint256 index) external view returns (address);
149
    
150
    /**
151
     * @dev Returns the number of accounts that have role
152
     */
153
    function getRoleMemberCount(bytes32 role) external view returns (uint256);
154
}
155
```
156

157
### Simple Ownership
158

159
Traditional single-owner access control pattern.
160

161
```solidity { .api }
162
/**
163
 * @dev Contract module providing basic ownership functionality
164
 */
165
abstract contract OwnableUpgradeable {
166
    function __Ownable_init(address initialOwner) internal onlyInitializing;
167
    
168
    /**
169
     * @dev Returns the address of the current owner
170
     */
171
    function owner() external view returns (address);
172
    
173
    /**
174
     * @dev Transfers ownership to a new account
175
     */
176
    function transferOwnership(address newOwner) external onlyOwner;
177
    
178
    /**
179
     * @dev Leaves the contract without owner (renounces ownership)
180
     */
181
    function renounceOwnership() external onlyOwner;
182
    
183
    /**
184
     * @dev Throws if called by any account other than the owner
185
     */
186
    modifier onlyOwner();
187
}
188

189
// Custom errors
190
error OwnableUnauthorizedAccount(address account);
191
error OwnableInvalidOwner(address owner);
192

193
// Events
194
event OwnershipTransferred(address indexed previousOwner, address indexed newOwner);
195
```
196

197
### Two-Step Ownership
198

199
Enhanced ownership pattern that requires new owner to accept ownership to prevent accidental transfers.
200

201
```solidity { .api }
202
/**
203
 * @dev Extension of Ownable that adds a two-step ownership transfer
204
 */
205
abstract contract Ownable2StepUpgradeable {
206
    function __Ownable2Step_init(address initialOwner) internal onlyInitializing;
207
    
208
    /**
209
     * @dev Returns the address of the pending owner
210
     */
211
    function pendingOwner() external view returns (address);
212
    
213
    /**
214
     * @dev Transfers ownership to a new account (two-step process)
215
     */
216
    function transferOwnership(address newOwner) external override onlyOwner;
217
    
218
    /**
219
     * @dev The new owner accepts the ownership transfer
220
     */
221
    function acceptOwnership() external;
222
}
223

224
// Events
225
event OwnershipTransferStarted(address indexed previousOwner, address indexed newOwner);
226
```
227

228
### Access Manager
229

230
Advanced access control system with fine-grained permissions and scheduling.
231

232
```solidity { .api }
233
/**
234
 * @dev AccessManager is a central contract for access control
235
 */
236
contract AccessManagerUpgradeable {
237
    function __AccessManager_init(address initialAdmin) internal onlyInitializing;
238
    
239
    /**
240
     * @dev Check if caller can call target with selector
241
     */
242
    function canCall(address caller, address target, bytes4 selector) external view returns (bool immediate, uint32 delay);
243
    
244
    /**
245
     * @dev Grant role to account with execution delay
246
     */
247
    function grantRole(uint64 roleId, address account, uint32 executionDelay) external;
248
    
249
    /**
250
     * @dev Revoke role from account
251
     */
252
    function revokeRole(uint64 roleId, address account) external;
253
    
254
    /**
255
     * @dev Set which role can call specific functions
256
     */
257
    function setTargetFunctionRole(address target, bytes4[] calldata selectors, uint64 roleId) external;
258
    
259
    /**
260
     * @dev Schedule an operation for future execution
261
     */
262
    function schedule(address target, bytes calldata data, uint48 when) external returns (bytes32);
263
    
264
    /**
265
     * @dev Execute a scheduled operation
266
     */
267
    function execute(address target, bytes calldata data) external payable returns (bytes32);
268
    
269
    /**
270
     * @dev Cancel a scheduled operation
271
     */
272
    function cancel(address caller, address target, bytes calldata data) external returns (bytes32);
273
}
274
```
275

276
### Access Managed
277

278
Contract base for integration with AccessManager.
279

280
```solidity { .api }
281
/**
282
 * @dev This contract module allows children to restrict access to specific functions
283
 */
284
abstract contract AccessManagedUpgradeable {
285
    function __AccessManaged_init(address initialAuthority) internal onlyInitializing;
286
    
287
    /**
288
     * @dev Returns the current authority
289
     */
290
    function authority() external view returns (address);
291
    
292
    /**
293
     * @dev Transfers control to a new authority
294
     */
295
    function setAuthority(address newAuthority) external restricted;
296
    
297
    /**
298
     * @dev Returns true if the function is being executed by the manager during a scheduled operation
299
     */
300
    function isConsumingScheduledOp() external view returns (bytes4);
301
    
302
    /**
303
     * @dev Restricts access to the calling account
304
     */
305
    modifier restricted();
306
}
307
```
308

309
## Usage Patterns
310

311
### Basic Role Setup
312

313
```solidity { .api }
314
contract MyToken is ERC20Upgradeable, AccessControlUpgradeable {
315
    bytes32 public constant MINTER_ROLE = keccak256("MINTER_ROLE");
316
    bytes32 public constant BURNER_ROLE = keccak256("BURNER_ROLE");
317

318
    function initialize(address defaultAdmin, address minter) initializer public {
319
        __ERC20_init("MyToken", "MTK");
320
        __AccessControl_init();
321
        
322
        _grantRole(DEFAULT_ADMIN_ROLE, defaultAdmin);
323
        _grantRole(MINTER_ROLE, minter);
324
    }
325

326
    function mint(address to, uint256 amount) public onlyRole(MINTER_ROLE) {
327
        _mint(to, amount);
328
    }
329
}
330
```
331

332
### Hierarchical Roles
333

334
```solidity
335
function setupRoles() external onlyRole(DEFAULT_ADMIN_ROLE) {
336
    // Create manager role that can grant minter role
337
    _setRoleAdmin(MINTER_ROLE, MANAGER_ROLE);
338
    _grantRole(MANAGER_ROLE, managerAddress);
339
}
340
```
341

342
### Combined Ownership and Roles
343

344
```solidity { .api }
345
contract HybridAccess is OwnableUpgradeable, AccessControlUpgradeable {
346
    function initialize(address owner) initializer public {
347
        __Ownable_init(owner);
348
        __AccessControl_init();
349
        _grantRole(DEFAULT_ADMIN_ROLE, owner);
350
    }
351
    
352
    // Owner can always grant roles
353
    function grantRole(bytes32 role, address account) public override {
354
        require(hasRole(getRoleAdmin(role), _msgSender()) || owner() == _msgSender(), "Access denied");
355
        _grantRole(role, account);
356
    }
357
}
358
```