difftreelog
doc(rmrk): adjusted for clarity
in: master
4 files changed
pallets/proxy-rmrk-core/src/lib.rsdiffbeforeafterboth--- a/pallets/proxy-rmrk-core/src/lib.rs
+++ b/pallets/proxy-rmrk-core/src/lib.rs
@@ -48,7 +48,43 @@
//! - Docs: <https://docs.rmrk.app/getting-started/>
//! - 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>
+//! - RMRK specification 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
//!
@@ -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(<SelfWeightOf<T>>::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<misc::CollectionType, DispatchError> {
@@ -1921,9 +1948,9 @@
<TokenData<T>>::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<Key, Value, R, Mapper>(
collection_id: CollectionId,
token_id: Option<TokenId>,
pallets/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,
pallets/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 =
primitives/rmrk-traits/src/resource.rsdiffbeforeafterboth151 "#)151 "#)152)]152)]153pub struct ResourceInfo<BoundedString, BoundedParts> {153pub struct ResourceInfo<BoundedString, BoundedParts> {154 /// id is a 5-character string of reasonable uniqueness.154 /// ID a unique identifier for a resource across all those of a single NFT.155 /// The combination of base ID and resource id should be unique across the entire RMRK155 /// The combination of a collection ID, an NFT ID, and the resource ID must be 156 /// ecosystem which156 /// unique across the entire RMRK ecosystem.157 //#[cfg_attr(feature = "std", serde(with = "serialize::vec"))]157 //#[cfg_attr(feature = "std", serde(with = "serialize::vec"))]158 pub id: ResourceId,158 pub id: ResourceId,159159160 /// Resource160 /// Resource type and the accordingly structured data stored161 pub resource: ResourceTypes<BoundedString, BoundedParts>,161 pub resource: ResourceTypes<BoundedString, BoundedParts>,162162163 /// If resource is sent to non-rootowned NFT, pending will be false and need to be accepted163 /// If resource is sent to non-rootowned NFT, pending will be false and need to be accepted