difftreelog
Merge pull request #442 from UniqueNetwork/doc/nonfungible-pallet
in: master
6 files changed
pallets/nonfungible/src/common.rsdiffbeforeafterboth--- a/pallets/nonfungible/src/common.rs
+++ b/pallets/nonfungible/src/common.rs
@@ -133,6 +133,8 @@
}
}
+/// Implementation of `CommonCollectionOperations` for `NonfungibleHandle`. It wraps Nonfungible Pallete
+/// methods and adds weight info.
impl<T: Config> CommonCollectionOperations<T> for NonfungibleHandle<T> {
fn create_item(
&self,
pallets/nonfungible/src/erc.rsdiffbeforeafterboth--- a/pallets/nonfungible/src/erc.rs
+++ b/pallets/nonfungible/src/erc.rs
@@ -14,6 +14,11 @@
// You should have received a copy of the GNU General Public License
// along with Unique Network. If not, see <http://www.gnu.org/licenses/>.
+//! # Nonfungible Pallet EVM API
+//!
+//! Provides ERC-721 standart support implementation and EVM API for unique extensions for Nonfungible Pallet.
+//! Method implementations are mostly doing parameter conversion and calling Nonfungible Pallet methods.
+
extern crate alloc;
use core::{
char::{REPLACEMENT_CHARACTER, decode_utf16},
@@ -40,8 +45,15 @@
SelfWeightOf, weights::WeightInfo, TokenProperties,
};
+/// @title A contract that allows to set and delete token properties and change token property permissions.
#[solidity_interface(name = "TokenProperties")]
impl<T: Config> NonfungibleHandle<T> {
+ /// @notice Set permissions for token property.
+ /// @dev Throws error if `msg.sender` is not admin or owner of the collection.
+ /// @param key Property key.
+ /// @param is_mutable Permission to mutate property.
+ /// @param collection_admin Permission to mutate property by collection admin if property is mutable.
+ /// @param token_owner Permission to mutate property by token owner if property is mutable.
fn set_token_property_permission(
&mut self,
caller: caller,
@@ -68,6 +80,11 @@
.map_err(dispatch_to_evm::<T>)
}
+ /// @notice Set token property value.
+ /// @dev Throws error if `msg.sender` has no permission to edit the property.
+ /// @param tokenId ID of the token.
+ /// @param key Property key.
+ /// @param value Property value.
fn set_property(
&mut self,
caller: caller,
@@ -96,6 +113,10 @@
.map_err(dispatch_to_evm::<T>)
}
+ /// @notice Delete token property value.
+ /// @dev Throws error if `msg.sender` has no permission to edit the property.
+ /// @param tokenId ID of the token.
+ /// @param key Property key.
fn delete_property(&mut self, token_id: uint256, caller: caller, key: string) -> Result<()> {
let caller = T::CrossAccountId::from_eth(caller);
let token_id: u32 = token_id.try_into().map_err(|_| "token id overflow")?;
@@ -111,7 +132,11 @@
.map_err(dispatch_to_evm::<T>)
}
- /// Throws error if key not found
+ /// @notice Get token property value.
+ /// @dev Throws error if key not found
+ /// @param tokenId ID of the token.
+ /// @param key Property key.
+ /// @return Property value bytes
fn property(&self, token_id: uint256, key: string) -> Result<bytes> {
let token_id: u32 = token_id.try_into().map_err(|_| "token id overflow")?;
let key = <Vec<u8>>::from(key)
@@ -127,6 +152,11 @@
#[derive(ToLog)]
pub enum ERC721Events {
+ /// @dev This emits when ownership of any NFT changes by any mechanism.
+ /// This event emits when NFTs are created (`from` == 0) and destroyed
+ /// (`to` == 0). Exception: during contract creation, any number of NFTs
+ /// may be created and assigned without emitting Transfer. At the time of
+ /// any transfer, the approved address for that NFT (if any) is reset to none.
Transfer {
#[indexed]
from: address,
@@ -135,6 +165,10 @@
#[indexed]
token_id: uint256,
},
+ /// @dev This emits when the approved address for an NFT is changed or
+ /// reaffirmed. The zero address indicates there is no approved address.
+ /// When a Transfer event emits, this also indicates that the approved
+ /// address for that NFT (if any) is reset to none.
Approval {
#[indexed]
owner: address,
@@ -143,6 +177,8 @@
#[indexed]
token_id: uint256,
},
+ /// @dev This emits when an operator is enabled or disabled for an owner.
+ /// The operator can manage all NFTs of the owner.
#[allow(dead_code)]
ApprovalForAll {
#[indexed]
@@ -159,19 +195,27 @@
MintingFinished {},
}
+/// @title ERC-721 Non-Fungible Token Standard, optional metadata extension
+/// @dev See https://eips.ethereum.org/EIPS/eip-721
#[solidity_interface(name = "ERC721Metadata")]
impl<T: Config> NonfungibleHandle<T> {
+ /// @notice A descriptive name for a collection of NFTs in this contract
fn name(&self) -> Result<string> {
Ok(decode_utf16(self.name.iter().copied())
.map(|r| r.unwrap_or(REPLACEMENT_CHARACTER))
.collect::<string>())
}
+ /// @notice An abbreviated name for NFTs in this contract
fn symbol(&self) -> Result<string> {
Ok(string::from_utf8_lossy(&self.token_prefix).into())
}
- /// Returns token's const_metadata
+ /// @notice A distinct Uniform Resource Identifier (URI) for a given asset.
+ /// @dev Throws if `tokenId` is not a valid NFT. URIs are defined in RFC
+ /// 3986. The URI may point to a JSON file that conforms to the "ERC721
+ /// Metadata JSON Schema".
+ /// @return token's const_metadata
#[solidity(rename_selector = "tokenURI")]
fn token_uri(&self, token_id: uint256) -> Result<string> {
let key = token_uri_key();
@@ -192,32 +236,53 @@
}
}
+/// @title ERC-721 Non-Fungible Token Standard, optional enumeration extension
+/// @dev See https://eips.ethereum.org/EIPS/eip-721
#[solidity_interface(name = "ERC721Enumerable")]
impl<T: Config> NonfungibleHandle<T> {
+ /// @notice Enumerate valid NFTs
+ /// @param index A counter less than `totalSupply()`
+ /// @return The token identifier for the `index`th NFT,
+ /// (sort order not specified)
fn token_by_index(&self, index: uint256) -> Result<uint256> {
Ok(index)
}
- /// Not implemented
+ /// @dev Not implemented
fn token_of_owner_by_index(&self, _owner: address, _index: uint256) -> Result<uint256> {
// TODO: Not implemetable
Err("not implemented".into())
}
+ /// @notice Count NFTs tracked by this contract
+ /// @return A count of valid NFTs tracked by this contract, where each one of
+ /// them has an assigned and queryable owner not equal to the zero address
fn total_supply(&self) -> Result<uint256> {
self.consume_store_reads(1)?;
Ok(<Pallet<T>>::total_supply(self).into())
}
}
+/// @title ERC-721 Non-Fungible Token Standard
+/// @dev See https://github.com/ethereum/EIPs/blob/master/EIPS/eip-721.md
#[solidity_interface(name = "ERC721", events(ERC721Events))]
impl<T: Config> NonfungibleHandle<T> {
+ /// @notice Count all NFTs assigned to an owner
+ /// @dev NFTs assigned to the zero address are considered invalid, and this
+ /// function throws for queries about the zero address.
+ /// @param owner An address for whom to query the balance
+ /// @return The number of NFTs owned by `owner`, possibly zero
fn balance_of(&self, owner: address) -> Result<uint256> {
self.consume_store_reads(1)?;
let owner = T::CrossAccountId::from_eth(owner);
let balance = <AccountBalance<T>>::get((self.id, owner));
Ok(balance.into())
}
+ /// @notice Find the owner of an NFT
+ /// @dev NFTs assigned to zero address are considered invalid, and queries
+ /// about them do throw.
+ /// @param tokenId The identifier for an NFT
+ /// @return The address of the owner of the NFT
fn owner_of(&self, token_id: uint256) -> Result<address> {
self.consume_store_reads(1)?;
let token: TokenId = token_id.try_into()?;
@@ -226,7 +291,7 @@
.owner
.as_eth())
}
- /// Not implemented
+ /// @dev Not implemented
fn safe_transfer_from_with_data(
&mut self,
_from: address,
@@ -238,7 +303,7 @@
// TODO: Not implemetable
Err("not implemented".into())
}
- /// Not implemented
+ /// @dev Not implemented
fn safe_transfer_from(
&mut self,
_from: address,
@@ -250,6 +315,16 @@
Err("not implemented".into())
}
+ /// @notice Transfer ownership of an NFT -- THE CALLER IS RESPONSIBLE
+ /// TO CONFIRM THAT `to` IS CAPABLE OF RECEIVING NFTS OR ELSE
+ /// THEY MAY BE PERMANENTLY LOST
+ /// @dev Throws unless `msg.sender` is the current owner or an authorized
+ /// operator for this NFT. Throws if `from` is not the current owner. Throws
+ /// if `to` is the zero address. Throws if `tokenId` is not a valid NFT.
+ /// @param from The current owner of the NFT
+ /// @param to The new owner
+ /// @param tokenId The NFT to transfer
+ /// @param _value Not used for an NFT
#[weight(<SelfWeightOf<T>>::transfer_from())]
fn transfer_from(
&mut self,
@@ -272,6 +347,12 @@
Ok(())
}
+ /// @notice Set or reaffirm the approved address for an NFT
+ /// @dev The zero address indicates there is no approved address.
+ /// @dev Throws unless `msg.sender` is the current NFT owner, or an authorized
+ /// operator of the current owner.
+ /// @param approved The new approved NFT controller
+ /// @param tokenId The NFT to approve
#[weight(<SelfWeightOf<T>>::approve())]
fn approve(
&mut self,
@@ -289,7 +370,7 @@
Ok(())
}
- /// Not implemented
+ /// @dev Not implemented
fn set_approval_for_all(
&mut self,
_caller: caller,
@@ -300,21 +381,26 @@
Err("not implemented".into())
}
- /// Not implemented
+ /// @dev Not implemented
fn get_approved(&self, _token_id: uint256) -> Result<address> {
// TODO: Not implemetable
Err("not implemented".into())
}
- /// Not implemented
+ /// @dev Not implemented
fn is_approved_for_all(&self, _owner: address, _operator: address) -> Result<address> {
// TODO: Not implemetable
Err("not implemented".into())
}
}
+/// @title ERC721 Token that can be irreversibly burned (destroyed).
#[solidity_interface(name = "ERC721Burnable")]
impl<T: Config> NonfungibleHandle<T> {
+ /// @notice Burns a specific ERC721 token.
+ /// @dev Throws unless `msg.sender` is the current NFT owner, or an authorized
+ /// operator of the current owner.
+ /// @param tokenId The NFT to approve
#[weight(<SelfWeightOf<T>>::burn_item())]
fn burn(&mut self, caller: caller, token_id: uint256) -> Result<void> {
let caller = T::CrossAccountId::from_eth(caller);
@@ -325,14 +411,18 @@
}
}
+/// @title ERC721 minting logic.
#[solidity_interface(name = "ERC721Mintable", events(ERC721MintableEvents))]
impl<T: Config> NonfungibleHandle<T> {
fn minting_finished(&self) -> Result<bool> {
Ok(false)
}
- /// `token_id` should be obtained with `next_token_id` method,
- /// unlike standard, you can't specify it manually
+ /// @notice Function to mint token.
+ /// @dev `tokenId` should be obtained with `nextTokenId` method,
+ /// unlike standard, you can't specify it manually
+ /// @param to The new owner
+ /// @param tokenId ID of the minted NFT
#[weight(<SelfWeightOf<T>>::create_item())]
fn mint(&mut self, caller: caller, to: address, token_id: uint256) -> Result<bool> {
let caller = T::CrossAccountId::from_eth(caller);
@@ -364,8 +454,12 @@
Ok(true)
}
- /// `token_id` should be obtained with `next_token_id` method,
- /// unlike standard, you can't specify it manually
+ /// @notice Function to mint token with the given tokenUri.
+ /// @dev `tokenId` should be obtained with `nextTokenId` method,
+ /// unlike standard, you can't specify it manually
+ /// @param to The new owner
+ /// @param tokenId ID of the minted NFT
+ /// @param tokenUri Token URI that would be stored in the NFT properties
#[solidity(rename_selector = "mintWithTokenURI")]
#[weight(<SelfWeightOf<T>>::create_item())]
fn mint_with_token_uri(
@@ -420,7 +514,7 @@
Ok(true)
}
- /// Not implemented
+ /// @dev Not implemented
fn finish_minting(&mut self, _caller: caller) -> Result<bool> {
Err("not implementable".into())
}
@@ -449,8 +543,15 @@
false
}
+/// @title Unique extensions for ERC721.
#[solidity_interface(name = "ERC721UniqueExtensions")]
impl<T: Config> NonfungibleHandle<T> {
+ /// @notice Transfer ownership of an NFT
+ /// @dev Throws unless `msg.sender` is the current owner. Throws if `to`
+ /// is the zero address. Throws if `tokenId` is not a valid NFT.
+ /// @param to The new owner
+ /// @param tokenId The NFT to transfer
+ /// @param _value Not used for an NFT
#[weight(<SelfWeightOf<T>>::transfer())]
fn transfer(
&mut self,
@@ -470,6 +571,13 @@
Ok(())
}
+ /// @notice Burns a specific ERC721 token.
+ /// @dev Throws unless `msg.sender` is the current owner or an authorized
+ /// operator for this NFT. Throws if `from` is not the current owner. Throws
+ /// if `to` is the zero address. Throws if `tokenId` is not a valid NFT.
+ /// @param from The current owner of the NFT
+ /// @param tokenId The NFT to transfer
+ /// @param _value Not used for an NFT
#[weight(<SelfWeightOf<T>>::burn_from())]
fn burn_from(
&mut self,
@@ -490,6 +598,7 @@
Ok(())
}
+ /// @notice Returns next free NFT ID.
fn next_token_id(&self) -> Result<uint256> {
self.consume_store_reads(1)?;
Ok(<TokensMinted<T>>::get(self.id)
@@ -498,6 +607,11 @@
.into())
}
+ /// @notice Function to mint multiple tokens.
+ /// @dev `tokenIds` should be an array of consecutive numbers and first number
+ /// should be obtained with `nextTokenId` method
+ /// @param to The new owner
+ /// @param tokenIds IDs of the minted NFTs
#[weight(<SelfWeightOf<T>>::create_multiple_items(token_ids.len() as u32))]
fn mint_bulk(&mut self, caller: caller, to: address, token_ids: Vec<uint256>) -> Result<bool> {
let caller = T::CrossAccountId::from_eth(caller);
@@ -529,6 +643,11 @@
Ok(true)
}
+ /// @notice Function to mint multiple tokens with the given tokenUris.
+ /// @dev `tokenIds` is array of pairs of token ID and token URI. Token IDs should be consecutive
+ /// numbers and first number should be obtained with `nextTokenId` method
+ /// @param to The new owner
+ /// @param tokens array of pairs of token ID and token URI for minted tokens
#[solidity(rename_selector = "mintBulkWithTokenURI")]
#[weight(<SelfWeightOf<T>>::create_multiple_items(tokens.len() as u32))]
fn mint_bulk_with_token_uri(
pallets/nonfungible/src/lib.rsdiffbeforeafterboth14// You should have received a copy of the GNU General Public License14// You should have received a copy of the GNU General Public License15// along with Unique Network. If not, see <http://www.gnu.org/licenses/>.15// along with Unique Network. If not, see <http://www.gnu.org/licenses/>.1617//! # Nonfungible Pallet18//!19//! The Nonfungible pallet provides functionality for handling nonfungible collections and tokens.20//!21//! - [`Config`]22//! - [`NonfungibleHandle`]23//! - [`Pallet`]24//! - [`CommonWeights`]25//!26//! ## Overview27//!28//! The Nonfungible pallet provides functions for:29//!30//! - NFT collection creation and removal31//! - Minting and burning of NFT tokens32//! - Retrieving account balances33//! - Transfering NFT tokens34//! - Setting and checking allowance for NFT tokens35//! - Setting properties and permissions for NFT collections and tokens36//! - Nesting and unnesting tokens37//!38//! ### Terminology39//!40//! - **NFT token:** Non fungible token.41//!42//! - **NFT Collection:** A collection of NFT tokens. All NFT tokens are part of a collection.43//! Each collection can define it's own properties, properties for it's tokens and set of permissions.44//!45//! - **Balance:** Number of NFT tokens owned by an account46//!47//! - **Allowance:** NFT tokens owned by one account that another account is allowed to make operations on48//!49//! - **Burning:** The process of “deleting” a token from a collection and from50//! an account balance of the owner.51//!52//! - **Nesting:** Setting up parent-child relationship between tokens. Nested tokens are inhereting53//! owner from their parent. There could be multiple levels of nesting. Token couldn't be nested in54//! it's child token i.e. parent-child relationship graph shouldn't have cycles.55//!56//! - **Properties:** Key-Values pairs. Token properties are attached to a token. Collection properties are57//! attached to a collection. Set of permissions could be defined for each property.58//!59//! ### Implementations60//!61//! The Nonfungible pallet provides implementations for the following traits. If these traits provide62//! the functionality that you need, then you can avoid coupling with the Nonfungible pallet.63//!64//! - [`CommonWeightInfo`](pallet_common::CommonWeightInfo): Functions for retrieval of transaction weight65//! - [`CommonCollectionOperations`](pallet_common::CommonCollectionOperations): Functions for dealing66//! with collections67//!68//! ## Interface69//!70//! ### Dispatchable Functions71//!72//! - `init_collection` - Create NFT collection. NFT collection can be configured to allow or deny access for73//! some accounts.74//! - `destroy_collection` - Destroy exising NFT collection. There should be no tokens in the collection.75//! - `burn` - Burn NFT token owned by account.76//! - `transfer` - Transfer NFT token. Transfers should be enabled for NFT collection.77//! Nests the NFT token if it is sent to another token.78//! - `create_item` - Mint NFT token in collection. Sender should have permission to mint tokens.79//! - `set_allowance` - Set allowance for another account.80//! - `set_token_property` - Set token property value.81//! - `delete_token_property` - Remove property from the token.82//! - `set_collection_properties` - Set collection properties.83//! - `delete_collection_properties` - Remove properties from the collection.84//! - `set_property_permission` - Set collection property permission.85//! - `set_token_property_permissions` - Set token property permissions.86//!87//! ## Assumptions88//!89//! * To perform operations on tokens sender should be in collection's allow list if collection access mode is `AllowList`.169017#![cfg_attr(not(feature = "std"), no_std)]91#![cfg_attr(not(feature = "std"), no_std)]1892102 #[pallet::generate_store(pub(super) trait Store)]176 #[pallet::generate_store(pub(super) trait Store)]103 pub struct Pallet<T>(_);177 pub struct Pallet<T>(_);104178179 /// Amount of tokens minted for collection.105 #[pallet::storage]180 #[pallet::storage]106 pub type TokensMinted<T: Config> =181 pub type TokensMinted<T: Config> =107 StorageMap<Hasher = Twox64Concat, Key = CollectionId, Value = u32, QueryKind = ValueQuery>;182 StorageMap<Hasher = Twox64Concat, Key = CollectionId, Value = u32, QueryKind = ValueQuery>;183184 /// Amount of burnt tokens for collection.108 #[pallet::storage]185 #[pallet::storage]109 pub type TokensBurnt<T: Config> =186 pub type TokensBurnt<T: Config> =110 StorageMap<Hasher = Twox64Concat, Key = CollectionId, Value = u32, QueryKind = ValueQuery>;187 StorageMap<Hasher = Twox64Concat, Key = CollectionId, Value = u32, QueryKind = ValueQuery>;111188189 /// Custom data serialized to bytes for token.112 #[pallet::storage]190 #[pallet::storage]113 pub type TokenData<T: Config> = StorageNMap<191 pub type TokenData<T: Config> = StorageNMap<114 Key = (Key<Twox64Concat, CollectionId>, Key<Twox64Concat, TokenId>),192 Key = (Key<Twox64Concat, CollectionId>, Key<Twox64Concat, TokenId>),115 Value = ItemData<T::CrossAccountId>,193 Value = ItemData<T::CrossAccountId>,116 QueryKind = OptionQuery,194 QueryKind = OptionQuery,117 >;195 >;118196197 /// Key-Value map stored for token.119 #[pallet::storage]198 #[pallet::storage]120 #[pallet::getter(fn token_properties)]199 #[pallet::getter(fn token_properties)]121 pub type TokenProperties<T: Config> = StorageNMap<200 pub type TokenProperties<T: Config> = StorageNMap<125 OnEmpty = up_data_structs::TokenProperties,204 OnEmpty = up_data_structs::TokenProperties,126 >;205 >;127206207 /// Custom data that is serialized to bytes and attached to a token property.208 /// Currently used to store RMRK data.128 #[pallet::storage]209 #[pallet::storage]129 #[pallet::getter(fn token_aux_property)]210 #[pallet::getter(fn token_aux_property)]130 pub type TokenAuxProperties<T: Config> = StorageNMap<211 pub type TokenAuxProperties<T: Config> = StorageNMap<138 QueryKind = OptionQuery,219 QueryKind = OptionQuery,139 >;220 >;140221141 /// Used to enumerate tokens owned by account222 /// Used to enumerate tokens owned by account.142 #[pallet::storage]223 #[pallet::storage]143 pub type Owned<T: Config> = StorageNMap<224 pub type Owned<T: Config> = StorageNMap<144 Key = (225 Key = (150 QueryKind = ValueQuery,231 QueryKind = ValueQuery,151 >;232 >;152233153 /// Used to enumerate token's children234 /// Used to enumerate token's children.154 #[pallet::storage]235 #[pallet::storage]155 #[pallet::getter(fn token_children)]236 #[pallet::getter(fn token_children)]156 pub type TokenChildren<T: Config> = StorageNMap<237 pub type TokenChildren<T: Config> = StorageNMap<163 QueryKind = ValueQuery,244 QueryKind = ValueQuery,164 >;245 >;165246247 /// Amount of tokens owned by account.166 #[pallet::storage]248 #[pallet::storage]167 pub type AccountBalance<T: Config> = StorageNMap<249 pub type AccountBalance<T: Config> = StorageNMap<168 Key = (250 Key = (173 QueryKind = ValueQuery,255 QueryKind = ValueQuery,174 >;256 >;175257258 /// Allowance set by an owner for a spender for a token.176 #[pallet::storage]259 #[pallet::storage]177 pub type Allowance<T: Config> = StorageNMap<260 pub type Allowance<T: Config> = StorageNMap<178 Key = (Key<Twox64Concat, CollectionId>, Key<Twox64Concat, TokenId>),261 Key = (Key<Twox64Concat, CollectionId>, Key<Twox64Concat, TokenId>),273}356}274357275impl<T: Config> Pallet<T> {358impl<T: Config> Pallet<T> {359 /// Get number of NFT tokens in collection.276 pub fn total_supply(collection: &NonfungibleHandle<T>) -> u32 {360 pub fn total_supply(collection: &NonfungibleHandle<T>) -> u32 {277 <TokensMinted<T>>::get(collection.id) - <TokensBurnt<T>>::get(collection.id)361 <TokensMinted<T>>::get(collection.id) - <TokensBurnt<T>>::get(collection.id)278 }362 }363364 /// Check that NFT token exists.365 ///366 /// - `token`: Token ID.279 pub fn token_exists(collection: &NonfungibleHandle<T>, token: TokenId) -> bool {367 pub fn token_exists(collection: &NonfungibleHandle<T>, token: TokenId) -> bool {280 <TokenData<T>>::contains_key((collection.id, token))368 <TokenData<T>>::contains_key((collection.id, token))281 }369 }282370371 /// Set the token property with the scope.372 ///373 /// - `property`: Contains key-value pair.283 pub fn set_scoped_token_property(374 pub fn set_scoped_token_property(284 collection_id: CollectionId,375 collection_id: CollectionId,285 token_id: TokenId,376 token_id: TokenId,294 Ok(())385 Ok(())295 }386 }296387388 /// Batch operation to set multiple properties with the same scope.297 pub fn set_scoped_token_properties(389 pub fn set_scoped_token_properties(298 collection_id: CollectionId,390 collection_id: CollectionId,299 token_id: TokenId,391 token_id: TokenId,308 Ok(())400 Ok(())309 }401 }310402403 /// Add or edit auxiliary data for the property.404 ///405 /// - `f`: function that adds or edits auxiliary data.311 pub fn try_mutate_token_aux_property<R, E>(406 pub fn try_mutate_token_aux_property<R, E>(312 collection_id: CollectionId,407 collection_id: CollectionId,313 token_id: TokenId,408 token_id: TokenId,318 <TokenAuxProperties<T>>::try_mutate((collection_id, token_id, scope, key), f)413 <TokenAuxProperties<T>>::try_mutate((collection_id, token_id, scope, key), f)319 }414 }320415416 /// Remove auxiliary data for the property.321 pub fn remove_token_aux_property(417 pub fn remove_token_aux_property(322 collection_id: CollectionId,418 collection_id: CollectionId,323 token_id: TokenId,419 token_id: TokenId,327 <TokenAuxProperties<T>>::remove((collection_id, token_id, scope, key));423 <TokenAuxProperties<T>>::remove((collection_id, token_id, scope, key));328 }424 }329425426 /// Get all auxiliary data in a given scope.427 ///428 /// Returns iterator over Property Key - Data pairs.330 pub fn iterate_token_aux_properties(429 pub fn iterate_token_aux_properties(331 collection_id: CollectionId,430 collection_id: CollectionId,332 token_id: TokenId,431 token_id: TokenId,335 <TokenAuxProperties<T>>::iter_prefix((collection_id, token_id, scope))434 <TokenAuxProperties<T>>::iter_prefix((collection_id, token_id, scope))336 }435 }337436437 /// Get ID of the last minted token338 pub fn current_token_id(collection_id: CollectionId) -> TokenId {438 pub fn current_token_id(collection_id: CollectionId) -> TokenId {339 TokenId(<TokensMinted<T>>::get(collection_id))439 TokenId(<TokensMinted<T>>::get(collection_id))340 }440 }341}441}342442343// unchecked calls skips any permission checks443// unchecked calls skips any permission checks344impl<T: Config> Pallet<T> {444impl<T: Config> Pallet<T> {445 /// Create NFT collection446 ///447 /// `init_collection` will take non-refundable deposit for collection creation.448 ///449 /// - `data`: Contains settings for collection limits and permissions.345 pub fn init_collection(450 pub fn init_collection(346 owner: T::CrossAccountId,451 owner: T::CrossAccountId,347 data: CreateCollectionData<T::AccountId>,452 data: CreateCollectionData<T::AccountId>,350 <PalletCommon<T>>::init_collection(owner, data, is_external)455 <PalletCommon<T>>::init_collection(owner, data, is_external)351 }456 }457458 /// Destroy NFT collection459 ///460 /// `destroy_collection` will throw error if collection contains any tokens.461 /// Only owner can destroy collection.352 pub fn destroy_collection(462 pub fn destroy_collection(353 collection: NonfungibleHandle<T>,463 collection: NonfungibleHandle<T>,354 sender: &T::CrossAccountId,464 sender: &T::CrossAccountId,373 Ok(())483 Ok(())374 }484 }375485486 /// Burn NFT token487 ///488 /// `burn` removes `token` from the `collection`, from it's owner and from the parent token489 /// if the token is nested.490 /// Only the owner can `burn` the token. The `token` shouldn't have any nested tokens.491 /// Also removes all corresponding properties and auxiliary properties.492 ///493 /// - `token`: Token that should be burned494 /// - `collection`: Collection that contains the token376 pub fn burn(495 pub fn burn(377 collection: &NonfungibleHandle<T>,496 collection: &NonfungibleHandle<T>,378 sender: &T::CrossAccountId,497 sender: &T::CrossAccountId,442 Ok(())561 Ok(())443 }562 }444563564 /// Same as [`burn`] but burns all the tokens that are nested in the token first565 ///566 /// - `self_budget`: Limit for searching children in depth.567 /// - `breadth_budget`: Limit of breadth of searching children.568 ///569 /// [`burn`]: struct.Pallet.html#method.burn445 #[transactional]570 #[transactional]446 pub fn burn_recursively(571 pub fn burn_recursively(447 collection: &NonfungibleHandle<T>,572 collection: &NonfungibleHandle<T>,481 })606 })482 }607 }483608609 /// Batch operation to add, edit or remove properties for the token610 ///611 /// All affected properties should have mutable permission and sender should have612 /// permission to edit those properties.613 ///614 /// - `nesting_budget`: Limit for searching parents in depth to check ownership.615 /// - `is_token_create`: Indicates that method is called during token initialization.616 /// Allows to bypass ownership check.484 #[transactional]617 #[transactional]485 fn modify_token_properties(618 fn modify_token_properties(486 collection: &NonfungibleHandle<T>,619 collection: &NonfungibleHandle<T>,574 Ok(())707 Ok(())575 }708 }576709710 /// Batch operation to add or edit properties for the token711 ///712 /// Same as [`modify_token_properties`] but doesn't allow to remove properties713 ///714 /// [`modify_token_properties`]: struct.Pallet.html#method.modify_token_properties577 pub fn set_token_properties(715 pub fn set_token_properties(578 collection: &NonfungibleHandle<T>,716 collection: &NonfungibleHandle<T>,579 sender: &T::CrossAccountId,717 sender: &T::CrossAccountId,592 )730 )593 }731 }594732733 /// Add or edit single property for the token734 ///735 /// Calls [`set_token_properties`] internally736 ///737 /// [`set_token_properties`]: struct.Pallet.html#method.set_token_properties595 pub fn set_token_property(738 pub fn set_token_property(596 collection: &NonfungibleHandle<T>,739 collection: &NonfungibleHandle<T>,597 sender: &T::CrossAccountId,740 sender: &T::CrossAccountId,611 )754 )612 }755 }613756757 /// Batch operation to remove properties from the token758 ///759 /// Same as [`modify_token_properties`] but doesn't allow to add or edit properties760 ///761 /// [`modify_token_properties`]: struct.Pallet.html#method.modify_token_properties614 pub fn delete_token_properties(762 pub fn delete_token_properties(615 collection: &NonfungibleHandle<T>,763 collection: &NonfungibleHandle<T>,616 sender: &T::CrossAccountId,764 sender: &T::CrossAccountId,630 )778 )631 }779 }632780781 /// Remove single property from the token782 ///783 /// Calls [`delete_token_properties`] internally784 ///785 /// [`delete_token_properties`]: struct.Pallet.html#method.delete_token_properties633 pub fn delete_token_property(786 pub fn delete_token_property(634 collection: &NonfungibleHandle<T>,787 collection: &NonfungibleHandle<T>,635 sender: &T::CrossAccountId,788 sender: &T::CrossAccountId,646 )799 )647 }800 }648801802 /// Add or edit properties for the collection649 pub fn set_collection_properties(803 pub fn set_collection_properties(650 collection: &NonfungibleHandle<T>,804 collection: &NonfungibleHandle<T>,651 sender: &T::CrossAccountId,805 sender: &T::CrossAccountId,654 <PalletCommon<T>>::set_collection_properties(collection, sender, properties)808 <PalletCommon<T>>::set_collection_properties(collection, sender, properties)655 }809 }656810811 /// Remove properties from the collection657 pub fn delete_collection_properties(812 pub fn delete_collection_properties(658 collection: &CollectionHandle<T>,813 collection: &CollectionHandle<T>,659 sender: &T::CrossAccountId,814 sender: &T::CrossAccountId,662 <PalletCommon<T>>::delete_collection_properties(collection, sender, property_keys)817 <PalletCommon<T>>::delete_collection_properties(collection, sender, property_keys)663 }818 }664819820 /// Set property permissions for the token.821 ///822 /// Sender should be the owner or admin of token's collection.665 pub fn set_token_property_permissions(823 pub fn set_token_property_permissions(666 collection: &CollectionHandle<T>,824 collection: &CollectionHandle<T>,667 sender: &T::CrossAccountId,825 sender: &T::CrossAccountId,670 <PalletCommon<T>>::set_token_property_permissions(collection, sender, property_permissions)828 <PalletCommon<T>>::set_token_property_permissions(collection, sender, property_permissions)671 }829 }672830831 /// Set property permissions for the collection.832 ///833 /// Sender should be the owner or admin of the collection.673 pub fn set_property_permission(834 pub fn set_property_permission(674 collection: &CollectionHandle<T>,835 collection: &CollectionHandle<T>,675 sender: &T::CrossAccountId,836 sender: &T::CrossAccountId,678 <PalletCommon<T>>::set_property_permission(collection, sender, permission)839 <PalletCommon<T>>::set_property_permission(collection, sender, permission)679 }840 }680841842 /// Transfer NFT token from one account to another.843 ///844 /// `from` account stops being the owner and `to` account becomes the owner of the token.845 /// If `to` is token than `to` becomes owner of the token and the token become nested.846 /// Unnests token from previous parent if it was nested before.847 /// Removes allowance for the token if there was any.848 /// Throws if transfers aren't allowed for collection or if receiver reached token ownership limit.849 ///850 /// - `nesting_budget`: Limit for token nesting depth681 pub fn transfer(851 pub fn transfer(682 collection: &NonfungibleHandle<T>,852 collection: &NonfungibleHandle<T>,683 from: &T::CrossAccountId,853 from: &T::CrossAccountId,769 Ok(())939 Ok(())770 }940 }771941942 /// Batch operation to mint multiple NFT tokens.943 ///944 /// The sender should be the owner/admin of the collection or collection should be configured945 /// to allow public minting.946 /// Throws if amount of tokens reached it's limit for the collection or if caller reached947 /// token ownership limit.948 ///949 /// - `data`: Contains list of token properties and users who will become the owners of the950 /// corresponging tokens.951 /// - `nesting_budget`: Limit for token nesting depth772 pub fn create_multiple_items(952 pub fn create_multiple_items(773 collection: &NonfungibleHandle<T>,953 collection: &NonfungibleHandle<T>,774 sender: &T::CrossAccountId,954 sender: &T::CrossAccountId,953 }1133 }954 }1134 }95511351136 /// Set allowance for the spender to `transfer` or `burn` sender's token.1137 ///1138 /// - `token`: Token the spender is allowed to `transfer` or `burn`.956 pub fn set_allowance(1139 pub fn set_allowance(957 collection: &NonfungibleHandle<T>,1140 collection: &NonfungibleHandle<T>,958 sender: &T::CrossAccountId,1141 sender: &T::CrossAccountId,985 Ok(())1168 Ok(())986 }1169 }98711701171 /// Checks allowance for the spender to use the token.988 fn check_allowed(1172 fn check_allowed(989 collection: &NonfungibleHandle<T>,1173 collection: &NonfungibleHandle<T>,990 spender: &T::CrossAccountId,1174 spender: &T::CrossAccountId,1027 Ok(())1211 Ok(())1028 }1212 }102912131214 /// Transfer NFT token from one account to another.1215 ///1216 /// Same as the [`transfer`] but spender doesn't needs to be the owner of the token.1217 /// The owner should set allowance for the spender to transfer token.1218 ///1219 /// [`transfer`]: struct.Pallet.html#method.transfer1030 pub fn transfer_from(1220 pub fn transfer_from(1031 collection: &NonfungibleHandle<T>,1221 collection: &NonfungibleHandle<T>,1032 spender: &T::CrossAccountId,1222 spender: &T::CrossAccountId,1043 Self::transfer(collection, from, to, token, nesting_budget)1233 Self::transfer(collection, from, to, token, nesting_budget)1044 }1234 }104512351236 /// Burn NFT token for `from` account.1237 ///1238 /// Same as the [`burn`] but spender doesn't need to be an owner of the token. The owner should1239 /// set allowance for the spender to burn token.1240 ///1241 /// [`burn`]: struct.Pallet.html#method.burn1046 pub fn burn_from(1242 pub fn burn_from(1047 collection: &NonfungibleHandle<T>,1243 collection: &NonfungibleHandle<T>,1048 spender: &T::CrossAccountId,1244 spender: &T::CrossAccountId,1057 Self::burn(collection, from, token)1253 Self::burn(collection, from, token)1058 }1254 }105912551256 /// Check that `from` token could be nested in `under` token.1257 ///1060 pub fn check_nesting(1258 pub fn check_nesting(1061 handle: &NonfungibleHandle<T>,1259 handle: &NonfungibleHandle<T>,1062 sender: T::CrossAccountId,1260 sender: T::CrossAccountId,1126 .collect()1324 .collect()1127 }1325 }112813261327 /// Mint single NFT token.1328 ///1129 /// Delegated to `create_multiple_items`1329 /// Delegated to [`create_multiple_items`]1330 ///1331 /// [`create_multiple_items`]: struct.Pallet.html#method.create_multiple_items1130 pub fn create_item(1332 pub fn create_item(1131 collection: &NonfungibleHandle<T>,1333 collection: &NonfungibleHandle<T>,1132 sender: &T::CrossAccountId,1334 sender: &T::CrossAccountId,pallets/nonfungible/src/stubs/UniqueNFT.rawdiffbeforeafterbothbinary blob — no preview
pallets/nonfungible/src/stubs/UniqueNFT.soldiffbeforeafterboth--- a/pallets/nonfungible/src/stubs/UniqueNFT.sol
+++ b/pallets/nonfungible/src/stubs/UniqueNFT.sol
@@ -53,6 +53,13 @@
// Selector: 41369377
contract TokenProperties is Dummy, ERC165 {
+ // @notice Set permissions for token property.
+ // @dev Throws error if `msg.sender` is not admin or owner of the collection.
+ // @param key Property key.
+ // @param is_mutable Permission to mutate property.
+ // @param collection_admin Permission to mutate property by collection admin if property is mutable.
+ // @param token_owner Permission to mutate property by token owner if property is mutable.
+ //
// Selector: setTokenPropertyPermission(string,bool,bool,bool) 222d97fa
function setTokenPropertyPermission(
string memory key,
@@ -68,6 +75,12 @@
dummy = 0;
}
+ // @notice Set token property value.
+ // @dev Throws error if `msg.sender` has no permission to edit the property.
+ // @param token_id ID of the token.
+ // @param key Property key.
+ // @param value Property value.
+ //
// Selector: setProperty(uint256,string,bytes) 1752d67b
function setProperty(
uint256 tokenId,
@@ -81,6 +94,11 @@
dummy = 0;
}
+ // @notice Delete token property value.
+ // @dev Throws error if `msg.sender` has no permission to edit the property.
+ // @param token_id ID of the token.
+ // @param key Property key.
+ //
// Selector: deleteProperty(uint256,string) 066111d1
function deleteProperty(uint256 tokenId, string memory key) public {
require(false, stub_error);
@@ -89,7 +107,10 @@
dummy = 0;
}
- // Throws error if key not found
+ // @notice Get token property value.
+ // @dev Throws error if key not found
+ // @param token_id ID of the token.
+ // @param key Property key.
//
// Selector: property(uint256,string) 7228c327
function property(uint256 tokenId, string memory key)
@@ -107,6 +128,11 @@
// Selector: 42966c68
contract ERC721Burnable is Dummy, ERC165 {
+ // @notice Burns a specific ERC721 token.
+ // @dev Throws unless `msg.sender` is the current NFT owner, or an authorized
+ // operator of the current owner.
+ // @param tokenId The NFT to approve
+ //
// Selector: burn(uint256) 42966c68
function burn(uint256 tokenId) public {
require(false, stub_error);
@@ -117,6 +143,12 @@
// Selector: 58800161
contract ERC721 is Dummy, ERC165, ERC721Events {
+ // @notice Count all NFTs assigned to an owner
+ // @dev NFTs assigned to the zero address are considered invalid, and this
+ // function throws for queries about the zero address.
+ // @param _owner An address for whom to query the balance
+ // @return The number of NFTs owned by `_owner`, possibly zero
+ //
// Selector: balanceOf(address) 70a08231
function balanceOf(address owner) public view returns (uint256) {
require(false, stub_error);
@@ -125,6 +157,12 @@
return 0;
}
+ // @notice Find the owner of an NFT
+ // @dev NFTs assigned to zero address are considered invalid, and queries
+ // about them do throw.
+ // @param _tokenId The identifier for an NFT
+ // @return The address of the owner of the NFT
+ //
// Selector: ownerOf(uint256) 6352211e
function ownerOf(uint256 tokenId) public view returns (address) {
require(false, stub_error);
@@ -133,7 +171,7 @@
return 0x0000000000000000000000000000000000000000;
}
- // Not implemented
+ // @dev Not implemented
//
// Selector: safeTransferFromWithData(address,address,uint256,bytes) 60a11672
function safeTransferFromWithData(
@@ -150,7 +188,7 @@
dummy = 0;
}
- // Not implemented
+ // @dev Not implemented
//
// Selector: safeTransferFrom(address,address,uint256) 42842e0e
function safeTransferFrom(
@@ -165,6 +203,17 @@
dummy = 0;
}
+ // @notice Transfer ownership of an NFT -- THE CALLER IS RESPONSIBLE
+ // TO CONFIRM THAT `to` IS CAPABLE OF RECEIVING NFTS OR ELSE
+ // THEY MAY BE PERMANENTLY LOST
+ // @dev Throws unless `msg.sender` is the current owner or an authorized
+ // operator for this NFT. Throws if `from` is not the current owner. Throws
+ // if `to` is the zero address. Throws if `tokenId` is not a valid NFT.
+ // @param from The current owner of the NFT
+ // @param to The new owner
+ // @param tokenId The NFT to transfer
+ // @param _value Not used for an NFT
+ //
// Selector: transferFrom(address,address,uint256) 23b872dd
function transferFrom(
address from,
@@ -178,6 +227,13 @@
dummy = 0;
}
+ // @notice Set or reaffirm the approved address for an NFT
+ // @dev The zero address indicates there is no approved address.
+ // @dev Throws unless `msg.sender` is the current NFT owner, or an authorized
+ // operator of the current owner.
+ // @param approved The new approved NFT controller
+ // @param tokenId The NFT to approve
+ //
// Selector: approve(address,uint256) 095ea7b3
function approve(address approved, uint256 tokenId) public {
require(false, stub_error);
@@ -186,7 +242,7 @@
dummy = 0;
}
- // Not implemented
+ // @dev Not implemented
//
// Selector: setApprovalForAll(address,bool) a22cb465
function setApprovalForAll(address operator, bool approved) public {
@@ -196,7 +252,7 @@
dummy = 0;
}
- // Not implemented
+ // @dev Not implemented
//
// Selector: getApproved(uint256) 081812fc
function getApproved(uint256 tokenId) public view returns (address) {
@@ -206,7 +262,7 @@
return 0x0000000000000000000000000000000000000000;
}
- // Not implemented
+ // @dev Not implemented
//
// Selector: isApprovedForAll(address,address) e985e9c5
function isApprovedForAll(address owner, address operator)
@@ -224,6 +280,8 @@
// Selector: 5b5e139f
contract ERC721Metadata is Dummy, ERC165 {
+ // @notice A descriptive name for a collection of NFTs in this contract
+ //
// Selector: name() 06fdde03
function name() public view returns (string memory) {
require(false, stub_error);
@@ -231,6 +289,8 @@
return "";
}
+ // @notice An abbreviated name for NFTs in this contract
+ //
// Selector: symbol() 95d89b41
function symbol() public view returns (string memory) {
require(false, stub_error);
@@ -238,7 +298,11 @@
return "";
}
- // Returns token's const_metadata
+ // @notice A distinct Uniform Resource Identifier (URI) for a given asset.
+ // @dev Throws if `tokenId` is not a valid NFT. URIs are defined in RFC
+ // 3986. The URI may point to a JSON file that conforms to the "ERC721
+ // Metadata JSON Schema".
+ // @return token's const_metadata
//
// Selector: tokenURI(uint256) c87b56dd
function tokenURI(uint256 tokenId) public view returns (string memory) {
@@ -258,8 +322,11 @@
return false;
}
- // `token_id` should be obtained with `next_token_id` method,
- // unlike standard, you can't specify it manually
+ // @notice Function to mint token.
+ // @dev `tokenId` should be obtained with `nextTokenId` method,
+ // unlike standard, you can't specify it manually
+ // @param to The new owner
+ // @param tokenId ID of the minted NFT
//
// Selector: mint(address,uint256) 40c10f19
function mint(address to, uint256 tokenId) public returns (bool) {
@@ -270,8 +337,12 @@
return false;
}
- // `token_id` should be obtained with `next_token_id` method,
- // unlike standard, you can't specify it manually
+ // @notice Function to mint token with the given tokenUri.
+ // @dev `tokenId` should be obtained with `nextTokenId` method,
+ // unlike standard, you can't specify it manually
+ // @param to The new owner
+ // @param tokenId ID of the minted NFT
+ // @param tokenUri Token URI that would be stored in the NFT properties
//
// Selector: mintWithTokenURI(address,uint256,string) 50bb4e7f
function mintWithTokenURI(
@@ -287,7 +358,7 @@
return false;
}
- // Not implemented
+ // @dev Not implemented
//
// Selector: finishMinting() 7d64bcb4
function finishMinting() public returns (bool) {
@@ -299,6 +370,12 @@
// Selector: 780e9d63
contract ERC721Enumerable is Dummy, ERC165 {
+ // @notice Enumerate valid NFTs
+ // @dev Throws if `index` >= `totalSupply()`.
+ // @param index A counter less than `totalSupply()`
+ // @return The token identifier for the `index`th NFT,
+ // (sort order not specified)
+ //
// Selector: tokenByIndex(uint256) 4f6ccce7
function tokenByIndex(uint256 index) public view returns (uint256) {
require(false, stub_error);
@@ -307,7 +384,7 @@
return 0;
}
- // Not implemented
+ // @dev Not implemented
//
// Selector: tokenOfOwnerByIndex(address,uint256) 2f745c59
function tokenOfOwnerByIndex(address owner, uint256 index)
@@ -322,6 +399,10 @@
return 0;
}
+ // @notice Count NFTs tracked by this contract
+ // @return A count of valid NFTs tracked by this contract, where each one of
+ // them has an assigned and queryable owner not equal to the zero address
+ //
// Selector: totalSupply() 18160ddd
function totalSupply() public view returns (uint256) {
require(false, stub_error);
@@ -475,6 +556,15 @@
// Selector: d74d154f
contract ERC721UniqueExtensions is Dummy, ERC165 {
+ // @notice Transfer ownership of an NFT -- THE CALLER IS RESPONSIBLE
+ // TO CONFIRM THAT `to` IS CAPABLE OF RECEIVING NFTS OR ELSE
+ // THEY MAY BE PERMANENTLY LOST
+ // @dev Throws unless `msg.sender` is the current owner. Throws if `to`
+ // is the zero address. Throws if `tokenId` is not a valid NFT.
+ // @param to The new owner
+ // @param tokenId The NFT to transfer
+ // @param _value Not used for an NFT
+ //
// Selector: transfer(address,uint256) a9059cbb
function transfer(address to, uint256 tokenId) public {
require(false, stub_error);
@@ -483,6 +573,14 @@
dummy = 0;
}
+ // @notice Burns a specific ERC721 token.
+ // @dev Throws unless `msg.sender` is the current owner or an authorized
+ // operator for this NFT. Throws if `from` is not the current owner. Throws
+ // if `to` is the zero address. Throws if `tokenId` is not a valid NFT.
+ // @param from The current owner of the NFT
+ // @param tokenId The NFT to transfer
+ // @param _value Not used for an NFT
+ //
// Selector: burnFrom(address,uint256) 79cc6790
function burnFrom(address from, uint256 tokenId) public {
require(false, stub_error);
@@ -491,6 +589,8 @@
dummy = 0;
}
+ // @notice Returns next free NFT ID.
+ //
// Selector: nextTokenId() 75794a3c
function nextTokenId() public view returns (uint256) {
require(false, stub_error);
@@ -498,6 +598,12 @@
return 0;
}
+ // @notice Function to mint multiple tokens.
+ // @dev `tokenIds` should be an array of consecutive numbers and first number
+ // should be obtained with `nextTokenId` method
+ // @param to The new owner
+ // @param tokenIds IDs of the minted NFTs
+ //
// Selector: mintBulk(address,uint256[]) 44a9945e
function mintBulk(address to, uint256[] memory tokenIds)
public
@@ -510,6 +616,12 @@
return false;
}
+ // @notice Function to mint multiple tokens with the given tokenUris.
+ // @dev `tokenIds` is array of pairs of token ID and token URI. Token IDs should be consecutive
+ // numbers and first number should be obtained with `nextTokenId` method
+ // @param to The new owner
+ // @param tokens array of pairs of token ID and token URI for minted tokens
+ //
// Selector: mintBulkWithTokenURI(address,(uint256,string)[]) 36543006
function mintBulkWithTokenURI(address to, Tuple0[] memory tokens)
public
tests/src/eth/api/UniqueNFT.soldiffbeforeafterboth--- a/tests/src/eth/api/UniqueNFT.sol
+++ b/tests/src/eth/api/UniqueNFT.sol
@@ -44,6 +44,13 @@
// Selector: 41369377
interface TokenProperties is Dummy, ERC165 {
+ // @notice Set permissions for token property.
+ // @dev Throws error if `msg.sender` is not admin or owner of the collection.
+ // @param key Property key.
+ // @param is_mutable Permission to mutate property.
+ // @param collection_admin Permission to mutate property by collection admin if property is mutable.
+ // @param token_owner Permission to mutate property by token owner if property is mutable.
+ //
// Selector: setTokenPropertyPermission(string,bool,bool,bool) 222d97fa
function setTokenPropertyPermission(
string memory key,
@@ -52,6 +59,12 @@
bool tokenOwner
) external;
+ // @notice Set token property value.
+ // @dev Throws error if `msg.sender` has no permission to edit the property.
+ // @param token_id ID of the token.
+ // @param key Property key.
+ // @param value Property value.
+ //
// Selector: setProperty(uint256,string,bytes) 1752d67b
function setProperty(
uint256 tokenId,
@@ -59,10 +72,18 @@
bytes memory value
) external;
+ // @notice Delete token property value.
+ // @dev Throws error if `msg.sender` has no permission to edit the property.
+ // @param token_id ID of the token.
+ // @param key Property key.
+ //
// Selector: deleteProperty(uint256,string) 066111d1
function deleteProperty(uint256 tokenId, string memory key) external;
- // Throws error if key not found
+ // @notice Get token property value.
+ // @dev Throws error if key not found
+ // @param token_id ID of the token.
+ // @param key Property key.
//
// Selector: property(uint256,string) 7228c327
function property(uint256 tokenId, string memory key)
@@ -73,19 +94,36 @@
// Selector: 42966c68
interface ERC721Burnable is Dummy, ERC165 {
+ // @notice Burns a specific ERC721 token.
+ // @dev Throws unless `msg.sender` is the current NFT owner, or an authorized
+ // operator of the current owner.
+ // @param tokenId The NFT to approve
+ //
// Selector: burn(uint256) 42966c68
function burn(uint256 tokenId) external;
}
// Selector: 58800161
interface ERC721 is Dummy, ERC165, ERC721Events {
+ // @notice Count all NFTs assigned to an owner
+ // @dev NFTs assigned to the zero address are considered invalid, and this
+ // function throws for queries about the zero address.
+ // @param _owner An address for whom to query the balance
+ // @return The number of NFTs owned by `_owner`, possibly zero
+ //
// Selector: balanceOf(address) 70a08231
function balanceOf(address owner) external view returns (uint256);
+ // @notice Find the owner of an NFT
+ // @dev NFTs assigned to zero address are considered invalid, and queries
+ // about them do throw.
+ // @param _tokenId The identifier for an NFT
+ // @return The address of the owner of the NFT
+ //
// Selector: ownerOf(uint256) 6352211e
function ownerOf(uint256 tokenId) external view returns (address);
- // Not implemented
+ // @dev Not implemented
//
// Selector: safeTransferFromWithData(address,address,uint256,bytes) 60a11672
function safeTransferFromWithData(
@@ -95,7 +133,7 @@
bytes memory data
) external;
- // Not implemented
+ // @dev Not implemented
//
// Selector: safeTransferFrom(address,address,uint256) 42842e0e
function safeTransferFrom(
@@ -104,6 +142,17 @@
uint256 tokenId
) external;
+ // @notice Transfer ownership of an NFT -- THE CALLER IS RESPONSIBLE
+ // TO CONFIRM THAT `to` IS CAPABLE OF RECEIVING NFTS OR ELSE
+ // THEY MAY BE PERMANENTLY LOST
+ // @dev Throws unless `msg.sender` is the current owner or an authorized
+ // operator for this NFT. Throws if `from` is not the current owner. Throws
+ // if `to` is the zero address. Throws if `tokenId` is not a valid NFT.
+ // @param from The current owner of the NFT
+ // @param to The new owner
+ // @param tokenId The NFT to transfer
+ // @param _value Not used for an NFT
+ //
// Selector: transferFrom(address,address,uint256) 23b872dd
function transferFrom(
address from,
@@ -111,20 +160,27 @@
uint256 tokenId
) external;
+ // @notice Set or reaffirm the approved address for an NFT
+ // @dev The zero address indicates there is no approved address.
+ // @dev Throws unless `msg.sender` is the current NFT owner, or an authorized
+ // operator of the current owner.
+ // @param approved The new approved NFT controller
+ // @param tokenId The NFT to approve
+ //
// Selector: approve(address,uint256) 095ea7b3
function approve(address approved, uint256 tokenId) external;
- // Not implemented
+ // @dev Not implemented
//
// Selector: setApprovalForAll(address,bool) a22cb465
function setApprovalForAll(address operator, bool approved) external;
- // Not implemented
+ // @dev Not implemented
//
// Selector: getApproved(uint256) 081812fc
function getApproved(uint256 tokenId) external view returns (address);
- // Not implemented
+ // @dev Not implemented
//
// Selector: isApprovedForAll(address,address) e985e9c5
function isApprovedForAll(address owner, address operator)
@@ -135,13 +191,21 @@
// Selector: 5b5e139f
interface ERC721Metadata is Dummy, ERC165 {
+ // @notice A descriptive name for a collection of NFTs in this contract
+ //
// Selector: name() 06fdde03
function name() external view returns (string memory);
+ // @notice An abbreviated name for NFTs in this contract
+ //
// Selector: symbol() 95d89b41
function symbol() external view returns (string memory);
- // Returns token's const_metadata
+ // @notice A distinct Uniform Resource Identifier (URI) for a given asset.
+ // @dev Throws if `tokenId` is not a valid NFT. URIs are defined in RFC
+ // 3986. The URI may point to a JSON file that conforms to the "ERC721
+ // Metadata JSON Schema".
+ // @return token's const_metadata
//
// Selector: tokenURI(uint256) c87b56dd
function tokenURI(uint256 tokenId) external view returns (string memory);
@@ -152,14 +216,21 @@
// Selector: mintingFinished() 05d2035b
function mintingFinished() external view returns (bool);
- // `token_id` should be obtained with `next_token_id` method,
- // unlike standard, you can't specify it manually
+ // @notice Function to mint token.
+ // @dev `tokenId` should be obtained with `nextTokenId` method,
+ // unlike standard, you can't specify it manually
+ // @param to The new owner
+ // @param tokenId ID of the minted NFT
//
// Selector: mint(address,uint256) 40c10f19
function mint(address to, uint256 tokenId) external returns (bool);
- // `token_id` should be obtained with `next_token_id` method,
- // unlike standard, you can't specify it manually
+ // @notice Function to mint token with the given tokenUri.
+ // @dev `tokenId` should be obtained with `nextTokenId` method,
+ // unlike standard, you can't specify it manually
+ // @param to The new owner
+ // @param tokenId ID of the minted NFT
+ // @param tokenUri Token URI that would be stored in the NFT properties
//
// Selector: mintWithTokenURI(address,uint256,string) 50bb4e7f
function mintWithTokenURI(
@@ -168,7 +239,7 @@
string memory tokenUri
) external returns (bool);
- // Not implemented
+ // @dev Not implemented
//
// Selector: finishMinting() 7d64bcb4
function finishMinting() external returns (bool);
@@ -176,10 +247,16 @@
// Selector: 780e9d63
interface ERC721Enumerable is Dummy, ERC165 {
+ // @notice Enumerate valid NFTs
+ // @dev Throws if `index` >= `totalSupply()`.
+ // @param index A counter less than `totalSupply()`
+ // @return The token identifier for the `index`th NFT,
+ // (sort order not specified)
+ //
// Selector: tokenByIndex(uint256) 4f6ccce7
function tokenByIndex(uint256 index) external view returns (uint256);
- // Not implemented
+ // @dev Not implemented
//
// Selector: tokenOfOwnerByIndex(address,uint256) 2f745c59
function tokenOfOwnerByIndex(address owner, uint256 index)
@@ -187,6 +264,10 @@
view
returns (uint256);
+ // @notice Count NFTs tracked by this contract
+ // @return A count of valid NFTs tracked by this contract, where each one of
+ // them has an assigned and queryable owner not equal to the zero address
+ //
// Selector: totalSupply() 18160ddd
function totalSupply() external view returns (uint256);
}
@@ -257,20 +338,51 @@
// Selector: d74d154f
interface ERC721UniqueExtensions is Dummy, ERC165 {
+ // @notice Transfer ownership of an NFT -- THE CALLER IS RESPONSIBLE
+ // TO CONFIRM THAT `to` IS CAPABLE OF RECEIVING NFTS OR ELSE
+ // THEY MAY BE PERMANENTLY LOST
+ // @dev Throws unless `msg.sender` is the current owner. Throws if `to`
+ // is the zero address. Throws if `tokenId` is not a valid NFT.
+ // @param to The new owner
+ // @param tokenId The NFT to transfer
+ // @param _value Not used for an NFT
+ //
// Selector: transfer(address,uint256) a9059cbb
function transfer(address to, uint256 tokenId) external;
+ // @notice Burns a specific ERC721 token.
+ // @dev Throws unless `msg.sender` is the current owner or an authorized
+ // operator for this NFT. Throws if `from` is not the current owner. Throws
+ // if `to` is the zero address. Throws if `tokenId` is not a valid NFT.
+ // @param from The current owner of the NFT
+ // @param tokenId The NFT to transfer
+ // @param _value Not used for an NFT
+ //
// Selector: burnFrom(address,uint256) 79cc6790
function burnFrom(address from, uint256 tokenId) external;
+ // @notice Returns next free NFT ID.
+ //
// Selector: nextTokenId() 75794a3c
function nextTokenId() external view returns (uint256);
+ // @notice Function to mint multiple tokens.
+ // @dev `tokenIds` should be an array of consecutive numbers and first number
+ // should be obtained with `nextTokenId` method
+ // @param to The new owner
+ // @param tokenIds IDs of the minted NFTs
+ //
// Selector: mintBulk(address,uint256[]) 44a9945e
function mintBulk(address to, uint256[] memory tokenIds)
external
returns (bool);
+ // @notice Function to mint multiple tokens with the given tokenUris.
+ // @dev `tokenIds` is array of pairs of token ID and token URI. Token IDs should be consecutive
+ // numbers and first number should be obtained with `nextTokenId` method
+ // @param to The new owner
+ // @param tokens array of pairs of token ID and token URI for minted tokens
+ //
// Selector: mintBulkWithTokenURI(address,(uint256,string)[]) 36543006
function mintBulkWithTokenURI(address to, Tuple0[] memory tokens)
external