docs: change preflight wording to simulate transaction (#585)

* docs: change preflight wording to simulate transaction

A first attempt to resolve #478, there may be more work to be done.
I've used a few different phrases, depending on how the sentence
structure works, perhaps taking some liberties in the process.

I've also left alone the `releases` page for preview releases
older than 11. It seems unnecessary to rewrite the development
history too far into the past.

Refs: #478

* editorial on Update interacting-with-contracts.mdx

* added a couple "the"s Update state-expiration.mdx

* fix wording about ledger entries to be less confusing

* clearing up some other language surrounding footprints

---------

Co-authored-by: Bri Wylde <[email protected]>

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 Testnet as follows:
 

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.

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).

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).
 

docs/reference/releases.mdx

@@ -225,11 +225,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