feat(utxo-locking)!: Add commands to lock, unlock and list locked UTXOs by tvpeter · Pull Request #294 · bitcoindevkit/bdk-cli

tvpeter · 2026-06-30T14:37:14Z

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

- add BdkCli helper struct and impl methods - add integration tests for the key subcommand operations

- Add integration tests for wallets, descriptor, compile and config modules

- add integration tests for offline wallet operations

- Add test for creating, signing, broadcasting tx - Add test for combining psbt, fee bump and other psbt related commands - Add bip322 tests

- add saving proxy_opts for electrum and esplora clients to config and reading values - fix prepare_home_dir util fn

- Update bdk_wallet to v3.1.0 - Replaced Network enum with NetworkKind - Replaced `include_output_redeem_witness_script` with `add_global_xpubs` - update bdk_redb to v0.2.0

- update bdk_kyoto to v0.17.0 - add ew broadcast/subscriber API for KyotoClient

- add wallet commands to lock, unlock and list locked utxos - update unspent command to show status of each outpoint

-Temporary disable bip322 feature

codecov · 2026-07-09T08:25:57Z

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.

-add test for locking, unlocking and listing locked utxos

Musab1258 · 2026-07-12T15:08:14Z

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

Musab1258 · 2026-07-12T15:14:58Z

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 · 2026-07-12T16:39:44Z

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 · 2026-07-12T17:43:05Z

+        for out_point in &self.utxos {
+            if wallet.get_utxo(*out_point).is_none() {
+                eprintln!("warning: {out_point} is not a known wallet UTXO; locking anyway");
+            }
+            wallet.lock_outpoint(*out_point);
+        }


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?

What do you mean by "nonexistent record"? Locking a UTXO does not exclude it from unspent list. It displays with a lock is true. Locking simply makes it unavailable for coin selection.

If it is intentional, does locking this unknown outpoint pollute the persisted lock-state DB with a nonexistent record?

My understanding - the use case for locking a currently-unknown outpoint is that the user already knows the UTXO but the wallet doesn't yet (it hasn't synced). After a sync the wallet learns the UTXO, so it shows up among the locked ones and the lock takes effect for coin selection.

Since bdk-cli can't know in advance whether a locked outpoint will become a known wallet UTXO later or not, I can't think of a good solution against the possible DB bloat here - filtering out "unknown" outpoints would also drop these legitimate pre-sync locks.

That said, bdk-cli targets technically advanced users, so I'd lean on the assumption that the user knows what they're doing and won't lock arbitrary UTXOs.

Musab1258 · 2026-07-13T14:24:14Z

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

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?
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.

- update bdk_bip322 crate with replacement crate bdk_message_signer - re-enable bip322 feature

tvpeter · 2026-07-14T02:19:59Z

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

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?

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.

For exhaustive tests that cover all edge cases, check out the UTXO Locking feature in bdk_wallet. This is just to demo how users can utilize the feature.

va-an

utACK 4a889a7

Left a few comments, non-blocking in my view.

Looks like a typo in the PR description changelog: "Replace submit_package with broadcast_random" - the code does the reverse (broadcast_random -> submit_package).

va-an · 2026-07-14T18:17:51Z

