Skip to content

Feat: Add bip329 wallet labels#266

Open
Musab1258 wants to merge 4 commits intobitcoindevkit:masterfrom
Musab1258:feat/add-bip329-wallet-labels
Open

Feat: Add bip329 wallet labels#266
Musab1258 wants to merge 4 commits intobitcoindevkit:masterfrom
Musab1258:feat/add-bip329-wallet-labels

Conversation

@Musab1258
Copy link
Copy Markdown

@Musab1258 Musab1258 commented Mar 31, 2026

Description

This PR adds BIP-329 wallet label support to bdk-cli, to partially address issue #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.

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.

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::*.
  • Import and export of existing BIP-329 label files are intentionally out of the scope of this PR and will be addressed in a follow-up PR.

Changelog notice

Added

  • New label subcommand to OfflineWalletSubCommand for tagging transactions, addresses, and UTXOs with human-readable labels.
  • 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
Copy link
Copy Markdown
Author

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: No status

Development

Successfully merging this pull request may close these issues.

1 participant