Library with support for de/serialization, parsing and executing on data-structures and network messages related to Bitcoin

Overview

Rust Bitcoin

Rust Bitcoin logo by Hunter Trujillo, see license and source files under /logo

Library with support for de/serialization, parsing and executing on data-structures and network messages related to Bitcoin.

Crate Info CC0 1.0 Universal Licensed CI Status API Docs Rustc Version 1.41.1+ Chat on IRC Lines of code

Heads up for contributors: upcoming edition change

We're currently preparing to bump MSRV and change the edition to 2018. To minimize the churn we recommend you to submit your local WIP changes ASAP. There will be a lot of rebasing after the edition change.

Documentation

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)
  • PSBT creation, manipulation, merging and finalization
  • Pay-to-contract support as in Appendix A of the Blockstream sidechains whitepaper

For JSONRPC interaction with Bitcoin Core, it is recommended to use rust-bitcoincore-rpc.

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.

Support for 16-bit pointer sizes

16-bit pointer sizes are not supported and we can't promise they will be. If you care about them please let us know, so we can know how large the interest is and possibly decide to support them.

Documentation

Currently can be found on docs.rs/bitcoin. 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 #bitcoin-rust on libera.chat.

Minimum Supported Rust Version (MSRV)

This library should always compile with any combination of features (minus no-std) on Rust 1.41.1 or Rust 1.47 with no-std.

Installing Rust

Rust can be installed using your package manager of choice or 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 than the current stable one (see MSRV section).

Building

The library can be built and tested using cargo:

git clone [email protected]:rust-bitcoin/rust-bitcoin.git
cd rust-bitcoin
cargo build

You can run tests with:

cargo test

Please refer to the cargo documentation 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: .

CI Pipeline

The CI pipeline requires approval before being run on each MR.

In order to speed up the review process the CI pipeline can be run locally using act. The fuzz and Cross jobs will be skipped when using act due to caching being unsupported at this time. We do not actively support act but will merge PRs fixing act issues.

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 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.

Licensing

The code in this project is licensed under the Creative Commons CC0 1.0 Universal license.

