Skip to content

Update relayed v3 docs #1024

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
sstanculeanu merged 5 commits into from
Dec 11, 2024
Merged

Update relayed v3 docs #1024

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
edd02bb
updated relayed v3 docs
sstanculeanu Dec 5, 2024
518927c
fixes after review
sstanculeanu Dec 5, 2024
0a95ed5
removed note for dynft
sstanculeanu Dec 5, 2024
ada0c98
fixes after review
sstanculeanu Dec 9, 2024
e42af77
clarifications
sstanculeanu Dec 9, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
134 changes: 32 additions & 102 deletions docs/developers/relayed-transactions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -253,136 +253,66 @@ Decoding the arguments ([useful resources here](/developers/sc-calls-format/)) w
This feature is not yet available on **Mainnet**. See [Spica Protocol Upgrade](https://governance.multiversx.com/proposal/erd1qqqqqqqqqqqqqpgq4qvrwlr2e6ld50f3qfc94am38p8298kthg4s3f0vfn/1).
:::

Relayed transactions v3 feature comes with a change on the entire transaction structure, adding a new optional field `InnerTransactions`, which is a collection of inner transactions. That being said, relayed transactions v3 allow the user to send multiple inner transactions on the same relayed transaction which will be executed as normal transactions, without the gas consuming data field of the old relayed transactions versions.
Relayed transactions v3 feature comes with a change on the entire transaction structure, adding two new optional fields:
- `relayer`, which is the relayer address that will pay the fees.
- `relayerSignature`, the signature of the relayer that proves the agreement of the relayer.

In terms of gas limit computation, let's consider the following example: relayed transaction with one inner transaction of type move balance, that also has a data field `test` of length 4.
That being said, relayed transactions v3 will look and behave very similar to a regular transaction, the only difference being the gas consumption from the relayer. It is no longer needed to specify the user transaction in the data field.

In terms of gas limit computation, an extra base cost will be consumed. Let's consider the following example: relayed transaction with inner transaction of type move balance, that also has a data field `test` of length 4.
```js
gasLimitInnerTxs = <base_cost> + <cost_per_byte> * length(txData)
gasLimitInnerTxs = 50_000 + 4 * 1_500
gasLimitInnerTxs = 56_000
gasLimitInnerTx = <base_cost> + <cost_per_byte> * length(txData)
gasLimitInnerTx = 50_000 + 4 * 1_500
gasLimitInnerTx = 56_000

gasLimitRelayedTx = <move_balance_cost> * len(inner_transactions) + <gasLimitInnerTxs>
gasLimitRelayedTx = 50_000 * 1 + 56_000
gasLimitRelayedTx = <base_cost> + <gasLimitInnerTx>
gasLimitRelayedTx = 50_000 + 56_000
gasLimitRelayedTx = 106_000
```

Similar for a relayed transaction v3 that has 3 inner transactions of type move balance(empty data field on each):
```js
gasLimitInnerTxs = <move_balance_cost> + <move_balance_cost> + <move_balance_cost>
gasLimitInnerTxs = 50_000 + 50_000 + 50_000
gasLimitInnerTxs = 150_000

gasLimitRelayedTx = <move_balance_cost> * len(inner_transactions) + <gasLimitInnerTxs>
gasLimitRelayedTx = 50_000 * 3 + 150_000
gasLimitRelayedTx = 300_000
```

It would look like:

```rust
RelayedV3Transaction {
Sender: <Relayer address>
Receiver: <Relayer address>
Value: 0
GasLimit: <move_balance_cost> * len(InnerTransactions) + sum(<gas needed for each inner transaction>)
InnerTransactions: []Transaction {
{
"nonce": <Nonce>,
"value": <Value>,
"receiver": <Receiver address>,
"sender": <Sender address>,
"gasLimit": <Gas limit>,
"data": <Data>,
"relayer": <Relayer address>,
},
{
"nonce": <Nonce>,
"value": <Value>,
"receiver": <Receiver address>,
"sender": <Sender address>,
"gasLimit": <Gas limit>,
"data": <Data>,
"relayer": <Relayer address>,
},
...
}
Sender: <Sender address>
Receiver: <Receiver address>
Value: <value>
GasLimit: <base_cost> + <base_cost> + <cost_per_byte> * length(txData)
Relayer: <Relayer address>
RelayerSignature: <Relayer signature>
Signature: <Sender signature>
}
```

Therefore, in order to build such a transaction, one has to follow the next steps:

- create the inner transactions. Make sure that:
- all inner transactions have the `relayer` field set to the address that would pay the gas
- all inner transactions senders are in **the same shard** with the relayer
- in case there are multiple inner transactions from the same sender, the transactions are in the order of the execution, with increasing correct nonces, starting from the current sender's nonce
- all inner transactions are valid and signed
- create the relayed transactions:
- the receiver of the relayed transactions is the relayer
- value must be 0 and data field empty
- add all inner transactions on the `innerTransactions` field
- compute the gas limit: `move balance cost * number of inner transactions + sum of all inner transactions gas limits`
- set the `relayer` field to the address that would pay the gas
- add the extra base cost for the relayed operation
- add sender's signature
- add relayer's signature

:::note
1. If the relayed transaction v3 is guarded, the cost of the guarded transaction will be consumed only once, not for each inner transaction.
2. There are situations where inner transactions are initially accepted, but before their execution, the underlying state changes (due to the execution of other transactions), rendering some or all of these transactions invalid. In such cases, the relayer will still incur gas costs (pays the fee), even though these inner transactions produce no effects.
1. For a guarded relayed transaction, the guarded operation fee will also be consumed from the relayer.
2. Relayer must be different from guardian, in case of guarded sender.
3. Guarded relayers are not allowed.
:::

### Example

Here's an example of a relayed v3 transaction. Its intent is:
- 2 sc calls of method `add@01` of a previously deployed adder contract
- 1 move balance
Here's an example of a relayed v3 transaction. Its intent is to call the `add` method of a previously deployed adder contract, with parameter `01`

```json
{
"nonce": 0,
"value": "0",
"receiver": "erd1dcad0dlle658mggthhpvaypjag2et25yk3c2r7p9gjqkgqpxtukqcqakt0",
"sender": "erd1dcad0dlle658mggthhpvaypjag2et25yk3c2r7p9gjqkgqpxtukqcqakt0",
"receiver": "erd1qqqqqqqqqqqqqpgqeunf87ar9nqeey5ssvpqwe74ehmztx74qtxqs63nmx",
Copy link
Contributor

@AdoAdoAdo AdoAdoAdo Dec 5, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

data field is missing "YWRkQDAx"

"sender": "erd1spyavw0956vq68xj8y4tenjpq2wd5a9p2c6j8gsz7ztyrnpxrruqzu66jx",
"data": "YWRkQDAx",
"gasPrice": 1000000000,
"gasLimit": 10200000,
"gasLimit": 5000000,
"signature": "...",
"chainID": "T",
"version": 2,
"innerTransactions": [
{
"nonce": 1,
"value": "0",
"receiver": "erd1qqqqqqqqqqqqqpgq3tssqmcde5w6626mkrm9cehcqgquwmvwl0jq3umv7s",
"sender": "erd1ws52y4t8pmwx9zcuwg0swxymxkg6dwsfpcf3qxmsjvzjtmwkl0jqpn44dn",
"gasPrice": 1000000000,
"gasLimit": 5000000,
"data": "YWRkQDAx",
"signature": "...",
"chainID": "T",
"version": 2,
"relayer": "erd1dcad0dlle658mggthhpvaypjag2et25yk3c2r7p9gjqkgqpxtukqcqakt0"
},
{
"nonce": 2,
"value": "0",
"receiver": "erd1qqqqqqqqqqqqqpgq3tssqmcde5w6626mkrm9cehcqgquwmvwl0jq3umv7s",
"sender": "erd1ws52y4t8pmwx9zcuwg0swxymxkg6dwsfpcf3qxmsjvzjtmwkl0jqpn44dn",
"gasPrice": 1000000000,
"gasLimit": 5000000,
"data": "YWRkQDAx",
"signature": "...",
"chainID": "T",
"version": 2,
"relayer": "erd1dcad0dlle658mggthhpvaypjag2et25yk3c2r7p9gjqkgqpxtukqcqakt0"
},
{
"nonce": 0,
"value": "1000000000000000000",
"receiver": "erd1v7p7uefggz04qst7fzd8hwrl95v03g5uh5fj9vka6ydmdguqy6ws28at85",
"sender": "erd1xfr34s4yft7pk4gf8mt7a2kkfz4z2f3rvuy9pwlgkeymue8pcfkqfxv2mv",
"gasPrice": 1000000000,
"gasLimit": 50000,
"signature": "...",
"chainID": "T",
"version": 2,
"relayer": "erd1dcad0dlle658mggthhpvaypjag2et25yk3c2r7p9gjqkgqpxtukqcqakt0"
}
]
"relayer": "erd1qyu5wthldzr8wx5c9ucg8kjagg0jfs53s8nr3zpz3hypefsdd8ssycr6th",
"relayerSignature": "..."
}
```
47 changes: 35 additions & 12 deletions docs/sdk-and-tools/sdk-py/mxpy-cli.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -530,35 +530,58 @@ If your address is guarded by another wallet, you'll still need to provide the `

[comment]: # (mx-context-auto)

## Relayed V3 transactions
## Relayed transactions V3

Relayed transactions are transactions with the fee paid by a so-called relayer. In other words, if a relayer is willing to pay for a transaction, it is not mandatory for the sender to have any EGLD for fees. To learn more about relayed transactions check out [this page](/developers/relayed-transactions/).

In this section we'll see how we can send `Relayed V3` transactions using `mxpy`. For a more detailed look on `Relayed V3` transactions, take a look [here](/developers/relayed-transactions/#relayed-transactions-version-3). For these kind of transactions a new transaction field has been introduced, called `innerTransactions`. In this example we'll see how we can create both the inner transactions and the relayed transaction.
In this section we'll see how we can send `Relayed V3` transactions using `mxpy`. For a more detailed look on `Relayed V3` transactions, take a look [here](/developers/relayed-transactions/#relayed-transactions-version-3). For these kind of transactions two new transaction fields were introduced, `relayer` and `relayerSignature`. In this example we'll see how we can create the relayed transaction.

### Creating the inner transactions
For this, a new command `mxpy tx relay` has been added. The command can be used to relay a previously signed transaction. The saved transaction can be loaded from a file using the `--infile` argument.

We can simply create the inner transactions the same way we did above, by using the `mxpy tx new` command. The only difference is that we'll have to provide an additional argument called `--inner-transactions-outfile`, which represents the file where the inner transactions are saved to be later used by the relayer. To keep it simple, we'll send 1 EGLD from Alice to Bob, and Carol will be the relayer. To create the EGLD transfer transaction from Alice to Bob, we run the following command:
There are two options when creating the relayed transaction:
1. Create the relayed transaction separately. (Sender signature and relayer signature are added by different entities.)
2. Create the complete relayed transaction. (Both signatures are added by the same entity.)
Comment on lines +542 to +543
Copy link
Contributor

@andreibancioiu andreibancioiu Dec 9, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A bit of parenthesis and full stop inconsistencies.

Instead of:

Create the relayed transaction separately. (Sender signature and relayer signature are added by different entities.)

Maybe better:

Create the relayed transaction separately (sender signature and relayer signature are added by different entities).


### Creating the inner transaction
Copy link
Contributor

@popenta popenta Dec 5, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am not sure we should still call it inner transaction.

Copy link
Contributor Author

@sstanculeanu sstanculeanu Dec 5, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

should be ok, for both v1 and v2 inner is used


The inner transaction is any regular transaction, with the following notes:
- relayer address must be added
- extra 50000 (base cost) gas must be added for the relayed operation. For more details on how the gas is computed, check out [this page](/developers/relayed-transactions/#relayed-transactions-version-3).

This can be generated through `mxpy tx new` command. A new argument `--relayer` has been added for this feature.

```sh
mxpy tx new --pem ~/multiversx-sdk/testwallets/latest/users/alice.pem --recall-nonce \
--receiver erd1spyavw0956vq68xj8y4tenjpq2wd5a9p2c6j8gsz7ztyrnpxrruqzu66jx \
--gas-limit 50000 --value 1000000000000000000 \
--gas-limit 100000 --value 1000000000000000000 \
--proxy https://devnet-gateway.multiversx.com --chain D \
--relayer erd1k2s324ww2g0yj38qn2ch2jwctdy8mnfxep94q9arncc6xecg3xaq6mjse8
--inner-transactions-outfile inner_transactions.json
--relayer erd1k2s324ww2g0yj38qn2ch2jwctdy8mnfxep94q9arncc6xecg3xaq6mjse8 \
--outfile inner_tx.json
```

After creating the inner transaction, we are ready to create the relayed transaction. We have to keep in mind that for `Relayed V3` transactions, the receiver has to be the same as the relayer, in our case, Carol. Another requirement is that the relayed transaction has to have enough gas. The gas is computed by multiplying the base cost (50_000) with the number of inner transactions plus the gasLimit for each inner transaction. For more details on how the gas is computed, check out [this page](/developers/relayed-transactions/#relayed-transactions-version-3).
After creating the inner transaction, we are ready to create the relayed transaction.

### Creating the relayed transaction

We can create the relayed transaction by running the following command:

```sh
mxpy tx new --pem ~/multiversx-sdk/testwallets/latest/users/carol.pem --recall-nonce \
--receiver erd1k2s324ww2g0yj38qn2ch2jwctdy8mnfxep94q9arncc6xecg3xaq6mjse8 \
--gas-limit 1000000 --value 0 \
mxpy tx relay --relayer-pem ~/multiversx-sdk/testwallets/latest/users/carol.pem \
--proxy https://devnet-gateway.multiversx.com --chain D \
--infile inner_tx.json \
--send
```

### Creating the relayed transaction in one step

This can be done through `mxpy tx new` command, as follows:
```sh
mxpy tx new --pem ~/multiversx-sdk/testwallets/latest/users/alice.pem --recall-nonce \
--receiver erd1spyavw0956vq68xj8y4tenjpq2wd5a9p2c6j8gsz7ztyrnpxrruqzu66jx \
--relayer erd1k2s324ww2g0yj38qn2ch2jwctdy8mnfxep94q9arncc6xecg3xaq6mjse8 \
--relayer-pem ~/multiversx-sdk/testwallets/latest/users/carol.pem \
--gas-limit 100000 --value 1000000000000000000 \
--proxy https://devnet-gateway.multiversx.com --chain D \
--inner-transactions inner_transactions.json \
--send
```

Expand Down
3 changes: 0 additions & 3 deletions docs/tokens/nft-tokens.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,9 +15,6 @@ import TableWrapper from "@site/src/components/TableWrapper";

MultiversX NFTs(non-fungible tokens) are a breed of digital assets that are revolutionizing the world of art, collectibles, and more. These NFTs are unique, one-of-a-kind tokens that are built on blockchain technology, allowing for secure ownership and transfer of these assets. With MultiversX NFTs, every token is assigned a unique identification code(ticker) and metadata that distinguishes it from every other token, making each NFT truly one-of-a-kind. Read the full page for a comprehensive guide on how to brand, issue, transfer, assign roles and many other features, for both NFTs and SFTs.

:::note
Features related to dynamic NFTs are not yet available on **Mainnet**. See [Spica Protocol Upgrade](https://governance.multiversx.com/proposal/erd1qqqqqqqqqqqqqpgq4qvrwlr2e6ld50f3qfc94am38p8298kthg4s3f0vfn/1).
:::

[comment]: # (mx-context-auto)

Expand Down
Loading