Access Control
This crate 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
OwnableComponent
use openzeppelin::access::ownable::OwnableComponent;
Ownable
provides a basic access control mechanism where an account
(an owner) can be granted exclusive access to specific functions.
This module includes the internal assert_only_owner
to restrict a function to be used only by the 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. |
pending_owner(self: @ContractState) → ContractAddress
external
Returns the address of the pending owner.
accept_ownership(ref self: ContractState)
external
Transfers ownership of the contract to the pending owner. Can only be called by the pending owner. Resets pending owner to zero address.
Emits an OwnershipTransferred event.
transfer_ownership(ref self: ContractState, new_owner: ContractAddress)
external
Starts the two step ownership transfer process, by setting the pending owner. Can only be called by the current owner.
Emits an OwnershipTransferStarted 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. |
transferOwnership(ref self: ContractState, newOwner: ContractAddress)
external
See transfer_ownership.
renounceOwnership(ref self: ContractState)
external
See renounce_ownership.
pendingOwner(self: @ContractState)
external
See pending_owner.
acceptOwnership(self: @ContractState)
external
See accept_ownership.
transferOwnership(self: @ContractState)
external
See transfer_ownership.
renounceOwnership(self: @ContractState)
external
See renounce_ownership.
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.
_propose_owner(ref self: ContractState, new_owner: ContractAddress)
internal
Sets a new pending owner in a two step transfer.
Internal function without access restriction.
Emits an OwnershipTransferStarted event.
IAccessControl
use openzeppelin::access::accesscontrol::interface::IAccessControl;
External interface of AccessControl.
0x23700be02858dbe2ac4dc9c9f66d0b6b0ed81ec7f970ca6844500a56ff61751
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
.
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.
AccessControlComponent
use openzeppelin::access::accesscontrol::AccessControlComponent;
Component that allows contracts 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
:
(...)
#[external(v0)]
fn foo(ref self: ContractState) {
self.accesscontrol.assert_only_role(MY_ROLE);
// Do something
}
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.
|
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.
hasRole(self: @ContractState, role: felt252, account: ContractAddress) → bool
external
See has_role.
getRoleAdmin(self: @ContractState, role: felt252) → felt252
external
See get_role_admin.
grantRole(ref self: ContractState, role: felt252, account: ContractAddress)
external
See grant_role.
revokeRole(ref self: ContractState, role: felt252, account: ContractAddress)
external
See revoke_role.
renounceRole(ref self: ContractState, role: felt252, account: ContractAddress)
external
See renounce_role.
initializer(ref self: ContractState)
internal
Initializes the contract by registering the IAccessControl interface ID.
assert_only_role(self: @ContractState, role: felt252)
internal
Panics if called by any account without the given role
.
set_role_admin(ref self: ContractState, role: felt252, admin_role: felt252)
internal
Sets admin_role
as role
's admin role.
Internal function without access restriction.
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.