bitcoindevkit / bitcoindevkit/bdk_wallet
Privacy vulnerability detection for BDK wallets
- Dominant language
- Rust
- Stars
- 59
- Forks
- 105
- Avg merge
- 10d 9h
- Merged PRs (30d)
- 1
Description
**Describe the enhancement**
Today, a developer building a wallet with `bdk_wallet` has no way to detect or surface privacy leaks in a user's transaction history — address reuse, common input ownership (CIOH), identifiable change outputs, dust attacks, script type mixing, and more. Users accumulate privacy debt silently, and by the time they notice, the damage is on-chain and permanent.
BDK already ships preventive measures — shuffled ordering, anti-fee-sniping, signature grinding (#28) — but prevention alone isn't enough. Users need to **see** what's already exposed.
We've built [Stealth](https://github.com/stealth-bitcoin/stealth), a Rust privacy analysis engine that detects these leaks. We'd like to discuss making it available to `bdk_wallet` users — either as a crate under `bitcoindevkit/` or as an external crate that depends on `bdk_wallet`.
Stealth currently implements 12 detectors:
| Detector | What it catches |
|---|---|
| ADDRESS_REUSE | Addresses receiving multiple transactions |
| CIOH | Multiple wallet inputs spent together, revealing common ownership |
| CHANGE_DETECTION | Change outputs identifiable via round amounts, script type, or BIP-44 path |
| DUST / DUST_SPENDING | Tiny UTXOs used to track spending behavior |
| SCRIPT_TYPE_MIXING | Transactions mixing P2PKH, P2WPKH, P2TR, etc. |
| CONSOLIDATION | Multi-input consolidations that link UTXOs |
| CLUSTER_MERGE | Merging UTXOs from unrelated funding chains |
| UTXO_AGE_SPREAD | Spending old and new coins together (timing correlation) |
| EXCHANGE_ORIGIN | Outputs from exchange batch withdrawals |
| TAINTED_UTXO_MERGE | Mixing risky and clean inputs |
| BEHAVIORAL_FINGERPRINT | Repeated patterns in amounts, fees, RBF, locktime |
Each finding includes severity (Low/Medium/High/Critical), description, contextual details, and a correction suggestion. All thresholds are configurable and detectors can be individually toggled.
**Use case**
A wallet developer using `bdk_wallet` wants to show users a privacy health score, flag risky UTXOs before spending, or warn "this transaction will reveal you own these 3 addresses." Today they'd have to build all of this from scratch.
With a privacy analysis crate, it could look like:
```rust
use bdk_privacy::PrivacyAnalyzer;
let analyzer = PrivacyAnalyzer::default();
let report = analyzer.analyze(&wallet);
// "You have 3 critical findings, 5 warnings"
show_privacy_score(&report.summary);
// "Address bc1q...xyz has been reused 4 times"
// "Transaction abc...def merged UTXOs from unrelated sources"
for finding in &report.findings {
show_finding(finding);
}
```
No extra infrastructure. No RPC calls. Just pass a `&Wallet` and get a structured report. Every BDK-based wallet gets privacy analysis for free.
We've looked at `bdk_wallet`'s public API and the data needed is already there:
- `wallet.transactions()` — full transaction history with inputs/outputs
- `LocalOutput.keychain` — change vs receive classification (critical for change detection)
- `wallet.is_mine()` / `wallet.derivation_of_spk()` — script ownership
- `wallet.list_output()` — spent + unspent UTXOs
- `wallet.tx_graph().walk_ancestors()` — transaction graph traversal
- `wallet.calculate_fee_rate()` — fee analysis
The only gap is **counterparty transactions** — detecting things like cluster merge or exchange origin requires transactions beyond the wallet's own scripts. We currently fetch these via Bitcoin Core RPC. We'd like to discuss the best pattern for this within BDK's architecture.
**Impact**
- [x] Nice-to-have / UX improvement
**Are you using BDK in a production project?**
- [x] Not yet, but planning to
**Which backend(s) are relevant (if any)?**
- [x] Bitcoin Core RPC
- [x] None / not backend-related (e.g. `bdk_chain`, `bdk_core`)
**Project or organization (optional)**
[Stealth](https://github.com/stealth-bitcoin/stealth) — open source Bitcoin privacy analysis tool (MIT licensed).
**Additional context**
This proposal follows a conversation with @oleonardolima who suggested opening this issue to discuss whether it fits best under `bitcoindevkit/` or as an external crate.
We're also exploring how a privacy-aware `BnbMetric` for [`coin-select`](https://github.com/bitcoindevkit/coin-select) could complement detection with prevention — penalizing coin selections that create CIOH or change detection vulnerabilities.
We're ready to do the work — we just want to align on the right home for it.
Contributor guide
Assessment
This issue has not been assessed yet.