From 0e74039449d07de2e2f83c4b561de29bd9091c33 Mon Sep 17 00:00:00 2001 From: Farhad Hakimov Date: Fri, 22 Jul 2022 10:24:49 +0000 Subject: [PATCH] doc(rmrk): adjusted for clarity --- --- a/pallets/proxy-rmrk-core/src/lib.rs +++ b/pallets/proxy-rmrk-core/src/lib.rs @@ -48,7 +48,43 @@ //! - Docs: //! - FAQ: //! - Substrate code repository: -//! - RMRK spec repository: +//! - RMRK specification repository: +//! +//! ## Terminology +//! +//! For more information on RMRK, see RMRK's own documentation. +//! +//! ### Intro to RMRK +//! +//! - **Resource:** Additional piece of metadata of an NFT usually serving to add +//! a piece of media on top of the root metadata (NFT's own), be it a different wing +//! on the root template bird or something entirely unrelated. +//! +//! - **Base:** A list of possible "components" - Parts, a combination of which can +//! be appended/equipped to/on an NFT. +//! +//! - **Part:** Something that, together with other Parts, can constitute an NFT. +//! Parts are defined in the Base to which they belong. Parts can be either +//! of the `slot` type or `fixed` type. Slots are intended for equippables. +//! Note that "part of something" and "Part of a Base" can be easily confused, +//! and in this documentation these words are distinguished by the capital letter. +//! +//! - **Theme:** Named objects of variable => value pairs which get interpolated into +//! the Base's `themable` Parts. Themes can hold any value, but are often represented +//! in RMRK's examples as colors applied to visible Parts. +//! +//! ### Peculiarities in Unique +//! +//! - **Scoped properties:** Properties that are normally obscured from users. +//! Their purpose is to contain structured metadata that was not included in the Unique standard +//! for collections and tokens, meant to be operated on by proxies and other outliers. +//! Scoped properties are prefixed with `some-scope:`, where `some-scope` is +//! an arbitrary keyword, like "rmrk", and `:` is an unacceptable symbol in user-defined +//! properties, which, along with other safeguards, makes them impossible to tamper with. +//! +//! - **Auxiliary properties:** A slightly different structure of properties, +//! trading universality of use for more convenient storage, writes and access. +//! Meant to be inaccessible to end users. //! //! ## Proxy Implementation //! @@ -74,17 +110,17 @@ //! //! Many of RMRK's native parameters are stored as scoped properties of a collection //! or an NFT on the chain. Scoped properties are prefixed with `rmrk:`, where `:` -//! is an unacceptable symbol in user-defined proeprties, which, along with other safeguards, +//! is an unacceptable symbol in user-defined properties, which, along with other safeguards, //! makes them impossible to tamper with. //! -//! ### Collection and NFT Types +//! ### Collection and NFT Types, and Base, Parts and Themes Handling //! //! RMRK introduces the concept of a Base, which is a catalgoue of Parts, //! possible components of an NFT. Due to its similarity with the functionality //! of a token collection, a Base is stored and handled as one, and the Base's Parts and Themes //! are the collection's NFTs. See [`CollectionType`](pallet_rmrk_core::misc::CollectionType) and //! [`NftType`](pallet_rmrk_core::misc::NftType). -//! +//! //! ## Interface //! //! ### Dispatchables @@ -276,9 +312,9 @@ /* RMRK compatible events */ /// Only destroying collections without tokens is allowed. CollectionNotEmpty, - /// Could not find an ID for a collection. It is likely there were too many collections created on the chain. + /// Could not find an ID for a collection. It is likely there were too many collections created on the chain, causing an overflow. NoAvailableCollectionId, - /// Token does not exist, or there is no suitable ID for it, likely too many tokens were created in a collection. + /// Token does not exist, or there is no suitable ID for it, likely too many tokens were created in a collection, causing an overflow. NoAvailableNftId, /// Collection does not exist, has a wrong type, or does not map to a Unique ID. CollectionUnknown, @@ -301,7 +337,7 @@ CannotRejectNonPendingNft, /// Resource is not pending for the operation. ResourceNotPending, - /// Could not find an ID for the resource. Is is likely there were too many resources created on an NFT. + /// Could not find an ID for the resource. It is likely there were too many resources created on an NFT, causing an overflow. NoAvailableResourceId, } @@ -587,8 +623,9 @@ /// # Arguments: /// - `collection_id`: RMRK ID of the collection in which the NFT to burn belongs to. /// - `nft_id`: ID of the NFT to be destroyed. - /// - `max_burns`: Maximum number of tokens to burn, used for nesting. The transaction + /// - `max_burns`: Maximum number of tokens to burn, assuming nesting. The transaction /// is reverted if there are more tokens to burn in the nesting tree than this number. + /// This is primarily a mechanism of transaction weight control. #[transactional] #[pallet::weight(>::burn_nft(*max_burns))] pub fn burn_nft( @@ -1165,11 +1202,7 @@ /// Create and set/propose a basic resource for an NFT. /// - /// A resource is considered a part of an NFT, an additional piece of metadata - /// usually serving to add a piece of media on top of the root metadata, be it - /// a different wing on the root template bird or something entirely unrelated. - /// A basic resource is the simplest, lacking a base or composables. - /// + /// A basic resource is the simplest, lacking a Base and anything that comes with it. /// See RMRK docs for more information and examples. /// /// # Permissions: @@ -1211,11 +1244,7 @@ /// Create and set/propose a composable resource for an NFT. /// - /// A resource is considered a part of an NFT, an additional piece of metadata - /// usually serving to add a piece of media on top of the root metadata, be it - /// a different wing on the root template bird or something entirely unrelated. - /// A composable resource links to a base and has a subset of its parts it is composed of. - /// + /// A composable resource links to a Base and has a subset of its Parts it is composed of. /// See RMRK docs for more information and examples. /// /// # Permissions: @@ -1277,11 +1306,7 @@ /// Create and set/propose a slot resource for an NFT. /// - /// A resource is considered a part of an NFT, an additional piece of metadata - /// usually serving to add a piece of media on top of the root metadata, be it - /// a different wing on the root template bird or something entirely unrelated. - /// A slot resource links to a base and a slot in it which it now occupies. - /// + /// A slot resource links to a Base and a slot ID in it which it can fit into. /// See RMRK docs for more information and examples. /// /// # Permissions: @@ -1575,6 +1600,8 @@ /// Get incremented resource ID from within an NFT's properties and store the new latest ID. /// Thus, the returned resource ID should be used. + /// + /// Resource IDs are unique only across an NFT. fn acquire_next_resource_id( collection_id: CollectionId, nft_id: TokenId, @@ -1693,8 +1720,8 @@ Ok(()) } - /// Remove one usage of a base from an NFT's property of associated bases. The base will stay, however, - /// if the count of resources using the base is still non-zero. + /// Remove a Base ID from an NFT if they are associated. + /// The Base itself is deleted if the number of associated NFTs reaches 0. fn remove_associated_base_id( collection_id: CollectionId, nft_id: TokenId, @@ -1837,9 +1864,9 @@ Self::decode_property_value(&Self::get_collection_property(collection_id, key)?) } - /// Get the type of a collection stored in it as a scoped property. + /// Get the type of a collection stored as a scoped property. /// - /// RMRK Core proxy differentiates between regular collections as well as RMRK bases as collections. + /// RMRK Core proxy differentiates between regular collections as well as RMRK Bases as collections. pub fn get_collection_type( collection_id: CollectionId, ) -> Result { @@ -1921,9 +1948,9 @@ >::contains_key((collection_id, nft_id)) } - /// Get the type of an NFT stored in it as a scoped property. + /// Get the type of an NFT stored as a scoped property. /// - /// RMRK Core proxy differentiates between regular NFTs, and RMRK parts and themes. + /// RMRK Core proxy differentiates between regular NFTs, and RMRK Parts and Themes. pub fn get_nft_type( collection_id: CollectionId, token_id: TokenId, @@ -2013,8 +2040,8 @@ }) } - /// Get all non-scoped properties from a collection or a token, and apply some transformation - /// to each key-value pair. + /// Get all non-scoped properties from a collection or a token, and apply some transformation, + /// supplied by `mapper`, to each key-value pair. pub fn iterate_user_properties( collection_id: CollectionId, token_id: Option, --- a/pallets/proxy-rmrk-core/src/rpc.rs +++ b/pallets/proxy-rmrk-core/src/rpc.rs @@ -224,7 +224,7 @@ Ok(properties) } -/// Get data of resources of an NFT. +/// Get full information on each resource of an NFT, including pending. pub fn nft_resources( collection_id: RmrkCollectionId, nft_id: RmrkNftId, --- a/pallets/proxy-rmrk-equip/src/lib.rs +++ b/pallets/proxy-rmrk-equip/src/lib.rs @@ -30,7 +30,7 @@ //! of solutions based on RMRK. //! //! RMRK Equip itself contains functionality to equip NFTs, and work with Bases, -//! Parts, and Themes. +//! Parts, and Themes. See [Proxy Implementation](#proxy-implementation) for details. //! //! Equip Proxy is responsible for a more specific area of RMRK, and heavily relies on the Core. //! For a more foundational description of proxy implementation, please refer to [`pallet_rmrk_core`]. @@ -52,6 +52,42 @@ //! - FAQ: //! - Substrate code repository: //! - RMRK spec repository: +//! +//! ## Terminology +//! +//! For more information on RMRK, see RMRK's own documentation. +//! +//! ### Intro to RMRK +//! +//! - **Resource:** Additional piece of metadata of an NFT usually serving to add +//! a piece of media on top of the root metadata (NFT's own), be it a different wing +//! on the root template bird or something entirely unrelated. +//! +//! - **Base:** A list of possible "components" - Parts, a combination of which can +//! be appended/equipped to/on an NFT. +//! +//! - **Part:** Something that, together with other Parts, can constitute an NFT. +//! Parts are defined in the Base to which they belong. Parts can be either +//! of the `slot` type or `fixed` type. Slots are intended for equippables. +//! Note that "part of something" and "Part of a Base" can be easily confused, +//! and in this documentation these words are distinguished by the capital letter. +//! +//! - **Theme:** Named objects of variable => value pairs which get interpolated into +//! the Base's `themable` Parts. Themes can hold any value, but are often represented +//! in RMRK's examples as colors applied to visible Parts. +//! +//! ### Peculiarities in Unique +//! +//! - **Scoped properties:** Properties that are normally obscured from users. +//! Their purpose is to contain structured metadata that was not included in the Unique standard +//! for collections and tokens, meant to be operated on by proxies and other outliers. +//! Scoped properties are prefixed with `some-scope:`, where `some-scope` is +//! an arbitrary keyword, like "rmrk", and `:` is an unacceptable symbol in user-defined +//! properties, which, along with other safeguards, makes them impossible to tamper with. +//! +//! - **Auxiliary properties:** A slightly different structure of properties, +//! trading universality of use for more convenient storage, writes and access. +//! Meant to be inaccessible to end users. //! //! ## Proxy Implementation //! @@ -77,10 +113,10 @@ //! //! Many of RMRK's native parameters are stored as scoped properties of a collection //! or an NFT on the chain. Scoped properties are prefixed with `rmrk:`, where `:` -//! is an unacceptable symbol in user-defined proeprties, which, along with other safeguards, +//! is an unacceptable symbol in user-defined properties, which, along with other safeguards, //! makes them impossible to tamper with. //! -//! ### Collection and NFT Types +//! ### Collection and NFT Types, and Base, Parts and Themes Handling //! //! RMRK introduces the concept of a Base, which is a catalgoue of Parts, //! possible components of an NFT. Due to its similarity with the functionality @@ -134,13 +170,13 @@ type WeightInfo: WeightInfo; } - /// Map of a base ID and a part ID to an NFT in the base collection serving as the part. + /// Map of a Base ID and a Part ID to an NFT in the Base collection serving as the Part. #[pallet::storage] #[pallet::getter(fn internal_part_id)] pub type InernalPartId = StorageDoubleMap<_, Twox64Concat, CollectionId, Twox64Concat, RmrkPartId, TokenId>; - /// Checkmark that a base has a Theme NFT named "default". + /// Checkmark that a Base has a Theme NFT named "default". #[pallet::storage] #[pallet::getter(fn base_has_default_theme)] pub type BaseHasDefaultTheme = @@ -167,17 +203,17 @@ pub enum Error { /// No permission to perform action. PermissionError, - /// Could not find an ID for a base collection. It is likely there were too many collections created on the chain. + /// Could not find an ID for a Base collection. It is likely there were too many collections created on the chain, causing an overflow. NoAvailableBaseId, - /// Could not find a suitable ID for a part, likely too many part tokens were created in the base. + /// Could not find a suitable ID for a Part, likely too many Part tokens were created in the Base, causing an overflow NoAvailablePartId, /// Base collection linked to this ID does not exist. BaseDoesntExist, - /// No theme named "default" is associated with the Base. + /// No Theme named "default" is associated with the Base. NeedsDefaultThemeFirst, /// Part linked to this ID does not exist. PartDoesntExist, - /// Cannot assign equippables to a fixed part. + /// Cannot assign equippables to a fixed Part. NoEquippableOnFixedPart, } @@ -185,15 +221,15 @@ impl Pallet { /// Create a new Base. /// - /// Modeled after the [base interaction](https://github.com/rmrk-team/rmrk-spec/blob/master/standards/rmrk2.0.0/interactions/base.md) + /// Modeled after the [Base interaction](https://github.com/rmrk-team/rmrk-spec/blob/master/standards/rmrk2.0.0/interactions/base.md) /// /// # Permissions - /// - Anyone - will be assigned as the issuer of the base. + /// - Anyone - will be assigned as the issuer of the Base. /// /// # Arguments: /// - `base_type`: Arbitrary media type, e.g. "svg". /// - `symbol`: Arbitrary client-chosen symbol. - /// - `parts`: Array of Fixed and Slot parts composing the base, + /// - `parts`: Array of Fixed and Slot Parts composing the Base, /// confined in length by [`RmrkPartsLimit`](up_data_structs::RmrkPartsLimit). #[transactional] #[pallet::weight(>::create_base(parts.len() as u32))] @@ -254,7 +290,7 @@ /// Add a Theme to a Base. /// A Theme named "default" is required prior to adding other Themes. /// - /// Modeled after [themeadd interaction](https://github.com/rmrk-team/rmrk-spec/blob/master/standards/rmrk2.0.0/interactions/themeadd.md). + /// Modeled after [Themeadd interaction](https://github.com/rmrk-team/rmrk-spec/blob/master/standards/rmrk2.0.0/interactions/themeadd.md). /// /// # Permissions: /// - Base issuer @@ -379,8 +415,7 @@ } impl Pallet { - /// Create or renew an NFT serving as a part, setting its properties - /// to those of the part. + /// Create or renew an NFT serving as a Part. fn create_part( sender: &T::CrossAccountId, collection: &NonfungibleHandle, @@ -444,7 +479,7 @@ Ok(()) } - /// Ensure that the collection under the base ID is a base collection, + /// Ensure that the collection under the Base ID is a Base collection, /// and fetch it. fn get_base(base_id: CollectionId) -> Result, DispatchError> { let collection = --- a/primitives/rmrk-traits/src/resource.rs +++ b/primitives/rmrk-traits/src/resource.rs @@ -151,13 +151,13 @@ "#) )] pub struct ResourceInfo { - /// id is a 5-character string of reasonable uniqueness. - /// The combination of base ID and resource id should be unique across the entire RMRK - /// ecosystem which + /// ID a unique identifier for a resource across all those of a single NFT. + /// The combination of a collection ID, an NFT ID, and the resource ID must be + /// unique across the entire RMRK ecosystem. //#[cfg_attr(feature = "std", serde(with = "serialize::vec"))] pub id: ResourceId, - /// Resource + /// Resource type and the accordingly structured data stored pub resource: ResourceTypes, /// If resource is sent to non-rootowned NFT, pending will be false and need to be accepted -- gitstuff