git.delta.rocks / unique-network / refs/commits / 4efa9ce62081

--- a/pallets/evm-contract-helpers/src/eth.rs
+++ b/pallets/evm-contract-helpers/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/>.
 
+//! Implementation of magic contract
+
 use core::marker::PhantomData;
 use evm_coder::{abi::AbiWriter, execution::Result, generate_stubgen, solidity_interface, types::*};
 use pallet_evm_coder_substrate::{SubstrateRecorder, WithRecorder, dispatch_to_evm};
@@ -31,7 +33,8 @@
 use up_sponsorship::SponsorshipHandler;
 use sp_std::vec::Vec;
 
-struct ContractHelpers<T: Config>(SubstrateRecorder<T>);
+/// See [`ContractHelpersCall`]
+pub struct ContractHelpers<T: Config>(SubstrateRecorder<T>);
 impl<T: Config> WithRecorder<T> for ContractHelpers<T> {
 	fn recorder(&self) -> &SubstrateRecorder<T> {
 		&self.0
@@ -42,21 +45,24 @@
 	}
 }
 
+/// @title Magic contract, which allows users to reconfigure other contracts
 #[solidity_interface(name = ContractHelpers)]
 impl<T: Config> ContractHelpers<T>
 where
 	T::AccountId: AsRef<[u8; 32]>,
 {
-	/// Get contract ovner
-	///
-	/// @param contractAddress contract for which the owner is being determined.
-	/// @return Contract owner.
+	/// Get user, which deployed specified contract
+	/// @dev May return zero address in case if contract is deployed
+	///  using uniquenetwork evm-migration pallet, or using other terms not
+	///  intended by pallet-evm
+	/// @dev Returns zero address if contract does not exists
+	/// @param contractAddress Contract to get owner of
+	/// @return address Owner of contract
 	fn contract_owner(&self, contract_address: address) -> Result<address> {
 		Ok(<Owner<T>>::get(contract_address))
 	}
 
 	/// Set sponsor.
-	///
 	/// @param contractAddress Contract for which a sponsor is being established.
 	/// @param sponsor User address who set as pending sponsor.
 	fn set_sponsor(
@@ -163,6 +169,7 @@
 		&mut self,
 		caller: caller,
 		contract_address: address,
+		// TODO: implement support for enums in evm-coder
 		mode: uint8,
 	) -> Result<void> {
 		self.recorder().consume_sload()?;
@@ -175,10 +182,21 @@
 		Ok(())
 	}
 
-	fn sponsoring_mode(&self, contract_address: address) -> Result<uint8> {
-		Ok(<Pallet<T>>::sponsoring_mode(contract_address).to_eth())
+	/// Get current contract sponsoring rate limit
+	/// @param contractAddress Contract to get sponsoring mode of
+	/// @return uint32 Amount of blocks between two sponsored transactions
+	fn get_sponsoring_rate_limit(&self, contract_address: address) -> Result<uint32> {
+		Ok(<SponsoringRateLimit<T>>::get(contract_address)
+			.try_into()
+			.map_err(|_| "rate limit > u32::MAX")?)
 	}
 
+	/// Set contract sponsoring rate limit
+	/// @dev Sponsoring rate limit - is a minimum amount of blocks that should
+	///  pass between two sponsored transactions
+	/// @param contractAddress Contract to change sponsoring rate limit of
+	/// @param rateLimit Target rate limit
+	/// @dev Only contract owner can change this setting
 	fn set_sponsoring_rate_limit(
 		&mut self,
 		caller: caller,
@@ -190,57 +208,70 @@
 
 		<Pallet<T>>::ensure_owner(contract_address, caller).map_err(dispatch_to_evm::<T>)?;
 		<Pallet<T>>::set_sponsoring_rate_limit(contract_address, rate_limit.into());
-
 		Ok(())
 	}
 
-	fn get_sponsoring_rate_limit(&self, contract_address: address) -> Result<uint32> {
-		Ok(<SponsoringRateLimit<T>>::get(contract_address)
-			.try_into()
-			.map_err(|_| "rate limit > u32::MAX")?)
-	}
-
+	/// Is specified user present in contract allow list
+	/// @dev Contract owner always implicitly included
+	/// @param contractAddress Contract to check allowlist of
+	/// @param user User to check
+	/// @return bool Is specified users exists in contract allowlist
 	fn allowed(&self, contract_address: address, user: address) -> Result<bool> {
 		self.0.consume_sload()?;
 		Ok(<Pallet<T>>::allowed(contract_address, user))
 	}
 
-	fn allowlist_enabled(&self, contract_address: address) -> Result<bool> {
-		Ok(<AllowlistEnabled<T>>::get(contract_address))
-	}
-
-	fn toggle_allowlist(
+	/// Toggle user presence in contract allowlist
+	/// @param contractAddress Contract to change allowlist of
+	/// @param user Which user presence should be toggled
+	/// @param isAllowed `true` if user should be allowed to be sponsored
+	///  or call this contract, `false` otherwise
+	/// @dev Only contract owner can change this setting
+	fn toggle_allowed(
 		&mut self,
 		caller: caller,
 		contract_address: address,
-		enabled: bool,
+		user: address,
+		is_allowed: bool,
 	) -> Result<void> {
 		self.recorder().consume_sload()?;
 		self.recorder().consume_sstore()?;
 
 		<Pallet<T>>::ensure_owner(contract_address, caller).map_err(dispatch_to_evm::<T>)?;
-		<Pallet<T>>::toggle_allowlist(contract_address, enabled);
+		<Pallet<T>>::toggle_allowed(contract_address, user, is_allowed);
 
 		Ok(())
 	}
 
-	fn toggle_allowed(
+	/// Is this contract has allowlist access enabled
+	/// @dev Allowlist always can have users, and it is used for two purposes:
+	///  in case of allowlist sponsoring mode, users will be sponsored if they exist in allowlist
+	///  in case of allowlist access enabled, only users from allowlist may call this contract
+	/// @param contractAddress Contract to get allowlist access of
+	/// @return bool Is specified contract has allowlist access enabled
+	fn allowlist_enabled(&self, contract_address: address) -> Result<bool> {
+		Ok(<AllowlistEnabled<T>>::get(contract_address))
+	}
+
+	/// Toggle contract allowlist access
+	/// @param contractAddress Contract to change allowlist access of
+	/// @param enabled Should allowlist access to be enabled?
+	fn toggle_allowlist(
 		&mut self,
 		caller: caller,
 		contract_address: address,
-		user: address,
-		is_allowed: bool,
+		enabled: bool,
 	) -> Result<void> {
 		self.recorder().consume_sload()?;
 		self.recorder().consume_sstore()?;
 
 		<Pallet<T>>::ensure_owner(contract_address, caller).map_err(dispatch_to_evm::<T>)?;
-		<Pallet<T>>::toggle_allowed(contract_address, user, is_allowed);
-
+		<Pallet<T>>::toggle_allowlist(contract_address, enabled);
 		Ok(())
 	}
 }
 
+/// Implements [`OnMethodCall`], which delegates call to [`ContractHelpers`]
 pub struct HelpersOnMethodCall<T: Config>(PhantomData<*const T>);
 impl<T: Config> OnMethodCall<T> for HelpersOnMethodCall<T>
 where
@@ -283,6 +314,7 @@
 	}
 }
 
+/// Hooks into contract creation, storing owner of newly deployed contract
 pub struct HelpersOnCreate<T: Config>(PhantomData<*const T>);
 impl<T: Config> OnCreate<T> for HelpersOnCreate<T> {
 	fn on_create(owner: H160, contract: H160) {
@@ -290,6 +322,7 @@
 	}
 }
 
+/// Bridge to pallet-sponsoring
 pub struct HelpersContractSponsoring<T: Config>(PhantomData<*const T>);
 impl<T: Config> SponsorshipHandler<T::CrossAccountId, (H160, Vec<u8>)>
 	for HelpersContractSponsoring<T>

--- a/pallets/evm-contract-helpers/src/lib.rs
+++ b/pallets/evm-contract-helpers/src/lib.rs
@@ -14,7 +14,9 @@
 // You should have received a copy of the GNU General Public License
 // along with Unique Network. If not, see <http://www.gnu.org/licenses/>.
 
+#![doc = include_str!("../README.md")]
 #![cfg_attr(not(feature = "std"), no_std)]
+#![deny(missing_docs)]
 
 use codec::{Decode, Encode, MaxEncodedLen};
 pub use pallet::*;
@@ -35,13 +37,16 @@
 	pub trait Config:
 		frame_system::Config + pallet_evm_coder_substrate::Config + pallet_evm::account::Config
 	{
+		/// Address, under which magic contract will be available
 		type ContractAddress: Get<H160>;
+		/// In case of enabled sponsoring, but no sponsoring rate limit set,
+		/// this value will be used implicitly
 		type DefaultSponsoringRateLimit: Get<Self::BlockNumber>;
 	}
 
 	#[pallet::error]
 	pub enum Error<T> {
-		/// This method is only executable by owner.
+		/// This method is only executable by contract owner
 		NoPermission,
 
 		/// No pending sponsor for contract.
@@ -217,6 +222,7 @@
 			}
 		}
 
