Overview
ThesimulateTransaction endpoint in Stellar RPC allows you to submit a trial contract invocation to simulate how it would be executed by the Stellar network. This simulation 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. It can be a nice way to get contract data as well sometimes.
While calling the method on the rpc server is not the ONLY way to simulate a transaction, it will likely be the most common and easiest way.
Here we will look at the objects involved and their definitions.
RPC Services
Stellar Development Foundation provides a testnet RPC service athttp://soroban-testnet.stellar.org. For public network providers please refer to the Ecosystem RPC Providers list.
Testnet Endpoint:
https://soroban-testnet.stellar.org:443 SimulateTransactionParams is the argument passed to thesimulateTransaction RPC endpoint:
Things simulateTransaction is used for:
- Preparing
invokeHostFunctionOpTransactions: Anytime you need to submit aninvokeHostFunctionOptransaction to the network. - Footprint Determination: To determine the ledger footprint, which includes all the data entries the transaction will read or write.
- Authorization Identification: To identify the authorizations required for the transaction.
- Error Detection: To detect potential errors and issues before actual submission, saving time and network resources.
- Restoring Archived Ledger Entries or Contract Code: To restore archived data automatically in the invocation, or to prepare a manual restore when needed.
- Simulating Contract Getter Calls: To retrieve certain data from the contract without affecting the ledger state. (It’s worth noting you could also retrieve certain contract data direct from the ledgerkeys without simulation if it doesn’t require any manipulation within the contract logic.)
- Resource Calculation: To calculate the necessary resources (CPU instructions, memory, etc.) that a transaction will consume.
How to Call simulateTransaction
Using Fetch
Here’s an example of how to call thesimulateTransaction endpoint directly using fetch in JavaScript:
Using an SDK
The Stellar SDKs provide a convenient method to simulate a transaction:Running the example
To run the above code, you will need to install the Stellar SDK into your project. You can do this by running the following command in your project directory:.mjs file and run it with Node.js:
node <filename>.mjs
For Python, run it with python <filename>.py. For Go, run it with go run <filename>.go inside a Go module. For Java, save it as Simulate.java in a Maven project and run its main method.
Understanding the Footprint
A footprint is a set of ledger keys that the transaction will read or write. These keys are marked as either read-only or read-write:- Read-Only Keys: Available for reading only.
- Read-Write Keys: Available for reading and writing.
Assembling a Transaction
Once you have simulated the transaction and obtained the necessary data, you can assemble the transaction for actual submission. TheassembleTransaction function in the SDK helps with this process, but you can also call prepareTransaction to have it both simulate and assemble the transaction for you in one step. Using the JavaScript SDK, we can call assembleTransaction to easily assemble a transaction.
Handling Archived Ledger Entries
Since Protocol 23, you usually do not need a separate restore step. When simulation finds archived persistent entries, including contract code, it adds them to the restore list in the returnedtransactionData (archivedSorobanEntries). The same InvokeHostFunction transaction restores those entries first and then runs the host function. assembleTransaction and prepareTransaction copy this data into your transaction. Learn more in Contract Data Automatic Restoration.
For a contract invocation, Stellar RPC normally returns no restorePreamble. A manual RestoreFootprint operation is a rare fallback, for example when automatic restoration makes the transaction too large for the network limits, or when you want to pay the restoration fees yourself. The RestoreFootprintOp section lists these cases. When a simulation result does include a restorePreamble, it holds the fee and the transaction data for that restore transaction:
RestoreFootprint transaction from the restorePreamble and then retries the invocation.
Fees and Resource Usage
Soroban smart contracts on Stellar use a multidimensional resource fee model, charging fees for several resource types:- CPU Instructions: Number of CPU instructions the transaction uses.
- Ledger Entry Accesses: Reading or writing any single ledger entry.
- Ledger I/O: Number of bytes read from or written to the ledger.
- Transaction Size: Size of the transaction submitted to the network in bytes.
- Events & Return Value Size: Size of the events produced by the contract and the return value of the top-level contract function.
- Ledger Space Rent: Payment for ledger entry TTL extensions and rent payments for increasing ledger entry size.
Error Handling
The transaction simulation mechanism provides an estimation of CPU and memory consumption of a contract invocation during a transaction. It also highlights potential errors and resource limitations of the invocation before actual submission.Backend Code and Workflow
ThesimulateTransaction endpoint leverages various backend components to simulate the execution of a transaction. Here is a brief explanation of how it works:
-
Invocation of Simulation:
- The simulation is initiated by calling
simulate_invoke_host_function_opwhich takes in parameters such as the transaction to be simulated, resource configuration, and other necessary details.
- The simulation is initiated by calling
-
Snapshot Source and Network Configuration:
- The simulation utilizes a snapshot source (
MockSnapshotSource) and network configuration (NetworkConfig) to mimic the state of the ledger and network conditions.
- The simulation utilizes a snapshot source (
-
Resource Calculation:
- The function
simulate_invoke_host_function_op_resourcescomputes the resources (CPU instructions, memory bytes) required for the transaction by analyzing ledger changes.
- The function
-
Execution and Result Handling:
- The core of the execution is handled by
invoke_host_function_in_recording_mode, which records the transaction’s impact on the ledger. - The results are then processed, including any required authorizations, emitted events, and transaction data.
- The core of the execution is handled by
-
Adjustments and Fees:
- Adjustments to resource usage and fees are made based on predefined configurations (
SimulationAdjustmentConfig), ensuring accurate fee estimation.
- Adjustments to resource usage and fees are made based on predefined configurations (
rs-soroban-env and also in a soroban-simulation crate and handle the core logic for simulating transactions.