git.delta.rocks / unique-network / refs/commits / e2730ed07311

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//! ### Available 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
1#![cfg_attr(not(feature = "std"), no_std)]54#![cfg_attr(not(feature = "std"), no_std)]
255
82}135}
83136
84impl<T: Config> Pallet<T> {137impl<T: Config> Pallet<T> {
138	/// Find account owning the `token` or a token that the `token` is nested in.
139	///
140	/// Returns the enum that have three variants:
141	/// - [`User`](crate::Parent<T>::User): Contains account.
142	/// - [`Token`](crate::Parent<T>::Token): Contains token id and collection id.
143	/// - [`TokenNotFound`](crate::Parent<T>::TokenNotFound): Indicates that parent was not found
85	pub fn find_parent(144	pub fn find_parent(
86		collection: CollectionId,145		collection: CollectionId,
87		token: TokenId,146		token: TokenId,
103		})162		})
104	}163	}
105164
165	/// Get the chain of parents of a token in the nesting hierarchy
166	///
167	/// Returns an iterator of addresses of the owning tokens and the owning account,
168	/// starting from the immediate parent token, ending with the account.
169	/// Returns error if cycle is detected.
106	pub fn parent_chain(170	pub fn parent_chain(
107		mut collection: CollectionId,171		mut collection: CollectionId,
108		mut token: TokenId,172		mut token: TokenId,
133	/// Try to dereference address, until finding top level owner197	/// Try to dereference address, until finding top level owner
134	///198	///
135	/// May return token address if parent token not yet exists199	/// May return token address if parent token not yet exists
200	///
201	/// - `budget`: Limit for searching parents in depth.
136	pub fn find_topmost_owner(202	pub fn find_topmost_owner(
137		collection: CollectionId,203		collection: CollectionId,
138		token: TokenId,204		token: TokenId,
149		})215		})
150	}216	}
151217
218	/// Find the topmost parent and check that assigning `for_nest` token as a child for
219	/// `token` wouldn't create a cycle.
220	///
221	/// - `budget`: Limit for searching parents in depth.
152	pub fn get_checked_topmost_owner(222	pub fn get_checked_topmost_owner(
153		collection: CollectionId,223		collection: CollectionId,
154		token: TokenId,224		token: TokenId,
177		Err(<Error<T>>::DepthLimit.into())247		Err(<Error<T>>::DepthLimit.into())
178	}248	}
179249
250	/// Burn token and all of it's nested tokens
251	///
252	/// - `self_budget`: Limit for searching children in depth.
253	/// - `breadth_budget`: Limit of breadth of searching children.
180	pub fn burn_item_recursively(254	pub fn burn_item_recursively(
181		from: T::CrossAccountId,255		from: T::CrossAccountId,
182		collection: CollectionId,256		collection: CollectionId,
190		dispatch.burn_item_recursively(from.clone(), token, self_budget, breadth_budget)264		dispatch.burn_item_recursively(from.clone(), token, self_budget, breadth_budget)
191	}265	}
192266
193	/// Check if token indirectly owned by specified user267	/// Check if `token` indirectly owned by `user`
268	///
269	/// Returns `true` if `user` is `token`'s owner. Or If token is provided as `user` then
270	/// check that `user` and `token` have same owner.
271	/// Checks that assigning `for_nest` token as a child for `token` wouldn't create a cycle.
272	///
273	/// - `budget`: Limit for searching parents in depth.
194	pub fn check_indirectly_owned(274	pub fn check_indirectly_owned(
195		user: T::CrossAccountId,275		user: T::CrossAccountId,
196		collection: CollectionId,276		collection: CollectionId,
207			.map(|indirect_owner| indirect_owner == target_parent)287			.map(|indirect_owner| indirect_owner == target_parent)
208	}288	}
209289
290	/// Checks that `under` is valid token and that `token_id` could be nested under it
291	/// and that `from` is `under`'s owner
292	///
293	/// Returns OK if `under` is not a token
294	///
295	/// - `nesting_budget`: Limit for searching parents in depth.
210	pub fn check_nesting(296	pub fn check_nesting(
211		from: T::CrossAccountId,297		from: T::CrossAccountId,
212		under: &T::CrossAccountId,298		under: &T::CrossAccountId,
219		})305		})
220	}306	}
221307
308	/// Nests `token_id` under `under` token
309	///
310	/// Returns OK if `under` is not a token. Checks that nesting is possible.
311	///
312	/// - `nesting_budget`: Limit for searching parents in depth.
222	pub fn nest_if_sent_to_token(313	pub fn nest_if_sent_to_token(
223		from: T::CrossAccountId,314		from: T::CrossAccountId,
224		under: &T::CrossAccountId,315		under: &T::CrossAccountId,
235		})326		})
236	}327	}
237328
329	/// Nests `token_id` under `owner` token
330	///
331	/// Caller should check that nesting wouldn't cause recursion in nesting
238	pub fn nest_if_sent_to_token_unchecked(332	pub fn nest_if_sent_to_token_unchecked(
239		owner: &T::CrossAccountId,333		owner: &T::CrossAccountId,
240		collection_id: CollectionId,334		collection_id: CollectionId,
245		});339		});
246	}340	}
247341
342	/// Unnests `token_id` from `owner`.
248	pub fn unnest_if_nested(343	pub fn unnest_if_nested(
249		owner: &T::CrossAccountId,344		owner: &T::CrossAccountId,
250		collection_id: CollectionId,345		collection_id: CollectionId,