+		/// Get current sponsoring mode, performing lazy migration from legacy storage
 		pub fn sponsoring_mode(contract: H160) -> SponsoringModeT {
 			<SponsoringMode<T>>::get(contract)
 				.or_else(|| {
@@ -225,6 +231,7 @@
 				.unwrap_or_default()
 		}
 
+		/// Reconfigure contract sponsoring mode
 		pub fn set_sponsoring_mode(contract: H160, mode: SponsoringModeT) {
 			if mode == SponsoringModeT::Disabled {
 				<SponsoringMode<T>>::remove(contract);
@@ -234,22 +241,27 @@
 			<SelfSponsoring<T>>::remove(contract)
 		}
 
+		/// Set duration between two sponsored contract calls
 		pub fn set_sponsoring_rate_limit(contract: H160, rate_limit: T::BlockNumber) {
 			<SponsoringRateLimit<T>>::insert(contract, rate_limit);
 		}
 
+		/// Is user added to allowlist, or he is owner of specified contract
 		pub fn allowed(contract: H160, user: H160) -> bool {
 			<Allowlist<T>>::get(&contract, &user) || <Owner<T>>::get(&contract) == user
 		}
 
+		/// Toggle contract allowlist access
 		pub fn toggle_allowlist(contract: H160, enabled: bool) {
 			<AllowlistEnabled<T>>::insert(contract, enabled)
 		}
 
+		/// Toggle user presence in contract's allowlist
 		pub fn toggle_allowed(contract: H160, user: H160, allowed: bool) {
 			<Allowlist<T>>::insert(contract, user, allowed);
 		}
 
+		/// Throw error if user is not allowed to reconfigure target contract
 		pub fn ensure_owner(contract: H160, user: H160) -> DispatchResult {
 			ensure!(<Owner<T>>::get(&contract) == user, Error::<T>::NoPermission);
 			Ok(())
@@ -257,10 +269,15 @@
 	}
 }
 
-#[derive(Encode, Decode, PartialEq, TypeInfo, MaxEncodedLen)]
+/// Available contract sponsoring modes
+#[derive(Encode, Decode, PartialEq, TypeInfo, MaxEncodedLen, Default)]
 pub enum SponsoringModeT {
+	/// Sponsoring is disabled
+	#[default]
 	Disabled,
+	/// Only users from allowlist will be sponsored
 	Allowlisted,
+	/// All users will be sponsored
 	Generous,
 }
 
@@ -279,11 +296,5 @@
 			SponsoringModeT::Allowlisted => 1,
 			SponsoringModeT::Generous => 2,
 		}
-	}
-}
-
-impl Default for SponsoringModeT {
-	fn default() -> Self {
-		Self::Disabled
 	}
 }

