git.delta.rocks / unique-network / refs/commits / 0766e08cb8d3

difftreelog

doc(pallet-fungible): document public api

PraetorP2022-07-13parent: #956ec6e.patch.diff
in: master

3 files changed

modifiedpallets/fungible/src/common.rsdiffbeforeafterboth
before · pallets/fungible/src/common.rs
1// Copyright 2019-2022 Unique Network (Gibraltar) Ltd.2// This file is part of Unique Network.34// Unique Network is free software: you can redistribute it and/or modify5// it under the terms of the GNU General Public License as published by6// the Free Software Foundation, either version 3 of the License, or7// (at your option) any later version.89// Unique Network is distributed in the hope that it will be useful,10// but WITHOUT ANY WARRANTY; without even the implied warranty of11// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the12// GNU General Public License for more details.1314// You should have received a copy of the GNU General Public License15// along with Unique Network. If not, see <http://www.gnu.org/licenses/>.1617use core::marker::PhantomData;1819use frame_support::{dispatch::DispatchResultWithPostInfo, ensure, fail, weights::Weight, traits::Get};20use up_data_structs::{TokenId, CollectionId, CreateItemExData, budget::Budget, CreateItemData};21use pallet_common::{CommonCollectionOperations, CommonWeightInfo, RefungibleExtensions, with_weight};22use pallet_structure::Error as StructureError;23use sp_runtime::ArithmeticError;24use sp_std::{vec::Vec, vec};25use up_data_structs::{Property, PropertyKey, PropertyValue, PropertyKeyPermission};2627use crate::{28	Allowance, Balance, Config, Error, FungibleHandle, Pallet, SelfWeightOf, weights::WeightInfo,29};3031pub struct CommonWeights<T: Config>(PhantomData<T>);32impl<T: Config> CommonWeightInfo<T::CrossAccountId> for CommonWeights<T> {33	fn create_item() -> Weight {34		<SelfWeightOf<T>>::create_item()35	}3637	fn create_multiple_items(_data: &[CreateItemData]) -> Weight {38		// All items minted for the same user, so it works same as create_item39		Self::create_item()40	}4142	fn create_multiple_items_ex(data: &CreateItemExData<T::CrossAccountId>) -> Weight {43		match data {44			CreateItemExData::Fungible(f) => {45				<SelfWeightOf<T>>::create_multiple_items_ex(f.len() as u32)46			}47			_ => 0,48		}49	}5051	fn burn_item() -> Weight {52		<SelfWeightOf<T>>::burn_item()53	}5455	fn set_collection_properties(_amount: u32) -> Weight {56		// Error57		058	}5960	fn delete_collection_properties(_amount: u32) -> Weight {61		// Error62		063	}6465	fn set_token_properties(_amount: u32) -> Weight {66		// Error67		068	}6970	fn delete_token_properties(_amount: u32) -> Weight {71		// Error72		073	}7475	fn set_token_property_permissions(_amount: u32) -> Weight {76		// Error77		078	}7980	fn transfer() -> Weight {81		<SelfWeightOf<T>>::transfer()82	}8384	fn approve() -> Weight {85		<SelfWeightOf<T>>::approve()86	}8788	fn transfer_from() -> Weight {89		<SelfWeightOf<T>>::transfer_from()90	}9192	fn burn_from() -> Weight {93		<SelfWeightOf<T>>::burn_from()94	}9596	fn burn_recursively_self_raw() -> Weight {97		// Read to get total balance98		Self::burn_item() + T::DbWeight::get().reads(1)99	}100101	fn burn_recursively_breadth_raw(_amount: u32) -> Weight {102		// Fungible tokens can't have children103		0104	}105}106107impl<T: Config> CommonCollectionOperations<T> for FungibleHandle<T> {108	fn create_item(109		&self,110		sender: T::CrossAccountId,111		to: T::CrossAccountId,112		data: up_data_structs::CreateItemData,113		nesting_budget: &dyn Budget,114	) -> DispatchResultWithPostInfo {115		match data {116			up_data_structs::CreateItemData::Fungible(data) => with_weight(117				<Pallet<T>>::create_item(self, &sender, (to, data.value), nesting_budget),118				<CommonWeights<T>>::create_item(),119			),120			_ => fail!(<Error<T>>::NotFungibleDataUsedToMintFungibleCollectionToken),121		}122	}123124	fn create_multiple_items(125		&self,126		sender: T::CrossAccountId,127		to: T::CrossAccountId,128		data: Vec<up_data_structs::CreateItemData>,129		nesting_budget: &dyn Budget,130	) -> DispatchResultWithPostInfo {131		let mut sum: u128 = 0;132		for data in data {133			match data {134				up_data_structs::CreateItemData::Fungible(data) => {135					sum = sum136						.checked_add(data.value)137						.ok_or(ArithmeticError::Overflow)?;138				}139				_ => fail!(<Error<T>>::NotFungibleDataUsedToMintFungibleCollectionToken),140			}141		}142143		with_weight(144			<Pallet<T>>::create_item(self, &sender, (to, sum), nesting_budget),145			<CommonWeights<T>>::create_item(),146		)147	}148149	fn create_multiple_items_ex(150		&self,151		sender: <T>::CrossAccountId,152		data: up_data_structs::CreateItemExData<<T>::CrossAccountId>,153		nesting_budget: &dyn Budget,154	) -> DispatchResultWithPostInfo {155		let weight = <CommonWeights<T>>::create_multiple_items_ex(&data);156		let data = match data {157			up_data_structs::CreateItemExData::Fungible(f) => f,158			_ => fail!(<Error<T>>::NotFungibleDataUsedToMintFungibleCollectionToken),159		};160161		with_weight(162			<Pallet<T>>::create_multiple_items(self, &sender, data.into_inner(), nesting_budget),163			weight,164		)165	}166167	fn burn_item(168		&self,169		sender: T::CrossAccountId,170		token: TokenId,171		amount: u128,172	) -> DispatchResultWithPostInfo {173		ensure!(174			token == TokenId::default(),175			<Error<T>>::FungibleItemsHaveNoId176		);177178		with_weight(179			<Pallet<T>>::burn(self, &sender, amount),180			<CommonWeights<T>>::burn_item(),181		)182	}183184	fn burn_item_recursively(185		&self,186		sender: T::CrossAccountId,187		token: TokenId,188		self_budget: &dyn Budget,189		_breadth_budget: &dyn Budget,190	) -> DispatchResultWithPostInfo {191		// Should not happen?192		ensure!(193			token == TokenId::default(),194			<Error<T>>::FungibleItemsHaveNoId195		);196		ensure!(self_budget.consume(), <StructureError<T>>::DepthLimit,);197198		with_weight(199			<Pallet<T>>::burn(self, &sender, <Balance<T>>::get((self.id, &sender))),200			<CommonWeights<T>>::burn_recursively_self_raw(),201		)202	}203204	fn transfer(205		&self,206		from: T::CrossAccountId,207		to: T::CrossAccountId,208		token: TokenId,209		amount: u128,210		nesting_budget: &dyn Budget,211	) -> DispatchResultWithPostInfo {212		ensure!(213			token == TokenId::default(),214			<Error<T>>::FungibleItemsHaveNoId215		);216217		with_weight(218			<Pallet<T>>::transfer(self, &from, &to, amount, nesting_budget),219			<CommonWeights<T>>::transfer(),220		)221	}222223	fn approve(224		&self,225		sender: T::CrossAccountId,226		spender: T::CrossAccountId,227		token: TokenId,228		amount: u128,229	) -> DispatchResultWithPostInfo {230		ensure!(231			token == TokenId::default(),232			<Error<T>>::FungibleItemsHaveNoId233		);234235		with_weight(236			<Pallet<T>>::set_allowance(self, &sender, &spender, amount),237			<CommonWeights<T>>::approve(),238		)239	}240241	fn transfer_from(242		&self,243		sender: T::CrossAccountId,244		from: T::CrossAccountId,245		to: T::CrossAccountId,246		token: TokenId,247		amount: u128,248		nesting_budget: &dyn Budget,249	) -> DispatchResultWithPostInfo {250		ensure!(251			token == TokenId::default(),252			<Error<T>>::FungibleItemsHaveNoId253		);254255		with_weight(256			<Pallet<T>>::transfer_from(self, &sender, &from, &to, amount, nesting_budget),257			<CommonWeights<T>>::transfer_from(),258		)259	}260261	fn burn_from(262		&self,263		sender: T::CrossAccountId,264		from: T::CrossAccountId,265		token: TokenId,266		amount: u128,267		nesting_budget: &dyn Budget,268	) -> DispatchResultWithPostInfo {269		ensure!(270			token == TokenId::default(),271			<Error<T>>::FungibleItemsHaveNoId272		);273274		with_weight(275			<Pallet<T>>::burn_from(self, &sender, &from, amount, nesting_budget),276			<CommonWeights<T>>::burn_from(),277		)278	}279280	fn set_collection_properties(281		&self,282		_sender: T::CrossAccountId,283		_property: Vec<Property>,284	) -> DispatchResultWithPostInfo {285		fail!(<Error<T>>::SettingPropertiesNotAllowed)286	}287288	fn delete_collection_properties(289		&self,290		_sender: &T::CrossAccountId,291		_property_keys: Vec<PropertyKey>,292	) -> DispatchResultWithPostInfo {293		fail!(<Error<T>>::SettingPropertiesNotAllowed)294	}295296	fn set_token_properties(297		&self,298		_sender: T::CrossAccountId,299		_token_id: TokenId,300		_property: Vec<Property>,301	) -> DispatchResultWithPostInfo {302		fail!(<Error<T>>::SettingPropertiesNotAllowed)303	}304305	fn set_token_property_permissions(306		&self,307		_sender: &T::CrossAccountId,308		_property_permissions: Vec<PropertyKeyPermission>,309	) -> DispatchResultWithPostInfo {310		fail!(<Error<T>>::SettingPropertiesNotAllowed)311	}312313	fn delete_token_properties(314		&self,315		_sender: T::CrossAccountId,316		_token_id: TokenId,317		_property_keys: Vec<PropertyKey>,318	) -> DispatchResultWithPostInfo {319		fail!(<Error<T>>::SettingPropertiesNotAllowed)320	}321322	fn check_nesting(323		&self,324		_sender: <T>::CrossAccountId,325		_from: (CollectionId, TokenId),326		_under: TokenId,327		_budget: &dyn Budget,328	) -> sp_runtime::DispatchResult {329		fail!(<Error<T>>::FungibleDisallowsNesting)330	}331332	fn nest(&self, _under: TokenId, _to_nest: (CollectionId, TokenId)) {}333334	fn unnest(&self, _under: TokenId, _to_nest: (CollectionId, TokenId)) {}335336	fn collection_tokens(&self) -> Vec<TokenId> {337		vec![TokenId::default()]338	}339340	fn account_tokens(&self, account: T::CrossAccountId) -> Vec<TokenId> {341		if <Balance<T>>::get((self.id, account)) != 0 {342			vec![TokenId::default()]343		} else {344			vec![]345		}346	}347348	fn token_exists(&self, token: TokenId) -> bool {349		token == TokenId::default()350	}351352	fn last_token_id(&self) -> TokenId {353		TokenId::default()354	}355356	fn token_owner(&self, _token: TokenId) -> Option<T::CrossAccountId> {357		None358	}359360	fn token_property(&self, _token_id: TokenId, _key: &PropertyKey) -> Option<PropertyValue> {361		None362	}363364	fn token_properties(365		&self,366		_token_id: TokenId,367		_keys: Option<Vec<PropertyKey>>,368	) -> Vec<Property> {369		Vec::new()370	}371372	fn total_supply(&self) -> u32 {373		1374	}375376	fn account_balance(&self, account: T::CrossAccountId) -> u32 {377		if <Balance<T>>::get((self.id, account)) != 0 {378			1379		} else {380			0381		}382	}383384	fn balance(&self, account: T::CrossAccountId, token: TokenId) -> u128 {385		if token != TokenId::default() {386			return 0;387		}388		<Balance<T>>::get((self.id, account))389	}390391	fn allowance(392		&self,393		sender: T::CrossAccountId,394		spender: T::CrossAccountId,395		token: TokenId,396	) -> u128 {397		if token != TokenId::default() {398			return 0;399		}400		<Allowance<T>>::get((self.id, sender, spender))401	}402403	fn refungible_extensions(&self) -> Option<&dyn RefungibleExtensions<T>> {404		None405	}406}
modifiedpallets/fungible/src/erc.rsdiffbeforeafterboth
--- a/pallets/fungible/src/erc.rs
+++ b/pallets/fungible/src/erc.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/>.
 
