|Dec 30, 2023
|Nov 19, 2023
|Apr 26, 2023
|Mar 24, 2023
|Nov 23, 2021
#702 in Magic Beans
1,134 downloads per month
Used in 30 crates (10 directly)
Bitcoin standards implementation libraries
Modern, minimalistic & standard-compliant wallet-level libraries: an alternative
rust-bitcoin and BDK libraries from LNP/BP Standards Association.
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
- 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-primitiveslibrary (a part of
bp-corelibrary), 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;
- 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.
Why not use
The library doesn't rely on
rust-bitcoin crate. The reasons for that are:
- to keep the functionality set small and wallet-specific:
rust-bitcoinprovides "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-bitcoinwith 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 (
zeroiseand 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-bitcoinprovides 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-bitcoindoesn'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 (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
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 [ms-1].
Miniscript is also still unstable, having recent changes to the semantic due
to discovered bugs [ms-2] [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
rust-miniscript inherits all
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 tempaltes][#script-templates] convertable 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-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 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
Contribution guidelines can be found in CONTRIBUTING
This library requires minimum rust compiler version (MSRV) 1.60.0.
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.
The libraries are distributed on the terms of Apache 2.0 opensource license. See LICENCE file for the license details.