Access Control

This directory provides ways to restrict who can access the functions of a contract or when they can do it.

  • Ownable is a simple mechanism with a single "owner" role that can be assigned to a single account. This mechanism can be useful in simple scenarios, but fine grained access needs are likely to outgrow it.

  • AccessControl provides a general role based access control mechanism. Multiple hierarchical roles can be created and assigned each to multiple accounts.

Authorization

Ownable 

use openzeppelin::access::ownable::Ownable;

Ownable provides a basic access control mechanism where an account (an owner) can be granted exclusive access to specific functions.

This module includes the assert_only_owner internal to restrict a function to be used only by the owner.

External Functions
OwnableImpl
Internal Functions
InternalImpl
Events

External Functions

owner(self: @ContractState) → ContractAddress external

Returns the address of the current owner.

transfer_ownership(ref self: ContractState, new_owner: ContractAddress) external

Transfers ownership of the contract to a new account (new_owner). Can only be called by the current owner.

Emits an OwnershipTransferred event.

renounce_ownership(ref self: ContractState) external

Leaves the contract without owner. It will not be possible to call assert_only_owner functions anymore. Can only be called by the current owner.

Renouncing ownership will leave the contract without an owner, thereby removing any functionality that is only available to the owner.

Internal Functions

initializer(ref self: ContractState, owner: ContractAddress) internal

Initializes the contract and sets owner as the initial owner.

Emits an OwnershipTransferred event.

assert_only_owner(self: @ContractState) internal

Panics if called by any account other than the owner.

_transfer_ownership(ref self: ContractState, new_owner: ContractAddress) internal

Transfers ownership of the contract to a new account (new_owner). Internal function without access restriction.

Emits an OwnershipTransferred event.

Events

OwnershipTransferred(previous_owner: ContractAddress, new_owner: ContractAddress) event

Emitted when the ownership is transferred.

IAccessControl 

use openzeppelin::access::accesscontrol::interface::IAccessControl;

External interface of AccessControl.

SRC5 ID

0x23700be02858dbe2ac4dc9c9f66d0b6b0ed81ec7f970ca6844500a56ff61751

Functions
Events

Functions

has_role(role: felt252, account: ContractAddress) → bool external

Returns true if account has been granted role.

get_role_admin(role: felt252) → felt252 external

Returns the admin role that controls role. See grant_role and revoke_role.

To change a role’s admin, use _set_role_admin.

grant_role(role: felt252, account: ContractAddress) external

Grants role to account.

If account had not been already granted role, emits a RoleGranted event.

Requirements:

  • the caller must have role's admin role.

revoke_role(role: felt252, account: ContractAddress) external

Revokes role from account.

If account had been granted role, emits a RoleRevoked event.

Requirements:

  • the caller must have role's admin role.

renounce_role(role: felt252, account: ContractAddress) external

Revokes role from the calling account.

Roles are often managed via grant_role and revoke_role. This function’s purpose is to provide a mechanism for accounts to lose their privileges if they are compromised (such as when a trusted device is misplaced).

If the calling account had been granted role, emits a RoleRevoked event.

Requirements:

  • the caller must be account.

Events

RoleAdminChanged(role: felt252, previous_admin_role: ContractAddress, new_admin_role: ContractAddress) event

Emitted when new_admin_role is set as role's admin role, replacing previous_admin_role

DEFAULT_ADMIN_ROLE is the starting admin for all roles, despite RoleAdminChanged not being emitted signaling this.

RoleGranted(role: felt252, account: ContractAddress, sender: ContractAddress) event

Emitted when account is granted role.

sender is the account that originated the contract call, an admin role bearer.

RoleRevoked(role: felt252, account: ContractAddress, sender: ContractAddress) event

Emitted when account is revoked role.

sender is the account that originated the contract call:

  • if using revoke_role, it is the admin role bearer.

  • if using renounce_role, it is the role bearer (i.e. account).

AccessControl 

use openzeppelin::access::accesscontrol::AccessControl;