+//! ERC-20 standart support implementation.
+
 use core::char::{REPLACEMENT_CHARACTER, decode_utf16};
 use core::convert::TryInto;
 use evm_coder::{ToLog, execution::*, generate_stubgen, solidity_interface, types::*, weight};
modifiedpallets/fungible/src/lib.rsdiffbeforeafterboth
--- a/pallets/fungible/src/lib.rs
+++ b/pallets/fungible/src/lib.rs
@@ -14,6 +14,68 @@
 // You should have received a copy of the GNU General Public License
 // along with Unique Network. If not, see <http://www.gnu.org/licenses/>.
 
+//! # Fungible Pallet
+//!
+//! The Fungible pallet provides functionality for dealing with fungible assets.
+//!
+//! - [`CreateItemData`]
+//! - [`Config`]
+//! - [`FungibleHandle`]
+//! - [`Pallet`]
+//! - [`TotalSupply`]
+//! - [`Balance`]
+//! - [`Allowance`]
+//! - [`Error`]
+//!
+//! ## Fungible tokens
+//!
+//! Fungible tokens or assets are divisible and non-unique. For instance,
+//! fiat currencies like the dollar are fungible: A $1 bill
+//! in New York City has the same value as a $1 bill in Miami.
+//! A fungible token can also be a cryptocurrency like Bitcoin: 1 BTC is worth 1 BTC,
+//! no matter where it is issued. Thus, the fungibility refers to a specific currency’s
+//! ability to maintain one standard value. As well, it needs to have uniform acceptance.
+//! This means that a currency’s history should not be able to affect its value,
+//! and this is due to the fact that each piece that is a part of the currency is equal
+//! in value when compared to every other piece of that exact same currency.
+//! In the world of cryptocurrencies, this is essentially a coin or a token
+//! that can be replaced by another identical coin or token, and they are
+//! both mutually interchangeable. A popular implementation of fungible tokens is
+//! the ERC-20 token standard.
+//!
+//! ### ERC-20
+//!
+//! The [ERC-20](https://ethereum.org/en/developers/docs/standards/tokens/erc-20/) (Ethereum Request for Comments 20), proposed by Fabian Vogelsteller in November 2015,
+//! is a Token Standard that implements an API for tokens within Smart Contracts.
+//!
+//! Example functionalities ERC-20 provides:
+//!
+//! * transfer tokens from one account to another
+//! * get the current token balance of an account
+//! * get the total supply of the token available on the network
+//! * approve whether an amount of token from an account can be spent by a third-party account
+//!
+//! ## Overview
+//!
+//! The module provides functionality for asset management of fungible asset, supports ERC-20 standart, includes:
+//!
+//! * Asset Issuance
+//! * Asset Transferal
+//! * Asset Destruction
+//! * Delegated Asset Transfers
+//!
+//! **NOTE:** The created fungible asset always has `token_id` = 0.
+//! So `tokenA` and `tokenB` will have different `collection_id`.
+//!
+//! ### Implementations
+//!
+//! The Fungible pallet provides implementations for the following traits.
+//!
+//! - [`WithRecorder`](pallet_evm_coder_substrate::WithRecorder):
+//! - [`CommonCollectionOperations`](pallet_common::CommonCollectionOperations): Functions for dealing with collections
+//!	- [`CommonWeightInfo`](pallet_common::CommonWeightInfo): Functions for retrieval of transaction weight
+//! - [`CommonEvmHandler`](pallet_common::erc::CommonEvmHandler): Function for handling EVM runtime calls
+
 #![cfg_attr(not(feature = "std"), no_std)]
 
 use core::ops::Deref;
