#Should we consolidate the terms "Preflight" and "Simulate Transactions"?

45 messages · Page 1 of 1 (latest)

ionic vale
#

In our documentation and discourse we often use the term "preflight" (https://soroban.stellar.org/docs/learn/interacting-with-contracts#preflight ). However, the term used in our json-rpc API is "SimulateTransaction". I think we're talking about the same thing? I believe that the origin of the "Simulate Transaction" term is from the Solana json-rpc API which has something similar (but IIRC doesn't actually provide the same functionality wrt footprints and auth). Should we consolidate these? If so, under which of these names? Or maybe a new name? In addition, It's not obvious from any of these names that the same functionality is used to execute read-only (view) functions. (see this: #1113551521578225786 message)

golden timber
#

I like the term 'preflight' because one can use it as a noun (e.g. 'use preflight to determine your contract costs'). 'simulate' is what's actually used, but it seems too broad to refer to it in the docs ('simulate your transaction to determine your contract costs' - it's not immediately clear if we're referring to a service or something else)

ionic vale
#

@opal sand you ran into this issue - thoughts?

gaunt wyvern
#

Preflight is misleading because it implies it is never the end goal. However, if a wallet is invoking a contract and simulation indicates the invocation will be read-only, then the wallet can stop there, there is no need to submit on network.

opal sand
#

just dumping some thoughts:

Preflight

adjective
occurring or done before a flight:
a preflight briefing of the plane's crew.

noun
a preflight briefing or a ground check, as of an airplane.

related words: prelaunch, pre-release, quality control, checklist

Soroban's preflight/simulation is a flight, though, just of a different sort. If we want to stay somewhere within this metaphor area, maybe we could go with something like "probe", "scout", "recon" (short for "reconnaissance"), "survey", "scan", or "trace". I don't particularly like any of those, though. Maybe "trace"?

I wonder if something simpler would be nicer. "testTransaction", "trialTransaction", "attempt", "assess", "examine", "try".

https://www.wordnik.com/words/test led me to assay (https://www.wordnik.com/words/assay), which honestly might be a perfect metaphor, other than that I don't know how to pronounce it and it kinda sounds like a swear word.

golden timber
#

I don't really care about the exact terms, but I do want to have a noun for the service name and a verb for the endpoint name

#

just simulate/test/trialTransaction is not enough

#

because that's the name of the endpoint, but we also need to refer to the service that provides that endpoint

opal sand
#

noun trial or trials, verb try?

gaunt wyvern
#

Fwiw the endpoint name for submitting txs is submit which is not a noun, its a verb.

#

Actually, that's not true, it's actually POST /transactions. 😅

#

Why does the endpoint need to be a noun though?

#

cc @hollow geode @tender trail (folks from the platform / rpc team should probably weigh in on naming since they provide the interface)

golden timber
gaunt wyvern
#

We don't have a preflight/simulation service though.

opal sand
#

I like that try works two ways in English. The most common: I'm attempting this transaction. From the perspective of dapp developers making something-like-view calls, this is a fair way to think about it. It might work, it might not.

If it doesn't "work", because the transaction requires signature, then the better way to think about it is the other definition of "try"—to put on trial. The result of this trial is returned, telling you what needs to happen to make this a valid transaction.

gaunt wyvern
#

Does NEAR have a term they use for this type of execution?

opal sand
#

Not totally perfect, but it seems like it might get people pretty close to a useful understanding of what's happening?

#

NEAR doesn't have such a mechanism. At least not as of my last use of it.

gaunt wyvern
#

I can see someone asking "try what?" The term try doesn't imply much context.

opal sand
#

It could be called tryTransaction?

#

The biggest downside I see so far is that it implies that the transaction will work, aka be included in the ledger, if it's "valid".

#

The "put on trial" meaning always works decently though

gaunt wyvern
tender trail
#

Yes, I agree that tryTransaction might imply that on success the transaction would be included.

gaunt wyvern
#

Those terms don't work for us, but it is interesting to note that they are clearly distinguishing the two types of calls.

tender trail
#

Maybe evaluateTransaction?

opal sand
gaunt wyvern
#

tryTransaction suffers a similar problem for me that call does. It doesn't really tell me it is offline.

#

simulateTransaction is pretty explicit about that.

#

And if we need a noun to describe simulateTransaction, simulation is a noun.

golden timber
#

'use simulation service to simulate transaction'?

gaunt wyvern
opal sand
#

yeah, in my first message here I only used "preflight" as a starting point and didn't come back and give the same treatment to "simulation". It seemed like Tomer thought maybe "simulation" is different enough in Soroban from other blockchains that the term should be avoided, but it's probably fine?

gaunt wyvern
#

In docs for a generated client I can imagine something like the following:

/// Calls my_function on the contract.
///
/// First simulates the contract call and if simulation indicates that the transaction does not produce a state change, returns the value generated through simulation. If simulation indicates a state change occurs, submits the transaction to the network.
///
/// If options include `simulate_only: true` the contract call is never submitted to the network.
///
/// If options include `always_submit: true` the contract call is always submitted to the network, even if no state change is expected.
function my_function(param1, param2, options)

(I don't know if the client will do those things, I'm just trying to put the terms into an example.)

gaunt wyvern
#

Although the results returned are a mix of simulating against a real network and simulating for testing purposes.

opal sand
gaunt wyvern
#

I don't love that I included two exclusive booleans in that example 😅

#

If I was allowed to revisit that moment, I might have said:

/// If options include `execution_plan: 'simulate_only'` the contract call is never submitted to the network, even if state is seen to change.
/// If options include `execution_plan: 'always_submit'` the contract call is always submitted to the network, even if no state change is expected.
/// If options include `execution_plan: 'simulate_and_submit_if_state_change'` the default behavior described above takes place.
golden timber
#

I kind of hate to deliver the bad news, but these 3 options are likely not enough. we'll likely need something around auth mode and potentially even footprint mode (though the latter hopefully can be done automatically...)

#

also for always_submit plan, I think we might just reject txs without RW footprint

hollow geode
hollow geode
hollow geode