From b9addfed71d4138251070eb273eb0f659c908dcb Mon Sep 17 00:00:00 2001 From: miiu Date: Tue, 29 Jul 2025 13:37:49 +0300 Subject: [PATCH 1/4] extra info cost endpoint --- docs/sdk-and-tools/rest-api/transactions.mdx | 24 ++++++++++++++++---- 1 file changed, 20 insertions(+), 4 deletions(-) diff --git a/docs/sdk-and-tools/rest-api/transactions.mdx b/docs/sdk-and-tools/rest-api/transactions.mdx index 8889fc9cc..0d71343ae 100644 --- a/docs/sdk-and-tools/rest-api/transactions.mdx +++ b/docs/sdk-and-tools/rest-api/transactions.mdx @@ -347,7 +347,16 @@ Example response for cross-shard transactions: `https://gateway.multiversx.com/transaction/cost` -This endpoint allows one to estimate the cost of a transaction. + +:::note +This endpoint estimates the **gas cost** of a transaction. Use this value to determine the appropriate `gasLimit` before sending a transaction. + +In the background, this endpoint simulates the transaction in a read-only environment to estimate its gas cost. Any resulting smart contract results and events will also be returned. +::: + +:::warning +As the transaction is executed in a simulated environment, `providing the correct nonce is mandatory`. +::: REQUIRED | `string` | The Value to transfer, as a string representation of a Big Integer (can be "0"). | | receiver | REQUIRED | `string` | The Address (bech32) of the Receiver. | | sender | REQUIRED | `string` | The Address (bech32) of the Sender. | -| data | OPTIONAL | `string` | The base64 string representation of the Transaction's message (data). | | chainID | REQUIRED | `string` | The Chain identifier. | | version | REQUIRED | `number` | The Version of the Transaction (e.g. 1). | -| nonce | OPTIONAL | `number` | The Sender nonce. | +| nonce | REQUIRED | `number` | The Sender nonce. | +| options | OPTIONAL | `number` | The Options of the Transaction (e.g. 1). | +| data | OPTIONAL | `string` | The base64 string representation of the Transaction's message (data). | + @@ -390,7 +401,12 @@ The cost is estimated successfully. :::tip -This endpoint returns the cost on the transaction in **gas units**. The returned value can be used to fill in **gasLimit** field of the transaction. +- Use the returned `txGasUnits` value as the `gasLimit` in your actual transaction. +- Make sure to provide the correct `nonce` of transaction +::: + +:::tip +`Best practice:` when sending the transaction, add ~10% extra gas to the estimated value to avoid underestimation and failure due to insufficient gas. ::: Here's an example of a request: From 622c07118674f184c717cad37e7369349e600ebe Mon Sep 17 00:00:00 2001 From: miiu Date: Tue, 29 Jul 2025 13:55:56 +0300 Subject: [PATCH 2/4] extra info --- docs/sdk-and-tools/rest-api/transactions.mdx | 34 ++++++++++++++++---- 1 file changed, 27 insertions(+), 7 deletions(-) diff --git a/docs/sdk-and-tools/rest-api/transactions.mdx b/docs/sdk-and-tools/rest-api/transactions.mdx index 0d71343ae..77b79670d 100644 --- a/docs/sdk-and-tools/rest-api/transactions.mdx +++ b/docs/sdk-and-tools/rest-api/transactions.mdx @@ -347,16 +347,36 @@ Example response for cross-shard transactions: `https://gateway.multiversx.com/transaction/cost` +This endpoint is used to estimate the gas cost of a given transaction. -:::note -This endpoint estimates the **gas cost** of a transaction. Use this value to determine the appropriate `gasLimit` before sending a transaction. +It performs a read-only simulation of the transaction against the current on-chain state, returning the number of gas units the transaction would consume if executed in that exact state. -In the background, this endpoint simulates the transaction in a read-only environment to estimate its gas cost. Any resulting smart contract results and events will also be returned. -::: +💬 How it works: +- The endpoint takes all transaction input fields (value, sender, receiver, data, chainID, etc.). +- It executes the transaction in a sandboxed, non-persistent environment, meaning it simulates execution without affecting the actual blockchain. +- It uses the current state of the network (including smart contract storage, balances, etc.). +- It returns the estimated gas (txGasUnits) and may also return smart contract results and events triggered by the simulation. + +❓ How does it apply to smart contracts? + +For smart contracts, the endpoint simulates the contract call exactly as if it were executed live, including processing all logic, branches, and emitted events. +The gas estimate reflects the computation and storage impact that would occur if the state remained unchanged at the time of actual execution. + +❓ How does it approximate the cost if the contract logic has variable gas usage? + +If a smart contract’s logic has branches or conditional execution that result in variable gas usage (e.g., depending on internal storage state, previous executions, etc.), +the estimation will only reflect the gas used by the path taken during this particular simulation. + +❗ Why is providing the correct nonce important? + +Because the simulation engine mirrors real transaction behavior, it requires a valid and correct nonce to properly simulate the transaction. Using an outdated or incorrect +nonce may lead to simulation failure. + +⚠️ Can the estimated gas differ from the actual cost? + +Yes. Since the blockchain state may change between the moment you call /transaction/cost and when the transaction is actually sent to the network, the real gas usage can differ. +This is especially true for smart contract calls that depend on dynamic or mutable state. -:::warning -As the transaction is executed in a simulated environment, `providing the correct nonce is mandatory`. -::: Date: Tue, 29 Jul 2025 13:59:46 +0300 Subject: [PATCH 3/4] small change --- docs/sdk-and-tools/rest-api/transactions.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/sdk-and-tools/rest-api/transactions.mdx b/docs/sdk-and-tools/rest-api/transactions.mdx index 77b79670d..1cd992905 100644 --- a/docs/sdk-and-tools/rest-api/transactions.mdx +++ b/docs/sdk-and-tools/rest-api/transactions.mdx @@ -351,28 +351,28 @@ This endpoint is used to estimate the gas cost of a given transaction. It performs a read-only simulation of the transaction against the current on-chain state, returning the number of gas units the transaction would consume if executed in that exact state. -💬 How it works: +#### How it works: - The endpoint takes all transaction input fields (value, sender, receiver, data, chainID, etc.). - It executes the transaction in a sandboxed, non-persistent environment, meaning it simulates execution without affecting the actual blockchain. - It uses the current state of the network (including smart contract storage, balances, etc.). - It returns the estimated gas (txGasUnits) and may also return smart contract results and events triggered by the simulation. -❓ How does it apply to smart contracts? +#### How does it apply to smart contracts? For smart contracts, the endpoint simulates the contract call exactly as if it were executed live, including processing all logic, branches, and emitted events. The gas estimate reflects the computation and storage impact that would occur if the state remained unchanged at the time of actual execution. -❓ How does it approximate the cost if the contract logic has variable gas usage? +#### How does it approximate the cost if the contract logic has variable gas usage? If a smart contract’s logic has branches or conditional execution that result in variable gas usage (e.g., depending on internal storage state, previous executions, etc.), the estimation will only reflect the gas used by the path taken during this particular simulation. -❗ Why is providing the correct nonce important? +#### Why is providing the correct nonce important? Because the simulation engine mirrors real transaction behavior, it requires a valid and correct nonce to properly simulate the transaction. Using an outdated or incorrect nonce may lead to simulation failure. -⚠️ Can the estimated gas differ from the actual cost? +#### Can the estimated gas differ from the actual cost? Yes. Since the blockchain state may change between the moment you call /transaction/cost and when the transaction is actually sent to the network, the real gas usage can differ. This is especially true for smart contract calls that depend on dynamic or mutable state. From 7890309548a805b536da4b127ac3c1de06166c65 Mon Sep 17 00:00:00 2001 From: miiu Date: Tue, 29 Jul 2025 14:47:16 +0300 Subject: [PATCH 4/4] fixes --- docs/sdk-and-tools/rest-api/transactions.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/sdk-and-tools/rest-api/transactions.mdx b/docs/sdk-and-tools/rest-api/transactions.mdx index 1cd992905..38c2ebee6 100644 --- a/docs/sdk-and-tools/rest-api/transactions.mdx +++ b/docs/sdk-and-tools/rest-api/transactions.mdx @@ -422,11 +422,11 @@ The cost is estimated successfully. :::tip - Use the returned `txGasUnits` value as the `gasLimit` in your actual transaction. -- Make sure to provide the correct `nonce` of transaction +- Make sure to provide the correct `nonce` of the transaction ::: :::tip -`Best practice:` when sending the transaction, add ~10% extra gas to the estimated value to avoid underestimation and failure due to insufficient gas. +**Best practice:** when sending the transaction, add ~10% extra gas to the estimated value to avoid underestimation and failure due to insufficient gas. ::: Here's an example of a request: