# bitcoindevkit/bdk_wallet architecture

> Architecture diagram of the GitHub repository bitcoindevkit/bdk_wallet, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bitcoindevkit/bdk_wallet
- Repository: https://github.com/bitcoindevkit/bdk_wallet

## Overview

BDK is a Rust descriptor-based Bitcoin wallet library. An application configures descriptors and keys, creates a Wallet, supplies chain data, derives addresses and wallet state, builds and signs transactions, and persists changes. The graph preserves documented chain-source and storage integrations as external optional services. Source excerpts and the index support several internal calls; links based only on README-level capability descriptions are cited there. Some implementation details, especially chain-data ingestion and persistence adapters, were not sampled.

Main entry points: [`src/wallet/mod.rs`](https://github.com/bitcoindevkit/bdk_wallet/blob/master/src/wallet/mod.rs) (Wallet API), [`src/descriptor/mod.rs`](https://github.com/bitcoindevkit/bdk_wallet/blob/master/src/descriptor/mod.rs) (Descriptor handling), [`src/wallet/tx_builder.rs`](https://github.com/bitcoindevkit/bdk_wallet/blob/master/src/wallet/tx_builder.rs) (Transaction builder), [`src/wallet/changeset.rs`](https://github.com/bitcoindevkit/bdk_wallet/blob/master/src/wallet/changeset.rs) (Wallet changes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_wallet["Wallet state"]
  node_wallet["Wallet API<br/>[mod.rs]"]
  node_wallet_params["Wallet setup<br/>[params.rs]"]
  node_wallet_types["Wallet output types<br/>[types.rs]"]
end

subgraph group_descriptor["Descriptors and keys"]
  node_descriptor["Descriptor handling<br/>[mod.rs]"]
  node_descriptor_dsl["Descriptor DSL<br/>[dsl.rs]"]
  node_descriptor_templates["Descriptor templates<br/>[template.rs]"]
  node_descriptor_policy["Spending policies<br/>[policy.rs]"]
  node_descriptor_checksum["Descriptor checksums<br/>[checksum.rs]"]
  node_keys["Key handling<br/>[mod.rs]"]
  node_bip39["Mnemonic keys<br/>[bip39.rs]"]
end

subgraph group_transactions["Transaction lifecycle"]
  node_tx_builder["Transaction builder<br/>[tx_builder.rs]"]
  node_coin_selection["Coin selection<br/>[coin_selection.rs]"]
  node_psbt["PSBT utilities<br/>[mod.rs]"]
  node_psbt_params["PSBT parameters<br/>[params.rs]"]
  node_signer["Transaction signing<br/>[signer.rs]"]
end

subgraph group_state["Persistence and events"]
  node_changeset["Wallet changes<br/>[changeset.rs]"]
  node_persisted_wallet["Persisted wallet<br/>[persisted.rs]"]
  node_migration["Wallet migration<br/>[migration.rs]"]
  node_events["Wallet events<br/>[event.rs]"]
  node_export["Wallet export<br/>[export.rs]"]
end

node_app(("Bitcoin application"))
node_chain_sources["Chain source clients"]
node_storage[("External storage")]

node_app -->|"configures"| node_wallet_params
node_wallet_params -->|"creates"| node_wallet
node_wallet -->|"uses"| node_descriptor
node_descriptor_dsl -->|"constructs"| node_descriptor
node_descriptor_templates -->|"builds"| node_descriptor
node_descriptor -->|"uses"| node_keys
node_bip39 -->|"derives"| node_keys
node_descriptor -->|"checks"| node_descriptor_checksum
node_wallet -->|"extracts policy"| node_descriptor_policy
node_wallet -.->|"consumes chain data"| node_chain_sources
node_wallet -->|"tracks outputs"| node_wallet_types
node_app -->|"requests addresses"| node_wallet
node_app -->|"builds transactions"| node_tx_builder
node_tx_builder -->|"selects inputs"| node_coin_selection
node_tx_builder -->|"uses descriptors"| node_descriptor
node_tx_builder -->|"creates PSBT"| node_psbt
node_psbt -->|"exposes parameters"| node_psbt_params
node_app -->|"signs transactions"| node_signer
node_wallet -->|"uses signers"| node_signer
node_wallet -->|"records changes"| node_changeset
node_wallet -->|"emits events"| node_events
node_wallet -->|"exports wallet"| node_export
node_wallet -.->|"supports migration"| node_migration
node_app -->|"loads or saves"| node_persisted_wallet
node_persisted_wallet -.->|"persists"| node_changeset
node_app -->|"configures storage"| node_storage
node_storage -->|"reads and writes"| node_changeset

click node_wallet "https://github.com/bitcoindevkit/bdk_wallet/blob/master/src/wallet/mod.rs"
click node_wallet_params "https://github.com/bitcoindevkit/bdk_wallet/blob/master/src/wallet/params.rs"
click node_descriptor "https://github.com/bitcoindevkit/bdk_wallet/blob/master/src/descriptor/mod.rs"
click node_descriptor_dsl "https://github.com/bitcoindevkit/bdk_wallet/blob/master/src/descriptor/dsl.rs"
click node_descriptor_templates "https://github.com/bitcoindevkit/bdk_wallet/blob/master/src/descriptor/template.rs"
click node_descriptor_policy "https://github.com/bitcoindevkit/bdk_wallet/blob/master/src/descriptor/policy.rs"
click node_descriptor_checksum "https://github.com/bitcoindevkit/bdk_wallet/blob/master/src/descriptor/checksum.rs"
click node_keys "https://github.com/bitcoindevkit/bdk_wallet/blob/master/src/keys/mod.rs"
click node_bip39 "https://github.com/bitcoindevkit/bdk_wallet/blob/master/src/keys/bip39.rs"
click node_tx_builder "https://github.com/bitcoindevkit/bdk_wallet/blob/master/src/wallet/tx_builder.rs"
click node_coin_selection "https://github.com/bitcoindevkit/bdk_wallet/blob/master/src/wallet/coin_selection.rs"
click node_psbt "https://github.com/bitcoindevkit/bdk_wallet/blob/master/src/psbt/mod.rs"
click node_psbt_params "https://github.com/bitcoindevkit/bdk_wallet/blob/master/src/psbt/params.rs"
click node_signer "https://github.com/bitcoindevkit/bdk_wallet/blob/master/src/wallet/signer.rs"
click node_wallet_types "https://github.com/bitcoindevkit/bdk_wallet/blob/master/src/types.rs"
click node_changeset "https://github.com/bitcoindevkit/bdk_wallet/blob/master/src/wallet/changeset.rs"
click node_persisted_wallet "https://github.com/bitcoindevkit/bdk_wallet/blob/master/src/wallet/persisted.rs"
click node_migration "https://github.com/bitcoindevkit/bdk_wallet/blob/master/src/wallet/migration.rs"
click node_events "https://github.com/bitcoindevkit/bdk_wallet/blob/master/src/wallet/event.rs"
click node_export "https://github.com/bitcoindevkit/bdk_wallet/blob/master/src/wallet/export.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_wallet,node_wallet_params,node_wallet_types,node_chain_sources toneBlue
class node_descriptor,node_descriptor_dsl,node_descriptor_templates,node_descriptor_policy,node_descriptor_checksum,node_keys,node_bip39,node_storage toneAmber
class node_tx_builder,node_coin_selection,node_psbt,node_psbt_params,node_signer toneMint
class node_changeset,node_persisted_wallet,node_migration,node_events,node_export toneRose
class node_app toneIndigo
```

## Components

### Wallet state

- [Wallet API](https://github.com/bitcoindevkit/bdk_wallet/blob/master/src/wallet/mod.rs): `src/wallet/mod.rs`
- [Wallet setup](https://github.com/bitcoindevkit/bdk_wallet/blob/master/src/wallet/params.rs): `src/wallet/params.rs`
- [Wallet output types](https://github.com/bitcoindevkit/bdk_wallet/blob/master/src/types.rs): `src/types.rs`

### Descriptors and keys

- [Descriptor handling](https://github.com/bitcoindevkit/bdk_wallet/blob/master/src/descriptor/mod.rs): `src/descriptor/mod.rs`
- [Descriptor DSL](https://github.com/bitcoindevkit/bdk_wallet/blob/master/src/descriptor/dsl.rs): `src/descriptor/dsl.rs`
- [Descriptor templates](https://github.com/bitcoindevkit/bdk_wallet/blob/master/src/descriptor/template.rs): `src/descriptor/template.rs`
- [Spending policies](https://github.com/bitcoindevkit/bdk_wallet/blob/master/src/descriptor/policy.rs): `src/descriptor/policy.rs`
- [Descriptor checksums](https://github.com/bitcoindevkit/bdk_wallet/blob/master/src/descriptor/checksum.rs): `src/descriptor/checksum.rs`
- [Key handling](https://github.com/bitcoindevkit/bdk_wallet/blob/master/src/keys/mod.rs): `src/keys/mod.rs`
- [Mnemonic keys](https://github.com/bitcoindevkit/bdk_wallet/blob/master/src/keys/bip39.rs): `src/keys/bip39.rs`

### Transaction lifecycle

- [Transaction builder](https://github.com/bitcoindevkit/bdk_wallet/blob/master/src/wallet/tx_builder.rs): `src/wallet/tx_builder.rs`
- [Coin selection](https://github.com/bitcoindevkit/bdk_wallet/blob/master/src/wallet/coin_selection.rs): `src/wallet/coin_selection.rs`
- [PSBT utilities](https://github.com/bitcoindevkit/bdk_wallet/blob/master/src/psbt/mod.rs): `src/psbt/mod.rs`
- [PSBT parameters](https://github.com/bitcoindevkit/bdk_wallet/blob/master/src/psbt/params.rs): `src/psbt/params.rs`
- [Transaction signing](https://github.com/bitcoindevkit/bdk_wallet/blob/master/src/wallet/signer.rs): `src/wallet/signer.rs`

### Persistence and events

- [Wallet changes](https://github.com/bitcoindevkit/bdk_wallet/blob/master/src/wallet/changeset.rs): `src/wallet/changeset.rs`
- [Persisted wallet](https://github.com/bitcoindevkit/bdk_wallet/blob/master/src/wallet/persisted.rs): `src/wallet/persisted.rs`
- [Wallet migration](https://github.com/bitcoindevkit/bdk_wallet/blob/master/src/wallet/migration.rs): `src/wallet/migration.rs`
- [Wallet events](https://github.com/bitcoindevkit/bdk_wallet/blob/master/src/wallet/event.rs): `src/wallet/event.rs`
- [Wallet export](https://github.com/bitcoindevkit/bdk_wallet/blob/master/src/wallet/export.rs): `src/wallet/export.rs`

### Other components

- **Bitcoin application**
- **Chain source clients**
- **External storage**

## Connections

- Bitcoin application → Wallet setup: configures (evidence: `README.md`)
- Wallet setup → Wallet API: creates (evidence: `README.md`)
- Wallet API → Descriptor handling: uses (evidence: `src/wallet/mod.rs`)
- Descriptor DSL → Descriptor handling: constructs (evidence: `src/descriptor/dsl.rs`)
- Descriptor templates → Descriptor handling: builds (evidence: `src/descriptor/template.rs`)
- Descriptor handling → Key handling: uses (evidence: `src/descriptor/mod.rs`)
- Mnemonic keys → Key handling: derives (evidence: `src/keys/bip39.rs`)
- Descriptor handling → Descriptor checksums: checks (evidence: `src/descriptor/checksum.rs`)
- Wallet API → Spending policies: extracts policy (evidence: `src/wallet/mod.rs`)
- Wallet API → Chain source clients: consumes chain data (evidence: `README.md`)
- Wallet API → Wallet output types: tracks outputs (evidence: `src/wallet/mod.rs`)
- Bitcoin application → Wallet API: requests addresses (evidence: `README.md`)
- Bitcoin application → Transaction builder: builds transactions (evidence: `README.md`)
- Transaction builder → Coin selection: selects inputs (evidence: `src/wallet/tx_builder.rs`)
- Transaction builder → Descriptor handling: uses descriptors (evidence: `src/wallet/tx_builder.rs`)
- Transaction builder → PSBT utilities: creates PSBT (evidence: `src/wallet/mod.rs`)
- PSBT utilities → PSBT parameters: exposes parameters (evidence: `src/psbt/mod.rs`)
- Bitcoin application → Transaction signing: signs transactions (evidence: `README.md`)
- Wallet API → Transaction signing: uses signers (evidence: `src/descriptor/mod.rs`)
- Wallet API → Wallet changes: records changes (evidence: `src/wallet/mod.rs`)
- Wallet API → Wallet events: emits events (evidence: `src/wallet/event.rs`)
- Wallet API → Wallet export: exports wallet (evidence: `src/wallet/export.rs`)
- Wallet API → Wallet migration: supports migration (evidence: `src/wallet/mod.rs`)
- Bitcoin application → Persisted wallet: loads or saves (evidence: `README.md`)
- Persisted wallet → Wallet changes: persists
- Bitcoin application → External storage: configures storage (evidence: `README.md`)
- External storage → Wallet changes: reads and writes (evidence: `README.md`)