Which Horizon "Post Transaction" responses are final and immutable?

Question

I am working on the development of a software wallet. I am using Horizon Post Transaction API to post signed transaction. Following an issue I ran into, I am trying to understand which responses are final and immutable and which are provisional.

Timeout - Provisional

According to this, timeout is not a final answer:

A stellar-core instance may drop your transaction after failing to include it in several ledgers (currently 3). However other distributed instances may still rebroadcast the tx. See e.g. stellar/stellar-core#1811.

When Horizon provides you with a timeout, it means that Horizon has not had timely confirmation that your tx has made it into a ledger. It does not guarantee that the tx will never make it.

Success - Final & Immutable

According to this, success is considered final & immutable:

Success is a consensus-level return so you don't need to look it up again. You can see this is so because the response includes the result XDR, and such XDR could only come from stellar-core after ledger application.

Transaction malformed?

Are transaction_malformed results final & immutable?

Transaction failed with transaction result_code == tx_failed?

Are transaction_failed results with transaction result_code == tx_failed like this one final & immutable?

I assume they are, as they include the result XDR like the aforementioned success result.

Transaction failed with transaction result_code != tx_failed?

What about transaction_failed results with transaction result_code != tx_failed?

Sample transaction results codes are:

• tx_bad_auth
• tx_no_source_account
• tx_bad_seq

These are trickier since the HTTP response body includes a result XDR as you mentioned but the transaction failure will not appear on the chain like the previous case when transaction result_code == tx_failed and fees are deducted. In general, such transactions may soon be valid, if account sequence changes for example.

Can I treat such results as final and immutable?

Answer 1

In short, there are two cases when the transaction fails: during validation and during execution. The rule of thumb: any transaction that has been recorded on the ledger is final and immutable. So if you can fetch it from Horizon, it means that the transaction is final.

Transactions that were rejected during the validation phase, and thus weren't included in the ledger, can be resubmitted (even without modifications). There is a key difference in behavior between those two cases.

If a transaction passes preliminary checks (it's not malformed, the fee is correct, all fields are set, the transaction is signed, timebounds restrictions are met, etc.), it is included in the candidate transaction set and then applied on the ledger. In this case, even if the transaction is failed, the validator increments the sequence number of the source account and charges tx fees.

Therefore,

• success - final, transaction passed
• tx_failed - final, transaction failed, no point to resubmit since the source sequence has changed and it will be rejected during validation upon next submission
• timeout - provisional, you need to either resubmit transaction as-is or increase fees before resubmission if surge pricing is in effect (check the /fee_stats endpoint)
• transaction_malformed, tx_no_source_account - rejected during validation, no point to resubmit as it will never succeed
• tx_bad_auth, tx_bad_seq - rejected during validation, might become valid in the future, say, once the sequence or signers of the source account are changed, but from a wallet perspective it makes sense to treat it the same way transaction_malformed is handled since it's hard to automatically determine when this tx can be resubmitted