Contract module that allows children to implement role-based access control mechanisms. Roles are referred to by their felt252 identifier:

const MY_ROLE: felt252 = selector!('MY_ROLE');

Roles can be used to represent a set of permissions. To restrict access to a function call, use assert_only_role:

use openzeppelin::access::accesscontrol::AccessControl::InternalImpl::assert_only_role;
use openzeppelin::access::accesscontrol::AccessControl;
use openzeppelin::token::erc20::ERC20;

#[external(v0)]
fn foo(ref self: ContractState, account: ContractAddress, amount: u256) {
    let access_state = AccessControl::unsafe_new_contract_state();
    assert_only_role(@access_state, BURNER_ROLE);

    let mut erc20_state = ERC20::unsafe_new_contract_state();
    ERC20::InternalImpl::_burn(ref erc20_state, account, amount);
}

Roles can be granted and revoked dynamically via the grant_role and revoke_role functions. Each role has an associated admin role, and only accounts that have a role’s admin role can call grant_role and revoke_role.

By default, the admin role for all roles is DEFAULT_ADMIN_ROLE, which means that only accounts with this role will be able to grant or revoke other roles. More complex role relationships can be created by using _set_role_admin.

The DEFAULT_ADMIN_ROLE is also its own admin: it has permission to grant and revoke this role. Extra precautions should be taken to secure accounts that have been granted it.
External Functions
AccessControlImpl
SRC5Impl
Internal Functions
InternalImpl
Events
IAccessControl

External Functions

has_role(self: @ContractState, role: felt252, account: ContractAddress) → bool external

Returns true if account has been granted role.

get_role_admin(self: @ContractState, role: felt252) → felt252 external

Returns the admin role that controls role. See grant_role and revoke_role.

To change a role’s admin, use _set_role_admin.

grant_role(ref self: ContractState, role: felt252, account: ContractAddress) external

Grants role to account.

If account had not been already granted role, emits a RoleGranted event.

Requirements:

  • the caller must have role's admin role.

May emit a RoleGranted event.

revoke_role(ref self: ContractState, role: felt252, account: ContractAddress) external

Revokes role from account.

If account had been granted role, emits a RoleRevoked event.

Requirements:

  • the caller must have role's admin role.

May emit a RoleRevoked event.

renounce_role(ref self: ContractState, role: felt252, account: ContractAddress) external

Revokes role from the calling account.

Roles are often managed via grant_role and revoke_role. This function’s purpose is to provide a mechanism for accounts to lose their privileges if they are compromised (such as when a trusted device is misplaced).

If the calling account had been revoked role, emits a RoleRevoked event.

Requirements:

  • the caller must be account.

May emit a RoleRevoked event.

supports_interface(self: @ContractState, interface_id: felt252) → bool external

See ISRC5::supports_interface.

Internal Functions

initializer(ref self: ContractState) internal

Initializes the contract by registering the IAccessControl interface ID.

_set_role_admin(ref self: ContractState, role: felt252, admin_role: felt252) internal

Sets admin_role as role's admin role.

Emits a RoleAdminChanged event.

_grant_role(ref self: ContractState, role: felt252, account: ContractAddress) internal

Grants role to account.

Internal function without access restriction.

May emit a RoleGranted event.

_revoke_role(ref self: ContractState, role: felt252, account: ContractAddress) internal

Revokes role from account.

Internal function without access restriction.

May emit a RoleRevoked event.

assert_only_role(self: @ContractState, role: felt252) internal

Panics if called by any account without the given role.

Events

RoleAdminChanged(role: felt252, previous_admin_role: ContractAddress, new_admin_role: ContractAddress) event

See IAccessControl::RoleAdminChanged.

RoleGranted(role: felt252, account: ContractAddress, sender: ContractAddress) event

See IAccessControl::RoleGranted.

RoleRevoked(role: felt252, account: ContractAddress, sender: ContractAddress) event

See IAccessControl::RoleRevoked.

← Access Control
ERC20 →