From 270ecfc60b89351694ef864602559d4f1a55c065 Mon Sep 17 00:00:00 2001 From: Grigoriy Simonov Date: Wed, 13 Jul 2022 12:33:14 +0000 Subject: [PATCH] doc: added documentation for structure pallet --- --- a/pallets/structure/src/benchmarking.rs +++ b/pallets/structure/src/benchmarking.rs @@ -1,3 +1,19 @@ +// Copyright 2019-2022 Unique Network (Gibraltar) Ltd. +// This file is part of Unique Network. + +// Unique Network is free software: you can redistribute it and/or modify +// it under the terms of the GNU General Public License as published by +// the Free Software Foundation, either version 3 of the License, or +// (at your option) any later version. + +// Unique Network is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +// GNU General Public License for more details. + +// You should have received a copy of the GNU General Public License +// along with Unique Network. If not, see . + use super::*; use frame_benchmarking::{benchmarks, account}; --- a/pallets/structure/src/lib.rs +++ b/pallets/structure/src/lib.rs @@ -1,3 +1,60 @@ +// Copyright 2019-2022 Unique Network (Gibraltar) Ltd. +// This file is part of Unique Network. + +// Unique Network is free software: you can redistribute it and/or modify +// it under the terms of the GNU General Public License as published by +// the Free Software Foundation, either version 3 of the License, or +// (at your option) any later version. + +// Unique Network is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +// GNU General Public License for more details. + +// You should have received a copy of the GNU General Public License +// along with Unique Network. If not, see . + +//! # Structure Pallet +//! +//! The Structure pallet provides functionality for handling tokens nesting an unnesting. +//! +//! - [`Config`] +//! - [`Pallet`] +//! +//! ## Overview +//! +//! The Structure pallet provides functions for: +//! +//! - Searching for token parents, children and owners. Actual implementation of searching for +//! parent/child is done by pallets corresponding to token's collection type. +//! - Nesting and unnesting tokens. Actual implementation of nesting is done by pallets corresponding +//! to token's collection type. +//! +//! ### Terminology +//! +//! - **Nesting:** Setting up parent-child relationship between tokens. Nested tokens are inhereting +//! owner from their parent. There could be multiple levels of nesting. Token couldn't be nested in +//! it's child token i.e. parent-child relationship graph shouldn't have +//! +//! - **Parent:** Token that current token is nested in. +//! +//! - **Owner:** Account that owns the token and all nested tokens. +//! +//! ## Interface +//! +//! ### Dispatchable Functions +//! +//! - `find_parent` - Find parent of the token. It could be an account or another token. +//! - `parent_chain` - Find chain of parents of the token. +//! - `find_topmost_owner` - Find account or token in the end of the chain of parents. +//! - `check_nesting` - Check if the token could be nested in the other token +//! - `nest_if_sent_to_token` - Nest the token in the other token +//! - `unnest_if_nested` - Unnest the token from the other token +//! +//! ## Assumptions +//! +//! * Total issued balanced of all accounts should be less than `Config::Balance::max_value()`. + #![cfg_attr(not(feature = "std"), no_std)] use pallet_common::CommonCollectionOperations; @@ -82,6 +139,12 @@ } impl Pallet { + /// Find account owning the `token` or a token that the `token` is nested in. + /// + /// Returns the enum that have three variants: + /// - [`User`](crate::Parent::User): Contains account. + /// - [`Token`](crate::Parent::Token): Contains token id and collection id. + /// - [`TokenNotFound`](crate::Parent::TokenNotFound): Indicates that parent was not found pub fn find_parent( collection: CollectionId, token: TokenId, @@ -103,6 +166,10 @@ }) } + /// Find chain of parents of current token + /// + /// Returns the parent of the current token, than the parent of the parent and so on until token without a parent + /// is returned. Returns error if cycle is detected. pub fn parent_chain( mut collection: CollectionId, mut token: TokenId, @@ -133,6 +200,8 @@ /// Try to dereference address, until finding top level owner /// /// May return token address if parent token not yet exists + /// + /// - `budget`: Limit for searching parents in depth. pub fn find_topmost_owner( collection: CollectionId, token: TokenId, @@ -149,6 +218,10 @@ }) } + /// Find the topmost parent and check that assigning `for_nest` token as a parent for + /// any token in the parents chain wouldn't create a cycle. + /// + /// - `budget`: Limit for searching parents in depth. pub fn get_checked_topmost_owner( collection: CollectionId, token: TokenId, @@ -177,6 +250,10 @@ Err(>::DepthLimit.into()) } + /// Burn token and all of it's nested tokens + /// + /// - `self_budget`: Limit for searching children in depth. + /// - `breadth_budget`: Limit of breadth of searching children. pub fn burn_item_recursively( from: T::CrossAccountId, collection: CollectionId, @@ -190,7 +267,14 @@ dispatch.burn_item_recursively(from.clone(), token, self_budget, breadth_budget) } - /// Check if token indirectly owned by specified user + /// Check if `token` indirectly owned by `user` + /// + /// Returns `true` if `user` is `token`'s owner. Or If token is provided as `user` then + /// check that `user` and `token` have same owner. + /// Checks that assigning `for_nest` token as a parent for any token in the `token`'s + /// parents chain wouldn't create a cycle. + /// + /// - `budget`: Limit for searching parents in depth. pub fn check_indirectly_owned( user: T::CrossAccountId, collection: CollectionId, @@ -207,6 +291,12 @@ .map(|indirect_owner| indirect_owner == target_parent) } + /// Checks that `under` is valid token and that `token_id` could be nested under it + /// and that `from` is `under`'s owner + /// + /// Returns OK if `under` is not a token + /// + /// - `nesting_budget`: Limit for searching parents in depth. pub fn check_nesting( from: T::CrossAccountId, under: &T::CrossAccountId, @@ -219,6 +309,11 @@ }) } + /// Nests `token_id` under `under` token + /// + /// Returns OK if `under` is not a token. Checks that nesting is possible. + /// + /// - `nesting_budget`: Limit for searching parents in depth. pub fn nest_if_sent_to_token( from: T::CrossAccountId, under: &T::CrossAccountId, @@ -235,6 +330,7 @@ }) } + /// Nests `token_id` under `owner` token pub fn nest_if_sent_to_token_unchecked( owner: &T::CrossAccountId, collection_id: CollectionId, @@ -245,6 +341,7 @@ }); } + /// Unnests `token_id` from `owner`. pub fn unnest_if_nested( owner: &T::CrossAccountId, collection_id: CollectionId, -- gitstuff