Feat: Add bip329 wallet labels by Musab1258 · Pull Request #266 · bitcoindevkit/bdk-cli

Musab1258 · 2026-03-31T08:42:13Z

Description

This PR adds BIP-329 wallet label support to bdk-cli, to fix #184. It uses the [bip329] crate to manage label data, persists it in a separate labels.jsonl file within the wallet's data directory (e.g. ~/.bdk-bitcoin/<wallet_name>/labels.jsonl), and keeps it decoupled from the wallet's SQLite/redb database. It also exports and imports label files.

This PR includes the following functionality:

Set labels: It uses a new label offline subcommand to attach a human-readable label to either a transaction ID, address, or UTXO (outpoint).
Persist labels: It ensures that Labels are loaded from disk at the start of every offline wallet command and saved back after the command completes, so they survive across sessions.
Display labels: The unspent and transactions commands now include a Label column in both --pretty table output and standard JSON output, showing the stored label or an em dash if none exists.
Import labels: The import_labels subcommand merges labels from an external BIP-329 JSONL file into the wallet's current label state. If a label for the same item already exists, it is overwritten by the imported one.
Export labels: The export_labels subcommand writes the wallet's current label state to a user-specified BIP-329 JSONL file, suitable for backup or use in other BIP-329 compliant wallets.

Notes to the reviewers

Labels are stored in a separate labels.jsonl file rather than inside the wallet database. This keeps the label format portable and interoperable with other BIP-329 compliant wallets.
The Label import from bip329 is aliased as BipLabel in handlers.rs to avoid a name clash with the OfflineWalletSubCommand::Label variant brought into scope via use crate::commands::OfflineWalletSubCommand::*.
The import_labels command uses the existing add_or_update_label helper to merge incoming labels one at a time, new label references are inserted, and existing label references are overwritten by the imported value.
The export_labels command writes to a user-specified path, which is independent of the wallet's internal labels.jsonl file. The internal file is always managed automatically by the save-on-exit mechanism, so the two files remain separate.

Changelog notice

Added

New label subcommand to OfflineWalletSubCommand for tagging transactions, addresses, and UTXOs with human-readable labels.
New import_labels subcommand to merge labels from an external BIP-329 JSONL file into the wallet's current label state.
New export_labels subcommand to back up the wallet's current label state to a user-specified BIP-329 JSONL file.
BIP-329 compliant label persistence via a labels.jsonl file in the wallet data directory.
Label column in unspent and transactions output (both --pretty and JSON).
parse_txid helper in utils.rs.
bip329 = "0.4.0" dependency in Cargo.toml.

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

Bugfixes:

This pull request breaks the existing API
I've added tests to reproduce the issue which are now passing
I'm linking the issue being fixed by this PR

- Loads the \'Labels\' state from \'<wallet>.labels.jsonl\' after \'load_wallet_config\'. - Updates \'handle_offline_wallet_subcommand\' to accept mutable label state. - Exports and saves the in-memory labels to disk before the command return.

- Injects label lookups into the `unspent` and `transactions` match arms. - Updates the `--pretty` table formatting to include a new 'Label' column (using an em dash for missing labels). - Appends the label string to the standard JSON output

- Introduces the `Label` variant to `OfflineWalletSubCommand` with strict `clap` conflict rules. - Adds a `parse_txid` helper to utils.rs. - Implements an `add_or_add_update_label` helper in `handlers.rs` to mutate the in-memory label state in place.

Musab1258 · 2026-03-31T08:47:02Z

Hi @tvpeter, I am done with this. You can check it out when you are free.

I will start working on the follow-up PR to add import and export of label files.

- Introduces `ImportLabels` and `ExportLabels` variants to `OfflineWalletSubCommand` for CLI parsing. - Implements label merging from external JSONL files using `try_from_file` and `add_or_update_label`. - Enables backing up the current label state to a user-specified path using `export_to_file`.

Musab1258 · 2026-04-04T01:39:04Z

Hi @tvpeter, I eventually decided to add the import and export of BIP-329 JSONL files' implementation here when, after I was done with the implementation, I saw that it was something that could fit into this PR without bloating it.

So, instead of creating a second PR and having reviewers go through the stress of reviewing two PRs that can probably fit into one, I decided to make it one PR.

codecov · 2026-04-04T12:55:55Z

Codecov Report

❌ Patch coverage is 0% with 132 lines in your changes missing coverage. Please review.
✅ Project coverage is 10.59%. Comparing base (07fd32f) to head (8422d82).
⚠️ Report is 1 commits behind head on master.

