From 89a6c0cbb63747889168859b8f2ab0130da02f67 Mon Sep 17 00:00:00 2001 From: Iuga Mihai <50499646+miiu96@users.noreply.github.com> Date: Tue, 29 Jul 2025 14:59:39 +0300 Subject: [PATCH] Extra info /transaction/cost endpoint (#1139) * extra info cost endpoint * extra info * small change * fixes --- docs/sdk-and-tools/rest-api/transactions.mdx | 44 ++++++++++++++++++-- 1 file changed, 40 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..38c2ebee6 100644 --- a/docs/sdk-and-tools/rest-api/transactions.mdx +++ b/docs/sdk-and-tools/rest-api/transactions.mdx @@ -347,7 +347,36 @@ Example response for cross-shard transactions: `https://gateway.multiversx.com/transaction/cost` -This endpoint allows one to estimate the cost of a transaction. +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: +- 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. + 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 +421,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 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. ::: Here's an example of a request: