ERC721 URI Storage

CHANGELOG.md

@@ -10,7 +10,8 @@
 
 ### Added
 
+<<<<<<< HEAD
 - TimelockController component (#996)
 - HashCall implementation (#996)
 - Separated package for each submodule (#1065)
  - `openzeppelin_access`
@@ -22,6 +23,9 @@
  - `openzeppelin_token`
  - `openzeppelin_upgrades`
  - `openzeppelin_utils`
+=======
+- ERC721URIStorage (#1031)
+>>>>>>> e4e7368 (updated cairo version)
 
 ### Changed
 

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

@@ -689,6 +689,102 @@ See <<IERC721-ApprovalForAll,IERC721::ApprovalForAll>>.
 
 See <<IERC721-Transfer,IERC721::Transfer>>.
 
+== Extensions
+
+[.contract]
+[[ERC721URIStorageComponent]]
+=== `++ERC721URIStorageComponent++` link:https://github.com/OpenZeppelin/cairo-contracts/blob/release-v0.15.0-rc.0/src/token/erc721/extensions/erc721_uri_storage.cairo[{github-icon},role=heading-link]
+
+```cairo
+use openzeppelin::token::extensions::ERC721URIStorageComponent;
+```
+
+:MetadataUpdated: xref:ERC721URIStorageComponent-MetadataUpdated[MetadataUpdated]
+
+Extension of ERC721 to support storage-based URI management.
+It is an implementation of <<IERC721Metadata, IERC721Metadata>> but with a different `token_uri` behavior.
+
+NOTE: Implementing xref:#ERC721Component[ERC721Component] is a requirement for this component to be implemented.
+
+The ERC721URIStorage component provides a flexible IERC721Metadata implementation that enables storage-based token URI management.
+The URI of any `token_id` can be set by calling the internal function, xref:#ERC721URIStorageComponent-set_token_uri[set_token_uri].
+The updated URI can be queried through the external function xref:#ERC721URIStorageComponent-token_uri[token_uri].
+
+[.contract-index#ERC721URIStorageComponent-Embeddable-Impls]
+.Embeddable Implementations
+--
+[.sub-index#ERC721URIStorageComponent-Embeddable-Impls-ERC721URIStorageImpl]
+.ERC721URIStorageImpl
+* xref:#ERC721URIStorageComponent-name[`++name(self)++`]
+* xref:#ERC721URIStorageComponent-symbol[`++symbol(self)++`]
+* xref:#ERC721URIStorageComponent-token_uri[`++token_uri(self, token_id)++`]
+
+--
+
+[.contract-index]
+.Internal implementations
+--
+.InternalImpl
+* xref:#ERC721URIStorageComponent-set_token_uri[`++set_token_uri(self, token_id, token_uri)++`]
+
+--
+
+[.contract-index]
+.Events
+--
+* xref:#ERC721URIStorageComponent-MetadataUpdated[`++MetadataUpdated(token_id)++`]
+--
+
+[#ERC721URIStorageComponent-Embeddable-functions]
+==== Embeddable functions
+
+[.contract-item]
+[[ERC721URIStorageComponent-name]]
+==== `[.contract-item-name]#++name++#++(self: @ContractState) → ByteArray++` [.item-kind]#external#
+
+See <<IERC721Metadata-name,IERC721::name>>.
+
+[.contract-item]
+[[ERC721URIStorageComponent-symbol]]
+==== `[.contract-item-name]#++symbol++#++(self: @ContractState) → ByteArray++` [.item-kind]#external#
+
+See <<IERC721Metadata-symbol,IERC721::symbol>>.
+
+[.contract-item]
+[[ERC721URIStorageComponent-token_uri]]
+==== `[.contract-item-name]#++token_uri++#++(self: @ContractState, token_id : u256) → ByteArray++` [.item-kind]#external#
+
+Returns the Uniform Resource Identifier (URI) for the `token_id` token.
+
+
+If a base URI is set and the token URI is set, the resulting URI for each token will be the concatenation of the base URI and the token URI. 
+
+If a base URI is set and the token URI is not set, the resulting URI for each token will be the concatenation of the base URI and the `token_id`. 
+
+If a base URI is not set and the token URI is set, the resulting URI for each token will be the token URI. 
+
+If the base URI and token URI are not set for `token_id`, the return value will be an empty `ByteArray`.
+
+[#ERC721URIStorageComponent-Internal-functions]
+==== Internal functions
+
+[.contract-item]
+[[ERC721URIStorageComponent-set_token_uri]]
+==== `[.contract-item-name]#++set_token_uri++#++(ref self: ContractState, token_id: u256, token_uri: ByteArray)++` [.item-kind]#internal#
+
+Sets the `token_uri` of `token_id`.
+
+Emits a {MetadataUpdated} event.
+
+[#ERC721URIStorageComponent-Events]
+==== Events
+
+[.contract-item]
+[[ERC721URIStorageComponent-MetadataUpdated]]
+==== `[.contract-item-name]#++MetadataUpdated++#++(token_id: u256)++` [.item-kind]#event#
+
+Emitted when the URI of `token_id` is set.
+
 == Receiver
 
 [.contract]

packages/presets/src/tests/mocks.cairo

@@ -4,6 +4,7 @@ pub(crate) mod erc1155_receiver_mocks;
 pub(crate) mod erc20_mocks;
 pub(crate) mod erc721_mocks;
 pub(crate) mod erc721_receiver_mocks;
+pub(crate) mod erc721_uri_storage_mocks;
 pub(crate) mod eth_account_mocks;
 pub(crate) mod non_implementing_mock;
 pub(crate) mod src5_mocks;

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_uri_storage;
+
+pub use erc721_uri_storage::ERC721URIStorageComponent;

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

@@ -0,0 +1,103 @@
+// SPDX-License-Identifier: MIT
+// OpenZeppelin Contracts for Cairo v0.15.0-rc.0 (token/erc721/extensions/erc721_uri_storage.cairo)
+
+/// # ERC721URIStorage Component
+///
+/// The ERC721URIStorage component provides a flexible IERC721Metadata implementation that enables
+/// storage-based token URI management.
+#[starknet::component]
+pub mod ERC721URIStorageComponent {
+ use openzeppelin::introspection::src5::SRC5Component;
+ use openzeppelin::token::erc721::ERC721Component::InternalImpl as ERC721Impl;
+ use openzeppelin::token::erc721::interface::IERC721Metadata;
+ use openzeppelin::token::erc721::{ERC721Component, ERC721HooksEmptyImpl};
+ use starknet::ContractAddress;
+ use starknet::storage::Map;
+
+ #[storage]
+ struct Storage {
+ ERC721URIStorage_token_uris: Map<u256, ByteArray>,
+ }
+
+ #[event]
+ #[derive(Drop, PartialEq, starknet::Event)]
+ pub enum Event {
+ MetadataUpdated: MetadataUpdated,
+ }
+
+ /// Emitted when `token_uri` is changed for `token_id`.
+ #[derive(Drop, PartialEq, starknet::Event)]
+ pub struct MetadataUpdated {
+ pub token_id: u256,
+ }
+
+ #[embeddable_as(ERC721URIStorageImpl)]
+ impl ERC721URIStorage<
+ TContractState,
+ +HasComponent<TContractState>,
+ +SRC5Component::HasComponent<TContractState>,
+ impl ERC721: ERC721Component::HasComponent<TContractState>,
+ +Drop<TContractState>
+ > of IERC721Metadata<ComponentState<TContractState>> {
+ /// Returns the NFT name.
+ fn name(self: @ComponentState<TContractState>) -> ByteArray {
+ let erc721_component = get_dep_component!(self, ERC721);
+ erc721_component.ERC721_name.read()
+ }
+
+ /// Returns the NFT symbol.
+ fn symbol(self: @ComponentState<TContractState>) -> ByteArray {
+ let erc721_component = get_dep_component!(self, ERC721);
+ erc721_component.ERC721_symbol.read()
+ }
+
+
+ /// Returns the Uniform Resource Identifier (URI) for the `token_id` token.
+ ///
+ /// Requirements:
+ ///
+ /// - `token_id` exists.
+ fn token_uri(self: @ComponentState<TContractState>, token_id: u256) -> ByteArray {
+ let mut erc721_component = get_dep_component!(self, ERC721);
+ erc721_component._require_owned(token_id);
+ let base_uri: ByteArray = ERC721Impl::_base_uri(erc721_component);
+ let token_uri: ByteArray = self.ERC721URIStorage_token_uris.read(token_id);
+
+ // If there is no base_uri, return the token_uri
+ if base_uri.len() == 0 {
+ return token_uri;
+ }
+
+ // If both are set, concatenate the base_uri and token_uri
+ if token_uri.len() > 0 {
+ return format!("{}{}", base_uri, token_uri);
+ }
+
+ // Implementation from ERC721Metadata::token_uri
+ return format!("{}{}", base_uri, token_id);
+ }
+ }
+
+ //
+ // Internal
+ //
+
+ #[generate_trait]
+ pub impl InternalImpl<
+ TContractState,
+ +HasComponent<TContractState>,
+ +SRC5Component::HasComponent<TContractState>,
+ +ERC721Component::HasComponent<TContractState>,
+ +Drop<TContractState>
+ > of InternalTrait<TContractState> {
+ /// Sets or updates the `token_uri` for the respective `token_id`.
+ ///
+ /// Emits `MetadataUpdated` event.
+ fn set_token_uri(
+ ref self: ComponentState<TContractState>, token_id: u256, token_uri: ByteArray
+ ) {
+ self.ERC721URIStorage_token_uris.write(token_id, token_uri);
+ self.emit(MetadataUpdated { token_id: token_id });
+ }
+ }
+}

packages/token/src/tests/erc721/test_erc721_uri_storage.cairo

@@ -0,0 +1,153 @@
+use openzeppelin::tests::mocks::erc721_uri_storage_mocks::ERC721URIStorageMock;
+use openzeppelin::tests::utils::constants::{
+ ZERO, OWNER, RECIPIENT, NAME, SYMBOL, TOKEN_ID, TOKEN_ID_2, BASE_URI, BASE_URI_2, SAMPLE_URI
+};
+use openzeppelin::tests::utils;
+use openzeppelin::token::erc721::ERC721Component::InternalImpl as ERC721InternalImpl;
+use openzeppelin::token::erc721::extensions::ERC721URIStorageComponent::{
+ ERC721URIStorageImpl, InternalImpl
+};
+use openzeppelin::token::erc721::extensions::ERC721URIStorageComponent;
+use openzeppelin::token::erc721::extensions::erc721_uri_storage::ERC721URIStorageComponent::MetadataUpdated;
+use openzeppelin::utils::serde::SerializedAppend;
+use starknet::ContractAddress;
+
+
+//
+// Setup
+//
+
+type ComponentState =
+ ERC721URIStorageComponent::ComponentState<ERC721URIStorageMock::ContractState>;
+
+fn CONTRACT_STATE() -> ERC721URIStorageMock::ContractState {
+ ERC721URIStorageMock::contract_state_for_testing()
+}
+fn COMPONENT_STATE() -> ComponentState {
+ ERC721URIStorageComponent::component_state_for_testing()
+}
+
+fn setup() -> ComponentState {
+ let mut state = COMPONENT_STATE();
+ let mut mock_state = CONTRACT_STATE();
+ mock_state.erc721.initializer(NAME(), SYMBOL(), "");
+ mock_state.erc721.mint(OWNER(), TOKEN_ID);
+ utils::drop_event(ZERO());
+ state
+}
+
+#[test]
+fn test_token_uri_when_not_set() {
+ let state = setup();
+ let uri = state.token_uri(TOKEN_ID);
+ let empty = 0;
+ assert_eq!(uri.len(), empty);
+}
+
+#[test]
+#[should_panic(expected: ('ERC721: invalid token ID',))]
+fn test_token_uri_non_minted() {
+ let state = setup();
+ state.token_uri(TOKEN_ID_2);
+}
+
+#[test]
+fn test_set_token_uri() {
+ let mut state = setup();
+
+ state.set_token_uri(TOKEN_ID, SAMPLE_URI());
+ assert_only_event_metadata_update(ZERO(), TOKEN_ID);
+
+ let expected = SAMPLE_URI();
+ let uri = state.token_uri(TOKEN_ID);
+
+ assert_eq!(uri, expected);
+}
+
+#[test]
+fn test_set_token_uri_nonexistent() {
+ let mut state = setup();
+
+ state.set_token_uri(TOKEN_ID_2, SAMPLE_URI());
+ assert_only_event_metadata_update(ZERO(), TOKEN_ID_2);
+
+ let mut mock_contract_state = CONTRACT_STATE();
+ // Check that the URI is accessible after minting
+ mock_contract_state.erc721.mint(RECIPIENT(), TOKEN_ID_2);
+
+ let expected = SAMPLE_URI();
+ let uri = state.token_uri(TOKEN_ID_2);
+
+ assert_eq!(uri, expected);
+}
+
+#[test]
+fn test_token_uri_with_base_uri() {
+ let mut state = setup();
+
+ let mut mock_contract_state = CONTRACT_STATE();
+ mock_contract_state.erc721._set_base_uri(BASE_URI());
+ state.set_token_uri(TOKEN_ID, SAMPLE_URI());
+
+ let token_uri = state.token_uri(TOKEN_ID);
+ let expected = format!("{}{}", BASE_URI(), SAMPLE_URI());
+ assert_eq!(token_uri, expected);
+}
+
+#[test]
+fn test_base_uri_2_is_set_as_prefix() {
+ let mut state = setup();
+
+ let mut mock_contract_state = CONTRACT_STATE();
+ mock_contract_state.erc721._set_base_uri(BASE_URI());
+ state.set_token_uri(TOKEN_ID, SAMPLE_URI());
+
+ mock_contract_state.erc721._set_base_uri(BASE_URI_2());
+
+ let token_uri = state.token_uri(TOKEN_ID);
+ let expected = format!("{}{}", BASE_URI_2(), SAMPLE_URI());
+ assert_eq!(token_uri, expected);
+}
+
+#[test]
+fn test_token_uri_with_base_uri_and_token_id() {
+ let mut state = setup();
+
+ let mut mock_contract_state = CONTRACT_STATE();
+ mock_contract_state.erc721._set_base_uri(BASE_URI());
+
+ let token_uri = state.token_uri(TOKEN_ID);
+ let expected = format!("{}{}", BASE_URI(), TOKEN_ID);
+ assert_eq!(token_uri, expected);
+}
+
+#[test]
+fn test_token_uri_persists_when_burned_and_minted() {
+ let mut state = setup();
+
+ state.set_token_uri(TOKEN_ID, SAMPLE_URI());
+
+ let mut mock_contract_state = CONTRACT_STATE();
+ mock_contract_state.erc721.burn(TOKEN_ID);
+
+ mock_contract_state.erc721.mint(OWNER(), TOKEN_ID);
+
+ let token_uri = state.token_uri(TOKEN_ID);
+ let expected = SAMPLE_URI();
+ assert_eq!(token_uri, expected);
+}
+
+//
+// Helpers
+//
+
+fn assert_event_metadata_update(contract: ContractAddress, token_id: u256) {
+ let event = utils::pop_log::<ERC721URIStorageComponent::Event>(contract).unwrap();
+ let expected = ERC721URIStorageComponent::Event::MetadataUpdated(MetadataUpdated { token_id });
+ assert!(event == expected);
+}
+
+fn assert_only_event_metadata_update(contract: ContractAddress, token_id: u256) {
+ assert_event_metadata_update(contract, token_id);
+ utils::assert_no_events_left(contract);
+}