Add ERC721EnumerableComponent extension

CHANGELOG.md

@@ -10,6 +10,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- ERC721Enumerable component (#983)
 - TimelockController component (#996)
 - HashCall implementation (#996)
 - Separated package for each submodule (#1065)

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

@@ -477,7 +477,6 @@ WARNING: To track voting units, this extension requires that the
 xref:#ERC20VotesComponent-transfer_voting_units[transfer_voting_units] function is called after every transfer,
 mint, or burn operation. For this, the xref:ERC20Component-ERC20HooksTrait[ERC20HooksTrait] must be used.
 
-
 This extension keeps a history (checkpoints) of each account’s vote power. Vote power can be delegated either by calling
 the xref:#ERC20VotesComponent-delegate[delegate] function directly, or by providing a signature to be used with
 xref:#ERC20VotesComponent-delegate_by_sig[delegate_by_sig]. Voting power can be queried through the public accessors

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

@@ -179,6 +179,48 @@ Returns the NFT ticker symbol.
 Returns the Uniform Resource Identifier (URI) for the `token_id` token.
 If the URI is not set for `token_id`, the return value will be an empty `ByteArray`.
 
+[.contract]
+[[IERC721Enumerable]]
+=== `++IERC721Enumerable++` link:https://github.com/OpenZeppelin/cairo-contracts/blob/release-v0.15.0-rc.0/src/token/erc721/extensions/erc721_enumerable/interface.cairo[{github-icon},role=heading-link]
+
+Interface for the optional enumerable functions in {eip721}.
+
+[.contract-index]
+.{inner-src5}
+--
+0x16bc0f502eeaf65ce0b3acb5eea656e2f26979ce6750e8502a82f377e538c87
+--
+
+[.contract-index]
+.Functions
+--
+* xref:#IERC721Enumerable-total_supply[`++total_supply()++`]
+* xref:#IERC721Enumerable-token_by_index[`++token_by_index(index)++`]
+* xref:#IERC721Enumerable-token_of_owner_by_index[`++token_of_owner_by_index(owner, index)++`]
+--
+
+==== Functions
+
+[.contract-item]
+[[IERC721Enumerable-total_supply]]
+==== `[.contract-item-name]#++total_supply++#++() -> u256++` [.item-kind]#external#
+
+Returns the total amount of tokens stored by the contract.
+
+[.contract-item]
+[[IERC721Metadata-token_by_index]]
+==== `[.contract-item-name]#++token_by_index++#++(index) -> u256++` [.item-kind]#external#
+
+Returns a token id at a given `index` of all the tokens stored by the contract.
+Use along with xref:#IERC721Enumerable-total_supply[IERC721Enumerable::total_supply] to enumerate all tokens.
+
+[.contract-item]
+[[IERC721Metadata-token_of_owner_by_index]]
+==== `[.contract-item-name]#++token_of_owner_by_index++#++(owner, index) -> u256++` [.item-kind]#external#
+
+Returns the token id owned by `owner` at a given `index` of its token list.
+Use along with xref:#IERC721-balance_of[IERC721::balance_of] to enumerate all of ``owner``'s tokens.
+
 [.contract]
 [[ERC721Component]]
 === `++ERC721Component++` link:https://github.com/OpenZeppelin/cairo-contracts/blob/release-v0.15.0-rc.0/src/token/erc721/erc721.cairo#L7[{github-icon},role=heading-link]
@@ -629,6 +671,8 @@ Requirements:
 
 Emits an <<IERC721-Approval,Approval>> event.
 
+Emits an <<IERC721-Approval,Approval>> event.
+
 [.contract-item]
 [[ERC721Component-_set_base_uri]]
 ==== `[.contract-item-name]#++_set_base_uri++#++(ref self: ContractState, base_uri: ByteArray)++` [.item-kind]#internal#
@@ -689,6 +733,125 @@ See <<IERC721-ApprovalForAll,IERC721::ApprovalForAll>>.
 
 See <<IERC721-Transfer,IERC721::Transfer>>.
 
+[.contract]
+[[ERC721EnumerableComponent]]
+=== `++ERC721EnumerableComponent++` link:https://github.com/OpenZeppelin/cairo-contracts/blob/release-v0.15.0-rc.0/src/token/erc721/extensions/erc721_enumerable.cairo[{github-icon},role=heading-link]
+
+```cairo
+use openzeppelin::token::extensions::ERC721EnumerableComponent;
+```
+
+Extension of ERC721 as defined in the EIP that adds enumerability of all the token ids in the contract as well as all token ids owned by each account.
+This extension allows contracts to publish their entire list of NFTs and make them discoverable.
+
+NOTE: Implementing xref:#ERC721Component[ERC721Component] is a requirement for this component to be implemented.
+
+WARNING: To properly track token ids, this extension requires that the xref:#ERC721EnumerableComponent-before_update[ERC721EnumerableComponent::before_update] function is called after every transfer, mint, or burn operation.
+For this, the xref:ERC721Component-before_update[ERC721HooksTrait::before_update] hook must be used.
+
+[.contract-index#ERC721EnumerableComponent-Embeddable-Impls]
+.Embeddable Implementations
+--
+[.sub-index#ERC721EnumerableComponent-Embeddable-Impls-ERC721EnumerableImpl]
+.ERC721EnumerableImpl
+* xref:#ERC721EnumerableComponent-total_supply[`++total_supply(self)++`]
+* xref:#ERC721EnumerableComponent-token_by_index[`++token_by_index(self, index)++`]
+* xref:#ERC721EnumerableComponent-token_of_owner_by_index[`++token_of_owner_by_index(self, address, index)++`]
+--
+
+[.contract-index]
+.Internal implementations
+--
+.InternalImpl
+* xref:#ERC721EnumerableComponent-initializer[`++initializer(self)++`]
+* xref:#ERC721EnumerableComponent-before_update[`++before_update(self, to, token_id)++`]
+
+.PrivateImpl
+* xref:#ERC721EnumerableComponent-_add_token_to_owner_enumeration[`++_add_token_to_owner_enumeration(self, to, token_id)++`]
+* xref:#ERC721EnumerableComponent-_add_token_to_all_tokens_enumeration[`++_add_token_to_all_tokens_enumeration(self, token_id)++`]
+* xref:#ERC721EnumerableComponent-_remove_token_from_owner_enumeration[`++_remove_token_from_owner_enumeration(self, from, token_id)++`]
+* xref:#ERC721EnumerableComponent-_remove_token_from_all_tokens_enumeration[`++_remove_token_from_all_tokens_enumeration(self, token_id)++`]
+--
+
+[#ERC721EnumerableComponent-Embeddable-functions]
+==== Embeddable functions
+
+[.contract-item]
+[[ERC721EnumerableComponent-total_supply]]
+==== `[.contract-item-name]#++total_supply++#++(self: @ContractState) → u256++` [.item-kind]#external#
+
+Returns the current amount of votes that `account` has.
+
+[.contract-item]
+[[ERC721EnumerableComponent-token_by_index]]
+==== `[.contract-item-name]#++token_by_index++#++(self: @ContractState, index: u256) → u256++` [.item-kind]#external#
+
+See xref:#IERC721Enumerable-token_by_index[IERC721Enumerable::token_by_index].
+
+Requirements:
+
+- `index` is less than the total token supply.
+
+[.contract-item]
+[[ERC721EnumerableComponent-token_of_owner_by_index]]
+==== `[.contract-item-name]#++token_of_owner_by_index++#++(self: @ContractState, owner: ContractAddress, index: u256) → u256++` [.item-kind]#external#
+
+See xref:#IERC721Enumerable-token_of_owner_by_index[IERC721Enumerable::token_of_owner_by_index].
+
+Requirements:
+
+- `index` is less than ``owner``'s token balance.
+- `owner` is not the zero address.
+
+[#ERC721EnumerableComponent-Internal-functions]
+==== Internal functions
+
+[.contract-item]
+[[ERC721EnumerableComponent-initializer]]
+==== `[.contract-item-name]#++initializer++#++(ref self: ContractState)++` [.item-kind]#internal#
+
+Registers the `IERC721Enumerable` interface ID as supported through introspection.
+
+[.contract-item]
+[[ERC721EnumerableComponent-before_update]]
+==== `[.contract-item-name]#++before_update++#++(ref self: ContractState, to: ContractAddress, token_id: u256)++` [.item-kind]#internal#
+
+Updates the ownership and token-tracking data structures.
+
+When a token is minted (or burned), `token_id` is added to (or removed from) the token-tracking structures.
+
+When a token is transferred, minted, or burned, the ownership-tracking data structures reflect the change in ownership of `token_id`.
+
+This must be added to the implementing contract's xref:ERC721Component-before_update[ERC721HooksTrait::before_update] hook.
+
+[.contract-item]
+[[ERC721EnumerableComponent-_add_token_to_owner_enumeration]]
+==== `[.contract-item-name]#++_add_token_to_owner_enumeration++#++(ref self: ContractState, to: ContractAddress, token_id: u256)++` [.item-kind]#private#
+
+Adds token to this extension's ownership-tracking data structures.
+
+[.contract-item]
+[[ERC721EnumerableComponent-_add_token_to_all_tokens_enumeration]]
+==== `[.contract-item-name]#++_add_token_to_all_tokens_enumeration++#++(ref self: ContractState, token_id: u256)++` [.item-kind]#private#
+
+Adds token to this extension's token-tracking data structures.
+
+[.contract-item]
+[[ERC721EnumerableComponent-_remove_token_from_owner_enumeration]]
+==== `[.contract-item-name]#++_remove_token_from_owner_enumeration++#++(ref self: ContractState, from: ContractAddress, token_id: u256)++` [.item-kind]#private#
+
+Removes a token from this extension's ownership-tracking data structures.
+
+This has 0(1) time complexity but alters the indexed order of owned tokens by swapping `token_id` and the index thereof with the last token id and the index thereof e.g. removing `1` from `[1, 2, 3, 4]` results in `[4, 2, 3]`.
+
+[.contract-item]
+[[ERC721EnumerableComponent-_remove_token_from_all_tokens_enumeration]]
+==== `[.contract-item-name]#++_remove_token_from_all_tokens_enumeration++#++(ref self: ContractState, token_id: u256)++` [.item-kind]#private#
+
+Removes `token_id` from this extension's token-tracking data structures.
+
+This has 0(1) time complexity but alters the indexed order by swapping `token_id` and the index thereof with the last token id and the index thereof e.g. removing `1` from `[1, 2, 3, 4]` results in `[4, 2, 3]`.
+
 == Receiver
 
 [.contract]

packages/access/src/accesscontrol/accesscontrol.cairo

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Contracts for Cairo v0.12.0 (access/accesscontrol/accesscontrol.cairo)
+// OpenZeppelin Contracts for Cairo v0.15.0-rc.0 (access/accesscontrol/accesscontrol.cairo)
 
 /// # AccessControl Component
 ///

packages/token/src/erc721.cairo

@@ -2,6 +2,7 @@ pub mod dual721;
 pub mod dual721_receiver;
 pub mod erc721;
 pub mod erc721_receiver;
+pub mod extensions;
 pub mod interface;
 
 pub use erc721::ERC721Component;

packages/token/src/erc721/extensions.cairo

@@ -0,0 +1,3 @@
+pub mod erc721_enumerable;
+
+pub use erc721_enumerable::ERC721EnumerableComponent;

packages/token/src/erc721/extensions/erc721_enumerable.cairo

@@ -0,0 +1,4 @@
+pub mod erc721_enumerable;
+pub mod interface;
+
+pub use erc721_enumerable::ERC721EnumerableComponent;