git.delta.rocks / unique-network / refs/commits / 0e74039449d0

difftreelog

doc(rmrk): adjusted for clarity

Farhad Hakimov2022-07-22parent: #287a010.patch.diff
in: master

4 files changed

modifiedpallets/proxy-rmrk-core/src/lib.rsdiffbeforeafterboth
48//! - Docs: <https://docs.rmrk.app/getting-started/>48//! - Docs: <https://docs.rmrk.app/getting-started/>
49//! - FAQ: <https://coda.io/@rmrk/faq>49//! - FAQ: <https://coda.io/@rmrk/faq>
50//! - Substrate code repository: <https://github.com/rmrk-team/rmrk-substrate>50//! - Substrate code repository: <https://github.com/rmrk-team/rmrk-substrate>
51//! - RMRK spec repository: <https://github.com/rmrk-team/rmrk-spec>51//! - RMRK specification repository: <https://github.com/rmrk-team/rmrk-spec>
52//! 
53//! ## Terminology
54//! 
55//! For more information on RMRK, see RMRK's own documentation.
56//! 
57//! ### Intro to RMRK
58//! 
59//! - **Resource:** Additional piece of metadata of an NFT usually serving to add 
60//! a piece of media on top of the root metadata (NFT's own), be it a different wing 
61//! on the root template bird or something entirely unrelated.
62//! 
63//! - **Base:** A list of possible "components" - Parts, a combination of which can 
64//! be appended/equipped to/on an NFT.
65//! 
66//! - **Part:** Something that, together with other Parts, can constitute an NFT. 
67//! Parts are defined in the Base to which they belong. Parts can be either 
68//! of the `slot` type or `fixed` type. Slots are intended for equippables.
69//! Note that "part of something" and "Part of a Base" can be easily confused, 
70//! and in this documentation these words are distinguished by the capital letter.
71//! 
72//! - **Theme:** Named objects of variable => value pairs which get interpolated into 
73//! the Base's `themable` Parts. Themes can hold any value, but are often represented 
74//! in RMRK's examples as colors applied to visible Parts.
75//! 
76//! ### Peculiarities in Unique
77//! 
78//! - **Scoped properties:** Properties that are normally obscured from users. 
79//! Their purpose is to contain structured metadata that was not included in the Unique standard 
80//! for collections and tokens, meant to be operated on by proxies and other outliers. 
81//! Scoped properties are prefixed with `some-scope:`, where `some-scope` is 
82//! an arbitrary keyword, like "rmrk", and `:` is an unacceptable symbol in user-defined 
83//! properties, which, along with other safeguards, makes them impossible to tamper with.
84//! 
85//! - **Auxiliary properties:** A slightly different structure of properties, 
86//! trading universality of use for more convenient storage, writes and access. 
87//! Meant to be inaccessible to end users.
52//!88//!
53//! ## Proxy Implementation89//! ## Proxy Implementation
54//!90//!
74//!110//!
75//! Many of RMRK's native parameters are stored as scoped properties of a collection111//! Many of RMRK's native parameters are stored as scoped properties of a collection
76//! or an NFT on the chain. Scoped properties are prefixed with `rmrk:`, where `:`112//! or an NFT on the chain. Scoped properties are prefixed with `rmrk:`, where `:`
77//! is an unacceptable symbol in user-defined proeprties, which, along with other safeguards,113//! is an unacceptable symbol in user-defined properties, which, along with other safeguards,
78//! makes them impossible to tamper with.114//! makes them impossible to tamper with.
79//!115//!
80//! ### Collection and NFT Types116//! ### Collection and NFT Types, and Base, Parts and Themes Handling
81//!117//!
82//! RMRK introduces the concept of a Base, which is a catalgoue of Parts,118//! RMRK introduces the concept of a Base, which is a catalgoue of Parts,
83//! possible components of an NFT. Due to its similarity with the functionality119//! possible components of an NFT. Due to its similarity with the functionality
84//! of a token collection, a Base is stored and handled as one, and the Base's Parts and Themes120//! of a token collection, a Base is stored and handled as one, and the Base's Parts and Themes
85//! are the collection's NFTs. See [`CollectionType`](pallet_rmrk_core::misc::CollectionType) and121//! are the collection's NFTs. See [`CollectionType`](pallet_rmrk_core::misc::CollectionType) and
86//! [`NftType`](pallet_rmrk_core::misc::NftType).122//! [`NftType`](pallet_rmrk_core::misc::NftType).
87//!123//! 
88//! ## Interface124//! ## Interface
89//!125//!
90//! ### Dispatchables126//! ### Dispatchables
276		/* RMRK compatible events */312		/* RMRK compatible events */
277		/// Only destroying collections without tokens is allowed.313		/// Only destroying collections without tokens is allowed.
278		CollectionNotEmpty,314		CollectionNotEmpty,
279		/// Could not find an ID for a collection. It is likely there were too many collections created on the chain.315		/// Could not find an ID for a collection. It is likely there were too many collections created on the chain, causing an overflow.
280		NoAvailableCollectionId,316		NoAvailableCollectionId,
281		/// Token does not exist, or there is no suitable ID for it, likely too many tokens were created in a collection.317		/// Token does not exist, or there is no suitable ID for it, likely too many tokens were created in a collection, causing an overflow.
282		NoAvailableNftId,318		NoAvailableNftId,
283		/// Collection does not exist, has a wrong type, or does not map to a Unique ID.319		/// Collection does not exist, has a wrong type, or does not map to a Unique ID.
284		CollectionUnknown,320		CollectionUnknown,
301		CannotRejectNonPendingNft,337		CannotRejectNonPendingNft,
302		/// Resource is not pending for the operation.338		/// Resource is not pending for the operation.
303		ResourceNotPending,339		ResourceNotPending,
304		/// Could not find an ID for the resource. Is is likely there were too many resources created on an NFT.340		/// Could not find an ID for the resource. It is likely there were too many resources created on an NFT, causing an overflow.
305		NoAvailableResourceId,341		NoAvailableResourceId,
306	}342	}
307343
587		/// # Arguments:623		/// # Arguments:
588		/// - `collection_id`: RMRK ID of the collection in which the NFT to burn belongs to.624		/// - `collection_id`: RMRK ID of the collection in which the NFT to burn belongs to.
589		/// - `nft_id`: ID of the NFT to be destroyed.625		/// - `nft_id`: ID of the NFT to be destroyed.
590		/// - `max_burns`: Maximum number of tokens to burn, used for nesting. The transaction626		/// - `max_burns`: Maximum number of tokens to burn, assuming nesting. The transaction
591		/// is reverted if there are more tokens to burn in the nesting tree than this number.627		/// is reverted if there are more tokens to burn in the nesting tree than this number.
628		/// This is primarily a mechanism of transaction weight control.
592		#[transactional]629		#[transactional]
593		#[pallet::weight(<SelfWeightOf<T>>::burn_nft(*max_burns))]630		#[pallet::weight(<SelfWeightOf<T>>::burn_nft(*max_burns))]
594		pub fn burn_nft(631		pub fn burn_nft(
11651202
1166		/// Create and set/propose a basic resource for an NFT.1203		/// Create and set/propose a basic resource for an NFT.
1167		///1204		///
1168		/// A resource is considered a part of an NFT, an additional piece of metadata
1169		/// usually serving to add a piece of media on top of the root metadata, be it
1170		/// a different wing on the root template bird or something entirely unrelated.
1171		/// A basic resource is the simplest, lacking a base or composables.1205		/// A basic resource is the simplest, lacking a Base and anything that comes with it.
1172		///
1173		/// See RMRK docs for more information and examples.1206		/// See RMRK docs for more information and examples.
1174		///1207		///
1175		/// # Permissions:1208		/// # Permissions:
12111244
1212		/// Create and set/propose a composable resource for an NFT.1245		/// Create and set/propose a composable resource for an NFT.
1213		///1246		///
1214		/// A resource is considered a part of an NFT, an additional piece of metadata
1215		/// usually serving to add a piece of media on top of the root metadata, be it
1216		/// a different wing on the root template bird or something entirely unrelated.
1217		/// A composable resource links to a base and has a subset of its parts it is composed of.1247		/// A composable resource links to a Base and has a subset of its Parts it is composed of.
1218		///
1219		/// See RMRK docs for more information and examples.1248		/// See RMRK docs for more information and examples.
1220		///1249		///
1221		/// # Permissions:1250		/// # Permissions:
12771306
1278		/// Create and set/propose a slot resource for an NFT.1307		/// Create and set/propose a slot resource for an NFT.
1279		///1308		///
1280		/// A resource is considered a part of an NFT, an additional piece of metadata
1281		/// usually serving to add a piece of media on top of the root metadata, be it
1282		/// a different wing on the root template bird or something entirely unrelated.
1283		/// A slot resource links to a base and a slot in it which it now occupies.1309		/// A slot resource links to a Base and a slot ID in it which it can fit into.
1284		///
1285		/// See RMRK docs for more information and examples.1310		/// See RMRK docs for more information and examples.
1286		///1311		///
1287		/// # Permissions:1312		/// # Permissions:
15751600
1576	/// Get incremented resource ID from within an NFT's properties and store the new latest ID.1601	/// Get incremented resource ID from within an NFT's properties and store the new latest ID.
1577	/// Thus, the returned resource ID should be used.1602	/// Thus, the returned resource ID should be used.
1603	/// 
1604	/// Resource IDs are unique only across an NFT.
1578	fn acquire_next_resource_id(1605	fn acquire_next_resource_id(
1579		collection_id: CollectionId,1606		collection_id: CollectionId,
1580		nft_id: TokenId,1607		nft_id: TokenId,
1693		Ok(())1720		Ok(())
1694	}1721	}
16951722
1696	/// Remove one usage of a base from an NFT's property of associated bases. The base will stay, however,1723	/// Remove a Base ID from an NFT if they are associated. 
1697	/// if the count of resources using the base is still non-zero.1724	/// The Base itself is deleted if the number of associated NFTs reaches 0.
1698	fn remove_associated_base_id(1725	fn remove_associated_base_id(
1699		collection_id: CollectionId,1726		collection_id: CollectionId,
1700		nft_id: TokenId,1727		nft_id: TokenId,
1837		Self::decode_property_value(&Self::get_collection_property(collection_id, key)?)1864		Self::decode_property_value(&Self::get_collection_property(collection_id, key)?)
1838	}1865	}
18391866
1840	/// Get the type of a collection stored in it as a scoped property.1867	/// Get the type of a collection stored as a scoped property.
1841	///1868	///
1842	/// RMRK Core proxy differentiates between regular collections as well as RMRK bases as collections.1869	/// RMRK Core proxy differentiates between regular collections as well as RMRK Bases as collections.
1843	pub fn get_collection_type(1870	pub fn get_collection_type(
1844		collection_id: CollectionId,1871		collection_id: CollectionId,
1845	) -> Result<misc::CollectionType, DispatchError> {1872	) -> Result<misc::CollectionType, DispatchError> {
1921		<TokenData<T>>::contains_key((collection_id, nft_id))1948		<TokenData<T>>::contains_key((collection_id, nft_id))
1922	}1949	}
19231950
1924	/// Get the type of an NFT stored in it as a scoped property.1951	/// Get the type of an NFT stored as a scoped property.
1925	///1952	///
1926	/// RMRK Core proxy differentiates between regular NFTs, and RMRK parts and themes.1953	/// RMRK Core proxy differentiates between regular NFTs, and RMRK Parts and Themes.
1927	pub fn get_nft_type(1954	pub fn get_nft_type(
1928		collection_id: CollectionId,1955		collection_id: CollectionId,
1929		token_id: TokenId,1956		token_id: TokenId,
2013			})2040			})
2014	}2041	}
20152042
2016	/// Get all non-scoped properties from a collection or a token, and apply some transformation2043	/// Get all non-scoped properties from a collection or a token, and apply some transformation,
2017	/// to each key-value pair.2044	/// supplied by `mapper`, to each key-value pair.
2018	pub fn iterate_user_properties<Key, Value, R, Mapper>(2045	pub fn iterate_user_properties<Key, Value, R, Mapper>(
2019		collection_id: CollectionId,2046		collection_id: CollectionId,
2020		token_id: Option<TokenId>,2047		token_id: Option<TokenId>,
modifiedpallets/proxy-rmrk-core/src/rpc.rsdiffbeforeafterboth
--- 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<T: Config>(
 	collection_id: RmrkCollectionId,
 	nft_id: RmrkNftId,
modifiedpallets/proxy-rmrk-equip/src/lib.rsdiffbeforeafterboth
--- 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: <https://coda.io/@rmrk/faq>
 //! - Substrate code repository: <https://github.com/rmrk-team/rmrk-substrate>
 //! - RMRK spec repository: <https://github.com/rmrk-team/rmrk-spec>
+//! 
+//! ## 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<T: Config> =
 		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<T: Config> =
@@ -167,17 +203,17 @@
 	pub enum Error<T> {
 		/// 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<T: Config> Pallet<T> {
 		/// 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(<SelfWeightOf<T>>::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<T: Config> Pallet<T> {
-	/// 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<T>,
@@ -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<NonfungibleHandle<T>, DispatchError> {
 		let collection =
modifiedprimitives/rmrk-traits/src/resource.rsdiffbeforeafterboth
--- a/primitives/rmrk-traits/src/resource.rs
+++ b/primitives/rmrk-traits/src/resource.rs
@@ -151,13 +151,13 @@
 		"#)
 )]
 pub struct ResourceInfo<BoundedString, BoundedParts> {
-	/// 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<BoundedString, BoundedParts>,
 
 	/// If resource is sent to non-rootowned NFT, pending will be false and need to be accepted