# The Parity Bitcoin client. [![Build Status][travis-image]][travis-url] [![Snap Status](https://build.snapcraft.io/badge/paritytech/parity-bitcoin.svg)](https://build.snapcraft.io/user/paritytech/parity-bitcoin) Gitter [![Gitter https://gitter.im/paritytech/parity-bitcoin](https://badges.gitter.im/paritytech/parity-bitcoin.svg)](https://gitter.im/paritytech/parity-bitcoin) - [Installing from source](#installing-from-source) - [Installing the snap](#installing-the-snap) - [Running tests](#running-tests) - [Going online](#going-online) - [Importing bitcoind database](#importing-bitcoind-database) - [Command line interface](#command-line-interface) - [JSON-RPC](#json-rpc) - [Logging](#logging) - [Internal Documentation](#internal-documentation) - [Project Graph][graph] [graph]: ./tools/graph.svg [travis-image]: https://travis-ci.com/paritytech/parity-bitcoin.svg?token=DMFvZu71iaTbUYx9UypX&branch=master [travis-url]: https://travis-ci.com/paritytech/parity-bitcoin [doc-url]: https://paritytech.github.io/parity-bitcoin/pbtc/index.html ## Installing from source Installing `pbtc` from source requires `rustc` and `cargo`. Minimal supported version is `rustc 1.16.0 (30cf806ef 2017-03-10)` #### Install rustc and cargo Both `rustc` and `cargo` are a part of rust tool-chain. An easy way to install the stable binaries for Linux and Mac is to run this in your shell: ``` curl -sSf https://static.rust-lang.org/rustup.sh | sh ``` Windows binaries can be downloaded from [rust-lang website](https://www.rust-lang.org/en-US/downloads.html). #### Install C and C++ compilers You will need the cc and gcc compilers to build some of the dependencies. ``` sudo apt-get update sudo apt-get install build-essential ``` #### Clone and build pbtc Now let's clone `pbtc` and enter it's directory: ``` git clone https://github.com/paritytech/parity-bitcoin cd parity-bitcoin ``` `pbtc` can be build in two modes. `--debug` and `--release`. Debug is the default. ``` # builds pbtc in debug mode cargo build -p pbtc ``` ``` # builds pbtc in release mode cargo build -p pbtc --release ``` `pbtc` is now available at either `./target/debug/pbtc` or `./target/release/pbtc`. ## Installing the snap In any of the [supported Linux distros](https://snapcraft.io/docs/core/install): ``` sudo snap install parity-bitcoin --edge ``` ## Running tests `pbtc` has internal unit tests and it conforms to external integration tests. #### Running unit tests Assuming that repository is already cloned, we can run unit tests with this command: ``` ./tools/test.sh ``` #### Running external integration tests Running integration tests is automated, as the regtests repository is one of the submodules. Let's download it first: ``` git submodule update --init ``` Now we can run them: ``` ./tools/regtests.sh ``` It's also possible to run regtests manually: ``` # let's start pbtc in regtest compatible mode ./target/release/pbtc --regtest # now in second shell window cd $HOME git clone https://github.com/TheBlueMatt/test-scripts cd test-scripts java -jar pull-tests-f56eec3.jar ``` ## Going online By default parity connects to bitcoind-seednodes. Full list is [here](./pbtc/seednodes.rs). To start syncing the main network, just start the client: ``` ./target/release/pbtc ``` To start syncing the testnet: ``` ./target/release/pbtc --testnet ``` To not print any syncing progress add `--quiet` flag: ``` ./target/release/pbtc --quiet ``` ## Importing bitcoind database It it is possible to import existing `bitcoind` database: ``` # where $BITCOIND_DB is path to your bitcoind database, e.g., "/Users/user/Library/Application Support" ./target/release/pbtc import "$BITCOIND_DB/Bitcoin/blocks" ``` By default import verifies imported the blocks. You can disable this, by adding `--skip-verification flag. ``` ./target/release/pbtc import "#BITCOIND_DB/Bitcoin/blocks" --skip-verification ``` ## Command line interface Full list of CLI options, which is available under `pbtc --help`: ``` pbtc 0.1.0 Parity Technologies Parity Bitcoin client USAGE: pbtc [FLAGS] [OPTIONS] [SUBCOMMAND] FLAGS: --bitcoin-cash Use Bitcoin Cash verification rules. -h, --help Prints help information --no-jsonrpc Disable the JSON-RPC API server. -q, --quiet Do not show any synchronization information in the console. --regtest Use a private network for regression tests. --segwit2x Enable SegWit2x verification rules. --testnet Use the test network (Testnet3). -V, --version Prints version information OPTIONS: --blocknotify Execute COMMAND when the best block changes (%s in COMMAND is replaced by the block hash). -c, --connect Connect only to the specified node. -d, --data-dir Specify the database and configuration directory PATH. --db-cache Sets the database cache size. --jsonrpc-apis Specify the APIs available through the JSONRPC interface. APIS is a comma-delimited list of API names. --jsonrpc-cors Specify CORS header for JSON-RPC API responses. --jsonrpc-hosts List of allowed Host header values. --jsonrpc-interface The hostname portion of the JSONRPC API server. --jsonrpc-port Specify the PORT for the JSONRPC API server. --only-net Only connect to nodes in network version (ipv4 or ipv6). --port Listen for connections on PORT. -s, --seednode Connect to a seed-node to retrieve peer addresses, and disconnect. --verification-edge Non-default verification-level is applied until a block with given hash is met. --verification-level Sets the Blocks verification level to full (default), header (scripts are not verified), or none (no verification at all). SUBCOMMANDS: help Prints this message or the help of the given subcommand(s) import Import blocks from a Bitcoin Core database. rollback Rollback the database to given canonical-chain block. ``` ## JSON-RPC TODO ## Logging This is a section only for developers and power users. You can enable detailed client logging by setting the environment variable `RUST_LOG`, e.g., ``` RUST_LOG=verification=info ./target/release/pbtc --quiet ``` `pbtc` started with this environment variable will print all logs coming from `verification` module with verbosity `info` or higher. Available log levels are: - `error` - `warn` - `info` - `debug` - `trace` It's also possible to start logging from multiple modules in the same time: ``` RUST_LOG=sync=trace,p2p=trace,verification=trace,db=trace ./target/release/pbtc --quiet ``` **Note:** `RUST_LOG` does only work together with command line option `--quiet` which will suppress the default `sync=info` logging. ## Internal documentation Once released, `pbtc` documentation will be available [here][doc-url]. Meanwhile it's only possible to build it locally: ``` cd parity-bitcoin ./tools/doc.sh open target/doc/pbtc/index.html ```