Skip to content
This repository has been archived by the owner on Aug 21, 2024. It is now read-only.

docs: change preflight wording to simulate transaction #585

Merged
Merged
Show file tree
Hide file tree
Changes from 2 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/fundamentals-and-concepts/fees-and-metering.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down
30 changes: 15 additions & 15 deletions docs/fundamentals-and-concepts/interacting-with-contracts.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -101,21 +101,21 @@ 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 always know which ledger entries a given contract call will attempt to read or write (especially those entries caused by contracts called by other contracts deep within a transaction) the host provides an auxiliary `simulateTransaction` mechanism that executes a transaction against a temporary, possibly slightly-stale _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 it to its caller.
ElliotFriend marked this conversation as resolved.
Show resolved Hide resolved
ElliotFriend marked this conversation as resolved.
Show resolved Hide resolved

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.
Such a 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

Expand All @@ -125,22 +125,22 @@ authorization.

[auth-data]: ./invoking-contracts-with-transactions.mdx#authorization-data

Preflight mechanism can also be used to compute the `SorobanAuthorizedInvocation` trees
Soroban's `simulateTransaction` mechanism can also be used to compute the `SorobanAuthorizedInvocation` trees
that have to be authorized by the `Address`es in order 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
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
Expand All @@ -149,8 +149,8 @@ requires all the signatures to be valid.

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.
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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).
6 changes: 3 additions & 3 deletions docs/fundamentals-and-concepts/state-expiration.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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 transaction simulation mentioned in the provided link, or make
sure `readBytes` includes the key and entry size of every entry in the
`readOnly` set.

Expand Down Expand Up @@ -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 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`.
Expand All @@ -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).

Expand Down
4 changes: 2 additions & 2 deletions docs/reference/releases.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down