Skip to content

Commit

Permalink
SendWrapper improved docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@andrei-marinica
andrei-marinica committed Sep 8, 2023
1 parent 84ffda6 commit 9de7e9e
Showing 1 changed file with 106 additions and 28 deletions.
134 changes: 106 additions & 28 deletions framework/base/src/contract_base/wrappers/send_wrapper.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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<A> {
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<R>(
&self,
Expand All @@ -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<A>, amount: &BigUint<A>) {
if amount == &0 {
return;
Expand All @@ -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,
Expand All @@ -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<D>(
&self,
Expand Down Expand Up @@ -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<D>(
&self,
Expand Down Expand Up @@ -172,6 +187,7 @@ where
);
}

/// Sends a single ESDT transfer to target address.
#[inline]
#[allow(clippy::too_many_arguments)]
pub fn direct_esdt(
Expand All @@ -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<A>,
Expand All @@ -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<D>(
&self,
Expand Down Expand Up @@ -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<D>(
&self,
Expand All @@ -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<A>,
Expand All @@ -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,
Expand All @@ -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<A>,
Expand All @@ -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<A>,
Expand All @@ -321,14 +357,19 @@ 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<A>,
) -> ContractCallNoPayment<A, ()> {
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<A>,
Expand All @@ -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<A>, nonce: u64, amount: &BigUint<A>) {
let mut arg_buffer = ManagedArgBuffer::new();
Expand All @@ -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<A>,
Expand All @@ -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<A>, nonce: u64, amount: &BigUint<A>) {
let mut arg_buffer = ManagedArgBuffer::new();
let func_name: &str;
Expand All @@ -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<A>,
Expand Down Expand Up @@ -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<A, EsdtTokenPayment<A>>) {
for payment in payments {
self.esdt_non_zero_local_burn(
Expand All @@ -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<T: codec::TopEncode>(
Expand Down Expand Up @@ -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<T: codec::TopEncode>(
&self,
Expand All @@ -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<T: codec::TopEncode>(
&self,
Expand All @@ -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<T: codec::TopEncode>(
&self,
token: &TokenIdentifier<A>,
Expand All @@ -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<T: codec::TopEncode>(
&self,
Expand All @@ -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<T: codec::TopEncode>(
&self,
token: &TokenIdentifier<A>,
Expand All @@ -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(
Expand Down Expand Up @@ -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(
Expand Down Expand Up @@ -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<A>,
Expand All @@ -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<A>,
Expand All @@ -707,6 +784,7 @@ where
);
}

/// Changes attributes of an NFT, via a synchronous builtin function call.
pub fn nft_update_attributes<T: codec::TopEncode>(
&self,
token_id: &TokenIdentifier<A>,
Expand Down

0 comments on commit 9de7e9e

Please sign in to comment.