diff --git a/framework/base/src/contract_base/wrappers/send_wrapper.rs b/framework/base/src/contract_base/wrappers/send_wrapper.rs index 790fbd1631..02387193a1 100644 --- a/framework/base/src/contract_base/wrappers/send_wrapper.rs +++ b/framework/base/src/contract_base/wrappers/send_wrapper.rs @@ -50,11 +50,17 @@ where SendRawWrapper::new() } + /// A proxy for calling the system smart contract. + /// + /// Use the methods of this proxy to launch contract calls to the system SC. #[inline] pub fn esdt_system_sc_proxy(&self) -> ESDTSystemSmartContractProxy { ESDTSystemSmartContractProxy::new_proxy_obj() } + /// Convenient way to quickly instance a minimal contract call (with no EGLD, no arguments, etc.) + /// + /// You can further configure this contract call by chaining methods to it. #[inline] pub fn contract_call( &self, @@ -73,7 +79,8 @@ where /// Sends EGLD to a given address, directly. /// Used especially for sending EGLD to regular accounts. - /// If amount is 0 returns without error + /// + /// If the amount is 0, it returns without error. pub fn direct_non_zero_egld(&self, to: &ManagedAddress, amount: &BigUint) { if amount == &0 { return; @@ -96,8 +103,9 @@ where } /// Sends either EGLD, ESDT or NFT to the target address, - /// depending on the token identifier and nonce - /// If amount is 0 returns without error + /// depending on the token identifier and nonce. + /// + /// If the amount is 0, it returns without error. #[inline] pub fn direct_non_zero( &self, @@ -109,6 +117,9 @@ where self.direct_non_zero_with_gas_limit(to, token, nonce, amount, 0, Empty, &[]); } + /// Sends a single ESDT transfer, and calls an endpoint at the destination. + /// + /// Avoid if possible, use a contract call with ESDT transfer instead, and call `.transfer_execute()` on it. #[allow(clippy::too_many_arguments)] pub fn direct_esdt_with_gas_limit( &self, @@ -144,7 +155,11 @@ where } } - /// If amount is 0 returns without error + /// Sends a single ESDT transfer, and calls an endpoint at the destination. + /// + /// If the amount is 0, it returns without error. + /// + /// Avoid if possible, use a contract call with ESDT transfer instead, and call `.transfer_execute()` on it. #[allow(clippy::too_many_arguments)] pub fn direct_non_zero_esdt_with_gas_limit( &self, @@ -172,6 +187,7 @@ where ); } + /// Sends a single ESDT transfer to target address. #[inline] #[allow(clippy::too_many_arguments)] pub fn direct_esdt( @@ -184,7 +200,9 @@ where self.direct_esdt_with_gas_limit(to, token_identifier, nonce, amount, 0, Empty, &[]); } - /// If amount is 0 returns without error + /// Sends a single ESDT transfer to target address. + /// + /// If the amount is 0, it returns without error. pub fn direct_non_zero_esdt_payment( &self, to: &ManagedAddress, @@ -202,6 +220,11 @@ where ); } + /// Sends either EGLD, ESDT or NFT to the target address, + /// depending on the token identifier and nonce. + /// Also and calls an endpoint at the destination. + /// + /// Avoid if possible, use a contract call with ESDT transfer instead, and call `.transfer_execute()` on it. #[allow(clippy::too_many_arguments)] pub fn direct_with_gas_limit( &self, @@ -235,8 +258,13 @@ where ); } } - - /// If amount is 0 returns without error + /// Sends either EGLD, ESDT or NFT to the target address, + /// depending on the token identifier and nonce. + /// Also and calls an endpoint at the destination. + /// + /// If the amount is 0, it returns without error. + /// + /// Avoid if possible, use a contract call with ESDT transfer instead, and call `.transfer_execute()` on it. #[allow(clippy::too_many_arguments)] pub fn direct_non_zero_with_gas_limit( &self, @@ -256,6 +284,7 @@ where self.direct_with_gas_limit(to, token, nonce, amount, gas, endpoint_name, arguments); } + /// Sends multiple ESDT tokens to a target address. pub fn direct_multi( &self, to: &ManagedAddress, @@ -271,9 +300,12 @@ where } /// Performs a simple ESDT/NFT transfer, but via async call. - /// As with any async call, this immediately terminates the execution of the current call. - /// So only use as the last call in your endpoint. - /// If you want to perform multiple transfers, use `self.send().transfer_multiple_esdt_via_async_call()` instead. + /// + /// As with any async call, this immediately terminates the execution of the current call, + /// so only use as the last call in your endpoint. + /// + /// If you want to perform multiple transfers, use `self.send().transfer_multiple_esdt_via_async_call()` instead. + /// /// Note that EGLD can NOT be transfered with this function. pub fn transfer_esdt_via_async_call( &self, @@ -289,11 +321,14 @@ where } /// Performs a simple ESDT/NFT transfer, but via async call. - /// As with any async call, this immediately terminates the execution of the current call. - /// So only use as the last call in your endpoint. + /// + /// As with any async call, this immediately terminates the execution of the current call, + /// so only use as the last call in your endpoint. + /// /// If you want to perform multiple transfers, use `self.send().transfer_multiple_esdt_via_async_call()` instead. /// Note that EGLD can NOT be transfered with this function. - /// If amount is 0 returns without error + /// + /// If the amount is 0, it returns without error. pub fn transfer_esdt_non_zero_via_async_call( &self, to: ManagedAddress, @@ -310,6 +345,7 @@ where .call_and_exit_ignore_callback() } + /// Sends multiple ESDT tokens to a target address, via an async call. pub fn transfer_multiple_esdt_via_async_call( &self, to: ManagedAddress, @@ -321,6 +357,9 @@ where .call_and_exit_ignore_callback() } + /// Creates a call to the `ClaimDeveloperRewards` builtin function. + /// + /// In itself, this does nothing. You need to then call turn the contract call into an async call. pub fn claim_developer_rewards( &self, child_sc_address: ManagedAddress, @@ -328,7 +367,9 @@ where ContractCallNoPayment::new(child_sc_address, CLAIM_DEVELOPER_REWARDS_FUNC_NAME) } - /// Sends a synchronous call to change a smart contract address. + /// Creates a call to the `ChangeOwnerAddress` builtin function. + /// + /// In itself, this does nothing. You need to then call turn the contract call into an async call. pub fn change_owner_address( &self, child_sc_address: ManagedAddress, @@ -354,9 +395,12 @@ where } /// Allows synchronous minting of ESDT/SFT (depending on nonce). Execution is resumed afterwards. + /// /// Note that the SC must have the ESDTLocalMint or ESDTNftAddQuantity roles set, - /// or this will fail with "action is not allowed" + /// or this will fail with "action is not allowed". + /// /// For SFTs, you must use `self.send().esdt_nft_create()` before adding additional quantity. + /// /// This function cannot be used for NFTs. pub fn esdt_local_mint(&self, token: &TokenIdentifier, nonce: u64, amount: &BigUint) { let mut arg_buffer = ManagedArgBuffer::new(); @@ -381,11 +425,14 @@ where } /// Allows synchronous minting of ESDT/SFT (depending on nonce). Execution is resumed afterwards. + /// /// Note that the SC must have the ESDTLocalMint or ESDTNftAddQuantity roles set, - /// or this will fail with "action is not allowed" + /// or this will fail with "action is not allowed". + /// /// For SFTs, you must use `self.send().esdt_nft_create()` before adding additional quantity. /// This function cannot be used for NFTs. - /// If amount is 0 returns without error + /// + /// If the amount is 0, it returns without error. pub fn esdt_non_zero_local_mint( &self, token: &TokenIdentifier, @@ -399,8 +446,9 @@ where } /// Allows synchronous burning of ESDT/SFT/NFT (depending on nonce). Execution is resumed afterwards. + /// /// Note that the SC must have the ESDTLocalBurn or ESDTNftBurn roles set, - /// or this will fail with "action is not allowed" + /// or this will fail with "action is not allowed". pub fn esdt_local_burn(&self, token: &TokenIdentifier, nonce: u64, amount: &BigUint) { let mut arg_buffer = ManagedArgBuffer::new(); let func_name: &str; @@ -423,9 +471,11 @@ where } /// Allows synchronous burning of ESDT/SFT/NFT (depending on nonce). Execution is resumed afterwards. + /// /// Note that the SC must have the ESDTLocalBurn or ESDTNftBurn roles set, - /// or this will fail with "action is not allowed" - /// If amount is 0 returns without error + /// or this will fail with "action is not allowed". + /// + /// If the amount is 0, it returns without error. pub fn esdt_non_zero_local_burn( &self, token: &TokenIdentifier, @@ -454,7 +504,8 @@ where /// Allows burning of multiple ESDT tokens at once. /// /// Will execute a synchronous call to the appropriate burn builtin function for each. - /// If any of the token amounts is 0 skips that token without throwing error + /// + /// If any of the token amounts is 0 skips that token without throwing error. pub fn esdt_non_zero_local_burn_multi(&self, payments: &ManagedVec>) { for payment in payments { self.esdt_non_zero_local_burn( @@ -465,10 +516,13 @@ where } } - /// Creates a new NFT token of a certain type (determined by `token_identifier`). + /// Creates a new NFT token of a certain type (determined by `token_identifier`). /// `attributes` can be any serializable custom struct. - /// This is a built-in function, so the smart contract execution is resumed after. + /// + /// This is a synchronous built-in function call, so the smart contract execution is resumed afterwards. + /// /// Must have ESDTNftCreate role set, or this will fail with "action is not allowed". + /// /// Returns the nonce of the newly created NFT. #[allow(clippy::too_many_arguments)] pub fn esdt_nft_create( @@ -513,12 +567,16 @@ where } } - /// Creates a new NFT token of a certain type (determined by `token_identifier`). - /// `attributes` can be any serializable custom struct. + /// Creates a new NFT token of a certain type (determined by `token_identifier`). + /// + /// `attributes` can be any serializable custom struct. + /// /// This is a built-in function, so the smart contract execution is resumed after. /// Must have ESDTNftCreate role set, or this will fail with "action is not allowed". + /// /// Returns the nonce of the newly created NFT. - /// If amount is 0 returns without error + /// + /// If the amount is 0, it returns without error. #[allow(clippy::too_many_arguments)] pub fn esdt_non_zero_nft_create( &self, @@ -537,6 +595,9 @@ where } } + /// Quick way of creating a new NFT token instance. + /// + /// Returns the new NFT nonce. #[inline] pub fn esdt_nft_create_compact( &self, @@ -547,6 +608,9 @@ where self.esdt_nft_create_compact_named(token, amount, &ManagedBuffer::new(), attributes) } + /// Quick way of creating a new NFT token instance, with custom name. + /// + /// Returns the new NFT nonce. pub fn esdt_nft_create_compact_named( &self, token: &TokenIdentifier, @@ -569,7 +633,11 @@ where ) } - /// If amount is 0 returns without error + /// Quick way of creating a new NFT token instance. + /// + /// Returns the new NFT nonce. + /// + /// If the amount is 0, it returns without error. #[inline] pub fn esdt_non_zero_nft_create_compact( &self, @@ -585,7 +653,11 @@ where ) } - /// If amount is 0 returns without error + /// Quick way of creating a new NFT token instance, with custom name. + /// + /// Returns the new NFT nonce. + /// + /// If the amount is 0, it returns without error. pub fn esdt_non_zero_nft_create_compact_named( &self, token: &TokenIdentifier, @@ -601,6 +673,7 @@ where } /// Sends the NFTs to the buyer address and calculates and sends the required royalties to the NFT creator. + /// /// Returns the payment amount left after sending royalties. #[allow(clippy::too_many_arguments)] pub fn sell_nft( @@ -645,7 +718,9 @@ where } /// Sends the NFTs to the buyer address and calculates and sends the required royalties to the NFT creator. + /// /// Returns the payment amount left after sending royalties. + /// /// If the nft_amount or the payment_amount is 0 returns without error #[allow(clippy::too_many_arguments)] pub fn sell_nft_non_zero( @@ -673,6 +748,7 @@ where } } + /// Adds a new URI to an NFT, via a synchronous builtin function call. pub fn nft_add_uri( &self, token_id: &TokenIdentifier, @@ -682,6 +758,7 @@ where self.nft_add_multiple_uri(token_id, nft_nonce, &ManagedVec::from_single_item(new_uri)); } + /// Adds a multiple URIs to an NFT, via a synchronous builtin function call. pub fn nft_add_multiple_uri( &self, token_id: &TokenIdentifier, @@ -707,6 +784,7 @@ where ); } + /// Changes attributes of an NFT, via a synchronous builtin function call. pub fn nft_update_attributes( &self, token_id: &TokenIdentifier,