96 lines
4.1 KiB
Markdown
96 lines
4.1 KiB
Markdown
[](https://travis-ci.org/rust-bitcoin/rust-bitcoin)
|
|
|
|
# Rust Bitcoin Library
|
|
|
|
Library with support for de/serialization, parsing and executing on data
|
|
structures and network messages related to Bitcoin and other blockchain-based
|
|
currencies.
|
|
|
|
[Documentation](https://docs.rs/bitcoin/)
|
|
|
|
Supports (or should support)
|
|
|
|
* De/serialization of Bitcoin protocol network messages
|
|
* De/serialization of blocks and transactions
|
|
* Script de/serialization
|
|
* Private keys and address creation, de/serialization and validation (including full BIP32 support)
|
|
* Pay-to-contract support as in Appendix A of the [Blockstream sidechains whitepaper](https://www.blockstream.com/sidechains.pdf)
|
|
|
|
For JSONRPC interaction with Bitcoin Core, it is recommended to use [rust-jsonrpc](https://github.com/apoelstra/rust-jsonrpc)
|
|
which uses the underlying [strason library](https://github.com/apoelstra/strason)
|
|
which parses decimal numbers as strings, preventing precision errors.
|
|
|
|
# Known limitations
|
|
|
|
## Consensus
|
|
|
|
This library **must not** be used for consensus code (i.e. fully validating
|
|
blockchain data). It technically supports doing this, but doing so is very
|
|
ill-advised because there are many deviations, known and unknown, between
|
|
this library and the Bitcoin Core reference implementation. In a consensus
|
|
based cryptocurrency such as Bitcoin it is critical that all parties are
|
|
using the same rules to validate data, and this library is simply unable
|
|
to implement the same rules as Core.
|
|
|
|
Given the complexity of both C++ and Rust, it is unlikely that this will
|
|
ever be fixed, and there are no plans to do so. Of course, patches to
|
|
fix specific consensus incompatibilities are welcome.
|
|
|
|
## Documentation
|
|
|
|
Currently the [documentation](https://www.wpsoftware.net/rustdoc/bitcoin/)
|
|
is very sparse. Patches to add usage examples and to expand on existing
|
|
docs would be extremely appreciated.
|
|
|
|
# Contributing
|
|
Contributions are generally welcome. If you intend to make larger changes please discuss them in an issue before PRing
|
|
them to avoid duplicate work and architectural mismatches. If you have any questions or ideas you want to discuss
|
|
please join us in [#rust-bitcoin](http://webchat.freenode.net/?channels=%23rust-bitcoin) on freenode.
|
|
|
|
## Installing Rust
|
|
Rust can be installed using your package manager of choice or [rustup.rs](https://rustup.rs). The former way is
|
|
considered more secure since it typically doesn't involve trust in the CA system. But you should be aware that the version
|
|
of Rust shipped by your distribution might be out of date. Generally this isn't a problem for `rust-bitcoin` since
|
|
we support much older versions (>=1.22) than the current stable one.
|
|
|
|
## Building
|
|
The library can be built and tested using [`cargo`](https://github.com/rust-lang/cargo/):
|
|
|
|
```
|
|
git clone git@github.com:rust-bitcoin/rust-bitcoin.git
|
|
cd rust-bitcoin
|
|
cargo build
|
|
```
|
|
|
|
You can run tests with:
|
|
|
|
```
|
|
cargo test
|
|
```
|
|
|
|
Please refer to the [`cargo` documentation](https://doc.rust-lang.org/stable/cargo/) for more detailed instructions.
|
|
|
|
## Pull Requests
|
|
Every PR needs at least two reviews to get merged. During the review phase maintainers and contributors are likely to
|
|
leave comments and request changes. Please try to address them, otherwise your PR might get closed without merging after
|
|
a longer time of inactivity. If your PR isn't ready for review yet please mark it by prefixing the title with `WIP: `.
|
|
|
|
## Policy on Altcoins/Altchains
|
|
|
|
Patches which add support for non-Bitcoin cryptocurrencies by adding constants
|
|
to existing enums (e.g. to set the network message magic-byte sequence) are
|
|
welcome. Anything more involved will be considered on a case-by-case basis,
|
|
as the altcoin landscape includes projects which [frequently appear and
|
|
disappear, and are poorly designed anyway](https://download.wpsoftware.net/bitcoin/alts.pdf)
|
|
and keeping the codebase maintainable is a large priority.
|
|
|
|
In general, things that improve cross-chain compatibility (e.g. support for
|
|
cross-chain atomic swaps) are more likely to be accepted than things which
|
|
support only a single blockchain.
|
|
|
|
|
|
# Release Notes
|
|
|
|
See CHANGELOG.md
|
|
|