Change tx status method doc

[telezhnaya]

https://docs.near.org/api/rpc/transactions#transaction-status
In reality, we wait until the block of the last corresponding receipt_id is final, and only then return the result. So the user does not need to check anything.

Return type is FinalExecutionOutcomeView, it's by the definition Final execution outcome of the transaction and all of subsequent the receipts.

I've found this while working on near/nearcore#6837
Maybe I'll change the signature of tx status method or add the new one with more fine-grained way to ask for the result without waiting until everything is final

[render]

Your Render PR Server URL is https://near-docs-pr-1499.onrender.com.

Follow its progress at https://dashboard.render.com/static/srv-ck4upj6i9prc73ffb88g.

[bucanero]

let me know if we should merge it 👍

[wacban]

I'm not sure this is the case, can you explain a bit more? This RPC call eventually ends up in get_final_transaction_result and there it doesn't actually check the status of each receipt, it just returns the status for all available receipts. In particular it could return FinalExecutionStatus::NotStarted for some.

https://github.com/near/nearcore/blob/315d186b5b792bf942455fcbab0a0a5ddb08a621/chain/chain/src/chain.rs#L3605

cc @jakmeier do you happen to know how this works?

[telezhnaya]

Valid concern.
If it's true, then I want to clarify how EXPERIMENTAL_tx_status works
The doc is ambiguous
https://docs.near.org/api/rpc/transactions#transaction-status-with-receipts
I thought it gives fully final result
The main difference from tx is that it uses get_final_transaction_result_with_receipt underneath. It does not check if the corresponding blocks are finalised.
So, the receipts may not be included into finalised blocks yet, right?

@wacban @jakmeier I've created the proposal for improving tx status method, please leave any comments there
near/nearcore#9542

[jakmeier]

I am not sure about this TBH. But the description in near/nearcore#6834 suggests we indeed wait for all execution outcomes to be available in the polling loop. So this part of the documentation seems outdated:

In the case of function call transactions, this query will not wait for all receipts generated by this transaction to finish before returning a result. Rather, it will only wait for its return value to finish before returning; which could be a promise.

On the other hand, this seems to be still true:

In addition, tx endpoint does not provide finality guarantees. To make sure that the entire execution is final, it suffices to ensure every block_hash in every outcome is final.

I wrote my exact (but probably flawed) understanding in near/nearcore#9542

[wacban]

@gagdiez I see you merged this PR but I'm not sure if it was ready or abandonded. @telezhnaya, the author, did you mean to get it merged?

[gagdiez]

I saw an approved PR that was not in draft state, so I went ahead and merged it.

If this was a mistake, please let me know so I roll it back.

[telezhnaya]

@gagdiez please roll it back
It's not the time, we still need to wait for the release

[bucanero]

@telezhnaya change has been reverted in b9fc109

[bucanero]

@telezhnaya I have also created a new PR #1660 , and left it as draft state so you can let us know when this change is ready to be merged.