2018-03-12 15:55:56 +00:00
|
|
|
[](https://travis-ci.org/rust-bitcoin/rust-bitcoin)
|
2014-07-18 14:53:03 +00:00
|
|
|
|
2015-10-24 20:24:14 +00:00
|
|
|
# Rust Bitcoin Library
|
2014-07-18 14:53:03 +00:00
|
|
|
|
2015-10-24 20:24:14 +00:00
|
|
|
Library with support for de/serialization, parsing and executing on data
|
|
|
|
|
structures and network messages related to Bitcoin and other blockchain-based
|
|
|
|
|
currencies.
|
2014-07-18 14:53:03 +00:00
|
|
|
|
2018-03-12 15:55:56 +00:00
|
|
|
[Documentation](https://docs.rs/bitcoin/)
|
2014-07-18 14:53:03 +00:00
|
|
|
|
2015-10-24 20:24:14 +00:00
|
|
|
Supports (or should support)
|
2014-07-18 14:53:03 +00:00
|
|
|
|
2015-10-24 20:24:14 +00:00
|
|
|
* De/serialization of Bitcoin protocol network messages
|
|
|
|
|
* De/serialization of blocks and transactions
|
2017-05-08 16:01:20 +00:00
|
|
|
* Script de/serialization
|
2015-10-24 20:24:14 +00:00
|
|
|
* 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)
|
2014-07-18 14:53:03 +00:00
|
|
|
|
2017-05-08 16:01:20 +00:00
|
|
|
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.
|
|
|
|
|
|
2015-10-24 20:24:14 +00:00
|
|
|
# Usage
|
|
|
|
|
|
|
|
|
|
To use rust-bitcoin, just add the following to your Cargo.toml.
|
|
|
|
|
|
|
|
|
|
```toml
|
|
|
|
|
[dependencies]
|
2018-03-10 14:35:49 +00:00
|
|
|
bitcoin = "0.12"
|
2015-10-24 20:24:14 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
|
|
# Known limitations
|
|
|
|
|
|
|
|
|
|
## Consensus
|
|
|
|
|
|
|
|
|
|
This library **must not** be used for consensus code (i.e. fully validating
|
2018-03-10 14:35:49 +00:00
|
|
|
blockchain data). It technically supports doing this, but doing so is very
|
2015-10-24 20:24:14 +00:00
|
|
|
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
|
2015-10-28 16:27:23 +00:00
|
|
|
ever be fixed, and there are no plans to do so. Of course, patches to
|
|
|
|
|
fix specific consensus incompatibilities are welcome.
|
2015-10-24 20:24:14 +00:00
|
|
|
|
|
|
|
|
## 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.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
# 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.
|
2014-07-18 14:53:03 +00:00
|
|
|
|
|
|
|
|
|
2018-02-18 15:20:59 +00:00
|
|
|
## Release Notes
|
|
|
|
|
|
|
|
|
|
I will try to document all breaking changes here so that people upgrading will know
|
|
|
|
|
what they need to change.
|
|
|
|
|
|
|
|
|
|
### 0.11
|
|
|
|
|
|
|
|
|
|
Remove `num` dependency at Matt's request; agree this is obnoxious to require all
|
|
|
|
|
downstream users to also have a `num` dependency just so they can use `Uint256::from_u64`.
|
2014-07-18 14:53:03 +00:00
|
|
|
|
2018-03-10 14:35:49 +00:00
|
|
|
### 0.12
|
|
|
|
|
|
|
|
|
|
* The in-memory blockchain was moved into a dedicated project rust-bitcoin-chain.
|
|
|
|
|
|
|
|
|
|
* Removed old script interpreter
|
|
|
|
|
|
|
|
|
|
* A new optional feature "bitcoinconsenus" lets this library use Bitcoin Core's native
|
|
|
|
|
script verifier, wrappend into Rust by the rust-bitcoinconsenus project.
|
2018-03-23 15:27:56 +00:00
|
|
|
See `Transaction::verify` and `Script::verify` methods.
|
2018-03-10 14:35:49 +00:00
|
|
|
|
2018-03-23 15:27:56 +00:00
|
|
|
* Replaced Base58 traits with `encode_slice`, `check_encode_slice`, from and `from_check` functions in the base58 module.
|
2018-03-10 14:35:49 +00:00
|
|
|
|
2018-03-12 20:02:21 +00:00
|
|
|
* Un-reversed the Debug output for Sha256dHash
|
|
|
|
|
|
2018-03-09 20:27:13 +00:00
|
|
|
* Add bech32 support
|
|
|
|
|
|
2018-03-14 03:53:03 +00:00
|
|
|
* Support segwit address types
|
|
|
|
|
|
