Role Registry

Registry for Roles.

Overview

The Role Registry is a smart contract used to store and manage roles information. This information can be accessed by other contracts to determine which roles a user might have, and which functions those roles allow them to call. Because of the simplicity of this information, unlike most registries, the Roles Registry doesn't make use of the eternal storage pattern to store information, and doesn't inherit functionality from the Base Registry.

Structure

The Role Registry makes use of OpenZeppelin's AccessControl to implement role-based access control. This type of system for management is granular and customizable, allowing for responsibilities to be split and delegated safely. Roles are used to determine which functions a user or contract is allowed to call.

Roles Hierarchy

As can be seen in the example above, the roles in the Role Registry behave in a hierarchy. This means that a role can create other sub-roles in order to delegate responsibilities, but those roles may only be granted permissions that the parent role already has. This means that at most, a sub-role will only be able to have the same permissions as it's parent role has.

The hierarchy starts with the DEFAULT_ADMIN_ROLE, which is given to the address that deploys the Role Registry. This role allows for setting the contract manager role for each of the other contracts, including registries. The contract manager has all permissions over their contract by default, and may then create sub-roles that can only access select functionality.

Some roles are assigned automatically when contracts get deployed, but the majority of roles are unassigned and are left to administer by the KAIO Admin during the initial configuration. This grants vast flexibility in how the access will be managed, even over time.

Role

Roles are used to easily manage permissions for certain functionality. Groups of permissions are associated to a given role, and thus all users with that role are granted those permissions. Grouping them in a Role makes managing permissions simpler and clearer.

Creating Role

  • Function: createRole(bytes32 _role, bytes32 _subRole)

  • Purpose: Creates a new role, setting the existing role used to create it as the role admin.

  • Parameters:

    • bytes32 _role: Existing role used for creation.

    • bytes32 _subRole: New role to create.

  • Validation Checks:

    • Ensures the caller has the existing role used for creation.

    • Makes sure the role does not already exist.

  • Behavior:

    • Creates the new role.

    • Emits a RoleCreated event, signaling the role has been created.

  • Example:

Granting Role

  • Function: grantRole(bytes32 role, address account)

  • Purpose: Grants an existing role to a user.

  • Parameters:

    • bytes32 role: Role to be granted.

    • address account: Address of the user to grant the role to.

  • Validation Checks:

    • Ensures the caller has the admin role for the role to grant.

  • Behavior:

    • Grants the role to the user.

    • Emits a RoleGranted event, signaling the role has been granted.

  • Example:

Checking Role

  • Function: hasRole(bytes32 role, address account)

  • Purpose: Checks if a user has a given role.

  • Parameters:

    • bytes32 role: Role to be checked.

    • address account: User's address.

  • Return Values:

    • bool: Signals if user has the role.

  • Example:

Getting Role Admin

  • Function: getRoleAdmin(bytes32 role)

  • Purpose: Returns the admin role of the given role.

  • Parameters:

    • bytes32 role: Role to be checked.

  • Return Values:

    • bytes32: Admin role of the role.

  • Example:

Revoking Role

  • Function: revokeRole(bytes32 role, address account)

  • Purpose: Revokes a role for a specific user.

  • Parameters:

    • bytes32 role: Role to be revoked.

    • address account: Address to revoke the role from.

  • Behavior:

    • Removes the role from the user.

    • Emits a RoleRevoked event, signaling the role has been revoked.

  • Example:

Renouncing Role

  • Function: renounceRole(bytes32 role, address callerConfirmation)

  • Purpose: Revokes a role for the caller.

  • Parameters:

    • bytes32 role: Role to be revoked.

    • address callerConfirmation: Address of the caller.

  • Behavior:

    • Removes the role from the caller.

    • Emits a RoleRevoked event, signaling the role has been revoked.

  • Example:

Contract Manager

The contract manager is the role that manages permissions in a contract. This means they are able to grant and revoke access to the functions in that contracts to a role of their choice, while having access to all of them themselves. By default, the contract manager for a contract is the DEFAULT_ADMIN_ROLE.

Setting Manager

  • Function: setContractManager(address _contract, bytes32 _roleManager)

  • Purpose: Sets the contract manager role for a contract.

  • Parameters:

    • address _contract: Address of the contract.

    • bytes32 _roleManager: Role to set as manager.

  • Validation Checks:

    • Ensures the caller has the DEFAULT_ADMIN_ROLE.

  • Behavior:

    • Sets the contract manager.

    • Emits a ContractManagerAdded event, signaling the manager role has been set.

  • Example:

Getting Manager

  • Function: getContractManager(address _contract)

  • Purpose: Returns the contract manager role for a contract.

  • Parameters:

    • address _contract: Address of the contract.

  • Return Values:

    • bytes32: Manager role.

  • Example:

Permissions

Permissions refer to the authorization to access certain functions in a given contract. These permissions can be granted and revoked by the role admin of a given role, deciding which functionality the role can access.

Granting Access

  • Function: grantAccess(address _contract, bytes4 _selector, bytes32 _role)

  • Purpose: Grants a role access to call a specific function in a given contract.

  • Parameters:

    • address _contract: Address of the contract.

    • bytes4 _selector: Selector that indicates the function.

    • bytes32 _role: Role to grant access to.

  • Validation Checks:

    • Ensures the caller has the contract manager role for the contract.

  • Behavior:

    • Grants the role access to the function.

    • Emits a AccessGranted event, signaling the access has been granted.

  • Example:

Checking Access

  • Function: hasAccess(address _contract, bytes4 _selector, address _requestor, bytes32 _role)

  • Purpose: Checks if a user has a role with permission to call a function in a given contract.

  • Parameters:

    • address _contract: Address of the contract.

    • bytes4 _selector: Selector that indicates the function.

    • address _requestor: Address of the user.

    • bytes32 _role: Role to check access to.

  • Validation Checks:

    • Ensures the caller has the role they claim.

    • Verifies that the role is able to call the selected function in the contract.

  • Return Values:

    • bool: Returns if the user has access.

  • Example:

Revoking Access

  • Function: revokeAccess(address _contract, bytes4 _selector, bytes32 _role)

  • Purpose: Revokes access to call a specific function in a given contract for a role.

  • Parameters:

    • address _contract: Address of the contract.

    • bytes4 _selector: Selector that indicates the function.

    • bytes32 _role: Role to revoke access from.

  • Validation Checks:

    • Ensures the caller has the contract manager role for the contract.

  • Behavior:

    • Revokes the role's access to the function.

    • Emits a RevokedAccess event, signaling the access has been revoked.

  • Example:

Resetting Access

  • Function: resetAccess(address _contract, bytes4 _selector)

  • Purpose: Revokes access to call a specific function in a given contract for all roles except the contract manager.

  • Parameters:

    • address _contract: Address of the contract.

    • bytes4 _selector: Selector that indicates the function.

  • Validation Checks:

    • Ensures the caller has the contract manager role for the contract.

  • Behavior:

    • Revokes access to the function for all roles.

    • Emits a ResetedAccess event, signaling the access has been reset for all roles.

  • Example:

Last updated