diff --git a/docs/fundamentals-and-concepts/fees-and-metering.mdx b/docs/fundamentals-and-concepts/fees-and-metering.mdx index 8ad75319..a61eac2d 100644 --- a/docs/fundamentals-and-concepts/fees-and-metering.mdx +++ b/docs/fundamentals-and-concepts/fees-and-metering.mdx @@ -58,7 +58,7 @@ Some parameters may contribute to multiple fee components. For example, the tran The implementation details for fee computation are provided by the following [library](https://github.com/stellar/rs-soroban-env/blob/main/soroban-env-host/src/fees.rs). This library is used by the protocol to compute the fees and thus can be considered canonical. The resource fee rates may be updated based on network validator consensus. -The best way to find the required fees for any Soroban transaction is to use the transaction simulation with [preflight service](./interacting-with-contracts.mdx#preflight). +The best way to find the required fees for any Soroban transaction is to use the [`simulateTransaction` mechanism](./interacting-with-contracts.mdx#transaction-simulation). The fee rates are currently defined for the Futurenet as follows: diff --git a/docs/fundamentals-and-concepts/interacting-with-contracts.mdx b/docs/fundamentals-and-concepts/interacting-with-contracts.mdx index 90f0de0d..459835b6 100644 --- a/docs/fundamentals-and-concepts/interacting-with-contracts.mdx +++ b/docs/fundamentals-and-concepts/interacting-with-contracts.mdx @@ -101,56 +101,56 @@ When a call occurs from inside the host, the caller and callee contracts _share Since host objects are immutable, there is limited risk to passing a shared reference from one contract to another: the callee cannot modify the object in a way that would surprise the caller, only create new objects. -## Preflight +## Transaction Simulation ### Footprint As mentioned in the [persisting data](../fundamentals-and-concepts/persisting-data.mdx) section, a contract can only load or store `CONTRACT_DATA` entries that are declared in a _footprint_ associated with its invocation. -A footprint is a set of ledger keys, each marked as either read-only or read-write. Read-only keys are available to the transaction for reading, read-write available for reading, writing or both. +A footprint is a set of ledger keys, each marked as either read-only or read-write. Read-only keys are available to the transaction for reading; read-write keys are available for reading, writing, or both. -Any transaction submitted by a user has to be accompanied by a footprint. A single footprint encompasses _all_ the data read and written by _all_ contracts transitively invoked by the transaction: not just the initial contract that the transaction calls, but also all contracts it calls, and so on. +Any Soroban transaction submitted by a user has to be accompanied by this footprint. A single footprint encompasses _all_ the data read and written by _all_ contracts transitively invoked by the transaction: not just the initial contract that the transaction calls, but also all contracts it calls, and so on. -Since it can be difficult for a user to always know which ledger entries a given contract call will attempt to read or write -- especially those caused by contracts called by other contracts deep within a transaction -- the host provides an auxiliary **"preflight"** mechanism that executes a transaction against a temporary, possibly slightly-stale _snapshot_ of the ledger. The preflight mechanism is _not_ constrained to only read or write the contents of a footprint; rather it _records_ a footprint describing the transaction's execution, discards the execution's effects, and then returns the recorded footprint it to its caller. +Since it can be difficult for a user to know which ledger entries a given contract call will attempt to read or write (especially entries that are caused by other contracts deep within a transaction), the host provides an auxiliary `simulateTransaction` mechanism that executes a transaction against a temporary, possibly out-of-date _snapshot_ of the ledger. The `simulateTransaction` mechanism is _not_ constrained to only read or write the contents of a footprint; rather it _records_ a footprint describing the transaction's execution, discards the execution's effects, and then returns the recorded footprint to its caller. -Such a preflight-provided footprint can then be used to accompany a "real" submission of the same transaction to the network for real execution. If the state of the ledger has changed too much between the time of the preflight and the real submission, the footprint may be too stale and no longer accurately identify the _keys_ the transaction needs to read and write, at which point the preflight must be retried to refresh the footprint. +This simulation-provided footprint can then be used to accompany a "real" submission of the same transaction to the network for real execution. If the state of the ledger has changed too much between the time of the simulated and the real submission, the footprint may be too stale and no longer accurately identify the _keys_ the transaction needs to read and/or write, at which point the simulation must be retried to refresh the footprint. -In any event -- whether successful or failing -- the real transaction will execute atomically, deterministically and with serializable consistency semantics. An inaccurate footprint simply causes deterministic transaction failure, not a stale-read anomaly. All effects of such a failed transaction are discarded, as they would be in the presence of any other error. +In any event (whether successful or failing), the real transaction will execute atomically, deterministically, and with serializable consistency semantics. An inaccurate footprint simply causes deterministic transaction failure, not a stale-read anomaly. All effects of such a failed transaction are discarded, as they would be in the presence of any other error. ### Authorization -See [authorization overview](authorization.mdx) and authorization in +See the [authorization overview](authorization.mdx) docs and authorization in transactions [section][auth-data] for general information on Soroban authorization. [auth-data]: ./invoking-contracts-with-transactions.mdx#authorization-data -Preflight mechanism can also be used to compute the `SorobanAuthorizedInvocation` trees -that have to be authorized by the `Address`es in order for all the +Soroban's `simulateTransaction` mechanism can also be used to compute the `SorobanAuthorizedInvocation` trees +that must be authorized by the `Address`es for all the `require_auth` checks to pass. Soroban host provides a special 'recording' mode for auth. Whenever -`require_auth` is called host records its context (address, contract id, -function, arguments), attributes it to an `SorobanAuthorizedInvocation` tree, and marks -it as successful. Then after the invocation has finished, preflight can return +`require_auth` is called, the host records its context (address, contract id, +function, arguments), attributes it to a `SorobanAuthorizedInvocation` tree, and marks +it as successful. Then, after the invocation has finished, `simulateTransaction` can return all the recorded trees, as well as the generated random nonce values. -Given this information from preflight, the client only needs to provide these +Given this information from the simulation, the client only needs to provide these trees and nonces to the respective `Address`es for signing and then build the -final transaction using the preflight output and the corresponding signatures. +final transaction using the simulation output and the corresponding signatures. -The recording auth mode is optional for preflight. For example, when dealing -with the custom account contracts, it may be necessary to preflight the custom +The recording auth mode is optional for `simulateTransaction`. For example, when dealing +with the custom account contracts, it may be necessary to simulate the custom account's `__check_auth` code (that is simply omitted in the recording auth mode), for example, to get its ledger footprint. The non-recording mode is referred to as 'enforcing'. Enforcing mode is basically equivalent to running the -transaction on-chain (with possibly a slightly stale ledger state) and hence it +transaction on-chain (with possibly a slightly stale ledger state); hence, it requires all the signatures to be valid. -Note, that the recording auth mode never emulates authorization failures. The +Note that the recording auth mode never emulates authorization failures. The reason for that is that failing authorization is always an exceptional -situation (the `Address`es for which you don't anticipate successful +situation (i.e., the `Address`es for which you don't anticipate successful authorization shouldn't be used in the first place). It is similar to how, for -example, the preflight doesn't emulate failures caused by the incorrect -footprint. Preflight with enforcing auth mode may still be used to verify the +example, the `simulateTransaction` mechanism doesn't emulate failures caused by the incorrect +footprint. `simulateTransaction` with enforcing auth mode may still be used to verify the signatures before executing the transaction on-chain. diff --git a/docs/fundamentals-and-concepts/invoking-contracts-with-transactions.mdx b/docs/fundamentals-and-concepts/invoking-contracts-with-transactions.mdx index 6a90b947..607e876a 100644 --- a/docs/fundamentals-and-concepts/invoking-contracts-with-transactions.mdx +++ b/docs/fundamentals-and-concepts/invoking-contracts-with-transactions.mdx @@ -498,11 +498,11 @@ that `function` performs (if any). corresponding to the created contract. Building `SorobanAuthorizedInvocation` trees may be simplified by using the -recording auth mode in Soroban preflight (see the [docs][preflight-doc] for more +recording auth mode in Soroban's `simulateTransaction` mechanism (see the [docs][simulate-transaction-doc] for more details). [envelope-xdr]: https://github.com/stellar/stellar-xdr/blob/e372df9f677961aac04c5a4cc80a3667f310b29f/Stellar-transaction.x#L703 -[preflight-doc]: ../fundamentals-and-concepts/interacting-with-contracts.mdx#authorization +[simulate-transaction-doc]: ../fundamentals-and-concepts/interacting-with-contracts.mdx#authorization ##### Stellar Account Signatures @@ -567,5 +567,4 @@ resource fee. The footprint must contain the `LedgerKey`s that will be read and/or written. The simplest method to determine the values in `SorobanResources` and -`refundableFee` is to use the transaction simulation with -[preflight service](../fundamentals-and-concepts/interacting-with-contracts.mdx#preflight). +`refundableFee` is to use the [`simulateTransaction` mechanism](../fundamentals-and-concepts/interacting-with-contracts.mdx#transaction-simulation). diff --git a/docs/fundamentals-and-concepts/state-expiration.mdx b/docs/fundamentals-and-concepts/state-expiration.mdx index cfa704b7..39252565 100644 --- a/docs/fundamentals-and-concepts/state-expiration.mdx +++ b/docs/fundamentals-and-concepts/state-expiration.mdx @@ -152,7 +152,7 @@ expirationLedger that is large enough. only operation in a transaction. The transaction also needs to populate `SorobanTransactionData` transaction extension explained [here](../fundamentals-and-concepts/invoking-contracts-with-transactions.mdx#transaction-resources). To fill -out `SorobanResources`, use preflight mentioned in the provided link, or make +out `SorobanResources`, use the transaction simulation mentioned in the provided link, or make sure `readBytes` includes the key and entry size of every entry in the `readOnly` set. @@ -189,7 +189,7 @@ parameter and is subject to be updated (likely increased) via network upgrades. operation in a transaction. The transaction also needs to populate `SorobanTransactionData` transaction extension explained [here](../fundamentals-and-concepts/invoking-contracts-with-transactions.mdx#transaction-resources). To fill -out `SorobanResources`, use preflight mentioned in the provided link, or make +out `SorobanResources`, use the transaction simulation mentioned in the provided link, or make sure `writeBytes` includes the key and entry size of every entry in the `readWrite` set and make sure `extendedMetaDataSizeBytes` is at least double of `writeBytes`. @@ -204,7 +204,7 @@ We've done our best to build tooling around state expiration in both the Soroban Both restoring and bumping the expiration of ledger entries follows a three-step process regardless of their nature (contract data, instances, etc.): -1. **Identify the ledger entries**. This usually means acquiring them from a Soroban RPC server as part of your initial transaction simulation (see the [preflight docs](https://soroban.stellar.org/docs/fundamentals-and-concepts/interacting-with-contracts#preflight) and the [`simulateTransaction`](https://soroban.stellar.org/api/methods/simulateTransaction) method). +1. **Identify the ledger entries**. This usually means acquiring them from a Soroban RPC server as part of your initial transaction simulation (see the [transaction simulation docs](https://soroban.stellar.org/docs/fundamentals-and-concepts/interacting-with-contracts#transaction-simulation) and the [`simulateTransaction`](https://soroban.stellar.org/api/methods/simulateTransaction) RPC method). 2. **Prepare your operation**. This means describing the ledger entries within the corresponding operation (i.e. `bumpFootprintOp` or `restoreFootprintOp`) and its ledger footprint (the `SorobanTransactionData` field), then simulating it to fill out fee and resource usage information (when restoring, you usually have simulation results already). diff --git a/docs/reference/releases.mdx b/docs/reference/releases.mdx index b2af2462..0dbc0878 100644 --- a/docs/reference/releases.mdx +++ b/docs/reference/releases.mdx @@ -222,11 +222,11 @@ The Soroban RPC version for Preview 11 is presently in Stellar's unstable and te - Limit number of concurrent requests - Improve HTTPRequestDurationLimiter by adding a recover handling - Stream ledgers on initialization -- Increase instruction leeway to 20% in preflight +- Increase instruction leeway to 20% in transaction simulation - Validate xdr payloads in soroban-rpc requests - Fix double-counting bug - Fix datarace in bufferedResponseWriter.WriteOut -- Fix set_authorization_entries bug in preflight +- Fix set_authorization_entries bug in transaction simulation - Restore CORS support #### Soroban CLI