access-control-patterns

Access Control Patterns

Ownable2Step (Preferred over Ownable)

Two-step ownership transfer prevents accidental transfer to a wrong address.

import {Ownable2Step, Ownable} from "@openzeppelin/contracts/access/Ownable2Step.sol";

contract Treasury is Ownable2Step {
    constructor(address initialOwner) Ownable(initialOwner) {}

    function withdrawFunds(address to, uint256 amount) external onlyOwner {
        if (to == address(0)) revert ZeroAddress();
        (bool success,) = to.call{value: amount}("");
        if (!success) revert TransferFailed();
    }
}

// Transfer flow:
// 1. Current owner calls transferOwnership(newOwner)
// 2. newOwner calls acceptOwnership()
// 3. Ownership transferred only after step 2

Role-Based Access Control

For protocols needing multiple permission levels.

import {AccessControl} from "@openzeppelin/contracts/access/AccessControl.sol";

contract Protocol is AccessControl {
    bytes32 public constant OPERATOR_ROLE = keccak256("OPERATOR_ROLE");
    bytes32 public constant GUARDIAN_ROLE = keccak256("GUARDIAN_ROLE");
    bytes32 public constant TREASURY_ROLE = keccak256("TREASURY_ROLE");

    constructor(address admin) {
        _grantRole(DEFAULT_ADMIN_ROLE, admin);
    }

    function updateParameters(uint256 newFee) external onlyRole(OPERATOR_ROLE) {
        // routine parameter updates
    }

    function emergencyPause() external onlyRole(GUARDIAN_ROLE) {
        _pause();
    }

    function withdrawFees(address to) external onlyRole(TREASURY_ROLE) {
        // treasury management
    }
}

Role Hierarchy Template

DEFAULT_ADMIN_ROLE (multisig/timelock)
├── OPERATOR_ROLE (parameter updates, routine operations)
├── GUARDIAN_ROLE (emergency pause, circuit breakers)
├── TREASURY_ROLE (fee collection, fund management)
├── UPGRADER_ROLE (proxy upgrades — timelock only)
└── MINTER_ROLE (token minting — restricted)

Custom Role Admin

constructor(address admin) {
    _grantRole(DEFAULT_ADMIN_ROLE, admin);

    // OPERATOR_ROLE is managed by DEFAULT_ADMIN_ROLE (default)
    // GUARDIAN can manage itself (guardians can add/remove other guardians)
    _setRoleAdmin(GUARDIAN_ROLE, GUARDIAN_ROLE);

    // MINTER is managed by OPERATOR (operators control minters)
    _setRoleAdmin(MINTER_ROLE, OPERATOR_ROLE);
}