2015-09-20 17:28:13 +00:00
|
|
|
[](https://travis-ci.org/apoelstra/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
|
|
|
|
2015-10-24 20:24:14 +00:00
|
|
|
[Documentation](https://www.wpsoftware.net/rustdoc/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
|
|
|
|
|
* Blockchain validation
|
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]
|
2017-12-13 21:20:16 +00:00
|
|
|
bitcoin = "0.10"
|
2015-10-24 20:24:14 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
|
|
# Known limitations
|
|
|
|
|
|
|
|
|
|
## Consensus
|
|
|
|
|
|
|
|
|
|
This library **must not** be used for consensus code (i.e. fully validating
|
2017-05-08 16:01:20 +00:00
|
|
|
blockchain data). It technically supports doing this, using the feature-gated
|
|
|
|
|
script parser, 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.
|
|
|
|
|
|
2017-12-13 21:20:16 +00:00
|
|
|
The script interpreter is now gated behind the `broken_consensus_code` flag
|
|
|
|
|
for this reason.
|
|
|
|
|
|
2015-10-24 20:24:14 +00:00
|
|
|
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
|
|
|
|
