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

Commit

Permalink
editorial on Update interacting-with-contracts.mdx
Browse files Browse the repository at this point in the history
  • Loading branch information
briwylde08 authored Oct 20, 2023
1 parent 63529c8 commit e4619ef
Showing 1 changed file with 11 additions and 11 deletions.
22 changes: 11 additions & 11 deletions docs/fundamentals-and-concepts/interacting-with-contracts.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -111,28 +111,28 @@ A footprint is a set of ledger keys, each marked as either read-only or read-wri

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 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.
Since it can be difficult for a user to 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 to its caller.

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

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
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, `simulateTransaction` 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 the simulation, the client only needs to provide these
Expand All @@ -144,12 +144,12 @@ 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 (i.e.,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 `simulateTransaction` mechanism doesn't emulate failures caused by the incorrect
footprint. `simulateTransaction` with enforcing auth mode may still be used to verify the
Expand Down

0 comments on commit e4619ef

Please sign in to comment.