Newer
Older
[![Build Status][travis-image]][travis-url] [](https://build.snapcraft.io/user/paritytech/parity-bitcoin)
Gitter [](https://gitter.im/paritytech/parity-bitcoin)
- [Installing from source](#installing-from-source)
- [Installing the snap](#installing-the-snap)
- [Going online](#going-online)
- [Importing bitcoind database](#importing-bitcoind-database)
- [Command line interface](#command-line-interface)
- [JSON-RPC](#json-rpc)
- [Logging](#logging)
- [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 `pbtc` from source requires `rustc` and `cargo`.
Minimal supported version is `rustc 1.16.0 (30cf806ef 2017-03-10)`
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
```
Now let's clone `pbtc` and enter it's directory:
`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
```
`pbtc` has internal unit tests and it conforms to external integration 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:
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 --testnet
```
To not print any syncing progress add `--quiet` flag:
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
Full list of CLI options, which is available under `pbtc --help`:
Parity Technologies <[email protected]>
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
--blocknotify <COMMAND> Execute COMMAND when the best block changes (%s in COMMAND is replaced by the block hash).
-c, --connect <IP> Connect only to the specified node.
-d, --data-dir <PATH> Specify the database and configuration directory PATH.
--db-cache <SIZE> Sets the database cache size.
--jsonrpc-apis <APIS> Specify the APIs available through the JSONRPC interface. APIS is a comma-delimited list of API names.
--jsonrpc-cors <URL> Specify CORS header for JSON-RPC API responses.
--jsonrpc-hosts <HOSTS> List of allowed Host header values.
--jsonrpc-interface <INTERFACE> The hostname portion of the JSONRPC API server.
--jsonrpc-port <PORT> Specify the PORT for the JSONRPC API server.
--only-net <NET> Only connect to nodes in network version <NET> (ipv4 or ipv6).
--port <PORT> Listen for connections on PORT.
-s, --seednode <IP> Connect to a seed-node to retrieve peer addresses, and disconnect.
--verification-edge <BLOCK> Non-default verification-level is applied until a block with given hash is met.
--verification-level <LEVEL> Sets the Blocks verification level to full (default), header (scripts are not verified), or none (no verification at all).
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