binary blob — no preview

--- a/tests/src/eth/api/ContractHelpers.sol
+++ b/tests/src/eth/api/ContractHelpers.sol
@@ -3,12 +3,6 @@
 
 pragma solidity >=0.8.0 <0.9.0;
 
-/// @dev anonymous struct
-struct Tuple0 {
-	address field_0;
-	uint256 field_1;
-}
-
 /// @dev common stubs holder
 interface Dummy {
 
@@ -18,39 +12,42 @@
 	function supportsInterface(bytes4 interfaceID) external view returns (bool);
 }
 
-/// @dev the ERC-165 identifier for this interface is 0x6073d917
+/// @title Magic contract, which allows users to reconfigure other contracts
+/// @dev the ERC-165 identifier for this interface is 0xd77fab70
 interface ContractHelpers is Dummy, ERC165 {
-	/// Get contract ovner
-	///
-	/// @param contractAddress contract for which the owner is being determined.
-	/// @return Contract owner.
-	///
-	/// Selector: contractOwner(address) 5152b14c
+	/// Get user, which deployed specified contract
+	/// @dev May return zero address in case if contract is deployed
+	///  using uniquenetwork evm-migration pallet, or using other terms not
+	///  intended by pallet-evm
+	/// @dev Returns zero address if contract does not exists
+	/// @param contractAddress Contract to get owner of
+	/// @return address Owner of contract
+	/// @dev EVM selector for this function is: 0x5152b14c,
+	///  or in textual repr: contractOwner(address)
 	function contractOwner(address contractAddress)
 		external
 		view
 		returns (address);
 
 	/// Set sponsor.
-	///
 	/// @param contractAddress Contract for which a sponsor is being established.
 	/// @param sponsor User address who set as pending sponsor.
-	///
-	/// Selector: setSponsor(address,address) f01fba93
+	/// @dev EVM selector for this function is: 0xf01fba93,
+	///  or in textual repr: setSponsor(address,address)
 	function setSponsor(address contractAddress, address sponsor) external;
 
 	/// Set contract as self sponsored.
 	///
 	/// @param contractAddress Contract for which a self sponsoring is being enabled.
-	///
-	/// Selector: selfSponsoredEnable(address) 89f7d9ae
+	/// @dev EVM selector for this function is: 0x89f7d9ae,
+	///  or in textual repr: selfSponsoredEnable(address)
 	function selfSponsoredEnable(address contractAddress) external;
 
 	/// Remove sponsor.
 	///
 	/// @param contractAddress Contract for which a sponsorship is being removed.
-	///
-	/// Selector: removeSponsor(address) ef784250
+	/// @dev EVM selector for this function is: 0xef784250,
+	///  or in textual repr: removeSponsor(address)
 	function removeSponsor(address contractAddress) external;
 
 	/// Confirm sponsorship.
@@ -58,16 +55,16 @@
 	/// @dev Caller must be same that set via [`setSponsor`].
 	///
 	/// @param contractAddress Сontract for which need to confirm sponsorship.
-	///
-	/// Selector: confirmSponsorship(address) abc00001
+	/// @dev EVM selector for this function is: 0xabc00001,
+	///  or in textual repr: confirmSponsorship(address)
 	function confirmSponsorship(address contractAddress) external;
 
 	/// Get current sponsor.
 	///
 	/// @param contractAddress The contract for which a sponsor is requested.
 	/// @return Tuble with sponsor address and his substrate mirror. If there is no confirmed sponsor error "Contract has no sponsor" throw.
-	///
-	/// Selector: getSponsor(address) 743fc745
+	/// @dev EVM selector for this function is: 0x743fc745,
+	///  or in textual repr: getSponsor(address)
 	function getSponsor(address contractAddress)
 		external
 		view
@@ -77,65 +74,102 @@
 	///
 	/// @param contractAddress The contract for which the presence of a confirmed sponsor is checked.
 	/// @return **true** if contract has confirmed sponsor.
-	///
-	/// Selector: hasSponsor(address) 97418603
+	/// @dev EVM selector for this function is: 0x97418603,
+	///  or in textual repr: hasSponsor(address)
 	function hasSponsor(address contractAddress) external view returns (bool);
 
 	/// Check tat contract has pending sponsor.
 	///
 	/// @param contractAddress The contract for which the presence of a pending sponsor is checked.
 	/// @return **true** if contract has pending sponsor.
-	///
-	/// Selector: hasPendingSponsor(address) 39b9b242
+	/// @dev EVM selector for this function is: 0x39b9b242,
+	///  or in textual repr: hasPendingSponsor(address)
 	function hasPendingSponsor(address contractAddress)
 		external
 		view
 		returns (bool);
 
-	/// Selector: sponsoringEnabled(address) 6027dc61
+	/// @dev EVM selector for this function is: 0x6027dc61,
+	///  or in textual repr: sponsoringEnabled(address)
 	function sponsoringEnabled(address contractAddress)
 		external
 		view
 		returns (bool);
 
-	/// Selector: setSponsoringMode(address,uint8) fde8a560
+	/// @dev EVM selector for this function is: 0xfde8a560,
+	///  or in textual repr: setSponsoringMode(address,uint8)
 	function setSponsoringMode(address contractAddress, uint8 mode) external;
 
-	/// Selector: sponsoringMode(address) b70c7267
-	function sponsoringMode(address contractAddress)
+	/// Get current contract sponsoring rate limit
+	/// @param contractAddress Contract to get sponsoring mode of
+	/// @return uint32 Amount of blocks between two sponsored transactions
+	/// @dev EVM selector for this function is: 0x610cfabd,
+	///  or in textual repr: getSponsoringRateLimit(address)
+	function getSponsoringRateLimit(address contractAddress)
 		external
 		view
-		returns (uint8);
+		returns (uint32);
 
-	/// Selector: setSponsoringRateLimit(address,uint32) 77b6c908
+	/// Set contract sponsoring rate limit
+	/// @dev Sponsoring rate limit - is a minimum amount of blocks that should
+	///  pass between two sponsored transactions
+	/// @param contractAddress Contract to change sponsoring rate limit of
+	/// @param rateLimit Target rate limit
+	/// @dev Only contract owner can change this setting
+	/// @dev EVM selector for this function is: 0x77b6c908,
+	///  or in textual repr: setSponsoringRateLimit(address,uint32)
 	function setSponsoringRateLimit(address contractAddress, uint32 rateLimit)
 		external;
 
-	/// Selector: getSponsoringRateLimit(address) 610cfabd
-	function getSponsoringRateLimit(address contractAddress)
-		external
-		view
-		returns (uint32);
-
-	/// Selector: allowed(address,address) 5c658165
+	/// Is specified user present in contract allow list
+	/// @dev Contract owner always implicitly included
+	/// @param contractAddress Contract to check allowlist of
+	/// @param user User to check
+	/// @return bool Is specified users exists in contract allowlist
+	/// @dev EVM selector for this function is: 0x5c658165,
+	///  or in textual repr: allowed(address,address)
 	function allowed(address contractAddress, address user)
 		external
 		view
 		returns (bool);
 
-	/// Selector: allowlistEnabled(address) c772ef6c
+	/// Toggle user presence in contract allowlist
+	/// @param contractAddress Contract to change allowlist of
+	/// @param user Which user presence should be toggled
+	/// @param isAllowed `true` if user should be allowed to be sponsored
+	///  or call this contract, `false` otherwise
+	/// @dev Only contract owner can change this setting
+	/// @dev EVM selector for this function is: 0x4706cc1c,
+	///  or in textual repr: toggleAllowed(address,address,bool)
+	function toggleAllowed(
+		address contractAddress,
+		address user,
+		bool isAllowed
+	) external;
+
+	/// Is this contract has allowlist access enabled
+	/// @dev Allowlist always can have users, and it is used for two purposes:
+	///  in case of allowlist sponsoring mode, users will be sponsored if they exist in allowlist
+	///  in case of allowlist access enabled, only users from allowlist may call this contract
+	/// @param contractAddress Contract to get allowlist access of
+	/// @return bool Is specified contract has allowlist access enabled
+	/// @dev EVM selector for this function is: 0xc772ef6c,
+	///  or in textual repr: allowlistEnabled(address)
 	function allowlistEnabled(address contractAddress)
 		external
 		view
 		returns (bool);
 
-	/// Selector: toggleAllowlist(address,bool) 36de20f5
+	/// Toggle contract allowlist access
+	/// @param contractAddress Contract to change allowlist access of
+	/// @param enabled Should allowlist access to be enabled?
+	/// @dev EVM selector for this function is: 0x36de20f5,
+	///  or in textual repr: toggleAllowlist(address,bool)
 	function toggleAllowlist(address contractAddress, bool enabled) external;
+}
 
-	/// Selector: toggleAllowed(address,address,bool) 4706cc1c
-	function toggleAllowed(
-		address contractAddress,
-		address user,
-		bool isAllowed
-	) external;
+/// @dev anonymous struct
+struct Tuple0 {
+	address field_0;
+	uint256 field_1;
 }

--- a/tests/src/eth/util/contractHelpersAbi.json
+++ b/tests/src/eth/util/contractHelpersAbi.json
@@ -197,19 +197,6 @@
   },
   {
     "inputs": [
-      {
-        "internalType": "address",
-        "name": "contractAddress",
-        "type": "address"
-      }
-    ],
-    "name": "sponsoringMode",
-    "outputs": [{ "internalType": "uint8", "name": "", "type": "uint8" }],
-    "stateMutability": "view",
-    "type": "function"
-  },
-  {
-    "inputs": [
       { "internalType": "bytes4", "name": "interfaceID", "type": "bytes4" }
     ],
     "name": "supportsInterface",