Common (Token)

This module provides extensions and utilities that are common to multiple token standards.

Interfaces

Starting from version 3.x.x, the interfaces are no longer part of the openzeppelin_token package. The references documented here are contained in the openzeppelin_interfaces package version v2.1.0.

IERC2981

use openzeppelin_interfaces::erc2981::IERC2981;

SRC5 ID

0x2d3414e45a8700c29f119a54b9f11dca0e29e06ddcb214018fc37340e165ed6

Interface of the ERC2981 standard as defined in EIP-2981.

Functions

• royalty_info(token_id, sale_price)

Functions

royalty_info(token_id: u256, sale_price: u256) → (ContractAddress, u256) external

Returns how much royalty is owed and to whom, based on a sale price that may be denominated in any unit of exchange. The royalty amount is denominated and must be paid in that same unit of exchange.

IERC2981Info

use openzeppelin_interfaces::erc2981::IERC2981Info;

Interface providing external read functions for discovering the state of ERC2981 component.

Functions

• default_royalty()
• token_royalty(token_id)

Functions

default_royalty() → (ContractAddress, u128, u128) external

Returns the royalty information that all ids in this contract will default to.

The returned tuple contains:

• t.0: The receiver of the royalty payment.
• t.1: The numerator of the royalty fraction.
• t.2: The denominator of the royalty fraction.

token_royalty(token_id: u256) → (ContractAddress, u128, u128) external

Returns the royalty information specific to a token.

The returned tuple contains:

• t.0: The receiver of the royalty payment.
• t.1: The numerator of the royalty fraction.
• t.2: The denominator of the royalty fraction.

IERC2981Admin

use openzeppelin_interfaces::erc2981::IERC2981Admin;

Interface providing external admin functions for managing the settings of ERC2981 component.

Functions

• set_default_royalty(receiver, fee_numerator)
• delete_default_royalty()
• set_token_royalty(token_id, receiver, fee_numerator)
• reset_token_royalty(token_id)

Functions

set_default_royalty(receiver: ContractAddress, fee_numerator: u128) external

Sets the royalty information that all ids in this contract will default to.

delete_default_royalty() external

Sets the default royalty percentage and receiver to zero.

set_token_royalty(token_id: u256, receiver: ContractAddress, fee_numerator: u128) external

Sets the royalty information for a specific token id that takes precedence over the global default.

reset_token_royalty(token_id: u256) external

Resets royalty information for the token id back to unset.

ERC2981

ERC2981Component

use openzeppelin_token::common::erc2981::ERC2981Component;

ERC2981 component extending IERC2981.

Immutable Component Config

constants

• FEE_DENOMINATOR

functions

• validate()

Embeddable Implementations

ERC2981Impl

• royalty_info(self, token_id, sale_price)

ERC2981InfoImpl

• default_royalty(self)
• token_royalty(self, token_id)

ERC2981AdminOwnableImpl

• set_default_royalty(self, receiver, fee_numerator)
• delete_default_royalty(self)
• set_token_royalty(self, token_id, receiver, fee_numerator)
• reset_token_royalty(self, token_id)

ERC2981AdminAccessControlImpl

• set_default_royalty(self, receiver, fee_numerator)
• delete_default_royalty(self)
• set_token_royalty(self, token_id, receiver, fee_numerator)
• reset_token_royalty(self, token_id)

Internal implementations

InternalImpl

• initializer(self, default_receiver, default_royalty_fraction)
• _default_royalty(self)
• _set_default_royalty(self, receiver, fee_numerator)
• _delete_default_royalty(self)
• _token_royalty(self, token_id)
• _set_token_royalty(self, token_id, receiver, fee_numerator)
• _reset_token_royalty(self, token_id)

Immutable Config constants

FEE_DENOMINATOR: u128 constant

The denominator with which to interpret the fee set in _set_token_royalty and _set_default_royalty as a fraction of the sale price.

validate() internal

Validates the given implementation of the contract’s configuration.

Requirements:

• FEE_DENOMINATOR must be greater than 0.

This function is called by the contract’s initializer.

Embeddable functions

royalty_info(@self: ContractState, token_id: u256, sale_price: u256) → (ContractAddress, u256) external

Returns how much royalty is owed and to whom, based on a sale price that may be denominated in any unit of exchange. The royalty amount is denominated and should be paid in that same unit of exchange.

The returned tuple contains:

• t.0: The receiver of the royalty payment.
• t.1: The amount of royalty payment.

default_royalty(@self: ContractState) → (ContractAddress, u128, u128) external

Returns the royalty information that all ids in this contract will default to.

The returned tuple contains:

• t.0: The receiver of the royalty payment.
• t.1: The numerator of the royalty fraction.
• t.2: The denominator of the royalty fraction.

token_royalty(self: @ContractState, token_id: u256) → (ContractAddress, u128, u128) external

Returns the royalty information specific to a token. If no specific royalty information is set for the token, the default is returned.

The returned tuple contains:

• t.0: The receiver of the royalty payment.
• t.1: The numerator of the royalty fraction.
• t.2: The denominator of the royalty fraction.

ERC2981AdminOwnableImpl

Provides admin functions for managing royalty settings that are restricted to be called only by the contract’s owner. Requires the contract to implement OwnableComponent.

set_default_royalty(ref self: ContractState, receiver: ContractAddress, fee_numerator: u128) external

Sets the royalty information that all ids in this contract will default to.

Requirements:

• The caller is the contract owner.
• receiver cannot be the zero address.
• fee_numerator cannot be greater than the fee denominator.

delete_default_royalty(ref self: ContractState) external

Sets the default royalty percentage and receiver to zero.

Requirements:

• The caller is the contract owner.

set_token_royalty(ref self: ContractState, token_id: u256, receiver: ContractAddress, fee_numerator: u128) external

Sets the royalty information for a specific token id that takes precedence over the global default.

Requirements:

• The caller is the contract owner.
• receiver cannot be the zero address.
• fee_numerator cannot be greater than the fee denominator.

reset_token_royalty(ref self: ContractState, token_id: u256) external

Resets royalty information for the token id back to unset.

Requirements:

• The caller is the contract owner.

ERC2981AdminAccessControlImpl

Provides admin functions for managing royalty settings that require ROYALTY_ADMIN_ROLE to be granted to the caller. Requires the contract to implement AccessControlComponent.

ROYALTY_ADMIN_ROLE: felt252 constant

Role for the admin responsible for managing royalty settings.

set_default_royalty(ref self: ContractState, receiver: ContractAddress, fee_numerator: u128) external

Sets the royalty information that all ids in this contract will default to.

Requirements:

• The caller must have ROYALTY_ADMIN_ROLE role.
• receiver cannot be the zero address.
• fee_numerator cannot be greater than the fee denominator.

delete_default_royalty(ref self: ContractState) external

Sets the default royalty percentage and receiver to zero.

Requirements:

• The caller must have ROYALTY_ADMIN_ROLE role.

set_token_royalty(ref self: ContractState, token_id: u256, receiver: ContractAddress, fee_numerator: u128) external

Sets the royalty information for a specific token id that takes precedence over the global default.

Requirements:

• The caller must have ROYALTY_ADMIN_ROLE role.
• receiver cannot be the zero address.
• fee_numerator cannot be greater than the fee denominator.

reset_token_royalty(ref self: ContractState, token_id: u256) external

Resets royalty information for the token id back to unset.

Requirements:

• The caller must have ROYALTY_ADMIN_ROLE role.

Internal functions

initializer(ref self: ContractState, default_receiver: ContractAddress, default_royalty_fraction: u128) internal

Initializes the contract by setting the default royalty and registering the supported interface.

Requirements:

• default_receiver cannot be the zero address.
• default_royalty_fraction cannot be greater than the fee denominator.
• The fee denominator must be greater than 0.

The fee denominator is set by the contract using the Immutable Component Config.

_default_royalty(self: @ContractState) → (ContractAddress, u128, u128) internal

Returns the royalty information that all ids in this contract will default to.

The returned tuple contains:

• t.0: The receiver of the royalty payment.
• t.1: The numerator of the royalty fraction.
• t.2: The denominator of the royalty fraction.

_set_default_royalty(ref self: ContractState, receiver: ContractAddress, fee_numerator: u128) internal

Sets the royalty information that all ids in this contract will default to.

Requirements:

• receiver cannot be the zero address.
• fee_numerator cannot be greater than the fee denominator.

_delete_default_royalty(ref self: ContractState) internal

Sets the default royalty percentage and receiver to zero.

_token_royalty(self: @ContractState, token_id: u256) → (ContractAddress, u256, u256) internal

Returns the royalty information that all ids in this contract will default to.

The returned tuple contains:

• t.0: The receiver of the royalty payment.
• t.1: The numerator of the royalty fraction.
• t.2: The denominator of the royalty fraction.

_set_token_royalty(ref self: ContractState, token_id: u256, receiver: ContractAddress, fee_numerator: u128) internal

Sets the royalty information for a specific token id that takes precedence over the global default.

Requirements:

• receiver cannot be the zero address.
• fee_numerator cannot be greater than the fee denominator.

_reset_token_royalty(ref self: ContractState, token_id: u256) internal

Resets royalty information for the token id back to unset.