@@ -57,13 +119,13 @@
 	pub enum Error<T> {
 		/// Not Fungible item data used to mint in Fungible collection.
 		NotFungibleDataUsedToMintFungibleCollectionToken,
-		/// Not default id passed as TokenId argument
+		/// Not default id passed as TokenId argument.
 		FungibleItemsHaveNoId,
-		/// Tried to set data for fungible item
+		/// Tried to set data for fungible item.
 		FungibleItemsDontHaveData,
-		/// Fungible token does not support nested
+		/// Fungible token does not support nesting.
 		FungibleDisallowsNesting,
-		/// Setting item properties is not allowed
+		/// Setting item properties is not allowed.
 		SettingPropertiesNotAllowed,
 	}
 
@@ -78,10 +140,12 @@
 	#[pallet::generate_store(pub(super) trait Store)]
 	pub struct Pallet<T>(_);
 
+	/// Total amount of fungible tokens inside a collection.
 	#[pallet::storage]
 	pub type TotalSupply<T: Config> =
 		StorageMap<Hasher = Twox64Concat, Key = CollectionId, Value = u128, QueryKind = ValueQuery>;
 
+	/// Amount of tokens owned by an account inside a collection.
 	#[pallet::storage]
 	pub type Balance<T: Config> = StorageNMap<
 		Key = (
@@ -92,6 +156,7 @@
 		QueryKind = ValueQuery,
 	>;
 
+	/// Storage for delegated assets.
 	#[pallet::storage]
 	pub type Allowance<T: Config> = StorageNMap<
 		Key = (
@@ -103,15 +168,19 @@
 		QueryKind = ValueQuery,
 	>;
 }
-
+/// Handler for fungible assets.
 pub struct FungibleHandle<T: Config>(pallet_common::CollectionHandle<T>);
 impl<T: Config> FungibleHandle<T> {
+	/// Casts [pallet_common::CollectionHandle] into [FungibleHandle].
 	pub fn cast(inner: pallet_common::CollectionHandle<T>) -> Self {
 		Self(inner)
 	}
+
+	/// Casts [FungibleHandle] into [pallet_common::CollectionHandle].
 	pub fn into_inner(self) -> pallet_common::CollectionHandle<T> {
 		self.0
 	}
+	/// Returns a mutable reference to the internal [pallet_common::CollectionHandle].
 	pub fn common_mut(&mut self) -> &mut pallet_common::CollectionHandle<T> {
 		&mut self.0
 	}
@@ -132,13 +201,17 @@
 	}
 }
 
