waitForConfirmation may throw errors unrelated to a transaction's success/failure

[jasonpaulos]

Problem

The waitForConfirmation function is responsible for returning a promise with the following properties:

• Successfully resolves when the identified transaction has been confirmed in a block
• Errors if waitRounds rounds have passed without the transaction being confirmed in a block
• Errors if the transaction was rejected from the pending pool

However, due to the nature of its implementation, there is another situation in which the function may error:

• Errors if a network issue happens or if an invalid algod status is returned

In addition to this unplanned error case, the design of this function has a problem: the caller has no way of determining why the function fails, except by parsing the returned error message string, which we consider to be error-prone and less than ideal.

This is a problem because the function may return an error due to timeout or network issues, but the transaction in question may still get confirmed in a block. This misleading messaging can be very problematic for the calling code.

Solution

We believe the optimal solution is to improve the caller's ability to determine why the waitForConfirmation function fails.

If the caller is able to know with certainty whether a failure is because the transaction was rejected or because of a different reason, the caller will be better equipped to take the appropriate follow-up actions. Appropriate actions may be attempting to further wait for confirmation, or determining that it's necessary to submit a variation of the original transaction again.

Specifically, this solution would create new error types which would allow the caller to more easily differentiate between them to determine the type of error that occurred.

If we find success with this solution, the goal is to replicate this work across the 3 other SDKs we support.

---

Thanks to @AlgoDoggo who first made us aware of this problem in #601.