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.

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
JavaScript
Python
JSON

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

let requestBody = {
  "jsonrpc": "2.0",
  "id": 8675309,
  "method": "simulateTransaction",
  "params": {
    "transaction": "AAAAAgAAAAAg4dbAxsGAGICfBG3iT2cKGYQ6hK4sJWzZ6or1C5v6GAAAAGQAJsOiAAAAEQAAAAEAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAEAAAAAAAAAGAAAAAAAAAABzAP+dP0PsNzYvFF1pv7a8RQXwH5eg3uZBbbWjE9PwAsAAAAJaW5jcmVtZW50AAAAAAAAAgAAABIAAAAAAAAAACDh1sDGwYAYgJ8EbeJPZwoZhDqEriwlbNnqivULm/oYAAAAAwAAAAMAAAAAAAAAAAAAAAA=",
    "resourceConfig": {
      "instructionLeeway": 3000000
    }
  }
}
let res = await fetch('https://soroban-testnet.stellar.org', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(requestBody),
})
let json = await res.json()
console.log(json)

import json, requests
res = requests.post('https://soroban-testnet.stellar.org', json={
    "jsonrpc": "2.0",
    "id": 8675309,
    "method": "simulateTransaction",
    "params": {
        "transaction": "AAAAAgAAAAAg4dbAxsGAGICfBG3iT2cKGYQ6hK4sJWzZ6or1C5v6GAAAAGQAJsOiAAAAEQAAAAEAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAEAAAAAAAAAGAAAAAAAAAABzAP+dP0PsNzYvFF1pv7a8RQXwH5eg3uZBbbWjE9PwAsAAAAJaW5jcmVtZW50AAAAAAAAAgAAABIAAAAAAAAAACDh1sDGwYAYgJ8EbeJPZwoZhDqEriwlbNnqivULm/oYAAAAAwAAAAMAAAAAAAAAAAAAAAA=",
        "resourceConfig": {
            "instructionLeeway": 3000000
        }
    }
})
print(json.dumps(res.json(), indent=4))

{
  "jsonrpc": "2.0",
  "id": 8675309,
  "method": "simulateTransaction",
  "params": {
    "transaction": "AAAAAgAAAAAg4dbAxsGAGICfBG3iT2cKGYQ6hK4sJWzZ6or1C5v6GAAAAGQAJsOiAAAAEQAAAAEAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAEAAAAAAAAAGAAAAAAAAAABzAP+dP0PsNzYvFF1pv7a8RQXwH5eg3uZBbbWjE9PwAsAAAAJaW5jcmVtZW50AAAAAAAAAgAAABIAAAAAAAAAACDh1sDGwYAYgJ8EbeJPZwoZhDqEriwlbNnqivULm/oYAAAAAwAAAAMAAAAAAAAAAAAAAAA=",
    "resourceConfig": {
      "instructionLeeway": 3000000
    }
  }
}

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
  }
}