Comments
  • Add a `LockTime` type

    Add a `LockTime` type

    Implement a LockTime type that adds support for lock time values based on nLockTime and OP_CHECKLOCKTIMEVERIFY.

    For example usage in rust-miniscript please see https://github.com/rust-bitcoin/rust-miniscript/pull/408.

    Notes:

    I probably should have opened a new PR, this is a total re-write and very different from what is being discussed below, sorry, my bad.

    This is just half of the 'timelock' story, its the easier half. The reason I switched terminology from timelock to locktime is that we have to compare two u32s so it does not make sense to call them both timelocks.

    If I have missed, or apparently ignored, anything you said reviewers please accept my apology in advance, it was not intentional. The thread of discussion is long and this topic is complex. Please do restate your views liberally :)

    Here is a useful blog post I used while touching up on timelock specifics: https://medium.com/summa-technology/bitcoins-time-locks-27e0c362d7a1. It links to all the relevant bips too.

    enhancement API break 1.0 release notes mention 
    opened by tcharding 116
  • Add API to PSBT to enable signing inputs

    Add API to PSBT to enable signing inputs

    Add an API for signing inputs to the PSBT struct. This is work based on code in rust-miniscript and the API design suggestions below from @sanket1729 and @Kixunil.

    Please note, this adds an unimplemented! call for taproot inputs. ECDSA signing is complete.

    Includes a patch adding the psbt example from https://github.com/rust-bitcoin/rust-bitcoin/pull/940 updated to use this new api. Run cargo run --example psbt --features=bitcoinconsensus to test it out.

    release notes mention 
    opened by tcharding 67
  • Rust 2018 & MSRV bump 1.41.1 tracking issue

    Rust 2018 & MSRV bump 1.41.1 tracking issue

        I wonder if we should have a Rust 2018 tracking issue and start tagging things that are blocked on it. 
        Would be good to have a clear picture of what we're missing by being on 1.29.
    

    — @apoelstra https://github.com/rust-bitcoin/rust-bitcoin/pull/373#issuecomment-708395995

    • No async support (not sure we need it at the level of this library)
    • We can not rename packages, which creates a lot of ambiguity with serde crate/feature and prevents from using normal solutions like https://github.com/rust-bitcoin/rust-bitcoin/pull/373#issuecomment-689172390
    • No able to use simple derive proc macros with syn 1.0 support like in amplify_derive instead if hard-to-read impl_ macro and multiple impl From... and impl Display... blocks (and there are wrapper types as well https://docs.rs/amplify_derive/2.0.6/amplify_derive/derive.Wrapper.html)
    • Not able to do #[non_exhaustive] to solve the problem of breaking API changes with gated enum veriants

    Checklist

    • [-] ~async - probably only for Read and Write async equivalents~ This is a nice to have, leave for another day.
    • [x] revive #373 - WIP in PR #1006
    • [-] ~use amplify_derive? note that this will blow up compile times for non-serde uses~ This is a nice to have, leave for another day.
    • [x] Implement TryFrom and use TryInto (#1007 does TryFrom but not the TryInto bit)
    • [x] sort_by_cached_key ~#524~ #1084
    • [-] ~Use alloc? Is this still relevant?~
    • [x] Use Infallible (#1075)
    • [x] Use contains() on ranges https://github.com/rust-bitcoin/rust-bitcoin/pull/644#discussion_r707950661 (#952)
    • [x] Use chunks_exact() instead of chunks (#952)
    • [x] use Trait as _ (#965)
    • [-] ~Exhaustive integer matching instead of comparing with zero~ (improves readability) (#1012)
    • [x] Use iter.copied() in https://github.com/rust-bitcoin/rust-bitcoin/pull/776#discussion_r784388347 (#1004)
    • [x] Use (;)? instead of (;)* in macros (#716) (#1010)
    • [x] Use literal instead of expr in macros (#716) (#1014)
    • [x] Usetrim_start_matches instead of trim_left_matches (#952)
    • [x] Use Vec::from([foo]) instead of Vec::new followed by v.push(). (#952, I checked all instances of mut foo = Vec::new() and also the same for BTreeMap)
    • [x] Change cause() to source() in impl of std::error::Error
    • [x] Use u16::to_be_bytes instead of swap_bytes (#952)
    • [x] Use #[non_exhaustive] (#1011 and #1026)

    non_exhaustive types:

    • [x] Error (#1026)
    • [x] AddressType (#1011)
    • [x] address::Payload (#1011)
    • [x] LeafVersion (#1011)

    PR list:

    • [-] ~#635~ closed in favour of 983
    • [x] https://github.com/rust-bitcoin/rust-bitcoin/pull/983
    epic 1.0 
    opened by dr-orlovsky 62
  • Hash new types as specified in #284

    Hash new types as specified in #284

    Progress report:

    • List of the new hash types was discussed and new types were defined: https://github.com/rust-bitcoin/rust-bitcoin/issues/284#issuecomment-524618641
    • bitcoin_hashes new_hashtype macro is fixed to work correctly and minimize amount of code changes required for adopting the new hash types: https://github.com/rust-bitcoin/bitcoin_hashes/pull/63 (it depends on the other PR here: https://github.com/rust-bitcoin/bitcoin_hashes/pull/64)
    • All new types are defined: https://github.com/rust-bitcoin/rust-bitcoin/pull/349/commits/e9c4d7d9070f317bb0de51a21bf3ce9680ae6051#diff-107236903cdf97a062c0be08467a2769
    • Txid is adopted, the library is compiling and tests are running correctly: https://github.com/rust-bitcoin/rust-bitcoin/pull/349/commits/e9c4d7d9070f317bb0de51a21bf3ce9680ae6051
    • All proposed hashes are implemented
    opened by dr-orlovsky 59
  • Re-work sighash type conversion methods

    Re-work sighash type conversion methods

    This PR has evolved into a full blown clean up of the conversion methods for all three sighash types based on the discussion below.

    Everything is split up into very small patches to aid review (and bikeshedding, this PR is almost totally just naming things).

    EDIT: I'm not convinced this should be an RC-fix, the changes are too wide spread now. It started as just a single method rename. Leaving label as is for others to consider.

    opened by tcharding 50
  • Add `Target` and `Work` types

    Add `Target` and `Work` types

    Ugh! 1600 lines of green and 1100 of red - my apologies.

    Currently we use the Uint256 type for proof-of-work calculations. It was observed in #1181 that providing a public 256 bit integer type like this implies that it is a general purpose integer type. We do not want to provide a general purpose integer type (see the 1000 arithmetic functions on stdlib integer types for why not :)

    Add two new opaque integer types Target and Work. These are the inverse of each other, both conceptually and mathematically.

    There is a lot of code in this PR, sorry about that. At a high level the PR does:

    • Add a pow module.
    • Put a modified version of Uint256 in pow, making it private.
    • Add two new wrapper types Target and Work that provide a very limited API specific to their use case. In particular there are methods on each to convert to the other.
    • Only implement methods that we use on each type.

    Note

    During development I got mixed up with the word "difficulty", I have discovered this has a very specific meaning in Bitcoin. Please see rustdocs on the Target::difficulty function for explanation of this term. For this reason we use the type Work defined as the inverse of target, and reserve "difficulty" for the Bitcoin concept.

    enhancement minor API Change release notes mention 
    opened by tcharding 49
  • Add trait `FromStrHex` for tuple structs with single `u32` member

    Add trait `FromStrHex` for tuple structs with single `u32` member

    Closes: #1112

    • Adds new trait FromStrHex with 2 methods: from_hex_str and from_hex_str_no_prefix
    • Impl new trait on each tuple struct with single u32 member. eg Time(u32)

    As stated in the issue, grep through codebase with \(u32\) and \(pub u32\) to see all implementations and verify none were missed.

    NonStandardSighashType is an error type and should never be constructed from a hex string. Therefore, it has been omitted from this change.

    Tests are somewhat redundant, but cover 4 cases each. 2 happy paths, 1 for each function. 1 case for malformed/invalid hex input, and 1 for calling no_prefix without a prefix

    opened by connormullett 48
  • [Discussion] Updating MSRV to 1.29.0

    [Discussion] Updating MSRV to 1.29.0

    Hi, I want to initiate a discussion about bumping the MSRV to 1.29.0.

    1. It was released at 2018-09-13, which is more than a year ago.
    2. mrustc now supports compiling it directly. so potential bootstrapping should be easy.

    A non exhaustive list of important(IMHO) features:

    1. the GlobalAlloc API is stable. meaning we can make better alignment guarantees in rust-secp256k1. (fix https://github.com/rust-bitcoin/rust-secp256k1/issues/138 which also affect non preallocated ). [1.28]
    2. repr(align(N)) on types. [1.25]
    3. The Error trait is a marker on top of Display. [1.27]
    4. Closures implement Clone/Copy (see tests of https://github.com/rust-bitcoin/rust-bitcoin/pull/319).
    5. u128/i128. [1.26]
    6. Duration no longer requires libstd. (https://github.com/rust-lang/rust/pull/46666) [1.25]
    7. Fix cargo's CVE-2019-16760. [1.26]
    8. NonNull pointer. [1.25]
    9. slice::align_to [1.30]

    Ergonomics reasons (again non exhaustive):

    1. Tests can return Result<(), E: Debug>. [1.28]
    2. dyn syntax. (shows explicitly that there's dynamic dispatch involved). [1.27]
    3. #[must_use] warning (https://github.com/rust-lang/rfcs/blob/master/text/1940-must-use-functions.md) [1.27]
    4. Inclusive range (getting rid of these warnings lol). [1.26]
    5. Nested imports (https://github.com/rust-lang/rfcs/blob/master/text/2128-use-nested-groups.md). [1.25]

    Important features for allowing dependencies:

    1. crate keyword (used by cc and ryu). [1.30]
    2. 2018 Edition (used by cc, ryu, serde_derive) [1.31]
    3. to_be_byte functions (used by base64(#413)) [1.32]
    4. TryInto trait (used by base64(#413)) [1.34]
    opened by elichai 48
  • no_std support, keeping MSRV

    no_std support, keeping MSRV

    TODO:

    • [x] needs release of bitcoin_hashes
    • [x] needs release of rust-bech32

    Based on the original work by Justin Moon in #528

    MSRV unchanged from 1.29.0.

    When std is off the no-std feature must be turned on, which turns on the alloc crate, which requires the user define a global allocator. It also pulls in the hashbrown crate and activates no_std and alloc support in a couple of dependencies.

    • Import from core and alloc instead of std
    • alloc only used if std is off
    • Create std feature
    • Create no-std feature which adds a core2 dependency to polyfill std::io features. This is an experimental feature and should be used with caution.
    • CI runs tests no_std code
    • MSRV of no_std is 1.51 or so

    Fixes #409

    opened by devrandom 46
  • Implement BIP69 (Lexicographical Indexing of Transaction Inputs and Outputs)

    Implement BIP69 (Lexicographical Indexing of Transaction Inputs and Outputs)

    BIP69 defines a canonical, lexicographical ordering of transaction inputs and outputs. This is mainly a privacy improvement as the purpose is to prevent the fingerprinting of wallets based on input/output ordering heuristics. In their most naive implementation, most wallets order payment outputs first, followed by any change outputs. The more wallets adopt this BIP the harder it is to fingerprint wallets based on this particular heuristic. It would be beneficial and useful to have this functionality available in the Rust Bitcoin library.

    The entire rationale is is explained in: https://github.com/bitcoin/bips/blob/master/bip-0069.mediawiki

    opened by straylight-orbit 40
  • Create `crypto` module

    Create `crypto` module

    Done as part of util flattening.

    Create a crypto module and move into it (out of util):

    • ecdsa
    • schnorr
    • key

    After review, this PR now includes some type re-names

    • EcdsaSig -> ecdsa::Signature
    • SchnorrSig -> schnorr::Signature
    • EcdsaSigError -> ecdsa::Error
    • SchnorrSigError -> schnorr::Error
    • InvalidSchnorrSigSize -> InvalidSignatureSize (this is an error enum variant)
    minor API Change P-high 1.0 aggregate release notes mention 
    opened by tcharding 39
  • Add more mutation testing to the `pow` module

    Add more mutation testing to the `pow` module

    Done on top of #1496 (so get the new mul_u64 implementation)

    All functions/methods that are non-trivial are tested excluding:

    • to_compact_lossy
    • from_compact
    • fmt_decimal

    I think its ok to not test fmt_decimal. The compact format ones require a bit of work to do but should be done at some stage.

    opened by tcharding 0
  • Use dtonlnay instead of actions-rs

    Use dtonlnay instead of actions-rs

    Done on top of #1508

    Currently we use the actions-rs GitHub action to run our tests. It seems the project is now unmaintained [0].

    Well known Rust developer dtonlnay maintains a GitHub action that can be used instead.

    Replace all uses of actions-rs/toolchain with dtonlnay/rust-toolchain. Note that with the new action there is no way to configure the toolchain, instead a different uses statement is required - this means we have to split our jobs up by toolchain. This is arguably cleaner anyways.

    Note that with this patch applied the "no-std" tests are now not run for MSRV since we explicitly support "no-std" only for the 1.47 and above toolchains - strange that this was working?

    [0] https://github.com/actions-rs/toolchain/issues/216

    opened by tcharding 1
  • Use cargo install cross `--locked`

    Use cargo install cross `--locked`

    cross currently fails to install, this has been reported already

    https://github.com/cross-rs/cross/issues/1177

    The workaround is to use cargo install --locked.

    opened by tcharding 0
  • Document test frameworks

    Document test frameworks

    Recently we started using various test frameworks; add documentation to the readme for running the various tests we now support (mutagen, kani, etc.)

    Note

    This was on a different PR originally, pushing it up on its own.

    documentation one ack 
    opened by tcharding 0
  • Improve test coverage for docs build

    Improve test coverage for docs build

    Currently the docs build commands in hashes and bitcoin differ, they should be the same.

    Add a command cargo doc to improve coverage e.g., recently we botched the feature guarding but since CI only runs cargo rustdoc with custom compiler conditional set we didn't catch it.

    Done after seeing: https://github.com/rust-bitcoin/rust-bitcoin/pull/1504 and CI should fail on this PR until 1504 is in.

    opened by tcharding 2
Owner
Rust Bitcoin Community
A Series of Projects to implement various Bitcoin Protocols in Rust
Rust Bitcoin Community
Minimal Bitcoin wallet intended for teaching rust-bitcoin

Insanely minimal Bitcoin wallet intended for demonstration of Rust Bitcoin ecosystem Absolutely DO NOT use with mainnet funds!!! No privacy - address

Martin Habovštiak 4 May 5, 2023
Modern, lightweight & standard-compliant bitcoin wallet runtime & cli without rust-bitcoin dependencies

Bitcoin protocol command-line wallet & tools Modern, minimalistic & standard-compliant cold wallet from LNP/BP Standards Association. Contributing Con

BP: Bitcoin protocol 3 Jul 31, 2023
Low-level Bitcoin P2P Network Client

Peerlink What is Peerlink? Peerlink is a low-level network client for the Bitcoin P2P network written in Rust. It uses a nonblocking reactor to accept

Alfred Hodler 6 Dec 23, 2022
Rust implementation of the Binary Canonical Serialization (BCS) format

Binary Canonical Serialization (BCS) BCS (formerly "Libra Canonical Serialization" or LCS) is a serialization format developed in the context of the D

Zefchain Labs 4 Nov 13, 2022
A memcomparable serialization format.

memcomparable A memcomparable serialization format. The memcomparable format allows comparison of two values by using the simple memcmp function. Inst

RisingWave Labs 13 Dec 2, 2022
The parser library to parse messages from crypto-crawler.

crypto-msg-parser The parser library to parse messages from crypto-crawler. Architecture crypto-msg-parser is the parser library to parse messages fro

null 5 Jan 2, 2023
A Rust library for working with Bitcoin SV

Rust-SV A library to build Bitcoin SV applications in Rust. Documentation Features P2P protocol messages (construction and serialization) Address enco

Brenton Gunning 51 Oct 13, 2022
A guide for Mozilla's developers and data scientists to analyze and interpret the data gathered by our data collection systems.

Mozilla Data Documentation This documentation was written to help Mozillians analyze and interpret data collected by our products, such as Firefox and

Mozilla 75 Dec 1, 2022
ARYA Network is a polkadot/substrate based chain for Non-fungible Token platform on which we can own sell and buy the NFT's on polkadot network.

ARYA Network ARYA Network is a polkadot/substrate based chain for Non-fungible Token platform on which we can own sell and buy the NFT's on polkadot n

Pankaj Chaudhary 6 Dec 20, 2022
Prototype: ORAM and related for Intel SGX enclaves

mc-oblivious Traits and implementations for Oblivious RAM inside of Intel SGX enclaves. The scope of this repository is: Traits for fast constant-time

MobileCoin 37 Nov 23, 2022
A tool to identify related SSL keys, CSRs, and certificates.

⛓ sslchains A tool to identify related SSL keys, CSRs, and certificates. Usage Default Display Mode Run with any number of path arguments to define th

Gary Locke 1 Apr 2, 2022
A general solution for commonly used crypt in rust, collection of cryptography-related traits and algorithms.

Crypto-rs A general solution for commonly used crypt in rust, collection of cryptography-related traits and algorithms. This is a Rust implementation

houseme 4 Nov 28, 2022
Cross-chain bridge message delivery network. We are hiring, [email protected]

Introduction Implementation of a https://darwinia.network node in Rust based on the Substrate framework. This repository contains runtimes for the Dar

Darwinia Network 225 Nov 8, 2022
The Zenotta Network Protocol (ZNP), the network that supports the Zenotta blockchain

Zenotta Network Protocol A repo for the development of the Zenotta Network Protocol (ZNP). We will regularly be updating links and easter eggs inside

Zenotta AG 10 Apr 2, 2023
HD wallet BIP-32 related key derivation utilities.

HDWallet Docs HD wallet(BIP-32) key derivation utilities. This crate is build upon secp256k1 crate, this crate only provides BIP-32 related features,

jjy 23 Nov 27, 2022
Cryptography-related format encoders/decoders: PKCS, PKIX

RustCrypto: Formats Cryptography-related format encoders/decoders: PKCS, PKIX. Crates Name crates.io Docs Description base64ct Constant-time encoder a

Rust Crypto 112 Dec 20, 2022
Traits - Collection of cryptography-related traits

RustCrypto: Traits Collection of traits which describe functionality of cryptographic primitives. Crates Name Algorithm Crates.io Docs MSRV aead Authe

Rust Crypto 401 Dec 27, 2022
A crate for working with Ethereum beacon chain light client protocol messages. `no_std` friendly!

eth-lightclient-rs A crate for working with Ethereum beacon chain light client protocol messages. no_std friendly! !! For hacking and experimentation

Willem Olding 12 Jan 6, 2023
EXPERIMENTAL: Bitcoin Core Prometheus exporter based on User-Space, Statically Defined Tracing and eBPF.

bitcoind-observer An experimental Prometheus metric exporter for Bitcoin Core based on Userspace, Statically Defined Tracing and eBPF. This demo is ba

0xB10C 24 Nov 8, 2022