Files with missing lines	Patch %	Lines
src/handlers.rs	0.00%	129 Missing ⚠️
src/utils.rs	0.00%	3 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #266      +/-   ##
==========================================
- Coverage   11.13%   10.59%   -0.55%     
==========================================
  Files           8        8              
  Lines        2488     2615     +127     
==========================================
  Hits          277      277              
- Misses       2211     2338     +127

Flag	Coverage Δ
rust	`10.59% <0.00%> (-0.55%)`	⬇️

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

☔ View full report in Codecov by Sentry.
📢 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.

notmandatory · 2026-04-22T14:39:10Z

This looks like a very useful feature and one that I'd love to see in the bdk-cli project. But instead of coding it directly into bdk-cli how would you feel about creating a new bdk_bip329 (or bdk-bip329) crate similar to bdk-bip322?

It will be a little more complicated than bdk-bip322 since you also need some sort of persistence trait to tie into the user's choice of database. But it would be nice to have something easy to integrate with any bdk_wallet based project.

Musab1258 · 2026-04-23T05:32:21Z

Thanks, @notmandatory, for the review and the suggestion! I really like the idea of creating a new bdk_bip329 crate similar to bdk-bip322 so other bdk_wallet projects can easily integrate it, and I would love to work on it.

Regarding the persistence trait to tie into the user's choice of database, I was thinking we could build an interface that lets users store labels internally in their database of choice (like SQLite or Redb). To keep it efficient, we could mirror bdk_wallet's approach by abstracting the backend and using a changeset pattern to persist only the diffs.

To maintain strict BIP-329 compliance, the crate would then provide dedicated import and export methods to convert the internal database state to and from the standard JSONL format.

Does this approach align with what you have in mind?

notmandatory · 2026-04-26T16:55:07Z

Yes this sounds like a good approach.

brh28 · 2026-04-26T18:38:49Z

Hey @Musab1258, glad to see you're working on this. I've been playing around with bdk-cli and had some thoughts around this

My thinking is to create a bdk_labels tool. The motivation is similar to the idea of a bdk_bip329 crate, but with some expanded functionality. Some ideas:

