From e666498627d8a0c32736d75a8d3e7c9590b1f29c Mon Sep 17 00:00:00 2001 From: "Julian.io" Date: Sun, 7 Jan 2024 21:52:08 +0100 Subject: [PATCH 1/3] Update esdt-tokens.mdx Add info about optional method call also in ESDT multi transfer --- docs/tokens/esdt-tokens.mdx | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/tokens/esdt-tokens.mdx b/docs/tokens/esdt-tokens.mdx index 0d6dfacf9..d350fcf95 100644 --- a/docs/tokens/esdt-tokens.mdx +++ b/docs/tokens/esdt-tokens.mdx @@ -330,6 +330,8 @@ Sending a transaction containing both an ESDT transfer _and a method call_ allow There is also the possibility to perform multiple tokens transfers in a single bulk. This way, one can send (to a single receiver) multiple fungible, semi-fungible or non-fungible tokens via a single transaction. +It is also possible to send ESDT tokens to a contract as part of a method call. + A multi-token transfer transaction has the following form: ```rust @@ -347,6 +349,9 @@ MultiTokensTransferTransaction { "@" + + "@" + + "@" + + + "@" + + + "@" + + + "@" + + ... } ``` From 5395ac6ed4492885ab2e2f65250d67def8f5bda2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Julian=20=C4=86wirko?= Date: Mon, 15 Jan 2024 18:40:41 +0100 Subject: [PATCH 2/3] add separate section for multi transfer to a smart contract --- docs/tokens/esdt-tokens.mdx | 72 ++++++++++++++++++++++++++++++++++--- 1 file changed, 67 insertions(+), 5 deletions(-) diff --git a/docs/tokens/esdt-tokens.mdx b/docs/tokens/esdt-tokens.mdx index d350fcf95..2cbcc4fbe 100644 --- a/docs/tokens/esdt-tokens.mdx +++ b/docs/tokens/esdt-tokens.mdx @@ -330,8 +330,6 @@ Sending a transaction containing both an ESDT transfer _and a method call_ allow There is also the possibility to perform multiple tokens transfers in a single bulk. This way, one can send (to a single receiver) multiple fungible, semi-fungible or non-fungible tokens via a single transaction. -It is also possible to send ESDT tokens to a contract as part of a method call. - A multi-token transfer transaction has the following form: ```rust @@ -349,9 +347,6 @@ MultiTokensTransferTransaction { "@" + + "@" + + "@" + + - "@" + + - "@" + + - "@" + + ... } ``` @@ -390,6 +385,73 @@ Using the transaction in the example above, the receiver should be credited `12 [comment]: # (mx-context-auto) +## **Multiple tokens transfer to a smart contract** + +Smart contracts may hold ESDT tokens and perform any kind of transaction with them, just like any Account. However, there are a few extra ESDT features dedicated to smart contracts: + +**Payable versus non-payable contract**: upon deployment, a smart contract may be marked as _payable_, which means that it can receive either EGLD or ESDT tokens without calling any of its methods (i.e. a simple transfer). But by default, all contracts are _non-payable_, which means that simple transfers of EGLD or ESDT tokens will be rejected, unless they are method calls. + +**ESDT transfer with method invocation**: it is possible to send ESDT tokens to a contract _as part of a method call_, just like sending EGLD as part of a method call. A transaction that sends ESDT tokens to a contract while also calling one of its methods has the following form: + +```rust +MultiTokensTransferWithCallTransaction { + Sender: + Receiver: + Value: 0 + GasLimit: 1_100_000 * num tokens + + Data: "MultiESDTNFTTransfer" + + "@" + + + "@" + + + "@" + + + "@" + + + "@" + + + "@" + + + "@" + + + "@" + + + "@" + + + "@" + + + "@" + + + ... +} +``` + +:::tip +Each token requires the token identifier, the nonce and the quantity to transfer. + +For fungible tokens (regular ESDT) the nonce has to be 0 (`00` hex-encoded) +::: + +_For more details about how arguments have to be encoded, check [here](/developers/sc-calls-format)._ + +Example: + +We send tokens and call the 'transfer' method on the smart contract. We also define the receiver as the argument of the transfer method. + +```rust +MultiTokensTransferWithCallTransaction { + Sender: erd1sg4u62lzvgkeu4grnlwn7h2s92rqf8a64z48pl9c7us37ajv9u8qj9w8xg + Receiver: erd1sg4u62lzvgkeu4grnlwn7h2s92rqf8a64z48pl9c7us37ajv9u8qj9w8xg + Value: 0 + GasLimit: 8_200_000 + Data: "MultiESDTNFTTransfer" + + "@0000000000000000050032a3dc7511d6062c6a3b90ac02d8c3f474ef71c65008" + // smart contract address: erd1qqqqqqqqqqqqqpgqx23acag36crzc63mjzkq9kxr736w7uwx2qyqcmq7ar + "@02" + // 2 tokens to transfer + "@414c432d363235386432" + // ALC-6258d2 + "@00" + // 0 -> the nonce is 0 for regular ESDT tokens + "@0c" + // 12 -> value to transfer + "@5346542d317134723869" + // SFT-1q4r8i + "@01" + // 1 -> the nonce of the SFT + "@03" + // 3 -> the quantity to transfer + "@7472616e73666572" + // method name is 'transfer' + "@f69adc800dca9e3ba3328d17ded25f3a8f328aa1e0e8a347f34ce5ea3aac5008" // there is one argument, the address: 'erd176ddeqqde20rhgej35taa5jl828n9z4pur52x3lnfnj75w4v2qyqa230vx' +} +``` + +Sending a transaction containing both an ESDT transfer _and a method call_ allows non-payable smart contracts to receive tokens as part of the call, as if it were EGLD. The smart contract may use dedicated API functions to inspect the name of the received ESDT tokens and their amount, and react accordingly. + +[comment]: # (mx-context-auto) + + ## **Transfers done programmatically** The [Rust framework](https://github.com/multiversx/mx-sdk-rs) exposes several ways in which you can transfer ESDT tokens. For example, in order to transfer _amount_ of _esdt_token_name_ to _address_, one would do the following: From 8fd86042ac17f4136f2bb7b838e8504137784820 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Julian=20=C4=86wirko?= Date: Mon, 15 Jan 2024 18:43:31 +0100 Subject: [PATCH 3/3] remove an empty line --- docs/tokens/esdt-tokens.mdx | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/tokens/esdt-tokens.mdx b/docs/tokens/esdt-tokens.mdx index 2cbcc4fbe..3a42589f7 100644 --- a/docs/tokens/esdt-tokens.mdx +++ b/docs/tokens/esdt-tokens.mdx @@ -451,7 +451,6 @@ Sending a transaction containing both an ESDT transfer _and a method call_ allow [comment]: # (mx-context-auto) - ## **Transfers done programmatically** The [Rust framework](https://github.com/multiversx/mx-sdk-rs) exposes several ways in which you can transfer ESDT tokens. For example, in order to transfer _amount_ of _esdt_token_name_ to _address_, one would do the following: