Royalty Info External Traits

CHANGELOG.md

@@ -9,6 +9,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
+### Added
+
+- Embeddable impls for ERC2981 component (#1173)
+ - `ERC2981Info` with read functions for discovering the component's state
+ - `ERC2981AdminOwnable` providing admin functions for a token that implements Ownable component
+ - `ERC2981AdminAccessControl` providing admin functions for a token that implements AccessControl component
+
+### Changed (Breaking)
+
+- Apply underscore pattern to the internal functions of `ERC2981Component` to prevent collisions
+with new external functions (#1173)
+
 ## 0.18.0 (2024-10-17)
 
 ### Added

Scarb.lock

@@ -136,6 +136,7 @@ dependencies = [
 name = "openzeppelin_token"
 version = "0.18.0"
 dependencies = [
+ "openzeppelin_access",
  "openzeppelin_account",
  "openzeppelin_introspection",
  "openzeppelin_test_common",

docs/modules/ROOT/pages/api/token_common.adoc

@@ -16,7 +16,7 @@ This module provides extensions and utilities that are common to multiple token
 
 [.hljs-theme-dark]
 ```cairo
-use openzeppelin_token::common::erc2981::IERC2981;
+use openzeppelin_token::common::erc2981::interface::IERC2981;
 ```
 
 [.contract-index]
@@ -44,6 +44,98 @@ Returns how much royalty is owed and to whom, based on a sale price that may be
 in any unit of exchange. The royalty amount is denominated and must be paid in that same
 unit of exchange.
 
+[.contract]
+[[IERC2981Info]]
+=== `++IERC2981Info++` link:https://github.com/OpenZeppelin/cairo-contracts/blob/release-v0.18.0/packages/token/src/common/erc2981/interface.cairo[{github-icon},role=heading-link]
+
+[.hljs-theme-dark]
+```cairo
+use openzeppelin_token::common::erc2981::interface::IERC2981Info;
+```
+
+Interface providing external read functions for discovering the state of ERC2981 component.
+
+[.contract-index]
+.Functions
+--
+* xref:#IERC2981Info-default_royalty[`++default_royalty()++`]
+* xref:#IERC2981Info-token_royalty[`++token_royalty(token_id)++`]
+--
+
+[#IERC2981Info-Functions]
+==== Functions
+
+[.contract-item]
+[[IERC2981Info-default_royalty]]
+==== `[.contract-item-name]#++default_royalty++#++() → (ContractAddress, u128, u128)++` [.item-kind]#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.
+
+[.contract-item]
+[[IERC2981Info-token_royalty]]
+==== `[.contract-item-name]#++token_royalty++#++(token_id: u256) → (ContractAddress, u128, u128)++` [.item-kind]#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.
+
+[.contract]
+[[IERC2981Admin]]
+=== `++IERC2981Admin++` link:https://github.com/OpenZeppelin/cairo-contracts/blob/release-v0.18.0/packages/token/src/common/erc2981/interface.cairo[{github-icon},role=heading-link]
+
+[.hljs-theme-dark]
+```cairo
+use openzeppelin_token::common::erc2981::interface::IERC2981Admin;
+```
+
+Interface providing external admin functions for managing the settings of ERC2981 component.
+
+[.contract-index]
+.Functions
+--
+* xref:#IERC2981Admin-set_default_royalty[`++set_default_royalty(receiver, fee_numerator)++`]
+* xref:#IERC2981Admin-delete_default_royalty[`++delete_default_royalty()++`]
+* xref:#IERC2981Admin-set_token_royalty[`++set_token_royalty(token_id, receiver, fee_numerator)++`]
+* xref:#IERC2981Admin-reset_token_royalty[`++reset_token_royalty(token_id)++`]
+--
+
+[#IERC2981Admin-Functions]
+==== Functions
+
+[.contract-item]
+[[IERC2981Admin-set_default_royalty]]
+==== `[.contract-item-name]#++set_default_royalty++#++(receiver: ContractAddress, fee_numerator: u128)++` [.item-kind]#external#
+
+Sets the royalty information that all ids in this contract will default to.
+
+[.contract-item]
+[[IERC2981Admin-delete_default_royalty]]
+==== `[.contract-item-name]#++delete_default_royalty++#++()++` [.item-kind]#external#
+
+Removes default royalty information.
+
+[.contract-item]
+[[IERC2981Admin-set_token_royalty]]
+==== `[.contract-item-name]#++set_token_royalty++#++(token_id: u256, receiver: ContractAddress, fee_numerator: u128)++` [.item-kind]#external#
+
+Sets the royalty information for a specific token id that takes precedence over the global default.
+
+[.contract-item]
+[[IERC2981Admin-reset_token_royalty]]
+==== `[.contract-item-name]#++reset_token_royalty++#++(token_id: u256)++` [.item-kind]#external#
+
+Resets royalty information for the token id back to unset.
+
 [.contract]
 [[ERC2981Component]]
 === `++ERC2981Component++` link:https://github.com/OpenZeppelin/cairo-contracts/blob/release-v0.18.0/packages/token/src/common/erc2981/erc2981.cairo[{github-icon},role=heading-link]
@@ -70,19 +162,38 @@ ERC2981 component extending <<IERC2981,IERC2981>>.
 [.sub-index#ERC2981Component-Embeddable-Impls-ERC20Impl]
 .ERC2981Impl
 * xref:#ERC2981Component-royalty_info[`++royalty_info(self, token_id, sale_price)++`]
+
+[.sub-index#ERC2981Component-Embeddable-Impls-ERC2981InfoImpl]
+.ERC2981InfoImpl
+* xref:#ERC2981InfoImpl-default_royalty[`++default_royalty(self)++`]
+* xref:#ERC2981InfoImpl-token_royalty[`++token_royalty(self, token_id)++`]
+
+[.sub-index#ERC2981Component-Embeddable-Impls-ERC2981AdminOwnableImpl]
+.ERC2981AdminOwnableImpl
+* xref:#ERC2981AdminOwnableImpl-set_default_royalty[`++set_default_royalty(self, receiver, fee_numerator)++`]
+* xref:#ERC2981AdminOwnableImpl-delete_default_royalty[`++delete_default_royalty(self)++`]
+* xref:#ERC2981AdminOwnableImpl-set_token_royalty[`++set_token_royalty(self, token_id, receiver, fee_numerator)++`]
+* xref:#ERC2981AdminOwnableImpl-reset_token_royalty[`++reset_token_royalty(self, token_id)++`]
+
+[.sub-index#ERC2981Component-Embeddable-Impls-ERC2981AdminAccessControlImpl]
+.ERC2981AdminAccessControlImpl
+* xref:#ERC2981AdminAccessControlImpl-set_default_royalty[`++set_default_royalty(self, receiver, fee_numerator)++`]
+* xref:#ERC2981AdminAccessControlImpl-delete_default_royalty[`++delete_default_royalty(self)++`]
+* xref:#ERC2981AdminAccessControlImpl-set_token_royalty[`++set_token_royalty(self, token_id, receiver, fee_numerator)++`]
+* xref:#ERC2981AdminAccessControlImpl-reset_token_royalty[`++reset_token_royalty(self, token_id)++`]
 --
 
 [.contract-index]
 .Internal implementations
 --
 .InternalImpl
 * xref:#ERC2981Component-initializer[`++initializer(self, default_receiver, default_royalty_fraction)++`]
-* xref:#ERC2981Component-default_royalty[`++default_royalty(self)++`]
-* xref:#ERC2981Component-set_default_royalty[`++set_default_royalty(self, receiver, fee_numerator)++`]
-* xref:#ERC2981Component-delete_default_royalty[`++delete_default_royalty(self)++`]
-* xref:#ERC2981Component-token_royalty[`++token_royalty(self, token_id)++`]
-* xref:#ERC2981Component-set_token_royalty[`++set_token_royalty(self, token_id, receiver, fee_numerator)++`]
-* xref:#ERC2981Component-reset_token_royalty[`++reset_token_royalty(self, token_id)++`]
+* xref:#ERC2981Component-_default_royalty[`++_default_royalty(self)++`]
+* xref:#ERC2981Component-_set_default_royalty[`++_set_default_royalty(self, receiver, fee_numerator)++`]
+* xref:#ERC2981Component-_delete_default_royalty[`++_delete_default_royalty(self)++`]
+* xref:#ERC2981Component-_token_royalty[`++_token_royalty(self, token_id)++`]
+* xref:#ERC2981Component-_set_token_royalty[`++_set_token_royalty(self, token_id, receiver, fee_numerator)++`]
+* xref:#ERC2981Component-_reset_token_royalty[`++_reset_token_royalty(self, token_id)++`]
 --
 
 [#ERC2981Component-Immutable-Config]
@@ -93,7 +204,7 @@ ERC2981 component extending <<IERC2981,IERC2981>>.
 ==== `[.contract-item-name]#++FEE_DENOMINATOR:++#++ u128++` [.item-kind]#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.
+`_set_token_royalty` and `_set_default_royalty` as a fraction of the sale price.
 
 [.contract-item]
 [[ERC2981Component-IC-validate]]
@@ -123,6 +234,141 @@ The returned tuple contains:
 - `t.0`: The receiver of the royalty payment.
 - `t.1`: The amount of royalty payment.
 
+[.contract-item]
+[[ERC2981InfoImpl-default_royalty]]
+==== `[.contract-item-name]#++default_royalty++#++(@self: ContractState) → (ContractAddress, u128, u128)++` [.item-kind]#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.
+
+[.contract-item]
+[[ERC2981InfoImpl-token_royalty]]
+==== `[.contract-item-name]#++token_royalty++#++(self: @ContractState, token_id: u256) → (ContractAddress, u128, u128)++` [.item-kind]#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.
+
+[#ERC2981Component-ERC2981AdminOwnableImpl]
+==== ERC2981AdminOwnableImpl
+
+:ownable-component: xref:/api/access.adoc#OwnableComponent[OwnableComponent]
+
+Provides admin functions for managing royalty settings that are restricted to be called only by the contract's owner. 
+Requires the contract to implement {ownable-component}.
+
+[.contract-item]
+[[ERC2981AdminOwnableImpl-set_default_royalty]]
+==== `[.contract-item-name]#++set_default_royalty++#++(ref self: ContractState, receiver: ContractAddress, fee_numerator: u128)++` [.item-kind]#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.
+
+[.contract-item]
+[[ERC2981AdminOwnableImpl-delete_default_royalty]]
+==== `[.contract-item-name]#++delete_default_royalty++#++(ref self: ContractState)++` [.item-kind]#external#
+
+Removes default royalty information.
+
+Requirements:
+
+- The caller is the contract owner.
+
+[.contract-item]
+[[ERC2981AdminOwnableImpl-set_token_royalty]]
+==== `[.contract-item-name]#++set_token_royalty++#++(ref self: ContractState, token_id: u256, receiver: ContractAddress, fee_numerator: u128)++` [.item-kind]#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.
+
+[.contract-item]
+[[ERC2981AdminOwnableImpl-reset_token_royalty]]
+==== `[.contract-item-name]#++reset_token_royalty++#++(ref self: ContractState, token_id: u256)++` [.item-kind]#external#
+
+Resets royalty information for the token id back to unset.
+
+Requirements:
+
+- The caller is the contract owner.
+
+[#ERC2981Component-ERC2981AdminAccessControlImpl]
+==== ERC2981AdminAccessControlImpl
+
+:accesscontrol-component: xref:api/access.adoc#AccessControlComponent[AccessControlComponent]
+
+Provides admin functions for managing royalty settings that require `ROYALTY_ADMIN_ROLE` to be granted to the caller. 
+Requires the contract to implement {accesscontrol-component}.
+
+[.contract-item]
+[[ERC2981AdminAccessControlImpl-ROYALTY_ADMIN_ROLE]]
+==== `[.contract-item-name]#++ROYALTY_ADMIN_ROLE:++#++ felt252++` [.item-kind]#constant#
+
+Role for the admin responsible for managing royalty settings.
+
+[.contract-item]
+[[ERC2981AdminAccessControlImpl-set_default_royalty]]
+==== `[.contract-item-name]#++set_default_royalty++#++(ref self: ContractState, receiver: ContractAddress, fee_numerator: u128)++` [.item-kind]#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.
+
+[.contract-item]
+[[ERC2981AdminAccessControlImpl-delete_default_royalty]]
+==== `[.contract-item-name]#++delete_default_royalty++#++(ref self: ContractState)++` [.item-kind]#external#
+
+Removes default royalty information.
+
+Requirements:
+
+- The caller must have `ROYALTY_ADMIN_ROLE` role.
+
+[.contract-item]
+[[ERC2981AdminAccessControlImpl-set_token_royalty]]
+==== `[.contract-item-name]#++set_token_royalty++#++(ref self: ContractState, token_id: u256, receiver: ContractAddress, fee_numerator: u128)++` [.item-kind]#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.
+
+[.contract-item]
+[[ERC2981AdminAccessControlImpl-reset_token_royalty]]
+==== `[.contract-item-name]#++reset_token_royalty++#++(ref self: ContractState, token_id: u256)++` [.item-kind]#external#
+
+Resets royalty information for the token id back to unset.
+
+Requirements:
+
+- The caller must have `ROYALTY_ADMIN_ROLE` role.
+
 [#ERC2981Component-Internal-functions]
 ==== Internal functions
 
@@ -141,8 +387,8 @@ Requirements:
 NOTE: The fee denominator is set by the contract using the {immutable-config}.
 
 [.contract-item]
-[[ERC2981Component-default_royalty]]
-==== `[.contract-item-name]#++default_royalty++#++(self: @ContractState) → (ContractAddress, u128, u128)++` [.item-kind]#internal#
+[[ERC2981Component-_default_royalty]]
+==== `[.contract-item-name]#++_default_royalty++#++(self: @ContractState) → (ContractAddress, u128, u128)++` [.item-kind]#internal#
 
 Returns the royalty information that all ids in this contract will default to.
 
@@ -153,8 +399,8 @@ The returned tuple contains:
 - `t.2`: The denominator of the royalty fraction.
 
 [.contract-item]
-[[ERC2981Component-set_default_royalty]]
-==== `[.contract-item-name]#++set_default_royalty++#++(ref self: ContractState, receiver: ContractAddress, fee_numerator: u128)++` [.item-kind]#internal#
+[[ERC2981Component-_set_default_royalty]]
+==== `[.contract-item-name]#++_set_default_royalty++#++(ref self: ContractState, receiver: ContractAddress, fee_numerator: u128)++` [.item-kind]#internal#
 
 Sets the royalty information that all ids in this contract will default to.
 
@@ -164,14 +410,14 @@ Requirements:
 - `fee_numerator` cannot be greater than the fee denominator.
 
 [.contract-item]
-[[ERC2981Component-delete_default_royalty]]
-==== `[.contract-item-name]#++delete_default_royalty++#++(ref self: ContractState)++` [.item-kind]#internal#
+[[ERC2981Component-_delete_default_royalty]]
+==== `[.contract-item-name]#++_delete_default_royalty++#++(ref self: ContractState)++` [.item-kind]#internal#
 
 Removes default royalty information.
 
 [.contract-item]
-[[ERC2981Component-token_royalty]]
-==== `[.contract-item-name]#++token_royalty++#++(self: @ContractState, token_id: u256) → (ContractAddress, u256, u256)++` [.item-kind]#internal#
+[[ERC2981Component-_token_royalty]]
+==== `[.contract-item-name]#++_token_royalty++#++(self: @ContractState, token_id: u256) → (ContractAddress, u256, u256)++` [.item-kind]#internal#
 
 Returns the royalty information that all ids in this contract will default to.
 
@@ -182,18 +428,18 @@ The returned tuple contains:
 - `t.2`: The denominator of the royalty fraction.
 
 [.contract-item]
-[[ERC2981Component-set_token_royalty]]
-==== `[.contract-item-name]#++set_token_royalty++#++(ref self: ContractState, token_id: u256, receiver: ContractAddress, fee_numerator: u128)++` [.item-kind]#internal#
+[[ERC2981Component-_set_token_royalty]]
+==== `[.contract-item-name]#++_set_token_royalty++#++(ref self: ContractState, token_id: u256, receiver: ContractAddress, fee_numerator: u128)++` [.item-kind]#internal#
 
-Sets the royalty information for a specific token id, overriding the global default.
+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.
 
 [.contract-item]
-[[ERC2981Component-reset_token_royalty]]
-==== `[.contract-item-name]#++reset_token_royalty++#++(ref self: ContractState, token_id: u256)++` [.item-kind]#internal#
+[[ERC2981Component-_reset_token_royalty]]
+==== `[.contract-item-name]#++_reset_token_royalty++#++(ref self: ContractState, token_id: u256)++` [.item-kind]#internal#
 
 Resets royalty information for the token id back to unset.