feat(utxo-locking)!: Add commands to lock, unlock and list locked UTXOs

[tvpeter]

Description

This PR updates the Wallet API to v3.1.0 and adds wallet subcommands to lock and unlock UTXOs. Locked outpoints are excluded from coin selection, and the lock state is stored in the wallet. It also updates the bdk_redb to v0.2.0 and bdk_kyoto to v0.17.0.

Fixes #293 and builds upon #289 and #278

Notes to the reviewers

Changelog notice

• Update bdk_wallet to v3.1.0
• Add wallet lock_utxo command
• Add wallet unlock_utxo command
• Add wallet locked_uxtos command
• Update bdk_redb to v0.2.0
• Update bdk_kyoto to v0.17.0
• Replace Network enum with NetworkKind
• Replace include_output_redeem_witness_script with add_global_xpubs in TxBuilder
• Replace submit_package with broadcast_random for broadcasting transactions in KyotoClient

Checklists

All Submissions:

• I've signed all my commits
• I followed the contribution guidelines
• I ran cargo fmt and cargo clippy before committing

New Features:

• I've added tests for the new feature
• I've added docs for the new feature
• I've updated CHANGELOG.md

[codecov]

Codecov Report

❌ Patch coverage is 73.91304% with 18 lines in your changes missing coverage. Please review.
✅ Project coverage is 57.47%. Comparing base (6000dd5) to head (4a889a7).
⚠️ Report is 4 commits behind head on master.

Files with missing lines	Patch %	Lines
src/client.rs	0.00%	9 Missing ⚠️
src/handlers/offline.rs	91.30%	4 Missing ⚠️
src/handlers/descriptor.rs	33.33%	2 Missing ⚠️
src/utils/descriptors.rs	60.00%	2 Missing ⚠️
src/handlers/dns/mod.rs	0.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #294      +/-   ##
==========================================
+ Coverage   56.89%   57.47%   +0.57%     
==========================================
  Files          22       22              
  Lines        3661     3694      +33     
==========================================
+ Hits         2083     2123      +40     
+ Misses       1578     1571       -7     

Flag	Coverage Δ
rust	57.47% <73.91%> (+0.57%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Musab1258]

Concept ACK, but I have a few concerns I want to point out.

[Musab1258]

I noticed the bip322 feature, its commands, and integration tests have been commented out.

I assume this was because of the hard dependency conflict between bdk_bip322 (which requires bdk_wallet ^2.1.0) and the bdk_wallet v3.1.0 dependency upgrade and that you left the code here to make it easier to restore later. However, leaving large blocks of dead code may lead to code rot.

Instead of commenting it out, could we cleanly remove the bip322 code in an isolated commit and open a tracking issue to reintroduce it? When bdk_bip322 is updated, we can simply git revert that removal commit to restore the work without needing to re-implement the feature from scratch.

[tvpeter]

I noticed the bip322 feature, its commands, and integration tests have been commented out.

I assume this was because of the hard dependency conflict between bdk_bip322 (which requires bdk_wallet ^2.1.0) and the bdk_wallet v3.1.0 dependency upgrade and that you left the code here to make it easier to restore later. However, leaving large blocks of dead code may lead to code rot.

Instead of commenting it out, could we cleanly remove the bip322 code in an isolated commit and open a tracking issue to reintroduce it? When bdk_bip322 is updated, we can simply git revert that removal commit to restore the work without needing to re-implement the feature from scratch.

Thank you for your suggestion. The reason the bip322 feature is currently commented out is that the maintainer of bdk_bip322 @aagbotemi, promised to update the library soon when I reached out to him. I commented out the feature to ensure that the CI checks are passing and to get reviews.

[Musab1258]

This prints a warning but proceeds to lock the outpoint even when wallet.get_utxo returns None. Is this intentional?

If it is intentional, does locking this unknown outpoint pollute the persisted lock-state DB with a nonexistent record? Since this outpoint will never appear in list_unspent and thus can never be spent by the wallet, will this orphaned lock record sit in the database forever and cause permanent bloat?

[Musab1258]

Regarding the tests, I've been considering a few edge cases:

1. What is the expected behavior when you try to unlock an already unlocked UTXO? Can we add a test to ensure the CLI handles this gracefully?

2. The current test_locked_utxo_excluded_from_coin_selection() only tests the scenario where the sole UTXO is locked. Could we add a test for when we have multiple UTXOs with only one of them locked? It would enable us to verify that the coin selection algorithm actively selects the unlocked UTXOs while automatically ignoring the locked ones.