feat!: Persist utxo lock status

[ValuedMammal]

This PR adds methods to Wallet to lock and unlock a UTXO by outpoint, to query the locked outpoints, and updates the wallet ChangeSet to persist the lock status of an outpoint.

fixes #166
fixes #245

Considerations for broadcast scenarios:

When a UTXO is locked, it won't be selected for a transaction. This is useful in cases where the user needs to permanently exclude an output from being spent, or reserve it until some time in the future and continue making transactions in the meantime. To eventually spend the coin the user has to explicitly unlock it. This process could perhaps be facilitated by implementing an automatic lock expiry based on block height.

If you submit a transaction to the network and then lock the inputs, then they won't be re-selected in subsequent transactions. This prevents us from inadvertently "double-spending" ourselves. Once broadcast, the lock effect depends on the fate of the transaction: If it confirms and the outpoint is still locked, then the lock is no longer useful, because the input can't be double spent anyway by virtue of consensus. If a conflict confirms which spends the same output, the lock is also irrelevant. If a conflict confirms but doesn't spend the already locked output then the lock remains in effect.

If the transaction is somehow dropped from the mempool but otherwise still valid, we can either rebroadcast the tx or create a replacement. As far as I can tell the implementation doesn't prevent us from creating a Replace-By-Fee transaction regardless of the lock status, since the inputs to the RBF are considered "manually selected".

To avoid the risk of double payment (sending two txs to the same payment invoice) one needs to examine the details of the second transaction to ensure that it actually replaces the first one, otherwise we've simply made a donation to our counterparty.

Changelog notice

Added these methods to `Wallet`

    - `lock_outpoint`
    - `unlock_outpoint`
    - `list_locked_outpoints`
    - `list_locked_unspent`
    - `is_outpoint_locked`

Added

   - New type `wallet::locked_outpoints::ChangeSet`
   - BREAKING: New member field `wallet::ChangeSet::locked_outpoints`

Checklists

All Submissions:

• I've signed all my commits
• I followed the contribution guidelines
• I ran just p before pushing

New Features:

• I've added tests for the new feature
• I've added docs for the new feature
• This pull request breaks the existing API
• I'm linking the issue being fixed by this PR

[coveralls]

Pull Request Test Coverage Report for Build 18143264122

Details

• 92 of 105 (87.62%) changed or added relevant lines in 4 files are covered.
• 1 unchanged line in 1 file lost coverage.
• Overall coverage increased (+0.1%) to 85.341%

---

Changes Missing Coverage	Covered Lines	Changed/Added Lines	%
src/wallet/mod.rs	41	44	93.18%
src/wallet/changeset.rs	45	49	91.84%
src/wallet/persisted.rs	0	6	0.0%

Files with Coverage Reduction	New Missed Lines	%
src/wallet/mod.rs	1	82.37%

Totals
Change from base Build 18099939060:	0.1%
Covered Lines:	3982
Relevant Lines:	4666

---

💛 - Coveralls

[ChidiChuks]

How do you handle UTXO locking in concurrent wallet instances?

[nymius]

Could you expand a little bit more on how this mechanism could be used in broadcast scenarios?
From the test I guess all the logic of why a UTxO becomes available again is kept by the lib user? Like unlock UTxO after a height in the future if there is not transaction spending it in the blockchain.

This is a competing solution for #257, right?

[evanlinjin]

How do you handle UTXO locking in concurrent wallet instances?

@ChidiChuks could you be a bit more specific with this question? Do you mean sharing lock status between multiple instances of the same wallet?

[evanlinjin]

This is a competing solution for #257, right?

@nymius My understanding is that this is NOT a competing solution with #257. UTXO-locking will not fully solve #166 as we want unbroadcasted outputs to be available for selection. In fact, UTXO-locking is already available by using TxBuilder::add_unspendable. The only difference here is that locked outpoints are persisted with BDK. So this is more of a convenience feature that users are requesting.

[evanlinjin]

Thanks for this work.

I propose adding the following methods:

• list_locked_outpoints - Lists all locked outpoints.
• list_locked_unspents - Lists locked outpoints that are unspent.

Imagine a situation where the caller broadcasts a tx and locks the prevouts. Then the tx gets evicted from the mempool. It will be helpful to list locked unspents at this point to recover those prevouts.

[ValuedMammal]

@evanlinjin I took all of your suggestions other than I think the proposed Wallet::list_locked_unspents is not yet implemented. edit: I have some ideas for this though.

[notmandatory]

I'm happy to see this feature moving along. In addition to helping L2 users like @tnull it also helps support one of my personal goals of improving feature parity with the bitcoin core wallet.

[evanlinjin]

Implementation looks good. Just need a bit more clarity on expiration_height before ACK.

[evanlinjin]

Other than my comment above, everything looks good!

[ValuedMammal]

• Changed Wallet locked_outpoints field to HashMap.
• Rebased