git.delta.rocks / unique-network / refs/commits / 270ecfc60b89

1// Copyright 2019-2022 Unique Network (Gibraltar) Ltd.
2// This file is part of Unique Network.
3
4// Unique Network is free software: you can redistribute it and/or modify
5// it under the terms of the GNU General Public License as published by
6// the Free Software Foundation, either version 3 of the License, or
7// (at your option) any later version.
8
9// Unique Network is distributed in the hope that it will be useful,
10// but WITHOUT ANY WARRANTY; without even the implied warranty of
11// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12// GNU General Public License for more details.
13
14// You should have received a copy of the GNU General Public License
15// along with Unique Network. If not, see <http://www.gnu.org/licenses/>.
16
1use super::*;17use super::*;
218

1// Copyright 2019-2022 Unique Network (Gibraltar) Ltd.
2// This file is part of Unique Network.
3
4// Unique Network is free software: you can redistribute it and/or modify
5// it under the terms of the GNU General Public License as published by
6// the Free Software Foundation, either version 3 of the License, or
7// (at your option) any later version.
8
9// Unique Network is distributed in the hope that it will be useful,
10// but WITHOUT ANY WARRANTY; without even the implied warranty of
11// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12// GNU General Public License for more details.
13
14// You should have received a copy of the GNU General Public License
15// along with Unique Network. If not, see <http://www.gnu.org/licenses/>.
16
17//! # Structure Pallet
18//!
19//! The Structure pallet provides functionality for handling tokens nesting an unnesting.
20//!
21//! - [`Config`]
22//! - [`Pallet`]
23//!
24//! ## Overview
25//!
26//! The Structure pallet provides functions for:
27//!
28//! - Searching for token parents, children and owners. Actual implementation of searching for
29//!   parent/child is done by pallets corresponding to token's collection type.
30//! - Nesting and unnesting tokens. Actual implementation of nesting is done by pallets corresponding
31//!   to token's collection type.
32//!
33//! ### Terminology
34//!
35//! - **Nesting:** Setting up parent-child relationship between tokens. Nested tokens are inhereting
36//!   owner from their parent. There could be multiple levels of nesting. Token couldn't be nested in
37//!   it's child token i.e. parent-child relationship graph shouldn't have
38//!
39//! - **Parent:** Token that current token is nested in.
40//!
41//! - **Owner:** Account that owns the token and all nested tokens.
42//!
43//! ## Interface
44//!
45//! ### Dispatchable Functions
46//!
47//! - `find_parent` - Find parent of the token. It could be an account or another token.
48//! - `parent_chain` - Find chain of parents of the token.
49//! - `find_topmost_owner` - Find account or token in the end of the chain of parents.
50//! - `check_nesting` - Check if the token could be nested in the other token
51//! - `nest_if_sent_to_token` - Nest the token in the other token
52//! - `unnest_if_nested` - Unnest the token from the other token
53//!
54//! ## Assumptions
55//!
56//! * Total issued balanced of all accounts should be less than `Config::Balance::max_value()`.
57
1#![cfg_attr(not(feature = "std"), no_std)]58#![cfg_attr(not(feature = "std"), no_std)]
259
82}139}
83140
84impl<T: Config> Pallet<T> {141impl<T: Config> Pallet<T> {
142	/// Find account owning the `token` or a token that the `token` is nested in.
143	///
144	/// Returns the enum that have three variants:
145	/// - [`User`](crate::Parent<T>::User): Contains account.
146	/// - [`Token`](crate::Parent<T>::Token): Contains token id and collection id.
147	/// - [`TokenNotFound`](crate::Parent<T>::TokenNotFound): Indicates that parent was not found
85	pub fn find_parent(148	pub fn find_parent(
86		collection: CollectionId,149		collection: CollectionId,
87		token: TokenId,150		token: TokenId,
103		})166		})
104	}167	}
105168
169	/// Find chain of parents of current token
170	///
171	/// Returns the parent of the current token, than the parent of the parent and so on until token without a parent
172	/// is returned. Returns error if cycle is detected.
106	pub fn parent_chain(173	pub fn parent_chain(
107		mut collection: CollectionId,174		mut collection: CollectionId,
108		mut token: TokenId,175		mut token: TokenId,
133	/// Try to dereference address, until finding top level owner200	/// Try to dereference address, until finding top level owner
134	///201	///
135	/// May return token address if parent token not yet exists202	/// May return token address if parent token not yet exists
203	///
204	/// - `budget`: Limit for searching parents in depth.
136	pub fn find_topmost_owner(205	pub fn find_topmost_owner(
137		collection: CollectionId,206		collection: CollectionId,
138		token: TokenId,207		token: TokenId,
149		})218		})
150	}219	}
151220
221	/// Find the topmost parent and check that assigning `for_nest` token as a parent for
222	/// any token in the parents chain wouldn't create a cycle.
223	///
224	/// - `budget`: Limit for searching parents in depth.
152	pub fn get_checked_topmost_owner(225	pub fn get_checked_topmost_owner(
153		collection: CollectionId,226		collection: CollectionId,
154		token: TokenId,227		token: TokenId,
177		Err(<Error<T>>::DepthLimit.into())250		Err(<Error<T>>::DepthLimit.into())
178	}251	}
179252
253	/// Burn token and all of it's nested tokens
254	///
255	/// - `self_budget`: Limit for searching children in depth.
256	/// - `breadth_budget`: Limit of breadth of searching children.
180	pub fn burn_item_recursively(257	pub fn burn_item_recursively(
181		from: T::CrossAccountId,258		from: T::CrossAccountId,
182		collection: CollectionId,259		collection: CollectionId,
190		dispatch.burn_item_recursively(from.clone(), token, self_budget, breadth_budget)267		dispatch.burn_item_recursively(from.clone(), token, self_budget, breadth_budget)
191	}268	}
192269
193	/// Check if token indirectly owned by specified user270	/// Check if `token` indirectly owned by `user`
271	///
272	/// Returns `true` if `user` is `token`'s owner. Or If token is provided as `user` then
273	/// check that `user` and `token` have same owner.
274	/// Checks that assigning `for_nest` token as a parent for any token in the `token`'s
275	/// parents chain wouldn't create a cycle.
276	///
277	/// - `budget`: Limit for searching parents in depth.
194	pub fn check_indirectly_owned(278	pub fn check_indirectly_owned(
195		user: T::CrossAccountId,279		user: T::CrossAccountId,
196		collection: CollectionId,280		collection: CollectionId,
207			.map(|indirect_owner| indirect_owner == target_parent)291			.map(|indirect_owner| indirect_owner == target_parent)
208	}292	}
209293
294	/// Checks that `under` is valid token and that `token_id` could be nested under it
295	/// and that `from` is `under`'s owner
296	///
297	/// Returns OK if `under` is not a token
298	///
299	/// - `nesting_budget`: Limit for searching parents in depth.
210	pub fn check_nesting(300	pub fn check_nesting(
211		from: T::CrossAccountId,301		from: T::CrossAccountId,
212		under: &T::CrossAccountId,302		under: &T::CrossAccountId,
219		})309		})
220	}310	}
221311
312	/// Nests `token_id` under `under` token
313	///
314	/// Returns OK if `under` is not a token. Checks that nesting is possible.
315	///
316	/// - `nesting_budget`: Limit for searching parents in depth.
222	pub fn nest_if_sent_to_token(317	pub fn nest_if_sent_to_token(
223		from: T::CrossAccountId,318		from: T::CrossAccountId,
224		under: &T::CrossAccountId,319		under: &T::CrossAccountId,
235		})330		})
236	}331	}
237332
333	/// Nests `token_id` under `owner` token
238	pub fn nest_if_sent_to_token_unchecked(334	pub fn nest_if_sent_to_token_unchecked(
239		owner: &T::CrossAccountId,335		owner: &T::CrossAccountId,
240		collection_id: CollectionId,336		collection_id: CollectionId,
245		});341		});
246	}342	}
247343
344	/// Unnests `token_id` from `owner`.
248	pub fn unnest_if_nested(345	pub fn unnest_if_nested(
249		owner: &T::CrossAccountId,346		owner: &T::CrossAccountId,
250		collection_id: CollectionId,347		collection_id: CollectionId,