# The Bitcoin Dev Kit
-The `bdk` libraries aims to be the core building block for Bitcoin wallets of any kind.
+<div align="center">
+ <h1>BDK</h1>
-The Bitcoin Dev Kit developers are in the process of releasing `v1.0` which is a fundamental
-re-write of how the library works.
+ <img src="./static/bdk.png" width="220" />
-See for some background on this project: https://bitcoindevkit.org/blog/road-to-bdk-1/ (ignore the timeline 😁)
+ <p>
+ <strong>A modern, lightweight, descriptor-based wallet library written in Rust!</strong>
+ </p>
-For a release timeline see the [`bdk_core_staging`] repo where a lot of the component work is being done. The plan is that everything in the `bdk_core_staging` repo will be moved into the `crates` directory here.
+ <p>
+ <a href="https://crates.io/crates/bdk"><img alt="Crate Info" src="https://img.shields.io/crates/v/bdk.svg"/></a>
+ <a href="https://github.com/bitcoindevkit/bdk/blob/master/LICENSE"><img alt="MIT or Apache-2.0 Licensed" src="https://img.shields.io/badge/license-MIT%2FApache--2.0-blue.svg"/></a>
+ <a href="https://github.com/bitcoindevkit/bdk/actions?query=workflow%3ACI"><img alt="CI Status" src="https://github.com/bitcoindevkit/bdk/workflows/CI/badge.svg"></a>
+ <a href="https://coveralls.io/github/bitcoindevkit/bdk?branch=master"><img src="https://coveralls.io/repos/github/bitcoindevkit/bdk/badge.svg?branch=master"/></a>
+ <a href="https://docs.rs/bdk"><img alt="API Docs" src="https://img.shields.io/badge/docs.rs-bdk-green"/></a>
+ <a href="https://blog.rust-lang.org/2021/12/02/Rust-1.57.0.html"><img alt="Rustc Version 1.57.0+" src="https://img.shields.io/badge/rustc-1.57.0%2B-lightgrey.svg"/></a>
+ <a href="https://discord.gg/d7NkDKm"><img alt="Chat on Discord" src="https://img.shields.io/discord/753336465005608961?logo=discord"></a>
+ </p>
+ <h4>
+ <a href="https://bitcoindevkit.org">Project Homepage</a>
+ <span> | </span>
+ <a href="https://docs.rs/bdk">Documentation</a>
+ </h4>
+</div>
-[`bdk_core_staging`]: https://github.com/LLFourn/bdk_core_staging
+## About
+
+The `bdk` libraries aims to provide well engineered and reviewed components for Bitcoin based applications.
+It is built upon the excellent [`rust-bitcoin`] and [`rust-miniscript`] crates.
+> ⚠ The Bitcoin Dev Kit developers are in the process of releasing a `v1.0` which is a fundamental re-write of how the library works.
+> See for some background on this project: https://bitcoindevkit.org/blog/road-to-bdk-1/ (ignore the timeline 😁)
+> For a release timeline see the [`bdk_core_staging`] repo where a lot of the component work is being done. The plan is that everything in the `bdk_core_staging` repo will be moved into the `crates` directory here.
+## Architecture
+The project is split up into several crates in the `/crates` directory:
+- [`bdk`](./crates/bdk): Contains the central high level `Wallet` type that is built from the low-level mechanisms provided by the other components
+- [`chain`](./crates/chain): Tools for storing and indexing chain data
+- [`file_store`](./crates/file_store): A (experimental) persistence backend for storing chain data in a single file.
+- [`esplora`](./crates/esplora): Extends the [`esplora-client`] crate with methods to fetch chain data from an esplora HTTP server in the form that [`bdk_chain`] and `Wallet` can consume.
+- [`electrum`](./crates/electrum): Extends the [`electrum-client`] crate with methods to fetch chain data from an electrum server in the form that [`bdk_chain`] and `Wallet` can consume.
+Fully working examples of how to use these components are in `/example-crates`
+
+[`bdk_core_staging`]: https://github.com/LLFourn/bdk_core_staging
+[`rust-miniscript`]: https://github.com/rust-bitcoin/rust-miniscript
+[`rust-bitcoin`]: https://github.com/rust-bitcoin/rust-bitcoin
+[`esplora-client`]: https://docs.rs/esplora-client/0.3.0/esplora_client/
</h4>
</div>
-## About
+## `bdk`
-The `bdk` library aims to be the core building block for Bitcoin wallets of any kind.
+The `bdk` crate provides the `Wallet` type which provides a high level interface to most of the low level mechanisms included in `bdk`.
+`Wallet` is the appropriate starting point for many simple applications as well as a good demonstration of how to use the other mechanisms to construct a wallet.
+It's simple. It has an external and internal keychain which both defined by two [miniscript descriptors][`rust-miniscript`] and uses them to generate addresses.
+When you give it chain data it also uses the descriptors to find transaction outputs owned by them.
+From there you can create transactions to spend the funds and even sign them
+For more information see [`Wallet`'s documentation](https://docs.rs/bdk/latest/bdk/wallet/struct.Wallet.html).
-* It uses [Miniscript](https://github.com/rust-bitcoin/rust-miniscript) to support descriptors with generalized conditions. This exact same library can be used to build
- single-sig wallets, multisigs, timelocked contracts and more.
-* It supports multiple blockchain backends and databases, allowing developers to choose exactly what's right for their projects.
-* It's built to be cross-platform: the core logic works on desktop, mobile, and even WebAssembly.
-* It's very easy to extend: developers can implement customized logic for blockchain backends, databases, signers, coin selection, and more, without having to fork and modify this library.
+### Chain data
-<!-- ## Examples -->
+In order to get the chain data for `Wallet` to consume you have to put it into particular form.
+Right now this the [`KeychainScan`] which defined in `bdk_chain`.
+
+This can be created manually or from some of the chain data libraries provided in the `bdk` repo like [`bdk_esplora`] and [`bdk_electrum`].
+
+See [`example-crates`] for examples on how to do this.
+
+TODO: make a short `no_run` example here
<!-- ### Sync the balance of a descriptor -->
<!-- Ok(()) -->
<!-- } -->
<!-- ``` -->
-
<!-- ### Generate a few addresses -->
<!-- ```rust -->
cargo test
```
-## Running under WASM
-
-If you want to run this library under WASM you will probably have to add the following lines to you `Cargo.toml`:
-
-```toml
-[dependencies]
-getrandom = { version = "0.2", features = ["js"] }
-```
-
-This enables the `rand` crate to work in environments where JavaScript is available. See [this link](https://docs.rs/getrandom/0.2.8/getrandom/#webassembly-support) to learn more.
-
## License
Licensed under either of
* Apache License, Version 2.0
- ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
+ ([LICENSE-APACHE](LICENSE-APACHE) or <https://www.apache.org/licenses/LICENSE-2.0>)
* MIT license
- ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
+ ([LICENSE-MIT](LICENSE-MIT) or <https://opensource.org/licenses/MIT>)
at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
dual licensed as above, without any additional terms or conditions.
+
+[`bdk_chain`]: https://docs.rs/bdk_chain/latest
+[`bdk_electrum`]: https://docs.rs/bdk_electrum/latest
+[`bdk_esplora`]: https://docs.rs/bdk_esplora/latest
+[`KeychainScan`]: https://docs.rs/bdk_chain/latest/bdk_chain/keychain/struct.KeychainScan.html
+[`rust-miniscript`]: https://docs.rs/miniscript/latest/miniscript/index.html
+++ /dev/null
-// Bitcoin Dev Kit
-// Written in 2020 by Alekos Filini <alekos.filini@gmail.com>
-//
-// Copyright (c) 2020-2021 Bitcoin Dev Kit Developers
-//
-// This file is licensed under the Apache License, Version 2.0 <LICENSE-APACHE
-// or http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
-// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your option.
-// You may not use this file except in accordance with one or both of these
-// licenses.
-
-#[doc = include_str!("../README.md")]
-#[cfg(doctest)]
-pub struct ReadmeDoctests;
-// Bitcoin Dev Kit
-// Written in 2020 by Alekos Filini <alekos.filini@gmail.com>
-//
-// Copyright (c) 2020-2021 Bitcoin Dev Kit Developers
-//
-// This file is licensed under the Apache License, Version 2.0 <LICENSE-APACHE
-// or http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
-// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your option.
-// You may not use this file except in accordance with one or both of these
-// licenses.
-//
-// rustdoc will warn if there are missing docs
-#![warn(missing_docs)]
-// only enables the `doc_cfg` feature when
-// the `docsrs` configuration attribute is defined
-#![cfg_attr(docsrs, feature(doc_cfg))]
-#![cfg_attr(
- docsrs,
- doc(html_logo_url = "https://github.com/bitcoindevkit/bdk/raw/master/static/bdk.png")
-)]
-
-//! A modern, lightweight, descriptor-based wallet library written in Rust.
-//!
-//! # About
-//!
-//! The BDK library aims to be the core building block for Bitcoin wallets of any kind.
-//!
-//! * It uses [Miniscript](https://github.com/rust-bitcoin/rust-miniscript) to support descriptors with generalized conditions. This exact same library can be used to build
-//! single-sig wallets, multisigs, timelocked contracts and more.
-//! * It supports multiple blockchain backends and databases, allowing developers to choose exactly what's right for their projects.
-//! * It is built to be cross-platform: the core logic works on desktop, mobile, and even WebAssembly.
-//! * It is very easy to extend: developers can implement customized logic for blockchain backends, databases, signers, coin selection, and more, without having to fork and modify this library.
-//!
-//! ## Generate a few addresses
-//!
-//! ### Example
-//! ```
-//! use bdk::{Wallet};
-//! use bdk::wallet::AddressIndex::New;
-//!
-//! fn main() -> Result<(), bdk::Error> {
-//! let mut wallet = Wallet::new_no_persist(
-//! "wpkh([c258d2e4/84h/1h/0h]tpubDDYkZojQFQjht8Tm4jsS3iuEmKjTiEGjG6KnuFNKKJb5A6ZUCUZKdvLdSDWofKi4ToRCwb9poe1XdqfUnP4jaJjCB2Zwv11ZLgSbnZSNecE/0/*)",
-//! Some("wpkh([c258d2e4/84h/1h/0h]tpubDDYkZojQFQjht8Tm4jsS3iuEmKjTiEGjG6KnuFNKKJb5A6ZUCUZKdvLdSDWofKi4ToRCwb9poe1XdqfUnP4jaJjCB2Zwv11ZLgSbnZSNecE/1/*)"),
-//! bitcoin::Network::Testnet,
-//! )?;
-//!
-//! println!("Address #0: {}", wallet.get_address(New));
-//! println!("Address #1: {}", wallet.get_address(New));
-//! println!("Address #2: {}", wallet.get_address(New));
-//!
-//! Ok(())
-//! }
-//! ```
-//! ## Sign a transaction
-//!
-//! ```no_run
-//! use core::str::FromStr;
-//!
-//! use bitcoin::util::psbt::PartiallySignedTransaction as Psbt;
-//!
-//! use bdk::{Wallet, SignOptions};
-//!
-//! fn main() -> Result<(), bdk::Error> {
-//! let wallet = Wallet::new_no_persist(
-//! "wpkh([c258d2e4/84h/1h/0h]tprv8griRPhA7342zfRyB6CqeKF8CJDXYu5pgnj1cjL1u2ngKcJha5jjTRimG82ABzJQ4MQe71CV54xfn25BbhCNfEGGJZnxvCDQCd6JkbvxW6h/0/*)",
-//! Some("wpkh([c258d2e4/84h/1h/0h]tprv8griRPhA7342zfRyB6CqeKF8CJDXYu5pgnj1cjL1u2ngKcJha5jjTRimG82ABzJQ4MQe71CV54xfn25BbhCNfEGGJZnxvCDQCd6JkbvxW6h/1/*)"),
-//! bitcoin::Network::Testnet,
-//! )?;
-//!
-//! let psbt = "...";
-//! let mut psbt = Psbt::from_str(psbt)?;
-//!
-//! let finalized = wallet.sign(&mut psbt, SignOptions::default())?;
-//!
-//! Ok(())
-//! }
-//! ```
-//!
-//! # Feature flags
-//!
-//! BDK uses a set of [feature flags](https://doc.rust-lang.org/cargo/reference/manifest.html#the-features-section)
-//! to reduce the amount of compiled code by allowing projects to only enable the features they need.
-//! By default, BDK enables two internal features, `key-value-db` and `electrum`.
-//!
-//! If you are new to BDK we recommended that you use the default features which will enable
-//! basic descriptor wallet functionality. More advanced users can disable the `default` features
-//! (`--no-default-features`) and build the BDK library with only the features you need.
-
-//! Below is a list of the available feature flags and the additional functionality they provide.
-//!
-//! * `all-keys`: all features for working with bitcoin keys
-//! * `async-interface`: async functions in bdk traits
-//! * `keys-bip39`: [BIP-39](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki) mnemonic codes for generating deterministic keys
-
+#![doc = include_str!("../README.md")]
#![no_std]
#[cfg(feature = "std")]
#[macro_use]
#[macro_use]
pub(crate) mod error;
pub mod descriptor;
-#[cfg(feature = "test-md-docs")]
-mod doctest;
pub mod keys;
pub mod psbt;
pub(crate) mod types;
projects / bdk / commitdiff