+#[derive(Parser, Debug, Clone, PartialEq)]
+pub struct LockUtxoCommand {
+    /// Outpoint(s) to lock, format TXID:VOUT.
+    #[arg(env = "TXID:VOUT", long = "utxo", required = true, value_parser = parse_outpoint)]


env = "TXID:VOUT" tells clap to read this argument from an env var named TXID:VOUT when it isn't passed on the command line.

The catch is that an env var with that name can't actually be set: a name containing : isn't a valid shell identifier, so export rejects it:

$ export TXID:VOUT=foo export: not valid in this context: TXID:VOUT

Might be worth renaming the env var to a more shell-compatible name (without :).

va-an · 2026-07-15T08:30:36Z


        if self.offline_signer {
-            tx_builder.include_output_redeem_witness_script();
+            tx_builder.add_global_xpubs();


This makes tx building (finish()) error with CreateTxError::MissingKeyOrigin if any descriptor key has no origin - a bare xpub with no [fingerprint/path] prefix (a master key is fine).

The previous include_output_redeem_witness_script() didn't have this requirement - in the bdk_wallet version currently on master (2.4.0) that flag was actually never read (checked the source), so it was effectively a no-op. add_global_xpubs() does populate the xpubs but is stricter, so in some cases it now surfaces this error.

bdk-cli's own descriptors always carry an origin, so they're fine. Just flagging that an imported watch-only descriptor with a bare origin-less xpub (wpkh(tpub.../0/*)) would error here where it previously produced a PSBT. Might be worth a docs note about the origin requirement.

(Same swap in create_sp_tx, bump_fee, create_dns_tx.)

va-an · 2026-07-15T09:03:38Z

+        for out_point in &self.utxos {
+            if wallet.get_utxo(*out_point).is_none() {
+                eprintln!("warning: {out_point} is not a known wallet UTXO; locking anyway");
+            }
+            wallet.lock_outpoint(*out_point);
+        }


If it is intentional, does locking this unknown outpoint pollute the persisted lock-state DB with a nonexistent record?

My understanding - the use case for locking a currently-unknown outpoint is that the user already knows the UTXO but the wallet doesn't yet (it hasn't synced). After a sync the wallet learns the UTXO, so it shows up among the locked ones and the lock takes effect for coin selection.

Since bdk-cli can't know in advance whether a locked outpoint will become a known wallet UTXO later or not, I can't think of a good solution against the possible DB bloat here - filtering out "unknown" outpoints would also drop these legitimate pre-sync locks.

That said, bdk-cli targets technically advanced users, so I'd lean on the assumption that the user knows what they're doing and won't lock arbitrary UTXOs.

tvpeter added 9 commits June 22, 2026 22:49

test: Add helper fns & integration tests for key

38a709f

- add BdkCli helper struct and impl methods - add integration tests for the key subcommand operations

test: Add wallets, descriptor, compile & config

b8761bc

- Add integration tests for wallets, descriptor, compile and config modules

test: Add integration tests for offline wallet ops

ae0c32a

- add integration tests for offline wallet operations

test(online): Add test transaction full cycle

dfeb580

- Add test for creating, signing, broadcasting tx - Add test for combining psbt, fee bump and other psbt related commands - Add bip322 tests

ref(verbose): Dropped verbose flag from tests

eec81e2

fix(proxy_opts): add saving and reading proxy_opts

cbee8a0

- add saving proxy_opts for electrum and esplora clients to config and reading values - fix prepare_home_dir util fn

feat(wallet-3.1.0): Update Wallet to v3.1.0

d89a08d

- Update bdk_wallet to v3.1.0 - Replaced Network enum with NetworkKind - Replaced `include_output_redeem_witness_script` with `add_global_xpubs` - update bdk_redb to v0.2.0

feat(cbf): Update bdk_kyoto to v0.17.0

205d46c

- update bdk_kyoto to v0.17.0 - add ew broadcast/subscriber API for KyotoClient

feat(utxo-locking): Add wallet locking commands

242d4da

- add wallet commands to lock, unlock and list locked utxos - update unspent command to show status of each outpoint

github-project-automation Bot added this to BDK-CLI Jun 30, 2026

tvpeter self-assigned this Jun 30, 2026

tvpeter changed the title ~~feat(utxo-locking)!: Add wallet commands to lock, unlock and list locked UTXOs~~ feat(utxo-locking)!: Add commands to lock, unlock and list locked UTXOs Jun 30, 2026

tvpeter added this to the CLI 4.0.0 milestone Jun 30, 2026

tvpeter added 2 commits July 9, 2026 06:50

Merge branch 'master' into feat/utxo-locking

73c3b9d

fix(bip322): disable bip322 feature

d3dde30

-Temporary disable bip322 feature

feat(utxo-locking): Add tests for utxo locking

aba6c66

-add test for locking, unlocking and listing locked utxos

tvpeter force-pushed the feat/utxo-locking branch from e26cf5e to aba6c66 Compare July 9, 2026 08:40

Musab1258 reviewed Jul 12, 2026

View reviewed changes

fix(bip322): Re-enable bip322 feature

4a889a7

- update bdk_bip322 crate with replacement crate bdk_message_signer - re-enable bip322 feature

va-an approved these changes Jul 15, 2026

View reviewed changes

Uh oh!

Conversation

tvpeter commented Jun 30, 2026

Description

Notes to the reviewers

Changelog notice

Checklists

All Submissions:

New Features:

Uh oh!

codecov Bot commented Jul 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Musab1258 commented Jul 12, 2026

Uh oh!

Musab1258 commented Jul 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

tvpeter commented Jul 12, 2026

Uh oh!

Musab1258 Jul 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tvpeter Jul 14, 2026

Choose a reason for hiding this comment

Uh oh!

va-an Jul 15, 2026

Choose a reason for hiding this comment

Uh oh!

Musab1258 commented Jul 13, 2026

Uh oh!

tvpeter commented Jul 14, 2026

Uh oh!

va-an left a comment

Choose a reason for hiding this comment

Uh oh!

va-an Jul 14, 2026

Choose a reason for hiding this comment

Uh oh!

va-an Jul 15, 2026

Choose a reason for hiding this comment

Uh oh!

va-an Jul 15, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

codecov Bot commented Jul 9, 2026 •

edited

Loading

Musab1258 commented Jul 12, 2026 •

edited

Loading

Musab1258 Jul 12, 2026 •

edited

Loading