# blockstream/lwk architecture

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

- Interactive diagram: https://gitdiagram.com/blockstream/lwk
- Repository: https://github.com/blockstream/lwk

## Overview

Liquid Wallet Kit is a Rust toolkit for building Liquid wallets and applications, rather than a single end-user wallet. A typical developer workflow defines a wallet from a descriptor, builds it, synchronizes wallet state from a chain service, then creates and signs transactions. The workspace also exposes app/RPC and language-binding entry points, hardware signers, swaps, payment instructions, asset registry and pricing, and Simplicity support. Edges below follow explicit imports or documented behavior; several major subsystems are represented from the tree and index without claiming their unsampled internals were inspected.

Main entry points: [`lwk_wollet/src/wollet.rs`](https://github.com/blockstream/lwk/blob/master/lwk_wollet/src/wollet.rs) (Watch-Only Wallet), [`lwk_wollet/src/elements_wallet.rs`](https://github.com/blockstream/lwk/blob/master/lwk_wollet/src/elements_wallet.rs) (Wallet Builder), [`lwk_app/src/lib.rs`](https://github.com/blockstream/lwk/blob/master/lwk_app/src/lib.rs) (App RPC Server), [`lwk_wollet/src/descriptor.rs`](https://github.com/blockstream/lwk/blob/master/lwk_wollet/src/descriptor.rs) (Wallet Descriptor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_wallet["Wallet Core"]
  node_descriptor["Wallet Descriptor<br/>[descriptor.rs]"]
  node_wallet_runtime["Watch-Only Wallet<br/>[wollet.rs]"]
  node_wallet_builder["Wallet Builder<br/>[elements_wallet.rs]"]
  node_chain_clients["Chain Clients"]
  node_wallet_sync["Wallet Updates<br/>[update.rs]"]
  node_tx_builder["Transaction Builder"]
  node_common["Shared Wallet Logic<br/>[lib.rs]"]
  node_persistence[("Wallet Persistence<br/>[store.rs]")]
end

subgraph group_interfaces["Developer Interfaces"]
  node_app_rpc["App RPC Server<br/>[lib.rs]"]
  node_rpc_methods["RPC Methods<br/>[method.rs]"]
  node_cli["Command Line<br/>[main.rs]"]
  node_wasm["WebAssembly API<br/>[lib.rs]"]
  node_bindings["Language Bindings<br/>[lib.rs]"]
end

subgraph group_signing["Signing Devices"]
  node_software_signer["Software Signer<br/>[software.rs]"]
  node_jade["Jade Signer<br/>[sign_liquid_tx.rs]"]
  node_ledger["Ledger Signer<br/>[client.rs]"]
end

subgraph group_services["Network Services"]
  node_boltz["Boltz Swaps<br/>[chain_swaps.rs]"]
  node_registry["Asset Registry<br/>[registry.rs]"]
  node_prices["Price Data<br/>[lib.rs]"]
end

subgraph group_domain["Payment and Contracts"]
  node_payments["Payment Instructions<br/>[lib.rs]"]
  node_simplicity["Simplicity Runtime<br/>[runner.rs]"]
end

node_developer(("Developer"))

node_developer -.->|"builds wallet"| node_wallet_builder
node_wallet_builder -->|"uses descriptor"| node_descriptor
node_wallet_builder -->|"builds"| node_wallet_runtime
node_wallet_runtime -->|"scans through"| node_chain_clients
node_wallet_runtime -->|"uses updates"| node_wallet_sync
node_wallet_runtime -->|"creates transactions"| node_tx_builder
node_wallet_runtime -->|"uses shared logic"| node_common
node_wallet_builder -->|"configures stores"| node_persistence
node_developer -.->|"calls RPC"| node_app_rpc
node_app_rpc -->|"dispatches methods"| node_rpc_methods
node_app_rpc -->|"wires wallet calls"| node_wallet_runtime
node_developer -.->|"runs commands"| node_cli
node_developer -.->|"uses API"| node_wasm
node_developer -.->|"uses bindings"| node_bindings
node_wallet_runtime -.->|"signs with"| node_software_signer
node_wallet_runtime -.->|"signs with"| node_jade
node_wallet_runtime -.->|"signs with"| node_ledger
node_developer -.->|"initiates swaps"| node_boltz
node_developer -.->|"queries assets"| node_registry
node_developer -.->|"queries prices"| node_prices
node_developer -.->|"parses payments"| node_payments
node_developer -.->|"runs programs"| node_simplicity

click node_descriptor "https://github.com/blockstream/lwk/blob/master/lwk_wollet/src/descriptor.rs"
click node_wallet_runtime "https://github.com/blockstream/lwk/blob/master/lwk_wollet/src/wollet.rs"
click node_wallet_builder "https://github.com/blockstream/lwk/blob/master/lwk_wollet/src/elements_wallet.rs"
click node_chain_clients "https://github.com/blockstream/lwk/tree/master/lwk_wollet/src/clients"
click node_wallet_sync "https://github.com/blockstream/lwk/blob/master/lwk_wollet/src/update.rs"
click node_tx_builder "https://github.com/blockstream/lwk/tree/master/lwk_wollet/src/tx_builder"
click node_common "https://github.com/blockstream/lwk/blob/master/lwk_common/src/lib.rs"
click node_app_rpc "https://github.com/blockstream/lwk/blob/master/lwk_app/src/lib.rs"
click node_rpc_methods "https://github.com/blockstream/lwk/blob/master/lwk_app/src/method.rs"
click node_cli "https://github.com/blockstream/lwk/blob/master/lwk_cli/src/main.rs"
click node_wasm "https://github.com/blockstream/lwk/blob/master/lwk_wasm/src/lib.rs"
click node_bindings "https://github.com/blockstream/lwk/blob/master/lwk_bindings/src/lib.rs"
click node_software_signer "https://github.com/blockstream/lwk/blob/master/lwk_signer/src/software.rs"
click node_jade "https://github.com/blockstream/lwk/blob/master/lwk_jade/src/sign_liquid_tx.rs"
click node_ledger "https://github.com/blockstream/lwk/blob/master/lwk_ledger/src/client.rs"
click node_boltz "https://github.com/blockstream/lwk/blob/master/lwk_boltz/src/chain_swaps.rs"
click node_registry "https://github.com/blockstream/lwk/blob/master/lwk_registry/src/registry.rs"
click node_prices "https://github.com/blockstream/lwk/blob/master/lwk_prices/src/lib.rs"
click node_payments "https://github.com/blockstream/lwk/blob/master/lwk_payment_instructions/src/lib.rs"
click node_simplicity "https://github.com/blockstream/lwk/blob/master/lwk_simplicity/src/runner.rs"
click node_persistence "https://github.com/blockstream/lwk/blob/master/lwk_common/src/store.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_descriptor,node_wallet_runtime,node_wallet_builder,node_chain_clients,node_wallet_sync,node_tx_builder,node_common,node_persistence toneBlue
class node_app_rpc,node_rpc_methods,node_cli,node_wasm,node_bindings toneAmber
class node_software_signer,node_jade,node_ledger toneMint
class node_boltz,node_registry,node_prices toneRose
class node_payments,node_simplicity,node_developer toneIndigo
```

## Components

### Wallet Core

- [Wallet Descriptor](https://github.com/blockstream/lwk/blob/master/lwk_wollet/src/descriptor.rs): `lwk_wollet/src/descriptor.rs`
- [Watch-Only Wallet](https://github.com/blockstream/lwk/blob/master/lwk_wollet/src/wollet.rs): `lwk_wollet/src/wollet.rs`
- [Wallet Builder](https://github.com/blockstream/lwk/blob/master/lwk_wollet/src/elements_wallet.rs): `lwk_wollet/src/elements_wallet.rs`
- [Chain Clients](https://github.com/blockstream/lwk/tree/master/lwk_wollet/src/clients): `lwk_wollet/src/clients`
- [Wallet Updates](https://github.com/blockstream/lwk/blob/master/lwk_wollet/src/update.rs): `lwk_wollet/src/update.rs`
- [Transaction Builder](https://github.com/blockstream/lwk/tree/master/lwk_wollet/src/tx_builder): `lwk_wollet/src/tx_builder`
- [Shared Wallet Logic](https://github.com/blockstream/lwk/blob/master/lwk_common/src/lib.rs): `lwk_common/src/lib.rs`
- [Wallet Persistence](https://github.com/blockstream/lwk/blob/master/lwk_common/src/store.rs): `lwk_common/src/store.rs`

### Developer Interfaces

- [App RPC Server](https://github.com/blockstream/lwk/blob/master/lwk_app/src/lib.rs): `lwk_app/src/lib.rs`
- [RPC Methods](https://github.com/blockstream/lwk/blob/master/lwk_app/src/method.rs): `lwk_app/src/method.rs`
- [Command Line](https://github.com/blockstream/lwk/blob/master/lwk_cli/src/main.rs): `lwk_cli/src/main.rs`
- [WebAssembly API](https://github.com/blockstream/lwk/blob/master/lwk_wasm/src/lib.rs): `lwk_wasm/src/lib.rs`
- [Language Bindings](https://github.com/blockstream/lwk/blob/master/lwk_bindings/src/lib.rs): `lwk_bindings/src/lib.rs`

### Signing Devices

- [Software Signer](https://github.com/blockstream/lwk/blob/master/lwk_signer/src/software.rs): `lwk_signer/src/software.rs`
- [Jade Signer](https://github.com/blockstream/lwk/blob/master/lwk_jade/src/sign_liquid_tx.rs): `lwk_jade/src/sign_liquid_tx.rs`
- [Ledger Signer](https://github.com/blockstream/lwk/blob/master/lwk_ledger/src/client.rs): `lwk_ledger/src/client.rs`

### Network Services

- [Boltz Swaps](https://github.com/blockstream/lwk/blob/master/lwk_boltz/src/chain_swaps.rs): `lwk_boltz/src/chain_swaps.rs`
- [Asset Registry](https://github.com/blockstream/lwk/blob/master/lwk_registry/src/registry.rs): `lwk_registry/src/registry.rs`
- [Price Data](https://github.com/blockstream/lwk/blob/master/lwk_prices/src/lib.rs): `lwk_prices/src/lib.rs`

### Payment and Contracts

- [Payment Instructions](https://github.com/blockstream/lwk/blob/master/lwk_payment_instructions/src/lib.rs): `lwk_payment_instructions/src/lib.rs`
- [Simplicity Runtime](https://github.com/blockstream/lwk/blob/master/lwk_simplicity/src/runner.rs): `lwk_simplicity/src/runner.rs`

### Other components

- **Developer**

## Connections

- Developer → Wallet Builder: builds wallet
- Wallet Builder → Wallet Descriptor: uses descriptor (evidence: `lwk_wollet/src/lib.rs`)
- Wallet Builder → Watch-Only Wallet: builds (evidence: `lwk_wollet/src/lib.rs`)
- Watch-Only Wallet → Chain Clients: scans through (evidence: `lwk_wollet/src/lib.rs`)
- Watch-Only Wallet → Wallet Updates: uses updates (evidence: `lwk_wollet/src/lib.rs`)
- Watch-Only Wallet → Transaction Builder: creates transactions (evidence: `lwk_wollet/src/lib.rs`)
- Watch-Only Wallet → Shared Wallet Logic: uses shared logic
- Wallet Builder → Wallet Persistence: configures stores
- Developer → App RPC Server: calls RPC
- App RPC Server → RPC Methods: dispatches methods (evidence: `lwk_app/src/lib.rs`)
- App RPC Server → Watch-Only Wallet: wires wallet calls (evidence: `lwk_app/src/lib.rs`)
- Developer → Command Line: runs commands
- Developer → WebAssembly API: uses API
- Developer → Language Bindings: uses bindings
- Watch-Only Wallet → Software Signer: signs with
- Watch-Only Wallet → Jade Signer: signs with
- Watch-Only Wallet → Ledger Signer: signs with
- Developer → Boltz Swaps: initiates swaps
- Developer → Asset Registry: queries assets
- Developer → Price Data: queries prices
- Developer → Payment Instructions: parses payments
- Developer → Simplicity Runtime: runs programs
