# Bitcoin standards implementation libraries ![Build](https://github.com/BP-WG/bp-std/workflows/Build/badge.svg) ![Tests](https://github.com/BP-WG/bp-std/workflows/Tests/badge.svg) ![Lints](https://github.com/BP-WG/bp-std/workflows/Lints/badge.svg) [![codecov](https://codecov.io/gh/BP-WG/bp-std/branch/master/graph/badge.svg)](https://codecov.io/gh/BP-WG/bp-std) [![crates.io](https://img.shields.io/crates/v/bp-std)](https://crates.io/crates/bp-std) [![Docs](https://docs.rs/bp-std/badge.svg)](https://docs.rs/bp-std) [![Apache-2 licensed](https://img.shields.io/crates/l/bp-std)](./LICENSE) Modern, minimalistic & standard-compliant wallet-level libraries: an alternative to `rust-bitcoin` and BDK libraries from [LNP/BP Standards Association][Assoc]. The main goals of the libraries are: - **fast stabilization of APIs**: the library will be targeting v1.0 version within the first year of its development; which should enable downstream crates using the library also to stabilize and not spend too much effort on changing the integration each time the new version of `bp-wallet` is released; - **no use of private keys**: the library analyzes wallet state using descriptors and allows to produce unsigned PSBTs, as well as publish and analyze (partially) signed PSBTs - but doesn't provide a signer or a way to work with any private key material (seeds, mnemonics, xprivs, private keys); PSBT files must be signed with some external signers or hardware wallets; - **standard-compliance**: the library tries to provide full compliance with existing bitcoin standards defined in BIPs and do not use any legacy approaches or "blockchain-not-bitcoin" practices (like the ones provided by BLIPs); - **separation of bitcoin consensus and standards**: the consensus-related code is not a part of this library; all data structures and business logic which may have consensus meaning and is required for a wallet is separated into an independent [`bp-primitives`] library (a part of [`bp-core`] library), which is planned to be more extensively audited and ossified alongside bitcoin protocol (while this library will continue to evolve with better APIs and to match new wallet standards); - **extensive use of descriptors**: library focuses on defining all parts of a wallet using descriptors; additionally to script pubkey descriptors it also supports xpub descriptors, derivation descriptors, applied to script pubkey descriptor as a whole, and input descriptors for RBFs. You can read more on specific descriptor types in the [section below](#descriptors); - **script templates**: the library allows to provide an arbitrary script as a part of a descriptor, which allows support for BOLT lightning channel transaction and makes it possible to ensure stability in the long run; you can read more about script templates vs miniscript below; - **opinionated high-level wallet abstractions**: the library provide a set of high-level wallet data structures abstracting away blockchain-level details; helping in writing less boilerplate business logic; - **APIs usable in all rust projects and in FFI**: the library doesn't use async rust, complex callbacks, threads etc., which allows to keep the API simple, usable from any rust app (like ones using reactive patterns instead of async); at the same time all the data structures of the library are `Send + Sync`, meaning that they can be used in any multi-thread or async environment; - **abstracted blockchain data providers**: the library abstracts blockchain indexer APIs (Electrum, Esplora, Bitcoin Core etc.) and also provides their implementation using this library structures. ## FAQs ### Why not use `rust-bitcoin`? The library doesn't rely on `rust-bitcoin` crate. The reasons for that are: - **to keep the functionality set small and wallet-specific**: `rust-bitcoin` provides "all in one" solution, covering many parts of bitcoin ecosystem, like bitcoin peer-to-peer protocol, not really used by a wallet; - **to keep API stable**: `rust-bitcoin` with each release significantly breaks APIs, being in constant refactoring since early 2022 - a process likely to last for few years more; update of wallet libraries after each major change is painful and takes a lot of developers time and effort, as well as introduces API breaking changes downstream preventing all dependent libraries from stabilization; - **separation of private key material**: in Rust it is impossible to achieve constant-time production of secret key material, as well as prevent the compiler from copying it all over the machine memory (`zeroise` and other approaches doesn't prevent that). Thus, providing secret keys alongside other APIs may lead to non-secure design of the wallet and should be avoided; - **separation of consensus code from standards**: `rust-bitcoin` provides next to each other consensus-related structures and higher level wallet abstractions, which contradicts to the design decision we are making in this library; - **to introduce strong semantic typing**: for instance, `rust-bitcoin` doesn't differentiate different forms of scripts (pubkey, sig, witness etc.), while in this library we are using semantic type approach, providing type-safe variants for each semantically-distinct entity even if it shares the same representation with others. As one may see from the list, `rust-bitcoin` design and maintenance approach contradicts to the major aims of this project - in fact, this project was created by [Maxim Orlovsky][orlovsky] (who was the most active contributor to `rust-bitcoin` since Q1 2019 till Q2 2022) in order to address these issues using different set of trade-offs, providing an alternative to `rust-bitcoin` to those who needs it. ### Why not use miniscript? Miniscript is great for many purposes, but it can't be used for many cases, including representation of BOLT-3 lightning channel transaction outputs, re-use of public key in different branches of pre-taproot scripts [1][ms-1]. Miniscript is also still unstable, having recent changes to the semantic due to discovered bugs [2][ms-2] [3][ms-3]; meaning that the descriptors created with miniscript before may not be able to deterministically reproduce the structure of some wallet UTXOs in a future. Finally, the existing Rust miniscript implementation [`rust-miniscript`] inherits all `rust-bitcoin` tradeoffs, and is much more unstable in terms of APIs and semantic. Thus, it was decided to use this library to provide an alternative to miniscript with introduction of [script templates][#script-templates] convertible to and from miniscript representation - but with some externally-provided tools instead of adding miniscript as a direct dependency here. ### Why not BDK? BDK is great, but it relies on `rust-bitcoin` and `rust-miniscript` and can't be used outside of that ecosystem, inheriting all tradeoffs described above. Since we try to address those trade-offs, we had to create a BDK alternative. ### How this project is related to `descriptor-wallet`? [Descriptor wallet][descriptor-wallet] was an earlier project by the same authors trying to address `rust-bitcoin` issues by building on top of it. With the recent v0.30 `rust-bitcoin` release it became clear that the effort of adoption to API-breaking changes is much higher than creating a new independent project from scratch, while at the same time the new project may address `rust-bitcoin` issues in much more efficient and elegant way. Thus, it was decided to discontinue `descriptor-wallet` and start the new `bp-wallet` project instead. ## Design ### Script templates ### Descriptors ## Contributing Contribution guidelines can be found in [CONTRIBUTING](CONTRIBUTING.md) ## More information ### MSRV Minimum supported rust compiler version (MSRV) is shown in `rust-version` of `Cargo.toml`. ### Policy on altcoins Altcoins and "blockchains" other than Bitcoin blockchain/Bitcoin protocols are not supported and not planned to be supported; pull requests targeting them will be declined. ### Licensing The libraries are distributed on the terms of Apache 2.0 opensource license. See [LICENCE](LICENSE) file for the license details. [Assoc]: https://lnp-bp.org [bp-primitives]: https://crates.io/crates/bp-primitives [bp-core]: https://github.com/BP-WG/bp-core [orlovsky]: https://github.com/dr-orlovsky [descriptor-wallet]: https://github.com/BP-WG/descriptor-wallet