Repository files navigation

Modern, minimalistic & standard-compliant wallet-level libraries: an alternativetorust-bitcoin and BDK libraries fromLNP/BP Standards Association.

The main goals of the libraries are:

• fast stabilization of APIs: the library will be targeting v1.0 versionwithin the first year of its development; which should enable downstreamcrates using the library also to stabilize and not spend too much efforton changing the integration each time the new version ofbp-wallet isreleased;
• no use of private keys: the library analyzes wallet state usingdescriptors and allows to produce unsigned PSBTs, as well as publish andanalyze (partially) signed PSBTs - but doesn't provide a signer or a way towork 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 withexisting bitcoin standards defined in BIPs and do not use any legacyapproaches or "blockchain-not-bitcoin" practices (like the ones provided byBLIPs);
• separation of bitcoin consensus and standards: the consensus-relatedcode is not a part of this library; all data structures and business logicwhich may have consensus meaning and is required for a wallet is separatedinto an independent [bp-primitives] library (a part of [bp-core] library),which is planned to be more extensively audited and ossified alongsidebitcoin protocol (while this library will continue to evolve with betterAPIs and to match new wallet standards);
• extensive use of descriptors: library focuses on defining all parts ofa wallet using descriptors; additionally to script pubkey descriptors it alsosupports xpub descriptors, derivation descriptors, applied to script pubkeydescriptor as a whole, and input descriptors for RBFs. You can read more onspecific descriptor types in thesection below;
• script templates: the library allows to provide an arbitrary script asa part of a descriptor, which allows support for BOLT lightning channeltransaction 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 setof high-level wallet data structures abstracting away blockchain-leveldetails; helping in writing less boilerplate business logic;
• APIs usable in all rust projects and in FFI: the library doesn't useasync rust, complex callbacks, threads etc., which allows to keep the APIsimple, usable from any rust app (like ones using reactive patterns instead ofasync); at the same time all the data structures of the library areSend + Sync, meaning that they can be used in any multi-thread or asyncenvironment;
• abstracted blockchain data providers: the library abstracts blockchainindexer APIs (Electrum, Esplora, Bitcoin Core etc.) and also provides theirimplementation using this library structures.

The library doesn't rely onrust-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, likebitcoin peer-to-peer protocol, not really used by a wallet;
• to keep API stable:rust-bitcoin with each release significantly breaksAPIs, being in constant refactoring since early 2022 - a process likely tolast for few years more; update of wallet libraries after each major change ispainful and takes a lot of developers time and effort, as well as introducesAPI breaking changes downstream preventing all dependent libraries fromstabilization;
• separation of private key material: in Rust it is impossible to achieveconstant-time production of secret key material, as well as prevent thecompiler from copying it all over the machine memory (zeroise and otherapproaches doesn't prevent that). Thus, providing secret keys alongsideother APIs may lead to non-secure design of the wallet and should be avoided;
• separation of consensus code from standards:rust-bitcoin provides nextto each other consensus-related structures and higher level walletabstractions, which contradicts to the design decision we are making in thislibrary;
• to introduce strong semantic typing: for instance,rust-bitcoin doesn'tdifferentiate different forms of scripts (pubkey, sig, witness etc.), whilein this library we are using semantic type approach, providing type-safevariants for each semantically-distinct entity even if it shares the samerepresentation with others.

As one may see from the list,rust-bitcoin design and maintenance approachcontradicts to the major aims of this project - in fact, this project wascreated byMaxim Orlovsky (who was the most active contributor torust-bitcoin since Q1 2019 till Q2 2022) in order to address these issuesusing different set of trade-offs, providing an alternative torust-bitcointo those who needs it.

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 dueto discovered bugs [2][ms-2] [3][ms-3]; meaning that the descriptors createdwith miniscript before may not be able to deterministically reproduce thestructure of some wallet UTXOs in a future. Finally, the existing Rustminiscript implementation [rust-miniscript] inherits allrust-bitcointradeoffs, and is much more unstable in terms of APIs and semantic. Thus, it wasdecided to use this library to provide an alternative to miniscript withintroduction of [script templates][#script-templates] convertible to and fromminiscript representation - but with some externally-provided tools insteadof adding miniscript as a direct dependency here.

BDK is great, but it relies onrust-bitcoin andrust-miniscript and can'tbe 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.

Descriptor wallet was an earlier project by the sameauthors trying to addressrust-bitcoin issues by building on top of it. Withthe recent v0.30rust-bitcoin release it became clear that the effort ofadoption to API-breaking changes is much higher than creating a new independentproject from scratch, while at the same time the new project may addressrust-bitcoin issues in much more efficient and elegant way. Thus, it wasdecided to discontinuedescriptor-wallet and start the newbp-wallet projectinstead.

Contribution guidelines can be found inCONTRIBUTING

Minimum supported rust compiler version (MSRV) is shown inrust-version ofCargo.toml.

Altcoins and "blockchains" other than Bitcoin blockchain/Bitcoin protocols arenot supported and not planned to be supported; pull requests targeting them willbe declined.

The libraries are distributed on the terms of Apache 2.0 opensource license.SeeLICENCE file for the license details.