Skip to main content

simulateTransaction

Submit a trial contract invocation to simulate how it would be executed by the network. This endpoint calculates the effective transaction data, required authorizations, and minimal resource fee. It provides a way to test and analyze the potential outcomes of a transaction without actually submitting it to the network.

Params

(2)

Please note that parameter structure within the request must contain named parameters as a by-name object, and not as positional arguments in a by-position array

1. transaction (required)

In order for the RPC server to successfully simulate a Stellar transaction, the provided transaction must contain only a single operation of the type invokeHostFunction.

string

A Stellar transaction, serialized as a base64 string

2. resourceConfig

Contains configuration for how resources will be calculated when simulating transactions.

Configuration for how resources will be calculated.

instructionLeeway
number

Allow this many extra instructions when budgeting resources.

Result

(simulateTransactionResult)

The response will include the anticipated affects the given transaction will have on the network. Additionally, information needed to build, sign, and actually submit the transaction will be provided.

latestLedger
number
required

The sequence number of the latest ledger known to Stellar RPC at the time it handled the request.

minResourceFee
string

(optional) Stringified number - Recommended minimum resource fee to add when submitting the transaction. This fee is to be added on top of the Stellar network fee. Not present in case of error.

cost
object
deprecated

(optional) - The cost object is legacy, inaccurate, and will be deprecated in future RPC releases. Please decode transactionData XDR to retrieve the correct resources.

cpuInsns
string
required

Stringified number - Total cpu instructions consumed by this transaction

memBytes
string
required

Stringified number - Total memory bytes allocated by this transaction

results
array[object]

(optional) - This array will only have one element: the result for the Host Function invocation. Only present on successful simulation (i.e. no error) of InvokeHostFunction operations.

xdr
string
required

Serialized base64 string - return value of the Host Function call.

auth
array[string]
required

Array of serialized base64 strings - Per-address authorizations recorded when simulating this Host Function call.

transactionData
string

(optional) Serialized base64 string - The recommended Soroban Transaction Data to use when submitting the simulated transaction. This data contains the refundable fee and resource usage information such as the ledger footprint and IO access data (serialized in a base64 string). Not present in case of error.

events
array[string]

(optional) Array of serialized base64 strings - Array of the events emitted during the contract invocation. The events are ordered by their emission time. (an array of serialized base64 strings). Only present when simulating of InvokeHostFunction operations, note that it can be present on error, providing extra context about what failed.

restorePreamble
object

(optional) - It can only be present on successful simulation (i.e. no error) of InvokeHostFunction operations. If present, it indicates that the simulation detected archived ledger entries which need to be restored before the submission of the InvokeHostFunction operation. The minResourceFee and transactionData fields should be used to submit a transaction containing a RestoreFootprint operation.

minResourceFee
string
required

Stringified number - Recommended minimum resource fee to add when submitting the RestoreFootprint operation. This fee is to be added on top of the Stellar network fee.

transactionData
string
required

Serialized base64 string - The recommended Soroban Transaction Data to use when submitting the RestoreFootprint operation.

stateChanges
array[object]

(optional) - On successful simulation of InvokeHostFunction operations, this field will be an array of LedgerEntrys before and after simulation occurred. Note that at least one of before or after will be present: before and no after indicates a deletion event, the inverse is a creation event, and both present indicates an update event. Or just check the type.

type
integer
required

Indicates if the entry was created (1), updated (2), or deleted (3)

Allowed values:
123
key
string
required

Base64 - the LedgerKey for this delta

before
string or null
required

Base64, if present - LedgerEntry state prior to simulation

after
string or null
required

Base64, if present - LedgerEntry state after simulation

error
string

(optional) - This field will include details about why the invoke host function call failed. Only present if the transaction simulation failed.

Examples

Transaction simulation that succeeds and returns the necessary information to prepare and submit the transaction.

Request

curl -X POST \
-H 'Content-Type: application/json' \
-d '{
  "jsonrpc": "2.0",
  "id": 8675309,
  "method": "simulateTransaction",
  "params": {
    "transaction": "AAAAAgAAAAAg4dbAxsGAGICfBG3iT2cKGYQ6hK4sJWzZ6or1C5v6GAAAAGQAJsOiAAAAEQAAAAEAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAEAAAAAAAAAGAAAAAAAAAABzAP+dP0PsNzYvFF1pv7a8RQXwH5eg3uZBbbWjE9PwAsAAAAJaW5jcmVtZW50AAAAAAAAAgAAABIAAAAAAAAAACDh1sDGwYAYgJ8EbeJPZwoZhDqEriwlbNnqivULm/oYAAAAAwAAAAMAAAAAAAAAAAAAAAA=",
    "resourceConfig": {
      "instructionLeeway": 3000000
    }
  }
}' \
https://soroban-testnet.stellar.org | jq

Result

{
  "jsonrpc": "2.0",
  "id": 8675309,
  "result": {
    "transactionData": "AAAAAAAAAAIAAAAGAAAAAcwD/nT9D7Dc2LxRdab+2vEUF8B+XoN7mQW21oxPT8ALAAAAFAAAAAEAAAAHy8vNUZ8vyZ2ybPHW0XbSrRtP7gEWsJ6zDzcfY9P8z88AAAABAAAABgAAAAHMA/50/Q+w3Ni8UXWm/trxFBfAfl6De5kFttaMT0/ACwAAABAAAAABAAAAAgAAAA8AAAAHQ291bnRlcgAAAAASAAAAAAAAAAAg4dbAxsGAGICfBG3iT2cKGYQ6hK4sJWzZ6or1C5v6GAAAAAEAHfKyAAAFiAAAAIgAAAAAAAAAAw==",
    "minResourceFee": "90353",
    "events": [
      "AAAAAQAAAAAAAAAAAAAAAgAAAAAAAAADAAAADwAAAAdmbl9jYWxsAAAAAA0AAAAgzAP+dP0PsNzYvFF1pv7a8RQXwH5eg3uZBbbWjE9PwAsAAAAPAAAACWluY3JlbWVudAAAAAAAABAAAAABAAAAAgAAABIAAAAAAAAAACDh1sDGwYAYgJ8EbeJPZwoZhDqEriwlbNnqivULm/oYAAAAAwAAAAM=",
      "AAAAAQAAAAAAAAABzAP+dP0PsNzYvFF1pv7a8RQXwH5eg3uZBbbWjE9PwAsAAAACAAAAAAAAAAIAAAAPAAAACWZuX3JldHVybgAAAAAAAA8AAAAJaW5jcmVtZW50AAAAAAAAAwAAAAw="
    ],
    "results": [
      {
        "auth": [],
        "xdr": "AAAAAwAAAAw="
      }
    ],
    "cost": {
      "cpuInsns": "1635562",
      "memBytes": "1295756"
    },
    "latestLedger": 2552139
  }
}