diff --git a/README.md b/README.md index b34a26fe..e6220de4 100644 --- a/README.md +++ b/README.md @@ -1,18 +1,53 @@ # The Bitcoin Dev Kit -The `bdk` libraries aims to be the core building block for Bitcoin wallets of any kind. +
+

BDK

-The Bitcoin Dev Kit developers are in the process of releasing `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 😁) +

+ A modern, lightweight, descriptor-based wallet library written in Rust! +

-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. +

+ Crate Info + MIT or Apache-2.0 Licensed + CI Status + + API Docs + Rustc Version 1.57.0+ + Chat on Discord +

+

+ Project Homepage + | + Documentation +

+
+ +## 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/ diff --git a/crates/bdk/README.md b/crates/bdk/README.md index 9531f1cd..2eb839d8 100644 --- a/crates/bdk/README.md +++ b/crates/bdk/README.md @@ -24,17 +24,25 @@ -## 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 - +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 @@ -60,7 +68,6 @@ The `bdk` library aims to be the core building block for Bitcoin wallets of any - @@ -157,25 +164,14 @@ The `bdk` library aims to be the core building block for Bitcoin wallets of any 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 ) * MIT license - ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT) + ([LICENSE-MIT](LICENSE-MIT) or ) at your option. @@ -184,3 +180,9 @@ 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 diff --git a/crates/bdk/src/doctest.rs b/crates/bdk/src/doctest.rs deleted file mode 100644 index 6c1f772c..00000000 --- a/crates/bdk/src/doctest.rs +++ /dev/null @@ -1,14 +0,0 @@ -// Bitcoin Dev Kit -// Written in 2020 by Alekos Filini -// -// Copyright (c) 2020-2021 Bitcoin Dev Kit Developers -// -// This file is licensed under the Apache License, Version 2.0 or the MIT license -// , 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; diff --git a/crates/bdk/src/lib.rs b/crates/bdk/src/lib.rs index e48d3561..19aa5540 100644 --- a/crates/bdk/src/lib.rs +++ b/crates/bdk/src/lib.rs @@ -1,98 +1,4 @@ -// Bitcoin Dev Kit -// Written in 2020 by Alekos Filini -// -// Copyright (c) 2020-2021 Bitcoin Dev Kit Developers -// -// This file is licensed under the Apache License, Version 2.0 or the MIT license -// , 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] @@ -117,8 +23,6 @@ extern crate bip39; #[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;