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.

Internal Implementations
InternalImpl
Events

Embeddable 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.

Embeddable functions (two step transfer)

owner(self: @ContractState) → ContractAddress external

Returns the address of the current 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.

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.

_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.

Events

OwnershipTransferStarted(previous_owner: ContractAddress, new_owner: ContractAddress) event

Emitted when the pending owner is updated.

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).

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.
Internal Implementations
InternalImpl
Events
IAccessControl

Embeddable 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.

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.

Internal functions

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.

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
Accounts →