difftreelog
docs(pallet_common) Add general documentation.
in: master
4 files changed
pallets/common/src/dispatch.rsdiffbeforeafterboth--- a/pallets/common/src/dispatch.rs
+++ b/pallets/common/src/dispatch.rs
@@ -1,3 +1,5 @@
+//! Module with interfaces for dispatching collections.
+
use frame_support::{
dispatch::{
DispatchResultWithPostInfo, PostDispatchInfo, Weight, DispatchErrorWithPostInfo,
@@ -20,7 +22,10 @@
// submit_logs is measured as part of collection pallets
}
-/// Helper function to implement substrate calls for common collection methods
+/// Helper function to implement substrate calls for common collection methods.
+///
+/// * `collection` - The collection on which to call the method.
+/// * `call` - The function in which to call the corresponding method from [CommonCollectionOperations].
pub fn dispatch_tx<
T: Config,
C: FnOnce(&dyn CommonCollectionOperations<T>) -> DispatchResultWithPostInfo,
@@ -64,15 +69,31 @@
result
}
+/// Interface for working with different collections through the dispatcher.
pub trait CollectionDispatch<T: Config> {
+ /// Create a collection. The collection will be created according to the value of [data.mode](CreateCollectionData::mode).
+ ///
+ /// * `sender` - The user who will become the owner of the collection.
+ /// * `data` - Description of the created collection.
fn create(
sender: T::CrossAccountId,
data: CreateCollectionData<T::AccountId>,
) -> DispatchResult;
+
+ /// Delete the collection.
+ ///
+ /// * `sender` - The owner of the collection.
+ /// * `handle` - Collection handle.
fn destroy(sender: T::CrossAccountId, handle: CollectionHandle<T>) -> DispatchResult;
+ /// Get a specialized collection from the handle.
+ ///
+ /// * `handle` - Collection handle.
fn dispatch(handle: CollectionHandle<T>) -> Self;
+
+ /// Get the collection handle for the corresponding implementation.
fn into_inner(self) -> CollectionHandle<T>;
+ /// Получить реализацию [CommonCollectionOperations].
fn as_dyn(&self) -> &dyn CommonCollectionOperations<T>;
}
pallets/common/src/erc.rsdiffbeforeafterboth14// You should have received a copy of the GNU General Public License14// You should have received a copy of the GNU General Public License15// along with Unique Network. If not, see <http://www.gnu.org/licenses/>.15// along with Unique Network. If not, see <http://www.gnu.org/licenses/>.1617//! This module contains the implementation of pallet methods for evm.161817use evm_coder::{19use evm_coder::{18 solidity_interface, solidity, ToLog,20 solidity_interface, solidity, ToLog,293130use crate::{Pallet, CollectionHandle, Config, CollectionProperties};32use crate::{Pallet, CollectionHandle, Config, CollectionProperties};313334/// Events for etherium collection helper.32#[derive(ToLog)]35#[derive(ToLog)]33pub enum CollectionHelpersEvents {36pub enum CollectionHelpersEvents {37 /// The collection has been created.34 CollectionCreated {38 CollectionCreated {39 /// Collection owner.35 #[indexed]40 #[indexed]36 owner: address,41 owner: address,4243 /// Collection ID.37 #[indexed]44 #[indexed]38 collection_id: address,45 collection_id: address,39 },46 },40}47}414842/// Does not always represent a full collection, for RFT it is either49/// Does not always represent a full collection, for RFT it is either43/// collection (Implementing ERC721), or specific collection token (Implementing ERC20)50/// collection (Implementing ERC721), or specific collection token (Implementing ERC20).44pub trait CommonEvmHandler {51pub trait CommonEvmHandler {45 const CODE: &'static [u8];52 const CODE: &'static [u8];465347 fn call(self, handle: &mut impl PrecompileHandle) -> Option<PrecompileResult>;54 fn call(self, handle: &mut impl PrecompileHandle) -> Option<PrecompileResult>;48}55}495657/// @title A contract that allows you to work with collections.50#[solidity_interface(name = "Collection")]58#[solidity_interface(name = "Collection")]51impl<T: Config> CollectionHandle<T>59impl<T: Config> CollectionHandle<T>52where60where53 T::AccountId: From<[u8; 32]>,61 T::AccountId: From<[u8; 32]>,54{62{63 /// Set collection property.64 /// 65 /// @param key Property key.66 /// @param value Propery value.55 fn set_collection_property(67 fn set_collection_property(56 &mut self,68 &mut self,57 caller: caller,69 caller: caller,68 .map_err(dispatch_to_evm::<T>)80 .map_err(dispatch_to_evm::<T>)69 }81 }7082 83 /// Delete collection property.84 /// 85 /// @param key Property key.71 fn delete_collection_property(&mut self, caller: caller, key: string) -> Result<()> {86 fn delete_collection_property(&mut self, caller: caller, key: string) -> Result<()> {72 let caller = T::CrossAccountId::from_eth(caller);87 let caller = T::CrossAccountId::from_eth(caller);73 let key = <Vec<u8>>::from(key)88 let key = <Vec<u8>>::from(key)77 <Pallet<T>>::delete_collection_property(self, &caller, key).map_err(dispatch_to_evm::<T>)92 <Pallet<T>>::delete_collection_property(self, &caller, key).map_err(dispatch_to_evm::<T>)78 }93 }799495 /// Get collection property.96 /// 80 /// Throws error if key not found97 /// @dev Throws error if key not found.98 /// 99 /// @param key Property key.100 /// @return bytes The property corresponding to the key.81 fn collection_property(&self, key: string) -> Result<bytes> {101 fn collection_property(&self, key: string) -> Result<bytes> {82 let key = <Vec<u8>>::from(key)102 let key = <Vec<u8>>::from(key)83 .try_into()103 .try_into()89 Ok(prop.to_vec())109 Ok(prop.to_vec())90 }110 }91111112 /// Set the sponsor of the collection.113 /// 114 /// @dev In order for sponsorship to work, it must be confirmed on behalf of the sponsor.115 /// 116 /// @param sponsor Address of the sponsor from whose account funds will be debited for operations with the contract.92 fn set_collection_sponsor(&mut self, caller: caller, sponsor: address) -> Result<void> {117 fn set_collection_sponsor(&mut self, caller: caller, sponsor: address) -> Result<void> {93 check_is_owner_or_admin(caller, self)?;118 check_is_owner_or_admin(caller, self)?;9411998 save(self)123 save(self)99 }124 }100125126 /// Collection sponsorship confirmation.127 /// 128 /// @dev After setting the sponsor for the collection, it must be confirmed with this function.101 fn confirm_collection_sponsorship(&mut self, caller: caller) -> Result<void> {129 fn confirm_collection_sponsorship(&mut self, caller: caller) -> Result<void> {102 let caller = T::CrossAccountId::from_eth(caller);130 let caller = T::CrossAccountId::from_eth(caller);103 if !self131 if !self109 save(self)137 save(self)110 }138 }111139140 /// Set limits for the collection.141 /// @dev Throws error if limit not found.142 /// @param limit Name of the limit. Valid names:143 /// "accountTokenOwnershipLimit",144 /// "sponsoredDataSize",145 /// "sponsoredDataRateLimit",146 /// "tokenLimit",147 /// "sponsorTransferTimeout",148 /// "sponsorApproveTimeout"149 /// @param value Value of the limit.112 #[solidity(rename_selector = "setCollectionLimit")]150 #[solidity(rename_selector = "setCollectionLimit")]113 fn set_int_limit(&mut self, caller: caller, limit: string, value: uint32) -> Result<void> {151 fn set_int_limit(&mut self, caller: caller, limit: string, value: uint32) -> Result<void> {114 check_is_owner_or_admin(caller, self)?;152 check_is_owner_or_admin(caller, self)?;145 save(self)183 save(self)146 }184 }147185186 /// Set limits for the collection.187 /// @dev Throws error if limit not found.188 /// @param limit Name of the limit. Valid names:189 /// "ownerCanTransfer",190 /// "ownerCanDestroy",191 /// "transfersEnabled"192 /// @param value Value of the limit.148 #[solidity(rename_selector = "setCollectionLimit")]193 #[solidity(rename_selector = "setCollectionLimit")]149 fn set_bool_limit(&mut self, caller: caller, limit: string, value: bool) -> Result<void> {194 fn set_bool_limit(&mut self, caller: caller, limit: string, value: bool) -> Result<void> {150 check_is_owner_or_admin(caller, self)?;195 check_is_owner_or_admin(caller, self)?;172 save(self)217 save(self)173 }218 }174219220 /// Get contract address.175 fn contract_address(&self, _caller: caller) -> Result<address> {221 fn contract_address(&self, _caller: caller) -> Result<address> {176 Ok(crate::eth::collection_id_to_address(self.id))222 Ok(crate::eth::collection_id_to_address(self.id))177 }223 }178224225 /// Add collection admin by substrate address.226 /// @param new_admin Substrate administrator address.179 fn add_collection_admin_substrate(&self, caller: caller, new_admin: uint256) -> Result<void> {227 fn add_collection_admin_substrate(&self, caller: caller, new_admin: uint256) -> Result<void> {180 let caller = T::CrossAccountId::from_eth(caller);228 let caller = T::CrossAccountId::from_eth(caller);181 let mut new_admin_arr: [u8; 32] = Default::default();229 let mut new_admin_arr: [u8; 32] = Default::default();186 Ok(())234 Ok(())187 }235 }188236237 /// Remove collection admin by substrate address.238 /// @param admin Substrate administrator address.189 fn remove_collection_admin_substrate(239 fn remove_collection_admin_substrate(190 &self,240 &self,191 caller: caller,241 caller: caller,192 new_admin: uint256,242 admin: uint256,193 ) -> Result<void> {243 ) -> Result<void> {194 let caller = T::CrossAccountId::from_eth(caller);244 let caller = T::CrossAccountId::from_eth(caller);195 let mut new_admin_arr: [u8; 32] = Default::default();245 let mut admin_arr: [u8; 32] = Default::default();196 new_admin.to_big_endian(&mut new_admin_arr);246 admin.to_big_endian(&mut admin_arr);197 let account_id = T::AccountId::from(new_admin_arr);247 let account_id = T::AccountId::from(admin_arr);198 let new_admin = T::CrossAccountId::from_sub(account_id);248 let admin = T::CrossAccountId::from_sub(account_id);199 <Pallet<T>>::toggle_admin(self, &caller, &new_admin, false)249 <Pallet<T>>::toggle_admin(self, &caller, &admin, false)200 .map_err(dispatch_to_evm::<T>)?;250 .map_err(dispatch_to_evm::<T>)?;201 Ok(())251 Ok(())202 }252 }203253254 /// Add collection admin.255 /// @param new_admin Address of the added administrator.204 fn add_collection_admin(&self, caller: caller, new_admin: address) -> Result<void> {256 fn add_collection_admin(&self, caller: caller, new_admin: address) -> Result<void> {205 let caller = T::CrossAccountId::from_eth(caller);257 let caller = T::CrossAccountId::from_eth(caller);206 let new_admin = T::CrossAccountId::from_eth(new_admin);258 let new_admin = T::CrossAccountId::from_eth(new_admin);207 <Pallet<T>>::toggle_admin(self, &caller, &new_admin, true).map_err(dispatch_to_evm::<T>)?;259 <Pallet<T>>::toggle_admin(self, &caller, &new_admin, true).map_err(dispatch_to_evm::<T>)?;208 Ok(())260 Ok(())209 }261 }210262263 /// Remove collection admin.264 /// 265 /// @param new_admin Address of the removed administrator.211 fn remove_collection_admin(&self, caller: caller, admin: address) -> Result<void> {266 fn remove_collection_admin(&self, caller: caller, admin: address) -> Result<void> {212 let caller = T::CrossAccountId::from_eth(caller);267 let caller = T::CrossAccountId::from_eth(caller);213 let admin = T::CrossAccountId::from_eth(admin);268 let admin = T::CrossAccountId::from_eth(admin);214 <Pallet<T>>::toggle_admin(self, &caller, &admin, false).map_err(dispatch_to_evm::<T>)?;269 <Pallet<T>>::toggle_admin(self, &caller, &admin, false).map_err(dispatch_to_evm::<T>)?;215 Ok(())270 Ok(())216 }271 }217272273 /// Toggle accessibility of collection nesting.274 /// 275 /// @param enable If "true" degenerates to nesting: 'Owner' else to nesting: 'Disabled'218 #[solidity(rename_selector = "setCollectionNesting")]276 #[solidity(rename_selector = "setCollectionNesting")]219 fn set_nesting_bool(&mut self, caller: caller, enable: bool) -> Result<void> {277 fn set_nesting_bool(&mut self, caller: caller, enable: bool) -> Result<void> {220 check_is_owner_or_admin(caller, self)?;278 check_is_owner_or_admin(caller, self)?;235 save(self)293 save(self)236 }294 }237295296 /// Toggle accessibility of collection nesting.297 /// 298 /// @param enable If "true" degenerates to nesting: {OwnerRestricted: [1, 2, 3]} else to nesting: 'Disabled'299 /// @param collections Addresses of collections that will be available for nesting.238 #[solidity(rename_selector = "setCollectionNesting")]300 #[solidity(rename_selector = "setCollectionNesting")]239 fn set_nesting(301 fn set_nesting(240 &mut self,302 &mut self,280 save(self)342 save(self)281 }343 }282344345 /// Set the collection access method.346 /// @param mode Access mode347 /// 0 for Normal348 /// 1 for AllowList283 fn set_collection_access(&mut self, caller: caller, mode: uint8) -> Result<void> {349 fn set_collection_access(&mut self, caller: caller, mode: uint8) -> Result<void> {284 check_is_owner_or_admin(caller, self)?;350 check_is_owner_or_admin(caller, self)?;285 let permissions = CollectionPermissions {351 let permissions = CollectionPermissions {300 save(self)366 save(self)301 }367 }302368369 /// Add the user to the allowed list.370 /// 371 /// @param user Address of a trusted user.303 fn add_to_collection_allow_list(&self, caller: caller, user: address) -> Result<void> {372 fn add_to_collection_allow_list(&self, caller: caller, user: address) -> Result<void> {304 let caller = T::CrossAccountId::from_eth(caller);373 let caller = T::CrossAccountId::from_eth(caller);305 let user = T::CrossAccountId::from_eth(user);374 let user = T::CrossAccountId::from_eth(user);306 <Pallet<T>>::toggle_allowlist(self, &caller, &user, true).map_err(dispatch_to_evm::<T>)?;375 <Pallet<T>>::toggle_allowlist(self, &caller, &user, true).map_err(dispatch_to_evm::<T>)?;307 Ok(())376 Ok(())308 }377 }309378 379 /// Remove the user from the allowed list.380 /// 381 /// @param user Address of a removed user.310 fn remove_from_collection_allow_list(&self, caller: caller, user: address) -> Result<void> {382 fn remove_from_collection_allow_list(&self, caller: caller, user: address) -> Result<void> {311 let caller = T::CrossAccountId::from_eth(caller);383 let caller = T::CrossAccountId::from_eth(caller);312 let user = T::CrossAccountId::from_eth(user);384 let user = T::CrossAccountId::from_eth(user);313 <Pallet<T>>::toggle_allowlist(self, &caller, &user, false).map_err(dispatch_to_evm::<T>)?;385 <Pallet<T>>::toggle_allowlist(self, &caller, &user, false).map_err(dispatch_to_evm::<T>)?;314 Ok(())386 Ok(())315 }387 }316388389 /// Switch permission for minting.390 /// 391 /// @param mode Enable if "true".317 fn set_collection_mint_mode(&mut self, caller: caller, mode: bool) -> Result<void> {392 fn set_collection_mint_mode(&mut self, caller: caller, mode: bool) -> Result<void> {318 check_is_owner_or_admin(caller, self)?;393 check_is_owner_or_admin(caller, self)?;319 let permissions = CollectionPermissions {394 let permissions = CollectionPermissions {351 Ok(())426 Ok(())352}427}353428429/// Get the "tokenURI" key as [PropertyKey](up_data_structs::PropertyKey).354pub fn token_uri_key() -> up_data_structs::PropertyKey {430pub fn token_uri_key() -> up_data_structs::PropertyKey {355 b"tokenURI"431 b"tokenURI"356 .to_vec()432 .to_vec()pallets/common/src/eth.rsdiffbeforeafterboth--- a/pallets/common/src/eth.rs
+++ b/pallets/common/src/eth.rs
@@ -14,6 +14,8 @@
// You should have received a copy of the GNU General Public License
// along with Unique Network. If not, see <http://www.gnu.org/licenses/>.
+//! The module contains a number of functions for converting and checking etherium identifiers.
+
use up_data_structs::CollectionId;
use sp_core::H160;
@@ -23,6 +25,7 @@
0x17, 0xc4, 0xe6, 0x45, 0x3c, 0xc4, 0x9a, 0xaa, 0xae, 0xac, 0xa8, 0x94, 0xe6, 0xd9, 0x68, 0x3e,
];
+/// Maps the etherium address of the collection in substrate.
pub fn map_eth_to_id(eth: &H160) -> Option<CollectionId> {
if eth[0..16] != ETH_COLLECTION_PREFIX {
return None;
@@ -31,6 +34,8 @@
id_bytes.copy_from_slice(ð[16..20]);
Some(CollectionId(u32::from_be_bytes(id_bytes)))
}
+
+/// Maps the substrate collection id in etherium.
pub fn collection_id_to_address(id: CollectionId) -> H160 {
let mut out = [0; 20];
out[0..16].copy_from_slice(Ð_COLLECTION_PREFIX);
@@ -38,6 +43,7 @@
H160(out)
}
+/// Check if the etherium address is a collection.
pub fn is_collection(address: &H160) -> bool {
address[0..16] == ETH_COLLECTION_PREFIX
}
pallets/common/src/lib.rsdiffbeforeafterboth--- a/pallets/common/src/lib.rs
+++ b/pallets/common/src/lib.rs
@@ -14,8 +14,46 @@
// You should have received a copy of the GNU General Public License
// along with Unique Network. If not, see <http://www.gnu.org/licenses/>.
-#![cfg_attr(not(feature = "std"), no_std)]
+//! # Common pallet
+//!
+//! The Common pallet provides functionality for handling collections.
+//!
+//! ## Overview
+//!
+//! The Common pallet provides functions for:
+//!
+//! - Setting and approving collection soponsor.
+//! - Get\set\delete allow list.
+//! - Get\set\delete collection properties.
+//! - Get\set\delete collection property permissions.
+//! - Get\set\delete token property permissions.
+//! - Get\set\delete collection administrators.
+//! - Checking access permissions.
+//! - Provides an interface for common collection operations for different collection types.
+//! - Provides dispatching for implementations of common collection operations, see [dispatch] module.
+//! - Provides functionality of collection into evm, see [erc] and [eth] module.
+//!
+//! ### Terminology
+//! **Collection sponsor** - For the collection, you can set a sponsor, at whose expense it will
+//! be possible to mint tokens.
+//!
+//! **Allow list** - List of users who have the right to minting tokens.
+//!
+//! **Collection properties** - Collection properties are simply key-value stores where various
+//! metadata can be placed.
+//!
+//! **Collection property permissions** - For each property in the collection can be set permission
+//! to change, see [PropertyPermission].
+//!
+//! **Permissions on token properties** - Similar to _permissions on collection properties_,
+//! only restrictions apply to token properties.
+//!
+//! **Collection administrator** - For a collection, you can set administrators who have the right
+//! to most actions on the collection.
+
+#![warn(missing_docs)]
+#![cfg_attr(not(feature = "std"), no_std)]
extern crate alloc;
use core::ops::{Deref, DerefMut};
@@ -90,14 +128,20 @@
pub mod eth;
pub mod weights;
+/// Weight info.
pub type SelfWeightOf<T> = <T as Config>::WeightInfo;
+/// Collection handle contains information about collection data and id.
+/// Also provides functionality to count consumed gas.
#[must_use = "Should call submit_logs or save, otherwise some data will be lost for evm side"]
pub struct CollectionHandle<T: Config> {
+ /// Collection id
pub id: CollectionId,
collection: Collection<T::AccountId>,
+ /// Substrate recorder for counting consumed gas
pub recorder: SubstrateRecorder<T>,
}
+
impl<T: Config> WithRecorder<T> for CollectionHandle<T> {
fn recorder(&self) -> &SubstrateRecorder<T> {
&self.recorder
@@ -106,7 +150,9 @@
self.recorder
}
}
+
impl<T: Config> CollectionHandle<T> {
+ /// Same as [CollectionHandle::new] but with an explicit gas limit.
pub fn new_with_gas_limit(id: CollectionId, gas_limit: u64) -> Option<Self> {
<CollectionById<T>>::get(id).map(|collection| Self {
id,
@@ -115,6 +161,7 @@
})
}
+ /// Same as [CollectionHandle::new] but with an existed [SubstrateRecorder].
pub fn new_with_recorder(id: CollectionId, recorder: SubstrateRecorder<T>) -> Option<Self> {
<CollectionById<T>>::get(id).map(|collection| Self {
id,
@@ -123,14 +170,18 @@
})
}
+ /// Retrives collection data from storage and creates collection handle with default parameters.
+ /// If collection not found return `None`
pub fn new(id: CollectionId) -> Option<Self> {
Self::new_with_gas_limit(id, u64::MAX)
}
+ /// Same as [CollectionHandle::new] but if collection not found [Error::CollectionNotFound] returned.
pub fn try_get(id: CollectionId) -> Result<Self, DispatchError> {
Ok(Self::new(id).ok_or(<Error<T>>::CollectionNotFound)?)
}
+ /// Consume gas for reading.
pub fn consume_store_reads(&self, reads: u64) -> evm_coder::execution::Result<()> {
self.recorder
.consume_gas(T::GasWeightMapping::weight_to_gas(
@@ -140,6 +191,7 @@
))
}
+ /// Consume gas for writing.
pub fn consume_store_writes(&self, writes: u64) -> evm_coder::execution::Result<()> {
self.recorder
.consume_gas(T::GasWeightMapping::weight_to_gas(
@@ -148,16 +200,27 @@
.saturating_mul(writes),
))
}
+
+ /// Save collection to storage.
pub fn save(self) -> DispatchResult {
<CollectionById<T>>::insert(self.id, self.collection);
Ok(())
}
+ /// Set collection sponsor.
+ ///
+ /// Unique collections allows sponsoring for certain actions.
+ /// This method allows you to set the sponsor of the collection.
+ /// In order for sponsorship to become active, it must be confirmed through [Self::confirm_sponsorship].
pub fn set_sponsor(&mut self, sponsor: T::AccountId) -> DispatchResult {
self.collection.sponsorship = SponsorshipState::Unconfirmed(sponsor);
Ok(())
}
+ /// Confirm sponsorship
+ ///
+ /// In order for the sponsorship to become active, the user set as the sponsor must confirm their participation.
+ /// Before confirming sponsorship, the user must be specified as the sponsor of the collection via [Self::set_sponsor].
pub fn confirm_sponsorship(&mut self, sender: &T::AccountId) -> Result<bool, DispatchError> {
if self.collection.sponsorship.pending_sponsor() != Some(sender) {
return Ok(false);
@@ -168,7 +231,7 @@
}
/// Checks that the collection was created with, and must be operated upon through **Unique API**.
- /// Now check only the `external_collection` flag and if it's **true**, then return `CollectionIsExternal` error.
+ /// Now check only the `external_collection` flag and if it's **true**, then return [Error::CollectionIsExternal] error.
pub fn check_is_internal(&self) -> DispatchResult {
if self.external_collection {
return Err(<Error<T>>::CollectionIsExternal)?;
@@ -178,7 +241,7 @@
}
/// Checks that the collection was created with, and must be operated upon through an **assimilated API**.
- /// Now check only the `external_collection` flag and if it's **false**, then return `CollectionIsInternal` error.
+ /// Now check only the `external_collection` flag and if it's **false**, then return [Error::CollectionIsInternal] error.
pub fn check_is_external(&self) -> DispatchResult {
if !self.external_collection {
return Err(<Error<T>>::CollectionIsInternal)?;
@@ -203,23 +266,34 @@
}
impl<T: Config> CollectionHandle<T> {
- pub fn check_is_owner(&self, subject: &T::CrossAccountId) -> DispatchResult {
- ensure!(*subject.as_sub() == self.owner, <Error<T>>::NoPermission);
+ /// Checks if the `user` is the owner of the collection.
+ pub fn check_is_owner(&self, user: &T::CrossAccountId) -> DispatchResult {
+ ensure!(*user.as_sub() == self.owner, <Error<T>>::NoPermission);
Ok(())
}
- pub fn is_owner_or_admin(&self, subject: &T::CrossAccountId) -> bool {
- *subject.as_sub() == self.owner || <IsAdmin<T>>::get((self.id, subject))
+
+ /// Returns **true** if the `user` is the owner or administrator of the collection.
+ pub fn is_owner_or_admin(&self, user: &T::CrossAccountId) -> bool {
+ *user.as_sub() == self.owner || <IsAdmin<T>>::get((self.id, user))
}
- pub fn check_is_owner_or_admin(&self, subject: &T::CrossAccountId) -> DispatchResult {
- ensure!(self.is_owner_or_admin(subject), <Error<T>>::NoPermission);
+
+ /// Checks if the `user` is the owner or administrator of the collection.
+ pub fn check_is_owner_or_admin(&self, user: &T::CrossAccountId) -> DispatchResult {
+ ensure!(self.is_owner_or_admin(user), <Error<T>>::NoPermission);
Ok(())
}
+
+ /// Return **true** if `user` was not allowed to have tokens, and he can ignore such restrictions.
pub fn ignores_allowance(&self, user: &T::CrossAccountId) -> bool {
self.limits.owner_can_transfer() && self.is_owner_or_admin(user)
}
+
+ /// Return **true** if `user` does not have enough token parts, and he can ignore such restrictions.
pub fn ignores_owned_amount(&self, user: &T::CrossAccountId) -> bool {
self.limits.owner_can_transfer() && self.is_owner_or_admin(user)
}
+
+ /// Checks if the user is in the allow list. If not [Error::AddressNotInAllowlist] returns.
pub fn check_allowlist(&self, user: &T::CrossAccountId) -> DispatchResult {
ensure!(
<Allowlist<T>>::get((self.id, user)),
@@ -249,21 +323,34 @@
+ TypeInfo
+ account::Config
{
+ /// Weight info.
type WeightInfo: WeightInfo;
+
+ /// Events compatible with [frame_system::Config::Event].
type Event: IsType<<Self as frame_system::Config>::Event> + From<Event<Self>>;
+ /// Currency.
type Currency: Currency<Self::AccountId>;
+ /// Price getter to create the collection.
#[pallet::constant]
type CollectionCreationPrice: Get<
<<Self as Config>::Currency as Currency<Self::AccountId>>::Balance,
>;
+
+ /// Collection dispatcher.
type CollectionDispatch: CollectionDispatch<Self>;
+ /// Treasury account id getter.
type TreasuryAccountId: Get<Self::AccountId>;
+
+ /// Contract address getter.
type ContractAddress: Get<H160>;
+ /// Mapper for tokens to Etherium addresses.
type EvmTokenAddressMapping: TokenAddressMapping<H160>;
+
+ /// Mapper for tokens to [CrossAccountId].
type CrossTokenAddressMapping: TokenAddressMapping<Self::CrossAccountId>;
}
@@ -276,6 +363,7 @@
#[pallet::extra_constants]
impl<T: Config> Pallet<T> {
+ /// Maximum admins per collection.
pub fn collection_admins_limit() -> u32 {
COLLECTION_ADMINS_LIMIT
}
@@ -285,94 +373,116 @@
#[pallet::generate_deposit(pub fn deposit_event)]
pub enum Event<T: Config> {
/// New collection was created
- ///
- /// # Arguments
- ///
- /// * collection_id: Globally unique identifier of newly created collection.
- ///
- /// * mode: [CollectionMode] converted into u8.
- ///
- /// * account_id: Collection owner.
- CollectionCreated(CollectionId, u8, T::AccountId),
+ CollectionCreated(
+ /// Globally unique identifier of newly created collection.
+ CollectionId,
+ /// [CollectionMode] converted into _u8_.
+ u8,
+ /// Collection owner.
+ T::AccountId
+ ),
/// New collection was destroyed
- ///
- /// # Arguments
- ///
- /// * collection_id: Globally unique identifier of collection.
- CollectionDestroyed(CollectionId),
+ CollectionDestroyed(
+ /// Globally unique identifier of collection.
+ CollectionId
+ ),
/// New item was created.
- ///
- /// # Arguments
- ///
- /// * collection_id: Id of the collection where item was created.
- ///
- /// * item_id: Id of an item. Unique within the collection.
- ///
- /// * recipient: Owner of newly created item
- ///
- /// * amount: Always 1 for NFT
- ItemCreated(CollectionId, TokenId, T::CrossAccountId, u128),
+ ItemCreated(
+ /// Id of the collection where item was created.
+ CollectionId,
+ /// Id of an item. Unique within the collection.
+ TokenId,
+ /// Owner of newly created item
+ T::CrossAccountId,
+ /// Always 1 for NFT
+ u128
+ ),
/// Collection item was burned.
- ///
- /// # Arguments
- ///
- /// * collection_id.
- ///
- /// * item_id: Identifier of burned NFT.
- ///
- /// * owner: which user has destroyed its tokens
- ///
- /// * amount: Always 1 for NFT
- ItemDestroyed(CollectionId, TokenId, T::CrossAccountId, u128),
+ ItemDestroyed(
+ /// Id of the collection where item was destroyed.
+ CollectionId,
+ /// Identifier of burned NFT.
+ TokenId,
+ /// Which user has destroyed its tokens.
+ T::CrossAccountId,
+ /// Amount of token pieces destroed. Always 1 for NFT.
+ u128),
/// Item was transferred
- ///
- /// * collection_id: Id of collection to which item is belong
- ///
- /// * item_id: Id of an item
- ///
- /// * sender: Original owner of item
- ///
- /// * recipient: New owner of item
- ///
- /// * amount: Always 1 for NFT
Transfer(
+ /// Id of collection to which item is belong.
CollectionId,
+ /// Id of an item.
TokenId,
+ /// Original owner of item.
T::CrossAccountId,
+ /// New owner of item.
T::CrossAccountId,
+ /// Amount of token pieces transfered. Always 1 for NFT.
u128,
),
- /// * collection_id
- ///
- /// * item_id
- ///
- /// * sender
- ///
- /// * spender
- ///
- /// * amount
+ /// Amount pieces of token owned by `sender` was approved for `spender`.
Approved(
+ /// Id of collection to which item is belong.
CollectionId,
+ /// Id of an item.
TokenId,
+ /// Original owner of item.
T::CrossAccountId,
+ /// Id for which the approval was granted.
T::CrossAccountId,
+ /// Amount of token pieces transfered. Always 1 for NFT.
u128,
),
- CollectionPropertySet(CollectionId, PropertyKey),
-
- CollectionPropertyDeleted(CollectionId, PropertyKey),
-
- TokenPropertySet(CollectionId, TokenId, PropertyKey),
-
- TokenPropertyDeleted(CollectionId, TokenId, PropertyKey),
-
- PropertyPermissionSet(CollectionId, PropertyKey),
+ /// The colletion property has been set.
+ CollectionPropertySet(
+ /// Id of collection to which property has been set.
+ CollectionId,
+ /// The property that was set.
+ PropertyKey
+ ),
+
+ /// The property has been deleted.
+ CollectionPropertyDeleted(
+ /// Id of collection to which property has been deleted.
+ CollectionId,
+ /// The property that was deleted.
+ PropertyKey
+ ),
+
+ /// The token property has been set.
+ TokenPropertySet(
+ /// Identifier of the collection whose token has the property set.
+ CollectionId,
+ /// The token for which the property was set.
+ TokenId,
+ /// The property that was set.
+ PropertyKey
+ ),
+
+
+ /// The token property has been deleted.
+ TokenPropertyDeleted(
+ /// Identifier of the collection whose token has the property deleted.
+ CollectionId,
+ /// The token for which the property was deleted.
+ TokenId,
+ /// The property that was deleted.
+ PropertyKey
+ ),
+
+ /// The colletion property permission has been set.
+ PropertyPermissionSet(
+ /// Id of collection to which property permission has been set.
+ CollectionId,
+ /// The property permission that was set.
+ PropertyKey
+ ),
}
#[pallet::error]
@@ -460,13 +570,16 @@
CollectionIsInternal,
}
+ /// Storage of the count of created collections.
#[pallet::storage]
pub type CreatedCollectionCount<T> = StorageValue<Value = CollectionId, QueryKind = ValueQuery>;
+
+ /// Storage of the count of deleted collections.
#[pallet::storage]
pub type DestroyedCollectionCount<T> =
StorageValue<Value = CollectionId, QueryKind = ValueQuery>;
- /// Collection info
+ /// Storage of collection info.
#[pallet::storage]
pub type CollectionById<T> = StorageMap<
Hasher = Blake2_128Concat,
@@ -475,7 +588,7 @@
QueryKind = OptionQuery,
>;
- /// Collection properties
+ /// Storage of collection properties.
#[pallet::storage]
#[pallet::getter(fn collection_properties)]
pub type CollectionProperties<T> = StorageMap<
@@ -486,6 +599,7 @@
OnEmpty = up_data_structs::CollectionProperties,
>;
+ /// Storage of collection properties permissions.
#[pallet::storage]
#[pallet::getter(fn property_permissions)]
pub type CollectionPropertyPermissions<T> = StorageMap<
@@ -495,6 +609,7 @@
QueryKind = ValueQuery,
>;
+ /// Storage of collection admins count.
#[pallet::storage]
pub type AdminAmount<T> = StorageMap<
Hasher = Blake2_128Concat,
@@ -525,7 +640,7 @@
QueryKind = ValueQuery,
>;
- /// Not used by code, exists only to provide some types to metadata
+ /// Not used by code, exists only to provide some types to metadata.
#[pallet::storage]
pub type DummyStorageValue<T: Config> = StorageValue<
Value = (
@@ -619,7 +734,9 @@
}
impl<T: Config> Pallet<T> {
- /// Ethereum receiver 0x0000000000000000000000000000000000000000 is reserved, and shouldn't own tokens
+ /// Enshure that receiver address is correct.
+ ///
+ /// Ethereum receiver 0x0000000000000000000000000000000000000000 is reserved, and shouldn't own tokens.
pub fn ensure_correct_receiver(receiver: &T::CrossAccountId) -> DispatchResult {
ensure!(
&T::CrossAccountId::from_eth(H160([0; 20])) != receiver,
@@ -627,19 +744,27 @@
);
Ok(())
}
+
+ /// Get a vector of collection admins.
pub fn adminlist(collection: CollectionId) -> Vec<T::CrossAccountId> {
<IsAdmin<T>>::iter_prefix((collection,))
.map(|(a, _)| a)
.collect()
}
+
+ /// Get a vector of users allowed to mint tokens.
pub fn allowlist(collection: CollectionId) -> Vec<T::CrossAccountId> {
<Allowlist<T>>::iter_prefix((collection,))
.map(|(a, _)| a)
.collect()
}
+
+ /// Is `user` allowed to mint token in `collection`.
pub fn allowed(collection: CollectionId, user: T::CrossAccountId) -> bool {
<Allowlist<T>>::get((collection, user))
}
+
+ /// Get statistics of collections.
pub fn collection_stats() -> CollectionStats {
let created = <CreatedCollectionCount<T>>::get();
let destroyed = <DestroyedCollectionCount<T>>::get();
@@ -650,6 +775,7 @@
}
}
+ /// Get the effective limits for the collection.
pub fn effective_collection_limits(collection: CollectionId) -> Option<CollectionLimits> {
let collection = <CollectionById<T>>::get(collection);
if collection.is_none() {
@@ -683,6 +809,7 @@
Some(effective_limits)
}
+ /// Returns information about the `collection` adapted for rpc.
pub fn rpc_collection(collection: CollectionId) -> Option<RpcCollection<T::AccountId>> {
let Collection {
name,
@@ -758,9 +885,14 @@
}
impl<T: Config> Pallet<T> {
+ /// Create new collection.
+ ///
+ /// * `owner` - The owner of the collection.
+ /// * `data` - Description of the created collection.
+ /// * `is_external` - Marks that collection managet by not "Unique network".
pub fn init_collection(
owner: T::CrossAccountId,
- data: CreateCollectionData<T::AccountId>,
+ data: CreateCollectionData<T::AccountId>,
is_external: bool,
) -> Result<CollectionId, DispatchError> {
{
@@ -858,6 +990,10 @@
Ok(id)
}
+ /// Destroy collection.
+ ///
+ /// * `collection` - Collection handler.
+ /// * `sender` - The owner or administrator of the collection.
pub fn destroy_collection(
collection: CollectionHandle<T>,
sender: &T::CrossAccountId,
@@ -886,6 +1022,11 @@
Ok(())
}
+ /// Set collection property.
+ ///
+ /// * `collection` - Collection handler.
+ /// * `sender` - The owner or administrator of the collection.
+ /// * `property` - The property to set.
pub fn set_collection_property(
collection: &CollectionHandle<T>,
sender: &T::CrossAccountId,
@@ -904,6 +1045,11 @@
Ok(())
}
+ /// Set scouped collection property.
+ ///
+ /// * `collection_id` - ID of the collection for which the property is being set.
+ /// * `scope` - Property scope.
+ /// * `property` - The property to set.
pub fn set_scoped_collection_property(
collection_id: CollectionId,
scope: PropertyScope,
@@ -913,10 +1059,15 @@
properties.try_scoped_set(scope, property.key, property.value)
})
.map_err(<Error<T>>::from)?;
-
+
Ok(())
}
-
+
+ /// Set scouped collection properties.
+ ///
+ /// * `collection_id` - ID of the collection for which the properties is being set.
+ /// * `scope` - Property scope.
+ /// * `properties` - The properties to set.
pub fn set_scoped_collection_properties(
collection_id: CollectionId,
scope: PropertyScope,
@@ -930,6 +1081,11 @@
Ok(())
}
+ /// Set collection properties.
+ ///
+ /// * `collection` - Collection handler.
+ /// * `sender` - The owner or administrator of the collection.
+ /// * `properties` - The properties to set.
#[transactional]
pub fn set_collection_properties(
collection: &CollectionHandle<T>,
@@ -939,30 +1095,40 @@
for property in properties {
Self::set_collection_property(collection, sender, property)?;
}
-
+
Ok(())
}
-
+
+ /// Delete collection property.
+ ///
+ /// * `collection` - Collection handler.
+ /// * `sender` - The owner or administrator of the collection.
+ /// * `property` - The property to delete.
pub fn delete_collection_property(
collection: &CollectionHandle<T>,
sender: &T::CrossAccountId,
property_key: PropertyKey,
) -> DispatchResult {
collection.check_is_owner_or_admin(sender)?;
-
+
CollectionProperties::<T>::try_mutate(collection.id, |properties| {
properties.remove(&property_key)
})
.map_err(<Error<T>>::from)?;
-
+
Self::deposit_event(Event::CollectionPropertyDeleted(
collection.id,
property_key,
));
-
+
Ok(())
}
-
+
+ /// Delete collection properties.
+ ///
+ /// * `collection` - Collection handler.
+ /// * `sender` - The owner or administrator of the collection.
+ /// * `properties` - The properties to delete.
#[transactional]
pub fn delete_collection_properties(
collection: &CollectionHandle<T>,
@@ -972,11 +1138,16 @@
for key in property_keys {
Self::delete_collection_property(collection, sender, key)?;
}
-
+
Ok(())
}
-
- // For migrations
+
+ /// Set collection propetry permission without any checks.
+ ///
+ /// Used for migrations.
+ ///
+ /// * `collection` - Collection handler.
+ /// * `property_permissions` - Property permissions.
pub fn set_property_permission_unchecked(
collection: CollectionId,
property_permission: PropertyKeyPermission,
@@ -988,6 +1159,11 @@
Ok(())
}
+ /// Set collection property permission.
+ ///
+ /// * `collection` - Collection handler.
+ /// * `sender` - The owner or administrator of the collection.
+ /// * `property_permission` - Property permission.
pub fn set_property_permission(
collection: &CollectionHandle<T>,
sender: &T::CrossAccountId,
@@ -1018,6 +1194,11 @@
Ok(())
}
+ /// Set token property permission.
+ ///
+ /// * `collection` - Collection handler.
+ /// * `sender` - The owner or administrator of the collection.
+ /// * `property_permissions` - Property permissions.
#[transactional]
pub fn set_token_property_permissions(
collection: &CollectionHandle<T>,
@@ -1031,6 +1212,7 @@
Ok(())
}
+ /// Get collection property.
pub fn get_collection_property(
collection_id: CollectionId,
key: &PropertyKey,
@@ -1038,6 +1220,7 @@
Self::collection_properties(collection_id).get(key).cloned()
}
+ /// Convert byte vector to property key vector.
pub fn bytes_keys_to_property_keys(
keys: Vec<Vec<u8>>,
) -> Result<Vec<PropertyKey>, DispatchError> {
@@ -1049,6 +1232,7 @@
.collect::<Result<Vec<PropertyKey>, DispatchError>>()
}
+ /// Get properties according to given keys.
pub fn filter_collection_properties(
collection_id: CollectionId,
keys: Option<Vec<PropertyKey>>,
@@ -1076,6 +1260,7 @@
Ok(properties)
}
+ /// Get property permissions according to given keys.
pub fn filter_property_permissions(
collection_id: CollectionId,
keys: Option<Vec<PropertyKey>>,
@@ -1105,6 +1290,7 @@
Ok(key_permissions)
}
+ /// Toggle `user` participation in the `collection`'s allow list.
pub fn toggle_allowlist(
collection: &CollectionHandle<T>,
sender: &T::CrossAccountId,
@@ -1124,6 +1310,7 @@
Ok(())
}
+ /// Toggle `user` participation in the `collection`'s admin list.
pub fn toggle_admin(
collection: &CollectionHandle<T>,
sender: &T::CrossAccountId,
@@ -1159,6 +1346,7 @@
Ok(())
}
+ /// Merge set fields from `new_limit` to `old_limit`.
pub fn clamp_limits(
mode: CollectionMode,
old_limit: &CollectionLimits,
@@ -1204,20 +1392,22 @@
Ok(new_limit)
}
+ /// Merge set fields from `new_permission` to `old_permission`.
pub fn clamp_permissions(
_mode: CollectionMode,
- old_limit: &CollectionPermissions,
- mut new_limit: CollectionPermissions,
+ old_permission: &CollectionPermissions,
+ mut new_permission: CollectionPermissions,
) -> Result<CollectionPermissions, DispatchError> {
- limit_default_clone!(old_limit, new_limit,
+ limit_default_clone!(old_permission, new_permission,
access => {},
mint_mode => {},
nesting => { /* todo check for permissive, if only it gets out of benchmarks */ },
);
- Ok(new_limit)
+ Ok(new_permission)
}
}
+/// Indicates unsupported methods by returning [Error::UnsupportedOperation].
#[macro_export]
macro_rules! unsupported {
() => {
@@ -1225,32 +1415,72 @@
};
}
-/// Worst cases
+/// Return weights for various worst-case operations.
pub trait CommonWeightInfo<CrossAccountId> {
+ /// Weight of item creation.
fn create_item() -> Weight;
+
+ /// Weight of items creation.
fn create_multiple_items(amount: &[CreateItemData]) -> Weight;
+
+ /// Weight of items creation.
fn create_multiple_items_ex(cost: &CreateItemExData<CrossAccountId>) -> Weight;
+
+ /// The weight of the burning item.
fn burn_item() -> Weight;
+
+ /// Property setting weight.
+ ///
+ /// * `amount`- The number of properties to set.
fn set_collection_properties(amount: u32) -> Weight;
+
+ /// Collection property deletion weight.
+ ///
+ /// * `amount`- The number of properties to set.
fn delete_collection_properties(amount: u32) -> Weight;
+
+ /// Token property setting weight.
+ ///
+ /// * `amount`- The number of properties to set.
fn set_token_properties(amount: u32) -> Weight;
+
+ /// Token property deletion weight.
+ ///
+ /// * `amount`- The number of properties to delete.
fn delete_token_properties(amount: u32) -> Weight;
+
+
+ /// Token property permissions set weight.
+ ///
+ /// * `amount`- The number of property permissions to set.
fn set_token_property_permissions(amount: u32) -> Weight;
+
+ /// Transfer price of the token or its parts.
fn transfer() -> Weight;
+
+ /// The price of setting the permission of the operation from another user.
fn approve() -> Weight;
+
+ /// Transfer price from another user.
fn transfer_from() -> Weight;
- fn burn_from() -> Weight;
+ /// The price of burning a token from another user.
+ fn burn_from() -> Weight;
+
/// Differs from burn_item in case of Fungible and Refungible, as it should burn
/// whole users's balance
///
- /// This method shouldn't be used directly, as it doesn't count breadth price, use `burn_recursively` instead
+ /// This method shouldn't be used directly, as it doesn't count breadth price, use [burn_recursively](CommonWeightInfo::burn_recursively) instead
fn burn_recursively_self_raw() -> Weight;
+
/// Cost of iterating over `amount` children while burning, without counting child burning itself
///
- /// This method shouldn't be used directly, as it doesn't count depth price, use `burn_recursively` instead
+ /// This method shouldn't be used directly, as it doesn't count depth price, use [burn_recursively](CommonWeightInfo::burn_recursively) instead
fn burn_recursively_breadth_raw(amount: u32) -> Weight;
-
+
+ /// The price of recursive burning a token.
+ ///
+ /// `max_selfs` -
fn burn_recursively(max_selfs: u32, max_breadth: u32) -> Weight {
Self::burn_recursively_self_raw()
.saturating_mul(max_selfs.max(1) as u64)
@@ -1258,11 +1488,23 @@
}
}
+/// Weight info extension trait for refungible pallet.
pub trait RefungibleExtensionsWeightInfo {
+ /// Weight of token repartition.
fn repartition() -> Weight;
}
+/// Common collection operations.
+///
+/// It wraps methods in Fungible, Nonfungible and Refungible pallets
+/// and adds weight info.
pub trait CommonCollectionOperations<T: Config> {
+ /// Create token.
+ ///
+ /// * `sender` - The user who mint the token and pays for the transaction.
+ /// * `to` - The user who will own the token.
+ /// * `data` - Token data.
+ /// * `nesting_budget` - A budget that can be spent on nesting tokens.
fn create_item(
&self,
sender: T::CrossAccountId,
@@ -1270,6 +1512,13 @@
data: CreateItemData,
nesting_budget: &dyn Budget,
) -> DispatchResultWithPostInfo;
+
+ /// Create multiple tokens.
+ ///
+ /// * `sender` - The user who mint the token and pays for the transaction.
+ /// * `to` - The user who will own the token.
+ /// * `data` - Token data.
+ /// * `nesting_budget` - A budget that can be spent on nesting tokens.
fn create_multiple_items(
&self,
sender: T::CrossAccountId,
@@ -1277,18 +1526,38 @@
data: Vec<CreateItemData>,
nesting_budget: &dyn Budget,
) -> DispatchResultWithPostInfo;
+
+ /// Create multiple tokens.
+ ///
+ /// * `sender` - The user who mint the token and pays for the transaction.
+ /// * `to` - The user who will own the token.
+ /// * `data` - Token data.
+ /// * `nesting_budget` - A budget that can be spent on nesting tokens.
fn create_multiple_items_ex(
&self,
sender: T::CrossAccountId,
data: CreateItemExData<T::CrossAccountId>,
nesting_budget: &dyn Budget,
) -> DispatchResultWithPostInfo;
+
+ /// Burn token.
+ ///
+ /// * `sender` - The user who owns the token.
+ /// * `token` - Token id that will burned.
+ /// * `amount` - The number of parts of the token that will be burned.
fn burn_item(
&self,
sender: T::CrossAccountId,
token: TokenId,
amount: u128,
) -> DispatchResultWithPostInfo;
+
+ /// Burn token and all nested tokens recursievly.
+ ///
+ /// * `sender` - The user who owns the token.
+ /// * `token` - Token id that will burned.
+ /// * `self_budget` - The budget that can be spent on burning tokens.
+ /// * `breadth_budget` - The budget that can be spent on burning nested tokens.
fn burn_item_recursively(
&self,
sender: T::CrossAccountId,
@@ -1296,43 +1565,95 @@
self_budget: &dyn Budget,
breadth_budget: &dyn Budget,
) -> DispatchResultWithPostInfo;
+
+ /// Set collection properties.
+ ///
+ /// * `sender` - Must be either the owner of the collection or its admin.
+ /// * `properties` - Properties to be set.
fn set_collection_properties(
&self,
sender: T::CrossAccountId,
properties: Vec<Property>,
) -> DispatchResultWithPostInfo;
+
+ /// Delete collection properties.
+ ///
+ /// * `sender` - Must be either the owner of the collection or its admin.
+ /// * `properties` - The properties to be removed.
fn delete_collection_properties(
&self,
sender: &T::CrossAccountId,
property_keys: Vec<PropertyKey>,
) -> DispatchResultWithPostInfo;
+
+ /// Set token properties.
+ ///
+ /// The appropriate [PropertyPermission] for the token property
+ /// must be set with [Self::set_token_property_permissions].
+ ///
+ /// * `sender` - Must be either the owner of the token or its admin.
+ /// * `token_id` - The token for which the properties are being set.
+ /// * `properties` - Properties to be set.
+ /// * `budget` - Budget for setting properties.
fn set_token_properties(
&self,
sender: T::CrossAccountId,
token_id: TokenId,
- property: Vec<Property>,
- nesting_budget: &dyn Budget,
+ properties: Vec<Property>,
+ budget: &dyn Budget,
) -> DispatchResultWithPostInfo;
+
+ /// Remove token properties.
+ ///
+ /// The appropriate [PropertyPermission] for the token property
+ /// must be set with [Self::set_token_property_permissions].
+ ///
+ /// * `sender` - Must be either the owner of the token or its admin.
+ /// * `token_id` - The token for which the properties are being remove.
+ /// * `property_keys` - Keys to remove corresponding properties.
+ /// * `budget` - Budget for removing properties.
fn delete_token_properties(
&self,
sender: T::CrossAccountId,
token_id: TokenId,
property_keys: Vec<PropertyKey>,
- nesting_budget: &dyn Budget,
+ budget: &dyn Budget,
) -> DispatchResultWithPostInfo;
+
+ /// Set token property permissions.
+ ///
+ /// * `sender` - Must be either the owner of the token or its admin.
+ /// * `token_id` - The token for which the properties are being set.
+ /// * `properties` - Properties to be set.
+ /// * `budget` - Budget for setting properties.
fn set_token_property_permissions(
&self,
sender: &T::CrossAccountId,
property_permissions: Vec<PropertyKeyPermission>,
) -> DispatchResultWithPostInfo;
+
+ /// Transfer amount of token pieces.
+ ///
+ /// * `sender` - Donor user.
+ /// * `to` - Recepient user.
+ /// * `token` - The token of which parts are being sent.
+ /// * `amount` - The number of parts of the token that will be transferred.
+ /// * `budget` - The maximum budget that can be spent on the transfer.
fn transfer(
&self,
sender: T::CrossAccountId,
to: T::CrossAccountId,
token: TokenId,
amount: u128,
- nesting_budget: &dyn Budget,
+ budget: &dyn Budget,
) -> DispatchResultWithPostInfo;
+
+ /// Grant access to another account to transfer parts of the token owned by the calling user via [Self::transfer_from].
+ ///
+ /// * `sender` - The user who grants access to the token.
+ /// * `spender` - The user to whom the rights are granted.
+ /// * `token` - The token to which access is granted.
+ /// * `amount` - The amount of pieces that another user can dispose of.
fn approve(
&self,
sender: T::CrossAccountId,
@@ -1340,6 +1661,17 @@
token: TokenId,
amount: u128,
) -> DispatchResultWithPostInfo;
+
+ /// Send parts of a token owned by another user.
+ ///
+ /// Before calling this method, you must grant rights to the calling user via [Self::approve].
+ ///
+ /// * `sender` - The user who has access to the token.
+ /// * `from` - The user who owns the token.
+ /// * `to` - Recepient user.
+ /// * `token` - The token of which parts are being sent.
+ /// * `amount` - The number of parts of the token that will be transferred.
+ /// * `budget` - The maximum budget that can be spent on the transfer.
fn transfer_from(
&self,
sender: T::CrossAccountId,
@@ -1347,67 +1679,140 @@
to: T::CrossAccountId,
token: TokenId,
amount: u128,
- nesting_budget: &dyn Budget,
+ budget: &dyn Budget,
) -> DispatchResultWithPostInfo;
+
+ /// Burn parts of a token owned by another user.
+ ///
+ /// Before calling this method, you must grant rights to the calling user via [Self::approve].
+ ///
+ /// * `sender` - The user who has access to the token.
+ /// * `from` - The user who owns the token.
+ /// * `token` - The token of which parts are being sent.
+ /// * `amount` - The number of parts of the token that will be transferred.
+ /// * `budget` - The maximum budget that can be spent on the burn.
fn burn_from(
&self,
sender: T::CrossAccountId,
from: T::CrossAccountId,
token: TokenId,
amount: u128,
- nesting_budget: &dyn Budget,
+ budget: &dyn Budget,
) -> DispatchResultWithPostInfo;
+ /// Check permission to nest token.
+ ///
+ /// * `sender` - The user who initiated the check.
+ /// * `from` - The token that is checked for embedding.
+ /// * `under` - Token under which to check.
+ /// * `budget` - The maximum budget that can be spent on the check.
fn check_nesting(
&self,
sender: T::CrossAccountId,
from: (CollectionId, TokenId),
under: TokenId,
- nesting_budget: &dyn Budget,
+ budget: &dyn Budget,
) -> DispatchResult;
+ /// Nest one token into another.
+ ///
+ /// * `under` - Token holder.
+ /// * `to_nest` - Nested token.
fn nest(&self, under: TokenId, to_nest: (CollectionId, TokenId));
+ /// Unnest token.
+ ///
+ /// * `under` - Token holder.
+ /// * `to_nest` - Token to unnest.
fn unnest(&self, under: TokenId, to_nest: (CollectionId, TokenId));
+ /// Get all user tokens.
+ ///
+ /// * `account` - Account for which you need to get tokens.
fn account_tokens(&self, account: T::CrossAccountId) -> Vec<TokenId>;
+
+ /// Get all the tokens in the collection.
fn collection_tokens(&self) -> Vec<TokenId>;
+
+ /// Check if the token exists.
+ ///
+ /// * `token` - Id token to check.
fn token_exists(&self, token: TokenId) -> bool;
+
+ /// Get the id of the last minted token.
fn last_token_id(&self) -> TokenId;
+ /// Get the owner of the token.
+ ///
+ /// * `token` - The token for which you need to find out the owner.
fn token_owner(&self, token: TokenId) -> Option<T::CrossAccountId>;
+
+ /// Get the value of the token property by key.
+ ///
+ /// * `token` - Token property to get.
+ /// * `key` - Property name.
fn token_property(&self, token_id: TokenId, key: &PropertyKey) -> Option<PropertyValue>;
- fn token_properties(&self, token_id: TokenId, keys: Option<Vec<PropertyKey>>) -> Vec<Property>;
+
+ /// Get a set of token properties by key vector.
+ ///
+ /// * `token` - Token property to get.
+ /// * `keys` - Vector of keys. If this parameter is [None](sp_std::result::Result),
+ /// then all properties are returned.
+ fn token_properties(&self, token: TokenId, keys: Option<Vec<PropertyKey>>) -> Vec<Property>;
+
/// Amount of unique collection tokens
fn total_supply(&self) -> u32;
- /// Amount of different tokens account has (Applicable to nonfungible/refungible)
+
+ /// Amount of different tokens account has.
+ ///
+ /// * `account` - The account for which need to get the balance.
fn account_balance(&self, account: T::CrossAccountId) -> u32;
- /// Amount of specific token account have (Applicable to fungible/refungible)
+
+ /// Amount of specific token account have.
fn balance(&self, account: T::CrossAccountId, token: TokenId) -> u128;
+
/// Amount of token pieces
fn total_pieces(&self, token: TokenId) -> Option<u128>;
+
+ /// Get the number of parts of the token that a trusted user can manage.
+ ///
+ /// * `sender` - Trusted user.
+ /// * `spender` - Owner of the token.
+ /// * `token` - The token for which to get the value.
fn allowance(
&self,
sender: T::CrossAccountId,
spender: T::CrossAccountId,
token: TokenId,
) -> u128;
+
+ /// Get extension for RFT collection.
fn refungible_extensions(&self) -> Option<&dyn RefungibleExtensions<T>>;
}
+/// Extension for RFT collection.
pub trait RefungibleExtensions<T>
where
T: Config,
{
+ /// Change the number of parts of the token.
+ ///
+ /// When the value changes down, this function is equivalent to burning parts of the token.
+ ///
+ /// * `sender` - The user calling the repartition operation. Must be the owner of the token.
+ /// * `token` - The token for which you want to change the number of parts.
+ /// * `amount` - The new value of the parts of the token.
fn repartition(
&self,
- owner: &T::CrossAccountId,
+ sender: &T::CrossAccountId,
token: TokenId,
amount: u128,
) -> DispatchResultWithPostInfo;
}
-// Flexible enough for implementing CommonCollectionOperations
+/// Merge [DispatchResult] with [Weight] into [DispatchResultWithPostInfo].
+///
+/// Used for [CommonCollectionOperations] implementations and flexible enough to do so.
pub fn with_weight(res: DispatchResult, weight: Weight) -> DispatchResultWithPostInfo {
let post_info = PostDispatchInfo {
actual_weight: Some(weight),