bdk_labels/
lib.rs

1//! # bdk-labels
2//!
3//! A Rust library providing native BIP-329 (Wallet Labels Export Format) support
4//! for the Bitcoin Dev Kit (BDK) ecosystem.
5//!
6//! This crate extends `bdk_wallet::Wallet` to allow developers to label transactions,
7//! addresses, UTXOs, and public keys with human-readable labels. It provides a
8//! deterministic, `BTreeMap`-backed memory structure (`LabelChangeset`) and a decoupled
9//! persistence trait (`LabelPersister`) for seamless integration with any database backend.
10
11pub mod changeset;
12pub mod error;
13pub mod extension;
14pub mod io;
15pub mod persist;
16
17pub use changeset::{LabelChangeset, MergeStrategy};
18pub use error::Error;
19pub use extension::*;
20pub use io::{export, import};
21pub use persist::LabelPersister;
22
23use bip329::Label;
24use bitcoin::address::NetworkUnchecked;
25use bitcoin::bip32::Xpub;
26use bitcoin::{Address, OutPoint, PublicKey, Txid};
27use std::io::{BufRead, Write};
28
29/// A wrapper type for targeting a specific transaction output (UTXO).
30pub struct OutputTarget(pub OutPoint);
31
32/// A wrapper type for targeting a specific transaction input.
33pub struct InputTarget(pub OutPoint);
34
35/// Represents the various Bitcoin primitives that can be tagged with a BIP-329 label.
36pub enum LabelTarget {
37    Txid(Txid),
38    Address(Address<NetworkUnchecked>),
39    PublicKey(String),
40    Input(OutPoint),
41    Output(OutPoint),
42    Xpub(String),
43}
44
45impl From<Txid> for LabelTarget {
46    fn from(txid: Txid) -> Self {
47        LabelTarget::Txid(txid)
48    }
49}
50
51impl From<Address<NetworkUnchecked>> for LabelTarget {
52    fn from(addr: Address<NetworkUnchecked>) -> Self {
53        LabelTarget::Address(addr)
54    }
55}
56
57impl From<PublicKey> for LabelTarget {
58    fn from(pk: PublicKey) -> Self {
59        LabelTarget::PublicKey(pk.to_string())
60    }
61}
62
63impl From<InputTarget> for LabelTarget {
64    fn from(input: InputTarget) -> Self {
65        LabelTarget::Input(input.0)
66    }
67}
68
69impl From<OutputTarget> for LabelTarget {
70    fn from(output: OutputTarget) -> Self {
71        LabelTarget::Output(output.0)
72    }
73}
74
75impl From<Xpub> for LabelTarget {
76    fn from(xp: Xpub) -> Self {
77        LabelTarget::Xpub(xp.to_string())
78    }
79}
80
81/// The core trait providing BIP-329 operations for a wallet.
82pub trait Bip329 {
83    /// Adds a new human-readable label to a specified target (e.g., Address, Txid).
84    fn add_label(
85        &mut self,
86        target: impl Into<LabelTarget>,
87        label_text: impl Into<String>,
88    ) -> Result<Label, Error>;
89
90    /// Imports labels from a BIP-329 compliant JSONL stream and merges them with the current state.
91    fn import_labels<R: BufRead>(
92        &mut self,
93        reader: R,
94        strategy: MergeStrategy,
95    ) -> Result<(), Error>;
96
97    /// Exports the current label state deterministically to a writable stream in BIP-329 JSONL format.
98    fn export_labels<W: Write>(&self, writer: W) -> Result<(), Error>;
99}
bdk_labels/lib.rs

bdk_labels/
lib.rs