+/// Pallet implementation for fungible assets
 impl<T: Config> Pallet<T> {
+	/// Initializes the collection. Returns [CollectionId] on success, [DispatchError] otherwise.
 	pub fn init_collection(
 		owner: T::CrossAccountId,
 		data: CreateCollectionData<T::AccountId>,
 	) -> Result<CollectionId, DispatchError> {
 		<PalletCommon<T>>::init_collection(owner, data, false)
 	}
+
+	/// Destroys a collection.
 	pub fn destroy_collection(
 		collection: FungibleHandle<T>,
 		sender: &T::CrossAccountId,
@@ -159,10 +232,14 @@
 		Ok(())
 	}
 
+	///Checks if collection has tokens. Return `true` if it has.
 	fn collection_has_tokens(collection_id: CollectionId) -> bool {
 		<TotalSupply<T>>::get(collection_id) != 0
 	}
 
+	/// Burns the specified amount of the token. If the token balance
+	/// or total supply is less than the given value,
+	/// it will return [DispatchError].
 	pub fn burn(
 		collection: &FungibleHandle<T>,
 		owner: &T::CrossAccountId,
@@ -207,6 +284,8 @@
 		Ok(())
 	}
 
+	/// Transfers the specified amount of tokens. Will check that
+	/// the transfer is allowed for the token.
 	pub fn transfer(
 		collection: &FungibleHandle<T>,
 		from: &T::CrossAccountId,
@@ -277,6 +356,7 @@
 		Ok(())
 	}
 
+	/// Minting tokens for multiple IDs.
 	pub fn create_multiple_items(
 		collection: &FungibleHandle<T>,
 		sender: &T::CrossAccountId,
@@ -378,6 +458,7 @@
 		));
 	}
 
+	/// Sets the amount of owner tokens that the spender can manage.
 	pub fn set_allowance(
 		collection: &FungibleHandle<T>,
 		owner: &T::CrossAccountId,
@@ -441,6 +522,7 @@
 		Ok(allowance)
 	}
 
+	/// Transfers of tokens that `from` gave to `spender` to manage, to `to` ID.
 	pub fn transfer_from(
 		collection: &FungibleHandle<T>,
 		spender: &T::CrossAccountId,
@@ -460,6 +542,7 @@
 		Ok(())
 	}
 
+	/// Burns managed tokens.
 	pub fn burn_from(
 		collection: &FungibleHandle<T>,
 		spender: &T::CrossAccountId,