From ddb68d7b0130948a7cf04ba25d4446eb5167fc3d Mon Sep 17 00:00:00 2001
From: Sacha Lansky <sacha@parity.io>
Date: Wed, 16 Aug 2023 11:54:03 +0200
Subject: [PATCH] [fix lint warnings: NFTs pallet] fix
clippy::missing_docs_in_private_items warnings (#14610)
* add docs for impl_codec_bitflags
* add missing docs for type aliases
* add docs to transfer module
* add docs for settings module
* add docs to roles module
* add docs to metadata module
* add docs to migration module
* add missing docs to feature library
* methods not functions
* add docs to lock module
* add docs to attributes module
* add docs to create_delete_item module
* add docs for create_delete_collection module
* add docs to buy_sell module
* add missing doc for buy_sell module
* add docs to atomic_swap module
* add docs to atomic_swap module
* add docs for approvals module
* run cargo fmt
* Fix issues with multi-line comments
* Apply suggestions from code review
Co-authored-by: Jegor Sidorenko <5252494+jsidorenko@users.noreply.github.com>
* update from review
* fmt
* update from review
* remove bitflag example
* ".git/.scripts/commands/fmt/fmt.sh"
* Apply suggestions from code review
Co-authored-by: Squirrel <gilescope@gmail.com>
* add note about pallet features
---------
Co-authored-by: Jegor Sidorenko <jegor@parity.io>
Co-authored-by: Jegor Sidorenko <5252494+jsidorenko@users.noreply.github.com>
Co-authored-by: parity-processbot <>
Co-authored-by: Squirrel <gilescope@gmail.com>
---
.../frame/nfts/src/features/approvals.rs | 49 ++++++++++
.../frame/nfts/src/features/atomic_swap.rs | 52 +++++++++-
.../frame/nfts/src/features/attributes.rs | 98 +++++++++++++++++++
substrate/frame/nfts/src/features/buy_sell.rs | 42 ++++++++
.../src/features/create_delete_collection.rs | 3 +
.../nfts/src/features/create_delete_item.rs | 16 +++
substrate/frame/nfts/src/features/lock.rs | 50 ++++++++++
substrate/frame/nfts/src/features/metadata.rs | 59 ++++++++++-
substrate/frame/nfts/src/features/roles.rs | 28 ++++--
substrate/frame/nfts/src/features/settings.rs | 67 +++++++++++++
substrate/frame/nfts/src/features/transfer.rs | 67 ++++++++++++-
substrate/frame/nfts/src/lib.rs | 5 +
substrate/frame/nfts/src/macros.rs | 11 +++
substrate/frame/nfts/src/migration.rs | 2 +
substrate/frame/nfts/src/types.rs | 16 ++-
15 files changed, 553 insertions(+), 12 deletions(-)
diff --git a/substrate/frame/nfts/src/features/approvals.rs b/substrate/frame/nfts/src/features/approvals.rs
index c78dd2d96b0..053fa67163b 100644
--- a/substrate/frame/nfts/src/features/approvals.rs
+++ b/substrate/frame/nfts/src/features/approvals.rs
@@ -15,10 +15,32 @@
// See the License for the specific language governing permissions and
// limitations under the License.
+//! This module contains helper functions for the approval logic implemented in the NFTs pallet.
+//! The bitflag [`PalletFeature::Approvals`] needs to be set in [`Config::Features`] for NFTs
+//! to have the functionality defined in this module.
+
use crate::*;
use frame_support::pallet_prelude::*;
impl<T: Config<I>, I: 'static> Pallet<T, I> {
+ /// Approves the transfer of an item to a delegate.
+ ///
+ /// This function is used to approve the transfer of the specified `item` in the `collection` to
+ /// a `delegate`. If `maybe_check_origin` is specified, the function ensures that the
+ /// `check_origin` account is the owner of the item, granting them permission to approve the
+ /// transfer. The `delegate` is the account that will be allowed to take control of the item.
+ /// Optionally, a `deadline` can be specified to set a time limit for the approval. The
+ /// `deadline` is expressed in block numbers and is added to the current block number to
+ /// determine the absolute deadline for the approval. After approving the transfer, the function
+ /// emits the `TransferApproved` event.
+ ///
+ /// - `maybe_check_origin`: The optional account that is required to be the owner of the item,
+ /// granting permission to approve the transfer. If `None`, no permission check is performed.
+ /// - `collection`: The identifier of the collection containing the item to be transferred.
+ /// - `item`: The identifier of the item to be transferred.
+ /// - `delegate`: The account that will be allowed to take control of the item.
+ /// - `maybe_deadline`: The optional deadline (in block numbers) specifying the time limit for
+ /// the approval.
pub(crate) fn do_approve_transfer(
maybe_check_origin: Option<T::AccountId>,
collection: T::CollectionId,
@@ -63,6 +85,20 @@ impl<T: Config<I>, I: 'static> Pallet<T, I> {
Ok(())
}
+ /// Cancels the approval for the transfer of an item to a delegate.
+ ///
+ /// This function is used to cancel the approval for the transfer of the specified `item` in the
+ /// `collection` to a `delegate`. If `maybe_check_origin` is specified, the function ensures
+ /// that the `check_origin` account is the owner of the item or that the approval is past its
+ /// deadline, granting permission to cancel the approval. After canceling the approval, the
+ /// function emits the `ApprovalCancelled` event.
+ ///
+ /// - `maybe_check_origin`: The optional account that is required to be the owner of the item or
+ /// that the approval is past its deadline, granting permission to cancel the approval. If
+ /// `None`, no permission check is performed.
+ /// - `collection`: The identifier of the collection containing the item.
+ /// - `item`: The identifier of the item.
+ /// - `delegate`: The account that was previously allowed to take control of the item.
pub(crate) fn do_cancel_approval(
maybe_check_origin: Option<T::AccountId>,
collection: T::CollectionId,
@@ -100,6 +136,19 @@ impl<T: Config<I>, I: 'static> Pallet<T, I> {
Ok(())
}
+ /// Clears all transfer approvals for an item.
+ ///
+ /// This function is used to clear all transfer approvals for the specified `item` in the
+ /// `collection`. If `maybe_check_origin` is specified, the function ensures that the
+ /// `check_origin` account is the owner of the item, granting permission to clear all transfer
+ /// approvals. After clearing all approvals, the function emits the `AllApprovalsCancelled`
+ /// event.
+ ///
+ /// - `maybe_check_origin`: The optional account that is required to be the owner of the item,
+ /// granting permission to clear all transfer approvals. If `None`, no permission check is
+ /// performed.
+ /// - `collection`: The collection ID containing the item.
+ /// - `item`: The item ID for which transfer approvals will be cleared.
pub(crate) fn do_clear_all_transfer_approvals(
maybe_check_origin: Option<T::AccountId>,
collection: T::CollectionId,
diff --git a/substrate/frame/nfts/src/features/atomic_swap.rs b/substrate/frame/nfts/src/features/atomic_swap.rs
index 5b0096d72a3..830283b73c2 100644
--- a/substrate/frame/nfts/src/features/atomic_swap.rs
+++ b/substrate/frame/nfts/src/features/atomic_swap.rs
@@ -15,6 +15,11 @@
// See the License for the specific language governing permissions and
// limitations under the License.
+//! This module contains helper functions for performing atomic swaps implemented in the NFTs
+//! pallet.
+//! The bitflag [`PalletFeature::Swaps`] needs to be set in [`Config::Features`] for NFTs
+//! to have the functionality defined in this module.
+
use crate::*;
use frame_support::{
pallet_prelude::*,
@@ -22,6 +27,25 @@ use frame_support::{
};
impl<T: Config<I>, I: 'static> Pallet<T, I> {
+ /// Creates a new swap offer for the specified item.
+ ///
+ /// This function is used to create a new swap offer for the specified item. The `caller`
+ /// account must be the owner of the item. The swap offer specifies the `offered_collection`,
+ /// `offered_item`, `desired_collection`, `maybe_desired_item`, `maybe_price`, and `duration`.
+ /// The `duration` specifies the deadline by which the swap must be claimed. If
+ /// `maybe_desired_item` is `Some`, the specified item is expected in return for the swap. If
+ /// `maybe_desired_item` is `None`, it indicates that any item from the `desired_collection` can
+ /// be offered in return. The `maybe_price` specifies an optional price for the swap. If
+ /// specified, the other party must offer the specified `price` or higher for the swap. After
+ /// creating the swap, the function emits the `SwapCreated` event.
+ ///
+ /// - `caller`: The account creating the swap offer, which must be the owner of the item.
+ /// - `offered_collection_id`: The collection ID containing the offered item.
+ /// - `offered_item_id`: The item ID offered for the swap.
+ /// - `desired_collection_id`: The collection ID containing the desired item (if any).
+ /// - `maybe_desired_item_id`: The ID of the desired item (if any).
+ /// - `maybe_price`: The optional price for the swap.
+ /// - `duration`: The duration (in block numbers) specifying the deadline for the swap claim.
pub(crate) fn do_create_swap(
caller: T::AccountId,
offered_collection_id: T::CollectionId,
@@ -77,7 +101,16 @@ impl<T: Config<I>, I: 'static> Pallet<T, I> {
Ok(())
}
-
+ /// Cancels the specified swap offer.
+ ///
+ /// This function is used to cancel the specified swap offer created by the `caller` account. If
+ /// the swap offer's deadline has not yet passed, the `caller` must be the owner of the offered
+ /// item; otherwise, anyone can cancel an expired offer.
+ /// After canceling the swap offer, the function emits the `SwapCancelled` event.
+ ///
+ /// - `caller`: The account canceling the swap offer.
+ /// - `offered_collection_id`: The collection ID containing the offered item.
+ /// - `offered_item_id`: The item ID offered for the swap.
pub(crate) fn do_cancel_swap(
caller: T::AccountId,
offered_collection_id: T::CollectionId,
@@ -107,6 +140,23 @@ impl<T: Config<I>, I: 'static> Pallet<T, I> {
Ok(())
}
+ /// Claims the specified swap offer.
+ ///
+ /// This function is used to claim a swap offer specified by the `send_collection_id`,
+ /// `send_item_id`, `receive_collection_id`, and `receive_item_id`. The `caller` account must be
+ /// the owner of the item specified by `send_collection_id` and `send_item_id`. If the claimed
+ /// swap has an associated `price`, it will be transferred between the owners of the two items
+ /// based on the `price.direction`. After the swap is completed, the function emits the
+ /// `SwapClaimed` event.
+ ///
+ /// - `caller`: The account claiming the swap offer, which must be the owner of the sent item.
+ /// - `send_collection_id`: The identifier of the collection containing the item being sent.
+ /// - `send_item_id`: The identifier of the item being sent for the swap.
+ /// - `receive_collection_id`: The identifier of the collection containing the item being
+ /// received.
+ /// - `receive_item_id`: The identifier of the item being received in the swap.
+ /// - `witness_price`: The optional witness price for the swap (price that was offered in the
+ /// swap).
pub(crate) fn do_claim_swap(
caller: T::AccountId,
send_collection_id: T::CollectionId,
diff --git a/substrate/frame/nfts/src/features/attributes.rs b/substrate/frame/nfts/src/features/attributes.rs
index 29e4de5e273..28f7bd2c58c 100644
--- a/substrate/frame/nfts/src/features/attributes.rs
+++ b/substrate/frame/nfts/src/features/attributes.rs
@@ -15,10 +15,38 @@
// See the License for the specific language governing permissions and
// limitations under the License.
+//! This module contains helper methods to configure attributes for items and collections in the
+//! NFTs pallet.
+//! The bitflag [`PalletFeature::Attributes`] needs to be set in [`Config::Features`] for NFTs
+//! to have the functionality defined in this module.
+
use crate::*;
use frame_support::pallet_prelude::*;
impl<T: Config<I>, I: 'static> Pallet<T, I> {
+ /// Sets the attribute of an item or a collection.
+ ///
+ /// This function is used to set an attribute for an item or a collection. It checks the
+ /// provided `namespace` and verifies the permission of the caller to perform the action. The
+ /// `collection` and `maybe_item` parameters specify the target for the attribute.
+ ///
+ /// - `origin`: The account attempting to set the attribute.
+ /// - `collection`: The identifier of the collection to which the item belongs, or the
+ /// collection itself if setting a collection attribute.
+ /// - `maybe_item`: The identifier of the item to which the attribute belongs, or `None` if
+ /// setting a collection attribute.
+ /// - `namespace`: The namespace in which the attribute is being set. It can be either
+ /// `CollectionOwner`, `ItemOwner`, or `Account` (pre-approved external address).
+ /// - `key`: The key of the attribute. It should be a vector of bytes within the limits defined
+ /// by `T::KeyLimit`.
+ /// - `value`: The value of the attribute. It should be a vector of bytes within the limits
+ /// defined by `T::ValueLimit`.
+ /// - `depositor`: The account that is paying the deposit for the attribute.
+ ///
+ /// Note: For the `CollectionOwner` namespace, the collection/item must have the
+ /// `UnlockedAttributes` setting enabled.
+ /// The deposit for setting an attribute is based on the `T::DepositPerByte` and
+ /// `T::AttributeDepositBase` configuration.
pub(crate) fn do_set_attribute(
origin: T::AccountId,
collection: T::CollectionId,
@@ -128,6 +156,23 @@ impl<T: Config<I>, I: 'static> Pallet<T, I> {
Ok(())
}
+ /// Sets the attribute of an item or a collection without performing deposit checks.
+ ///
+ /// This function is used to force-set an attribute for an item or a collection without
+ /// performing the deposit checks. It bypasses the deposit requirement and should only be used
+ /// in specific situations where deposit checks are not necessary or handled separately.
+ ///
+ /// - `set_as`: The account that would normally pay for the deposit.
+ /// - `collection`: The identifier of the collection to which the item belongs, or the
+ /// collection itself if setting a collection attribute.
+ /// - `maybe_item`: The identifier of the item to which the attribute belongs, or `None` if
+ /// setting a collection attribute.
+ /// - `namespace`: The namespace in which the attribute is being set. It can be either
+ /// `CollectionOwner`, `ItemOwner`, or `Account` (pre-approved external address).
+ /// - `key`: The key of the attribute. It should be a vector of bytes within the limits defined
+ /// by `T::KeyLimit`.
+ /// - `value`: The value of the attribute. It should be a vector of bytes within the limits
+ /// defined by `T::ValueLimit`.
pub(crate) fn do_force_set_attribute(
set_as: Option<T::AccountId>,
collection: T::CollectionId,
@@ -159,6 +204,15 @@ impl<T: Config<I>, I: 'static> Pallet<T, I> {
Ok(())
}
+ /// Sets multiple attributes for an item or a collection.
+ ///
+ /// This function checks the pre-signed data is valid and updates the attributes of an item or
+ /// collection. It is limited by [`Config::MaxAttributesPerCall`] to prevent excessive storage
+ /// consumption in a single transaction.
+ ///
+ /// - `origin`: The account initiating the transaction.
+ /// - `data`: The data containing the details of the pre-signed attributes to be set.
+ /// - `signer`: The account of the pre-signed attributes signer.
pub(crate) fn do_set_attributes_pre_signed(
origin: T::AccountId,
data: PreSignedAttributesOf<T, I>,
@@ -212,6 +266,22 @@ impl<T: Config<I>, I: 'static> Pallet<T, I> {
Ok(())
}
+ /// Clears an attribute of an item or a collection.
+ ///
+ /// This function allows clearing an attribute from an item or a collection. It verifies the
+ /// permission of the caller to perform the action based on the provided `namespace` and
+ /// `depositor` account. The deposit associated with the attribute, if any, will be unreserved.
+ ///
+ /// - `maybe_check_origin`: An optional account that acts as an additional security check when
+ /// clearing the attribute. This can be `None` if no additional check is required.
+ /// - `collection`: The identifier of the collection to which the item belongs, or the
+ /// collection itself if clearing a collection attribute.
+ /// - `maybe_item`: The identifier of the item to which the attribute belongs, or `None` if
+ /// clearing a collection attribute.
+ /// - `namespace`: The namespace in which the attribute is being cleared. It can be either
+ /// `CollectionOwner`, `ItemOwner`, or `Account`.
+ /// - `key`: The key of the attribute to be cleared. It should be a vector of bytes within the
+ /// limits defined by `T::KeyLimit`.
pub(crate) fn do_clear_attribute(
maybe_check_origin: Option<T::AccountId>,
collection: T::CollectionId,
@@ -288,6 +358,17 @@ impl<T: Config<I>, I: 'static> Pallet<T, I> {
Ok(())
}
+ /// Approves a delegate to set attributes on behalf of the item's owner.
+ ///
+ /// This function allows the owner of an item to approve a delegate to set attributes in the
+ /// `Account(delegate)` namespace. The maximum number of approvals is determined by
+ /// the configuration `T::MaxAttributesApprovals`.
+ ///
+ /// - `check_origin`: The account of the item's owner attempting to approve the delegate.
+ /// - `collection`: The identifier of the collection to which the item belongs.
+ /// - `item`: The identifier of the item for which the delegate is being approved.
+ /// - `delegate`: The account that is being approved to set attributes on behalf of the item's
+ /// owner.
pub(crate) fn do_approve_item_attributes(
check_origin: T::AccountId,
collection: T::CollectionId,
@@ -312,6 +393,22 @@ impl<T: Config<I>, I: 'static> Pallet<T, I> {
})
}
+ /// Cancels the approval of an item's attributes by a delegate.
+ ///
+ /// This function allows the owner of an item to cancel the approval of a delegate to set
+ /// attributes in the `Account(delegate)` namespace. The delegate's approval is removed, in
+ /// addition to attributes the `delegate` previously created, and any unreserved deposit
+ /// is returned. The number of attributes that the delegate has set for the item must
+ /// not exceed the `account_attributes` provided in the `witness`.
+ /// This function is used to prevent unintended or malicious cancellations.
+ ///
+ /// - `check_origin`: The account of the item's owner attempting to cancel the delegate's
+ /// approval.
+ /// - `collection`: The identifier of the collection to which the item belongs.
+ /// - `item`: The identifier of the item for which the delegate's approval is being canceled.
+ /// - `delegate`: The account whose approval is being canceled.
+ /// - `witness`: The witness containing the number of attributes set by the delegate for the
+ /// item.
pub(crate) fn do_cancel_item_attributes_approval(
check_origin: T::AccountId,
collection: T::CollectionId,
@@ -355,6 +452,7 @@ impl<T: Config<I>, I: 'static> Pallet<T, I> {
})
}
+ /// A helper method to check whether an attribute namespace is valid.
fn is_valid_namespace(
origin: &T::AccountId,
namespace: &AttributeNamespace<T::AccountId>,
diff --git a/substrate/frame/nfts/src/features/buy_sell.rs b/substrate/frame/nfts/src/features/buy_sell.rs
index ad721e0748a..d6ec6f50d27 100644
--- a/substrate/frame/nfts/src/features/buy_sell.rs
+++ b/substrate/frame/nfts/src/features/buy_sell.rs
@@ -15,6 +15,11 @@
// See the License for the specific language governing permissions and
// limitations under the License.
+//! This module contains helper functions to perform the buy and sell functionalities of the NFTs
+//! pallet.
+//! The bitflag [`PalletFeature::Trading`] needs to be set in the [`Config::Features`] for NFTs
+//! to have the functionality defined in this module.
+
use crate::*;
use frame_support::{
pallet_prelude::*,
@@ -22,6 +27,16 @@ use frame_support::{
};
impl<T: Config<I>, I: 'static> Pallet<T, I> {
+ /// Pays the specified tips to the corresponding receivers.
+ ///
+ /// This function is used to pay tips from the `sender` account to multiple receivers. The tips
+ /// are specified as a `BoundedVec` of `ItemTipOf` with a maximum length of `T::MaxTips`. For
+ /// each tip, the function transfers the `amount` to the `receiver` account. The sender is
+ /// responsible for ensuring the validity of the provided tips.
+ ///
+ /// - `sender`: The account that pays the tips.
+ /// - `tips`: A `BoundedVec` containing the tips to be paid, where each tip contains the
+ /// `collection`, `item`, `receiver`, and `amount`.
pub(crate) fn do_pay_tips(
sender: T::AccountId,
tips: BoundedVec<ItemTipOf<T, I>, T::MaxTips>,
@@ -40,6 +55,20 @@ impl<T: Config<I>, I: 'static> Pallet<T, I> {
Ok(())
}
+ /// Sets the price and whitelists a buyer for an item in the specified collection.
+ ///
+ /// This function is used to set the price and whitelist a buyer for an item in the
+ /// specified `collection`. The `sender` account must be the owner of the item. The item's price
+ /// and the whitelisted buyer can be set to allow trading the item. If `price` is `None`, the
+ /// item will be marked as not for sale.
+ ///
+ /// - `collection`: The identifier of the collection containing the item.
+ /// - `item`: The identifier of the item for which the price and whitelist information will be
+ /// set.
+ /// - `sender`: The account that sets the price and whitelist information for the item.
+ /// - `price`: The optional price for the item.
+ /// - `whitelisted_buyer`: The optional account that is whitelisted to buy the item at the set
+ /// price.
pub(crate) fn do_set_price(
collection: T::CollectionId,
item: T::ItemId,
@@ -83,6 +112,19 @@ impl<T: Config<I>, I: 'static> Pallet<T, I> {
Ok(())
}
+ /// Buys the specified item from the collection.
+ ///
+ /// This function is used to buy an item from the specified `collection`. The `buyer` account
+ /// will attempt to buy the item with the provided `bid_price`. The item's current owner will
+ /// receive the bid price if it is equal to or higher than the item's set price. If
+ /// `whitelisted_buyer` is specified in the item's price information, only that account is
+ /// allowed to buy the item. If the item is not for sale, or the bid price is too low, the
+ /// function will return an error.
+ ///
+ /// - `collection`: The identifier of the collection containing the item to be bought.
+ /// - `item`: The identifier of the item to be bought.
+ /// - `buyer`: The account that attempts to buy the item.
+ /// - `bid_price`: The bid price offered by the buyer for the item.
pub(crate) fn do_buy_item(
collection: T::CollectionId,
item: T::ItemId,
diff --git a/substrate/frame/nfts/src/features/create_delete_collection.rs b/substrate/frame/nfts/src/features/create_delete_collection.rs
index 9815958aac7..e343ad18e50 100644
--- a/substrate/frame/nfts/src/features/create_delete_collection.rs
+++ b/substrate/frame/nfts/src/features/create_delete_collection.rs
@@ -15,6 +15,9 @@
// See the License for the specific language governing permissions and
// limitations under the License.
+//! This module contains helper methods to perform functionality associated with creating and
+//! destroying collections for the NFTs pallet.
+
use crate::*;
use frame_support::pallet_prelude::*;
diff --git a/substrate/frame/nfts/src/features/create_delete_item.rs b/substrate/frame/nfts/src/features/create_delete_item.rs
index 33af70a9134..37f64ae1b1b 100644
--- a/substrate/frame/nfts/src/features/create_delete_item.rs
+++ b/substrate/frame/nfts/src/features/create_delete_item.rs
@@ -15,6 +15,9 @@
// See the License for the specific language governing permissions and
// limitations under the License.
+//! This module contains helper methods to perform functionality associated with minting and burning
+//! items for the NFTs pallet.
+
use crate::*;
use frame_support::{pallet_prelude::*, traits::ExistenceRequirement};
@@ -105,6 +108,19 @@ impl<T: Config<I>, I: 'static> Pallet<T, I> {
Ok(())
}
+ /// Mints a new item using a pre-signed message.
+ ///
+ /// This function allows minting a new item using a pre-signed message. The minting process is
+ /// similar to the regular minting process, but it is performed by a pre-authorized account. The
+ /// `mint_to` account receives the newly minted item. The minting process is configurable
+ /// through the provided `mint_data`. The attributes, metadata, and price of the item are set
+ /// according to the provided `mint_data`. The `with_details_and_config` closure is called to
+ /// validate the provided `collection_details` and `collection_config` before minting the item.
+ ///
+ /// - `mint_to`: The account that receives the newly minted item.
+ /// - `mint_data`: The pre-signed minting data containing the `collection`, `item`,
+ /// `attributes`, `metadata`, `deadline`, `only_account`, and `mint_price`.
+ /// - `signer`: The account that is authorized to mint the item using the pre-signed message.
pub(crate) fn do_mint_pre_signed(
mint_to: T::AccountId,
mint_data: PreSignedMintOf<T, I>,
diff --git a/substrate/frame/nfts/src/features/lock.rs b/substrate/frame/nfts/src/features/lock.rs
index 8b4914baeb4..1c3c9c8672f 100644
--- a/substrate/frame/nfts/src/features/lock.rs
+++ b/substrate/frame/nfts/src/features/lock.rs
@@ -15,10 +15,25 @@
// See the License for the specific language governing permissions and
// limitations under the License.
+//! This module contains helper methods to configure locks on collections and items for the NFTs
+//! pallet.
+
use crate::*;
use frame_support::pallet_prelude::*;
impl<T: Config<I>, I: 'static> Pallet<T, I> {
+ /// Locks a collection with specified settings.
+ ///
+ /// The origin must be the owner of the collection to lock it. This function disables certain
+ /// settings on the collection. The only setting that can't be disabled is `DepositRequired`.
+ ///
+ /// Note: it's possible only to lock the setting, but not to unlock it after.
+
+ ///
+ /// - `origin`: The origin of the transaction, representing the account attempting to lock the
+ /// collection.
+ /// - `collection`: The identifier of the collection to be locked.
+ /// - `lock_settings`: The collection settings to be locked.
pub(crate) fn do_lock_collection(
origin: T::AccountId,
collection: T::CollectionId,
@@ -41,6 +56,16 @@ impl<T: Config<I>, I: 'static> Pallet<T, I> {
})
}
+ /// Locks the transfer of an item within a collection.
+ ///
+ /// The origin must have the `Freezer` role within the collection to lock the transfer of the
+ /// item. This function disables the `Transferable` setting on the item, preventing it from
+ /// being transferred to other accounts.
+ ///
+ /// - `origin`: The origin of the transaction, representing the account attempting to lock the
+ /// item transfer.
+ /// - `collection`: The identifier of the collection to which the item belongs.
+ /// - `item`: The identifier of the item to be locked for transfer.
pub(crate) fn do_lock_item_transfer(
origin: T::AccountId,
collection: T::CollectionId,
@@ -61,6 +86,16 @@ impl<T: Config<I>, I: 'static> Pallet<T, I> {
Ok(())
}
+ /// Unlocks the transfer of an item within a collection.
+ ///
+ /// The origin must have the `Freezer` role within the collection to unlock the transfer of the
+ /// item. This function enables the `Transferable` setting on the item, allowing it to be
+ /// transferred to other accounts.
+ ///
+ /// - `origin`: The origin of the transaction, representing the account attempting to unlock the
+ /// item transfer.
+ /// - `collection`: The identifier of the collection to which the item belongs.
+ /// - `item`: The identifier of the item to be unlocked for transfer.
pub(crate) fn do_unlock_item_transfer(
origin: T::AccountId,
collection: T::CollectionId,
@@ -81,6 +116,21 @@ impl<T: Config<I>, I: 'static> Pallet<T, I> {
Ok(())
}
+ /// Locks the metadata and attributes of an item within a collection.
+ ///
+ /// The origin must have the `Admin` role within the collection to lock the metadata and
+ /// attributes of the item. This function disables the `UnlockedMetadata` and
+ /// `UnlockedAttributes` settings on the item, preventing modifications to its metadata and
+ /// attributes.
+ ///
+ /// - `maybe_check_origin`: An optional origin representing the account attempting to lock the
+ /// item properties. If provided, this account must have the `Admin` role within the
+ /// collection. If `None`, no permission check is performed, and the function can be called
+ /// from any origin.
+ /// - `collection`: The identifier of the collection to which the item belongs.
+ /// - `item`: The identifier of the item to be locked for properties.
+ /// - `lock_metadata`: A boolean indicating whether to lock the metadata of the item.
+ /// - `lock_attributes`: A boolean indicating whether to lock the attributes of the item.
pub(crate) fn do_lock_item_properties(
maybe_check_origin: Option<T::AccountId>,
collection: T::CollectionId,
diff --git a/substrate/frame/nfts/src/features/metadata.rs b/substrate/frame/nfts/src/features/metadata.rs
index 1493be1d856..e177f39bb8b 100644
--- a/substrate/frame/nfts/src/features/metadata.rs
+++ b/substrate/frame/nfts/src/features/metadata.rs
@@ -15,11 +15,29 @@
// See the License for the specific language governing permissions and
// limitations under the License.
+//! This module contains helper methods to configure the metadata of collections and items.
+
use crate::*;
use frame_support::pallet_prelude::*;
impl<T: Config<I>, I: 'static> Pallet<T, I> {
- /// Note: if `maybe_depositor` is None, that means the depositor will be a collection's owner
+ /// Sets the metadata for a specific item within a collection.
+ ///
+ /// - `maybe_check_origin`: An optional account ID that is allowed to set the metadata. If
+ /// `None`, it's considered the root account.
+ /// - `collection`: The ID of the collection to which the item belongs.
+ /// - `item`: The ID of the item to set the metadata for.
+ /// - `data`: The metadata to set for the item.
+ /// - `maybe_depositor`: An optional account ID that will provide the deposit for the metadata.
+ /// If `None`, the collection's owner provides the deposit.
+ ///
+ /// Emits `ItemMetadataSet` event upon successful setting of the metadata.
+ /// Returns `Ok(())` on success, or one of the following dispatch errors:
+ /// - `UnknownCollection`: The specified collection does not exist.
+ /// - `UnknownItem`: The specified item does not exist within the collection.
+ /// - `LockedItemMetadata`: The metadata for the item is locked and cannot be modified.
+ /// - `NoPermission`: The caller does not have the required permission to set the metadata.
+ /// - `DepositExceeded`: The deposit amount exceeds the maximum allowed value.
pub(crate) fn do_set_item_metadata(
maybe_check_origin: Option<T::AccountId>,
collection: T::CollectionId,
@@ -91,6 +109,19 @@ impl<T: Config<I>, I: 'static> Pallet<T, I> {
})
}
+ /// Clears the metadata for a specific item within a collection.
+ ///
+ /// - `maybe_check_origin`: An optional account ID that is allowed to clear the metadata. If
+ /// `None`, it's considered the root account.
+ /// - `collection`: The ID of the collection to which the item belongs.
+ /// - `item`: The ID of the item for which to clear the metadata.
+ ///
+ /// Emits `ItemMetadataCleared` event upon successful clearing of the metadata.
+ /// Returns `Ok(())` on success, or one of the following dispatch errors:
+ /// - `UnknownCollection`: The specified collection does not exist.
+ /// - `MetadataNotFound`: The metadata for the specified item was not found.
+ /// - `LockedItemMetadata`: The metadata for the item is locked and cannot be modified.
+ /// - `NoPermission`: The caller does not have the required permission to clear the metadata.
pub(crate) fn do_clear_item_metadata(
maybe_check_origin: Option<T::AccountId>,
collection: T::CollectionId,
@@ -131,6 +162,19 @@ impl<T: Config<I>, I: 'static> Pallet<T, I> {
Ok(())
}
+ /// Sets the metadata for a specific collection.
+ ///
+ /// - `maybe_check_origin`: An optional account ID that is allowed to set the collection
+ /// metadata. If `None`, it's considered the root account.
+ /// - `collection`: The ID of the collection for which to set the metadata.
+ /// - `data`: The metadata to set for the collection.
+ ///
+ /// Emits `CollectionMetadataSet` event upon successful setting of the metadata.
+ /// Returns `Ok(())` on success, or one of the following dispatch errors:
+ /// - `UnknownCollection`: The specified collection does not exist.
+ /// - `LockedCollectionMetadata`: The metadata for the collection is locked and cannot be
+ /// modified.
+ /// - `NoPermission`: The caller does not have the required permission to set the metadata.
pub(crate) fn do_set_collection_metadata(
maybe_check_origin: Option<T::AccountId>,
collection: T::CollectionId,
@@ -179,6 +223,19 @@ impl<T: Config<I>, I: 'static> Pallet<T, I> {
})
}
+ /// Clears the metadata for a specific collection.
+ ///
+ /// - `maybe_check_origin`: An optional account ID that is allowed to clear the collection
+ /// metadata. If `None`, it's considered the root account.
+ /// - `collection`: The ID of the collection for which to clear the metadata.
+ ///
+ /// Emits `CollectionMetadataCleared` event upon successful clearing of the metadata.
+ /// Returns `Ok(())` on success, or one of the following dispatch errors:
+ /// - `UnknownCollection`: The specified collection does not exist.
+ /// - `MetadataNotFound`: The metadata for the collection was not found.
+ /// - `LockedCollectionMetadata`: The metadata for the collection is locked and cannot be
+ /// modified.
+ /// - `NoPermission`: The caller does not have the required permission to clear the metadata.
pub(crate) fn do_clear_collection_metadata(
maybe_check_origin: Option<T::AccountId>,
collection: T::CollectionId,
diff --git a/substrate/frame/nfts/src/features/roles.rs b/substrate/frame/nfts/src/features/roles.rs
index 3bac002069c..f6d2785fd9c 100644
--- a/substrate/frame/nfts/src/features/roles.rs
+++ b/substrate/frame/nfts/src/features/roles.rs
@@ -15,11 +15,26 @@
// See the License for the specific language governing permissions and
// limitations under the License.
+//! This module contains helper methods to configure account roles for existing collections.
+
use crate::*;
use frame_support::pallet_prelude::*;
use sp_std::collections::btree_map::BTreeMap;
impl<T: Config<I>, I: 'static> Pallet<T, I> {
+ /// Set the team roles for a specific collection.
+ ///
+ /// - `maybe_check_owner`: An optional account ID used to check ownership permission. If `None`,
+ /// it is considered as the root.
+ /// - `collection`: The ID of the collection for which to set the team roles.
+ /// - `issuer`: An optional account ID representing the issuer role.
+ /// - `admin`: An optional account ID representing the admin role.
+ /// - `freezer`: An optional account ID representing the freezer role.
+ ///
+ /// This function allows the owner or the root (when `maybe_check_owner` is `None`) to set the
+ /// team roles for a specific collection. The root can change the role from `None` to
+ /// `Some(account)`, but other roles can only be updated by the root or an account with an
+ /// existing role in the collection.
pub(crate) fn do_set_team(
maybe_check_owner: Option<T::AccountId>,
collection: T::CollectionId,
@@ -59,10 +74,10 @@ impl<T: Config<I>, I: 'static> Pallet<T, I> {
let account_to_role = Self::group_roles_by_account(roles);
- // delete the previous records
+ // Delete the previous records.
Self::clear_roles(&collection)?;
- // insert new records
+ // Insert new records.
for (account, roles) in account_to_role {
CollectionRoleOf::<T, I>::insert(&collection, &account, roles);
}
@@ -76,8 +91,9 @@ impl<T: Config<I>, I: 'static> Pallet<T, I> {
///
/// - `collection_id`: A collection to clear the roles in.
///
- /// Throws an error if some of the roles were left in storage.
- /// This means the `CollectionRoles::max_roles()` needs to be adjusted.
+ /// This function clears all the roles associated with the given `collection_id`. It throws an
+ /// error if some of the roles were left in storage, indicating that the maximum number of roles
+ /// may need to be adjusted.
pub(crate) fn clear_roles(collection_id: &T::CollectionId) -> Result<(), DispatchError> {
let res = CollectionRoleOf::<T, I>::clear_prefix(
&collection_id,
@@ -94,7 +110,7 @@ impl<T: Config<I>, I: 'static> Pallet<T, I> {
/// - `account_id`: An account to check the role for.
/// - `role`: A role to validate.
///
- /// Returns boolean.
+ /// Returns `true` if the account has the specified role, `false` otherwise.
pub(crate) fn has_role(
collection_id: &T::CollectionId,
account_id: &T::AccountId,
@@ -123,7 +139,7 @@ impl<T: Config<I>, I: 'static> Pallet<T, I> {
///
/// - `input`: A vector of (Account, Role) tuples.
///
- /// Returns a grouped vector.
+ /// Returns a grouped vector of `(Account, Roles)` tuples.
pub fn group_roles_by_account(
input: Vec<(T::AccountId, CollectionRole)>,
) -> Vec<(T::AccountId, CollectionRoles)> {
diff --git a/substrate/frame/nfts/src/features/settings.rs b/substrate/frame/nfts/src/features/settings.rs
index 3d96a411ae7..d4f7533ffa4 100644
--- a/substrate/frame/nfts/src/features/settings.rs
+++ b/substrate/frame/nfts/src/features/settings.rs
@@ -15,10 +15,19 @@
// See the License for the specific language governing permissions and
// limitations under the License.
+//! This module provides helper methods to configure collection settings for the NFTs pallet.
+
use crate::*;
use frame_support::pallet_prelude::*;
impl<T: Config<I>, I: 'static> Pallet<T, I> {
+ /// Forcefully change the configuration of a collection.
+ ///
+ /// - `collection`: The ID of the collection for which to update the configuration.
+ /// - `config`: The new collection configuration to set.
+ ///
+ /// This function allows for changing the configuration of a collection without any checks.
+ /// It updates the collection configuration and emits a `CollectionConfigChanged` event.
pub(crate) fn do_force_collection_config(
collection: T::CollectionId,
config: CollectionConfigFor<T, I>,
@@ -29,6 +38,22 @@ impl<T: Config<I>, I: 'static> Pallet<T, I> {
Ok(())
}
+ /// Set the maximum supply for a collection.
+ ///
+ /// - `maybe_check_owner`: An optional account ID used to check permissions.
+ /// - `collection`: The ID of the collection for which to set the maximum supply.
+ /// - `max_supply`: The new maximum supply to set for the collection.
+ ///
+ /// This function checks if the setting `UnlockedMaxSupply` is enabled in the collection
+ /// configuration. If it is not enabled, it returns an `Error::MaxSupplyLocked`. If
+ /// `maybe_check_owner` is `Some(owner)`, it checks if the caller of the function is the
+ /// owner of the collection. If the caller is not the owner and the `maybe_check_owner`
+ /// parameter is provided, it returns an `Error::NoPermission`.
+ ///
+ /// It also checks if the new maximum supply is greater than the current number of items in
+ /// the collection, and if not, it returns an `Error::MaxSupplyTooSmall`. If all checks pass,
+ /// it updates the collection configuration with the new maximum supply and emits a
+ /// `CollectionMaxSupplySet` event.
pub(crate) fn do_set_collection_max_supply(
maybe_check_owner: Option<T::AccountId>,
collection: T::CollectionId,
@@ -56,6 +81,18 @@ impl<T: Config<I>, I: 'static> Pallet<T, I> {
})
}
+ /// Update the mint settings for a collection.
+ ///
+ /// - `maybe_check_origin`: An optional account ID used to check issuer permissions.
+ /// - `collection`: The ID of the collection for which to update the mint settings.
+ /// - `mint_settings`: The new mint settings to set for the collection.
+ ///
+ /// This function updates the mint settings for a collection. If `maybe_check_origin` is
+ /// `Some(origin)`, it checks if the caller of the function has the `CollectionRole::Issuer`
+ /// for the given collection. If the caller doesn't have the required permission and
+ /// `maybe_check_origin` is provided, it returns an `Error::NoPermission`. If all checks
+ /// pass, it updates the collection configuration with the new mint settings and emits a
+ /// `CollectionMintSettingsUpdated` event.
pub(crate) fn do_update_mint_settings(
maybe_check_origin: Option<T::AccountId>,
collection: T::CollectionId,
@@ -80,6 +117,13 @@ impl<T: Config<I>, I: 'static> Pallet<T, I> {
})
}
+ /// Get the configuration for a specific collection.
+ ///
+ /// - `collection_id`: The ID of the collection for which to retrieve the configuration.
+ ///
+ /// This function attempts to fetch the configuration (`CollectionConfigFor`) associated
+ /// with the given `collection_id`. If the configuration exists, it returns `Ok(config)`,
+ /// otherwise, it returns a `DispatchError` with `Error::NoConfig`.
pub(crate) fn get_collection_config(
collection_id: &T::CollectionId,
) -> Result<CollectionConfigFor<T, I>, DispatchError> {
@@ -88,6 +132,14 @@ impl<T: Config<I>, I: 'static> Pallet<T, I> {
Ok(config)
}
+ /// Get the configuration for a specific item within a collection.
+ ///
+ /// - `collection_id`: The ID of the collection to which the item belongs.
+ /// - `item_id`: The ID of the item for which to retrieve the configuration.
+ ///
+ /// This function attempts to fetch the configuration (`ItemConfig`) associated with the given
+ /// `collection_id` and `item_id`. If the configuration exists, it returns `Ok(config)`,
+ /// otherwise, it returns a `DispatchError` with `Error::UnknownItem`.
pub(crate) fn get_item_config(
collection_id: &T::CollectionId,
item_id: &T::ItemId,
@@ -97,6 +149,14 @@ impl<T: Config<I>, I: 'static> Pallet<T, I> {
Ok(config)
}
+ /// Get the default item settings for a specific collection.
+ ///
+ /// - `collection_id`: The ID of the collection for which to retrieve the default item settings.
+ ///
+ /// This function fetches the `default_item_settings` from the collection configuration
+ /// associated with the given `collection_id`. If the collection configuration exists, it
+ /// returns `Ok(default_item_settings)`, otherwise, it returns a `DispatchError` with
+ /// `Error::NoConfig`.
pub(crate) fn get_default_item_settings(
collection_id: &T::CollectionId,
) -> Result<ItemSettings, DispatchError> {
@@ -104,6 +164,13 @@ impl<T: Config<I>, I: 'static> Pallet<T, I> {
Ok(collection_config.mint_settings.default_item_settings)
}
+ /// Check if a specified pallet feature is enabled.
+ ///
+ /// - `feature`: The feature to check.
+ ///
+ /// This function checks if the given `feature` is enabled in the runtime using the
+ /// pallet's `T::Features::get()` function. It returns `true` if the feature is enabled,
+ /// otherwise it returns `false`.
pub(crate) fn is_pallet_feature_enabled(feature: PalletFeature) -> bool {
let features = T::Features::get();
return features.is_enabled(feature)
diff --git a/substrate/frame/nfts/src/features/transfer.rs b/substrate/frame/nfts/src/features/transfer.rs
index 149dbb9646f..0471bd67b29 100644
--- a/substrate/frame/nfts/src/features/transfer.rs
+++ b/substrate/frame/nfts/src/features/transfer.rs
@@ -15,11 +15,24 @@
// See the License for the specific language governing permissions and
// limitations under the License.
+//! This module contains helper methods to perform the transfer functionalities
+//! of the NFTs pallet.
+
use crate::*;
use frame_support::pallet_prelude::*;
impl<T: Config<I>, I: 'static> Pallet<T, I> {
- /// Performs the transfer action for the given `collection`, `item`, `dest`, and `event`.
+ /// Transfer an NFT to the specified destination account.
+ ///
+ /// - `collection`: The ID of the collection to which the NFT belongs.
+ /// - `item`: The ID of the NFT to transfer.
+ /// - `dest`: The destination account to which the NFT will be transferred.
+ /// - `with_details`: A closure that provides access to the collection and item details,
+ /// allowing customization of the transfer process.
+ ///
+ /// This function performs the actual transfer of an NFT to the destination account.
+ /// It checks various conditions like item lock status and transferability settings
+ /// for the collection and item before transferring the NFT.
///
/// # Errors
///
@@ -39,45 +52,57 @@ impl<T: Config<I>, I: 'static> Pallet<T, I> {
&mut ItemDetailsFor<T, I>,
) -> DispatchResult,
) -> DispatchResult {
+ // Retrieve collection details.
let collection_details =
Collection::<T, I>::get(&collection).ok_or(Error::<T, I>::UnknownCollection)?;
+ // Ensure the item is not locked.
ensure!(!T::Locker::is_locked(collection, item), Error::<T, I>::ItemLocked);
+
+ // Ensure the item is not transfer disabled on the system level attribute.
ensure!(
!Self::has_system_attribute(&collection, &item, PalletAttributes::TransferDisabled)?,
Error::<T, I>::ItemLocked
);
+ // Retrieve collection config and check if items are transferable.
let collection_config = Self::get_collection_config(&collection)?;
ensure!(
collection_config.is_setting_enabled(CollectionSetting::TransferableItems),
Error::<T, I>::ItemsNonTransferable
);
+ // Retrieve item config and check if the item is transferable.
let item_config = Self::get_item_config(&collection, &item)?;
ensure!(
item_config.is_setting_enabled(ItemSetting::Transferable),
Error::<T, I>::ItemLocked
);
+ // Retrieve the item details.
let mut details =
Item::<T, I>::get(&collection, &item).ok_or(Error::<T, I>::UnknownItem)?;
+
+ // Perform the transfer with custom details using the provided closure.
with_details(&collection_details, &mut details)?;
+ // Update account ownership information.
Account::<T, I>::remove((&details.owner, &collection, &item));
Account::<T, I>::insert((&dest, &collection, &item), ());
let origin = details.owner;
details.owner = dest;
- // The approved accounts have to be reset to None, because otherwise pre-approve attack
+ // The approved accounts have to be reset to `None`, because otherwise pre-approve attack
// would be possible, where the owner can approve their second account before making the
// transaction and then claiming the item back.
details.approvals.clear();
+ // Update item details.
Item::<T, I>::insert(&collection, &item, &details);
ItemPriceOf::<T, I>::remove(&collection, &item);
PendingSwapOf::<T, I>::remove(&collection, &item);
+ // Emit `Transferred` event.
Self::deposit_event(Event::Transferred {
collection,
item,
@@ -87,16 +112,28 @@ impl<T: Config<I>, I: 'static> Pallet<T, I> {
Ok(())
}
+ /// Transfer ownership of a collection to another account.
+ ///
+ /// - `origin`: The account requesting the transfer.
+ /// - `collection`: The ID of the collection to transfer ownership.
+ /// - `owner`: The new account that will become the owner of the collection.
+ ///
+ /// This function transfers the ownership of a collection to the specified account.
+ /// It performs checks to ensure that the `origin` is the current owner and that the
+ /// new owner is an acceptable account based on the collection's acceptance settings.
pub(crate) fn do_transfer_ownership(
origin: T::AccountId,
collection: T::CollectionId,
owner: T::AccountId,
) -> DispatchResult {
+ // Check if the new owner is acceptable based on the collection's acceptance settings.
let acceptable_collection = OwnershipAcceptance::<T, I>::get(&owner);
ensure!(acceptable_collection.as_ref() == Some(&collection), Error::<T, I>::Unaccepted);
+ // Try to retrieve and mutate the collection details.
Collection::<T, I>::try_mutate(collection, |maybe_details| {
let details = maybe_details.as_mut().ok_or(Error::<T, I>::UnknownCollection)?;
+ // Check if the `origin` is the current owner of the collection.
ensure!(origin == details.owner, Error::<T, I>::NoPermission);
if details.owner == owner {
return Ok(())
@@ -109,17 +146,28 @@ impl<T: Config<I>, I: 'static> Pallet<T, I> {
details.owner_deposit,
Reserved,
)?;
+
+ // Update account ownership information.
CollectionAccount::<T, I>::remove(&details.owner, &collection);
CollectionAccount::<T, I>::insert(&owner, &collection, ());
details.owner = owner.clone();
OwnershipAcceptance::<T, I>::remove(&owner);
+ // Emit `OwnerChanged` event.
Self::deposit_event(Event::OwnerChanged { collection, new_owner: owner });
Ok(())
})
}
-
+ /// Set or unset the ownership acceptance for an account regarding a specific collection.
+ ///
+ /// - `who`: The account for which to set or unset the ownership acceptance.
+ /// - `maybe_collection`: An optional collection ID to set the ownership acceptance.
+ ///
+ /// If `maybe_collection` is `Some(collection)`, then the account `who` will accept
+ /// ownership transfers for the specified collection. If `maybe_collection` is `None`,
+ /// then the account `who` will unset the ownership acceptance, effectively refusing
+ /// ownership transfers for any collection.
pub(crate) fn do_set_accept_ownership(
who: T::AccountId,
maybe_collection: Option<T::CollectionId>,
@@ -139,14 +187,25 @@ impl<T: Config<I>, I: 'static> Pallet<T, I> {
} else {
OwnershipAcceptance::<T, I>::remove(&who);
}
+
+ // Emit `OwnershipAcceptanceChanged` event.
Self::deposit_event(Event::OwnershipAcceptanceChanged { who, maybe_collection });
Ok(())
}
+ /// Forcefully change the owner of a collection.
+ ///
+ /// - `collection`: The ID of the collection to change ownership.
+ /// - `owner`: The new account that will become the owner of the collection.
+ ///
+ /// This function allows for changing the ownership of a collection without any checks.
+ /// It moves the deposit to the new owner, updates the collection's owner, and emits
+ /// an `OwnerChanged` event.
pub(crate) fn do_force_collection_owner(
collection: T::CollectionId,
owner: T::AccountId,
) -> DispatchResult {
+ // Try to retrieve and mutate the collection details.
Collection::<T, I>::try_mutate(collection, |maybe_details| {
let details = maybe_details.as_mut().ok_or(Error::<T, I>::UnknownCollection)?;
if details.owner == owner {
@@ -161,10 +220,12 @@ impl<T: Config<I>, I: 'static> Pallet<T, I> {
Reserved,
)?;
+ // Update collection accounts and set the new owner.
CollectionAccount::<T, I>::remove(&details.owner, &collection);
CollectionAccount::<T, I>::insert(&owner, &collection, ());
details.owner = owner.clone();
+ // Emit `OwnerChanged` event.
Self::deposit_event(Event::OwnerChanged { collection, new_owner: owner });
Ok(())
})
diff --git a/substrate/frame/nfts/src/lib.rs b/substrate/frame/nfts/src/lib.rs
index e1325d4cbb0..333fe97dd4a 100644
--- a/substrate/frame/nfts/src/lib.rs
+++ b/substrate/frame/nfts/src/lib.rs
@@ -37,6 +37,10 @@ pub mod mock;
mod tests;
mod common_functions;
+/// A library providing the feature set of this pallet. It contains modules with helper methods that
+/// perform storage updates and checks required by this pallet's dispatchables. To use pallet level
+/// features, make sure to set appropriate bitflags for [`Config::Features`] in your runtime
+/// configuration trait.
mod features;
mod impl_nonfungibles;
mod types;
@@ -63,6 +67,7 @@ pub use weights::WeightInfo;
/// The log target of this pallet.
pub const LOG_TARGET: &'static str = "runtime::nfts";
+/// A type alias for the account ID type used in the dispatchable functions of this pallet.
type AccountIdLookupOf<T> = <<T as SystemConfig>::Lookup as StaticLookup>::Source;
#[frame_support::pallet]
diff --git a/substrate/frame/nfts/src/macros.rs b/substrate/frame/nfts/src/macros.rs
index db560cfbc33..1a601ce0927 100644
--- a/substrate/frame/nfts/src/macros.rs
+++ b/substrate/frame/nfts/src/macros.rs
@@ -15,6 +15,17 @@
// See the License for the specific language governing permissions and
// limitations under the License.
+/// Implements encoding and decoding traits for a wrapper type that represents
+/// bitflags. The wrapper type should contain a field of type `$size`, where
+/// `$size` is an integer type (e.g., u8, u16, u32) that can represent the bitflags.
+/// The `$bitflag_enum` type is the enumeration type that defines the individual bitflags.
+///
+/// This macro provides implementations for the following traits:
+/// - `MaxEncodedLen`: Calculates the maximum encoded length for the wrapper type.
+/// - `Encode`: Encodes the wrapper type using the provided encoding function.
+/// - `EncodeLike`: Trait indicating the type can be encoded as is.
+/// - `Decode`: Decodes the wrapper type from the input.
+/// - `TypeInfo`: Provides type information for the wrapper type.
macro_rules! impl_codec_bitflags {
($wrapper:ty, $size:ty, $bitflag_enum:ty) => {
impl MaxEncodedLen for $wrapper {
diff --git a/substrate/frame/nfts/src/migration.rs b/substrate/frame/nfts/src/migration.rs
index ba14492be84..a4529148e35 100644
--- a/substrate/frame/nfts/src/migration.rs
+++ b/substrate/frame/nfts/src/migration.rs
@@ -36,6 +36,7 @@ pub mod v1 {
}
impl<AccountId, DepositBalance> OldCollectionDetails<AccountId, DepositBalance> {
+ /// Migrates the old collection details to the new v1 format.
fn migrate_to_v1(self, item_configs: u32) -> CollectionDetails<AccountId, DepositBalance> {
CollectionDetails {
owner: self.owner,
@@ -48,6 +49,7 @@ pub mod v1 {
}
}
+ /// A migration utility to update the storage version from v0 to v1 for the pallet.
pub struct MigrateToV1<T>(sp_std::marker::PhantomData<T>);
impl<T: Config> OnRuntimeUpgrade for MigrateToV1<T> {
fn on_runtime_upgrade() -> Weight {
diff --git a/substrate/frame/nfts/src/types.rs b/substrate/frame/nfts/src/types.rs
index e4e61657746..f083b116fe9 100644
--- a/substrate/frame/nfts/src/types.rs
+++ b/substrate/frame/nfts/src/types.rs
@@ -15,7 +15,7 @@
// See the License for the specific language governing permissions and
// limitations under the License.
-//! Various basic types for use in the Nfts pallet.
+//! This module contains various basic types and data structures used in the NFTs pallet.
use super::*;
use crate::macros::*;
@@ -29,36 +29,49 @@ use frame_support::{
use frame_system::pallet_prelude::BlockNumberFor;
use scale_info::{build::Fields, meta_type, Path, Type, TypeInfo, TypeParameter};
+/// A type alias for handling balance deposits.
pub(super) type DepositBalanceOf<T, I = ()> =
<<T as Config<I>>::Currency as Currency<<T as SystemConfig>::AccountId>>::Balance;
+/// A type alias representing the details of a collection.
pub(super) type CollectionDetailsFor<T, I> =
CollectionDetails<<T as SystemConfig>::AccountId, DepositBalanceOf<T, I>>;
+/// A type alias for keeping track of approvals used by a single item.
pub(super) type ApprovalsOf<T, I = ()> = BoundedBTreeMap<
<T as SystemConfig>::AccountId,
Option<BlockNumberFor<T>>,
<T as Config<I>>::ApprovalsLimit,
>;
+/// A type alias for keeping track of approvals for an item's attributes.
pub(super) type ItemAttributesApprovals<T, I = ()> =
BoundedBTreeSet<<T as SystemConfig>::AccountId, <T as Config<I>>::ItemAttributesApprovalsLimit>;
+/// A type that holds the deposit for a single item.
pub(super) type ItemDepositOf<T, I> =
ItemDeposit<DepositBalanceOf<T, I>, <T as SystemConfig>::AccountId>;
+/// A type that holds the deposit amount for an item's attribute.
pub(super) type AttributeDepositOf<T, I> =
AttributeDeposit<DepositBalanceOf<T, I>, <T as SystemConfig>::AccountId>;
+/// A type that holds the deposit amount for an item's metadata.
pub(super) type ItemMetadataDepositOf<T, I> =
ItemMetadataDeposit<DepositBalanceOf<T, I>, <T as SystemConfig>::AccountId>;
+/// A type that holds the details of a single item.
pub(super) type ItemDetailsFor<T, I> =
ItemDetails<<T as SystemConfig>::AccountId, ItemDepositOf<T, I>, ApprovalsOf<T, I>>;
+/// A type alias for an accounts balance.
pub(super) type BalanceOf<T, I = ()> =
<<T as Config<I>>::Currency as Currency<<T as SystemConfig>::AccountId>>::Balance;
+/// A type alias to represent the price of an item.
pub(super) type ItemPrice<T, I = ()> = BalanceOf<T, I>;
+/// A type alias for the tips held by a single item.
pub(super) type ItemTipOf<T, I = ()> = ItemTip<
<T as Config<I>>::CollectionId,
<T as Config<I>>::ItemId,
<T as SystemConfig>::AccountId,
BalanceOf<T, I>,
>;
+/// A type alias for the settings configuration of a collection.
pub(super) type CollectionConfigFor<T, I = ()> =
CollectionConfig<BalanceOf<T, I>, BlockNumberFor<T>, <T as Config<I>>::CollectionId>;
+/// A type alias for the pre-signed minting configuration for a specified collection.
pub(super) type PreSignedMintOf<T, I = ()> = PreSignedMint<
<T as Config<I>>::CollectionId,
<T as Config<I>>::ItemId,
@@ -66,6 +79,7 @@ pub(super) type PreSignedMintOf<T, I = ()> = PreSignedMint<
BlockNumberFor<T>,
BalanceOf<T, I>,
>;
+/// A type alias for the pre-signed minting configuration on the attribute level of an item.
pub(super) type PreSignedAttributesOf<T, I = ()> = PreSignedAttributes<
<T as Config<I>>::CollectionId,
<T as Config<I>>::ItemId,
--
GitLab