docs: add Provider doc section for cacheUtxo

[Torres-ssf]

• Close: Add docs related to the optional caching UTXOs logic #2056
• Close: Review UTXO caching logic #1515

[maschad]

Nice job on this 🚀 , left some suggestions.

[danielbate]

First pass, couple comments and questions.

1. If I have one utxo and am submitting multiple transactions, cacheUtxo has no effect and in fact we risk the second tx failing but we would be able to fund both txs initially?
2. Why would you not want to cacheUtxos?

[arboleya]

I'll think more about this before coming back to it.

At first glance, this flag looks confusing.

[Torres-ssf]

@danielbate

First pass, couple comments and questions.

1. If I have one utxo and am submitting multiple transactions, cacheUtxo has no effect, and in fact we risk the second tx failing but we would be able to fund both txs initially?

If you have just one UTXO and you fund and submit 2 TXs simultaneously:

• without cacheUtxo: The first TX to be processed would work, and the second one would fail with the error related to a non-existent UTXO

• with cacheUtxos: The first one will be funded normally, but now this UTXO is cached, then when funding the second one an error will thrown related to not having enough balance to fit the target.

When you have just one UTXO, you cannot send multiple TXs without waiting for the first one to complete. It will always fail

2. Why would you not want to cacheUtxos?

The only reason that comes to mind would be in a situation where your first TX failed, and then your UTXO that was not being spent is now unusable until the cache for it got whipped.

Also, the error message is different. Maybe you have just one UTXO and since the cache is being used by default, and you are completely unaware of it, if you try to send 2 transactions in a row the error message would be not enough balance to fit the target instead of UTXO not existent.

This flag makes it possible for users that own multiple UTXOs to submit multiple TXs in a row, without waiting for each one to be processed, and without running into the error UTXO non-existent.

This error will likely happen, as the TXs are going to be funded automatically, and TX1 and TX2 can be funded with the same UTXO(s). Then, when TX1 is processed, that specific UTXO will be spent, and TX2 will fail.

[danielbate]

Thanks for the detailed explanation

[github-actions]

Coverage Report:

Lines	Branches	Functions	Statements
79.54%(+0%)	71.37%(+0%)	76.91%(+0%)	79.62%(+0%)

Changed Files:

Coverage values did not change👌.