Clarify that terQUEUED can change ledger state

[ollyw]

The ter-codes document previously states that transaction responses with terCodes can't affect the state of the ledger. This is misleading, as terQUEUED does, normally in the next ledger, without any further action from the caller. It seems from the description that all other ter codes won't modify the ledger without resubmission.

[mDuo13]

Sorry, but this is not accurate.

Transactions that result in ter codes, even terQUEUED, do not change the ledger.

However, any transaction that results in a ter class code will be automatically retried. If it then succeeds, its result code changes.

They only thing that is different about terQUEUED is that it is more likely that the transaction will succeed when it is retried.

Although the original caution blurb here is technically accurate, I can see how it would be easy to misunderstand. I'll try to reword it in a way that is less confusing but still accurate.

[intelliot]

The important thing to remember is that, upon transaction submission, any response that the server gives you is tentative and can change, especially before the transaction is validated.

In the case of terQUEUED, when the transaction is applied, it will definitely have a different code when it is applied to the ledger. So it is not that a terQUEUED transaction can change ledger state, but that any transaction's result code can (and often will!) change when it is validated.

So yes, you are correct that a transaction that is given a tentative result of terQUEUED can change ledger state, but its result code will be different once that happens.

You must never trust the transaction result code until it is in a validated ledger.* Due to a current issue in rippled, this is the case no matter what the result code is.

It may make sense to call this out more clearly in the docs.

* (Aside: Of course, some transactions never get included in a validated ledger - for example, if the transaction is invalid, or expires due to LastLedgerSequence and thus becomes invalid)

[ollyw]

Thanks for the feedback. This has been very helpful. I must confess that I didn't realise all ter codes are automatically retried. Perhaps a tweak to the documentation in to state that more clearly would be good. e.g. current https://xrpl.org/transaction-results.html says:

Retry | ter | The transaction could not be applied, but it might be possible to apply later.`
Something like
Retry | ter | The transaction could not be applied, but attempts will be made automatically to apply to a future ledger

Is this clear and accurate?
Also, on the ter page https://xrpl.org/ter-codes.html:
current:

Transactions with ter codes are not applied to ledgers and cannot cause any changes to the XRP Ledger state. However, a transaction that provisionally failed may still succeed or fail with a different code after being reapplied. For more information, see Finality of Results and Reliable Transaction Submission.

Could be something like

Transactions with ter codes are not applied the current ledger and cannot cause any changes to the XRP Ledger state. However, a transaction that provisionally failed may still succeed or fail with a different code after being automatically reapplied. For more information, see Finality of Results and Reliable Transaction Submission.

Do you think this, or similar improvements are worthwhile. Certainly as a person trying to integrate with Ripple and determine what action to take in each scenario, the clearer the things can be, the better.

[ollyw]

I have pushed a new commit replacing the old one following up what was discussed on this thread. I hope it works for everyone.

[mDuo13]

Thanks for the contribution. I modified it just a little bit more because I want it to be clear that it's not just ter codes that get automatically retried. (In fact, there's a bug with transaction submission right now where even transactions that have no chance of succeeding, like ones with tem codes, get automatically retried. See XRPLF/rippled#2847 )

[ollyw]

Awesome @mDuo13. Thanks!