Import bip329 jsonl (e.g cat mywallet.jsonl | bdk_labels import --bip329)
Import existing bdk wallets (bdk_labels import --config # reads $DATADIR, else ~/.bdk-bitcoin)
Add a label to existing wallet using bip329 keys as arguments (e.g bdk-labels add --type tx --ref <txid> --label "groceries")
Add a label to types not-associated with a wallet. (e.g bdk-labels add --type addr --ref <addr> --label "Satoshi's Coins")
Export bip329 with filter arguments (bdk_labels export --origin multisigwallet)
Support a list of labels (or "tags" to distinguish nomenclature) (e.g bdk-labels tag --type output --ref <txid:3> "cost_basis_lot:20260426" "project_income" "kyc"). These tags can be serialized into the bip329 label
Query labels/tags (e.g bdk_labels list --type tx --tag project_income)

Just brainstorming somethings that I think would be useful. Would love to hear know your thoughts

Musab1258 · 2026-04-29T16:51:14Z

@notmandatory, since I don't have permissions to create a repository in the bitcoindevkit organization, what should the next steps be? Would you set up an empty repository within the organization (similar to how bdk-bip322 is set up) for me to work from?

Yes this sounds like a good approach.

Musab1258 · 2026-04-29T20:39:09Z

@brh28, these are really nice ideas for expanding the labeling functionality.

Actually, some of the features you mentioned (like importing a BIP-329 JSONL file and adding labels to existing wallet items) are already implemented in my current PR here. Since @notmandatory suggested implementing it in a new bdk_bip329 crate, we can implement the existing add, import, and export functionalities first. Then we can add the multi-tagging and filter logic later.

Also, the examples you made (like cat mywallet.jsonl | bdk_labels import --bip329 and the rest) show that you wanted the tool to be a CLI. But, I think what @notmandatory wants is a crate that can be integrated into other crates and CLI tools

@notmandatory may also have something to say about this.

Hey @Musab1258, glad to see you're working on this. I've been playing around with bdk-cli and had some thoughts around this

My thinking is to create a bdk_labels tool. The motivation is similar to the idea of a bdk_bip329 crate, but with some expanded functionality. Some ideas:

Import bip329 jsonl (e.g cat mywallet.jsonl | bdk_labels import --bip329)

Import existing bdk wallets (bdk_labels import --config # reads $DATADIR, else ~/.bdk-bitcoin)

Add a label to existing wallet using bip329 keys as arguments (e.g bdk-labels add --type tx --ref <txid> --label "groceries")

Add a label to types not-associated with a wallet. (e.g bdk-labels add --type addr --ref <addr> --label "Satoshi's Coins")

Export bip329 with filter arguments (bdk_labels export --origin multisigwallet)

Support a list of labels (or "tags" to distinguish nomenclature) (e.g bdk-labels tag --type output --ref <txid:3> "cost_basis_lot:20260426" "project_income" "kyc"). These tags can be serialized into the bip329 label

Query labels/tags (e.g bdk_labels list --type tx --tag project_income)

Just brainstorming somethings that I think would be useful. Would love to hear know your thoughts

brh28 · 2026-04-29T22:03:18Z

Thanks @Musab1258

I created my own repo bdk-labels to start implementing some of these features. As you pointed out, many of the features overlap with what you're working on, so it's quite similar to your PR, but perhaps it'll be of interest to you.

The biggest feature difference is tags, which are currently encoded into the label field but would ideally be it's own bip329 field.

~~Also, my implementation uses an existing bip329 crate if that's something that interests you.~~ you're already using it :)

brh28 · 2026-04-29T22:33:33Z

+        LabelRef::Address(addr) => format!("addr:{}", addr.assume_checked_ref()),
+        LabelRef::Output(op) => format!("output:{op}"),
+        LabelRef::Input(op) => format!("input:{op}"),
+        _ => item_ref.to_string(), // Fallback for pubkey/xpub


why fallback, rather than handle other types?

notmandatory · 2026-04-30T03:49:15Z

@notmandatory, since I don't have permissions to create a repository in the bitcoindevkit organization, what should the next steps be? Would you set up an empty repository within the organization (similar to how bdk-bip322 is set up) for me to work from?

Go ahead and create a new repo in your personal account and we can move it into the bitcoindevkit org when it's ready. I also prefer @brh28 's repo name bdk-labels. And glad to see you two collaborating on this project.

notmandatory · 2026-04-30T03:52:49Z

@brh28, these are really nice ideas for expanding the labeling functionality.

Actually, some of the features you mentioned (like importing a BIP-329 JSONL file and adding labels to existing wallet items) are already implemented in my current PR here. Since @notmandatory suggested implementing it in a new bdk_bip329 crate, we can implement the existing add, import, and export functionalities first. Then we can add the multi-tagging and filter logic later.

@Musab1258 you're correct that I do have a general purpose library in mind for this feature, not something only for use in bdk-cli. But still good to keep in mind how it will be used in this cli project.

brh28 · 2026-04-30T15:48:37Z

+            })?;
+
+            for label in imported_labels.into_iter() {
+                add_or_update_label(labels, label);


To avoid incidental data loss, I would suggest adding an --override flag on import. If the flag is not provided, either the command fails, or only new labels are added

Musab1258 added 4 commits March 30, 2026 21:07

fix: resolve clippy warnings introduced by BIP-329 label feature

4dd8d9f

github-project-automation Bot added this to BDK-CLI Mar 31, 2026

brh28 reviewed Apr 29, 2026

View reviewed changes

brh28 reviewed Apr 30, 2026

View reviewed changes

Conversation

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

Uh oh!

Description

Notes to the reviewers

Changelog notice

Added

Checklists

All Submissions:

New Features:

Bugfixes:

Uh oh!

Musab1258 commented Mar 31, 2026

Uh oh!

Musab1258 commented Apr 4, 2026

Uh oh!

codecov Bot commented Apr 4, 2026

Codecov Report

Uh oh!

notmandatory commented Apr 22, 2026

Uh oh!

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

Uh oh!

Uh oh!

notmandatory commented Apr 26, 2026

Uh oh!

brh28 commented Apr 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Musab1258 commented Apr 29, 2026

Uh oh!

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

Uh oh!

Uh oh!

brh28 commented Apr 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

brh28 Apr 29, 2026

Choose a reason for hiding this comment

Uh oh!

notmandatory commented Apr 30, 2026

Uh oh!

notmandatory commented Apr 30, 2026

Uh oh!

brh28 Apr 30, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Musab1258 commented Mar 31, 2026 •

edited

Loading

Musab1258 commented Apr 23, 2026 •

edited

Loading

brh28 commented Apr 26, 2026 •

edited

Loading

Musab1258 commented Apr 29, 2026 •

edited

Loading

brh28 commented Apr 29, 2026 •

edited

Loading