# 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 --segwit --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). Before starting synchronization, you must decide - which fork to follow - SegWit (`--segwit` flag), SegWit2x (`--segwit2x` flag) or Bitcoin Cash (`--bitcoin-cash` flag). On next start, passing the same flag is optional, as the database is already bound to selected fork and won't be synchronized using other verification rules. To start syncing the main network, just start the client, passing selected fork flag. For example: ``` ./target/release/pbtc --segwit ``` To start syncing the testnet: ``` ./target/release/pbtc --segwit --testnet ``` To not print any syncing progress add `--quiet` flag: ``` ./target/release/pbtc --segwit --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 `--verification-level==none` flag. ``` ./target/release/pbtc import "#BITCOIND_DB/Bitcoin/blocks" --segwit --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. --segwit Enable SegWit verification rules. --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 #### Network The Parity-bitcoin `network` interface. ##### addnode Add the node. curl -H 'content-type: application/json' --data-binary '{"jsonrpc": "2.0", "method": "addnode", "params": ["127.0.0.1:8888", "add"], "id":1 }' localhost:8332 Remove the node. curl -H 'content-type: application/json' --data-binary '{"jsonrpc": "2.0", "method": "addnode", "params": ["127.0.0.1:8888", "remove"], "id":1 }' localhost:8332 Connect to the node. curl -H 'content-type: application/json' --data-binary '{"jsonrpc": "2.0", "method": "addnode", "params": ["127.0.0.1:8888", "onetry"], "id":1 }' localhost:8332 ##### getaddednodeinfo Query info for all added nodes. curl -H 'content-type: application/json' --data-binary '{"jsonrpc": "2.0", "id":"1", "method": "getaddednodeinfo", "params": [true] }' localhost:8332 Query info for the specified node. curl -H 'content-type: application/json' --data-binary '{"jsonrpc": "2.0", "id":"1", "method": "getaddednodeinfo", "params": [true, "192.168.0.201"] }' localhost:8332 ##### getconnectioncount Get the peer count. curl -H 'content-type: application/json' --data-binary '{"jsonrpc": "2.0", "id":"1", "method": "getconnectioncount", "params": [] }' localhost:8332 #### Blockchain The Parity-bitcoin `blockchain` data interface. ##### getbestblockhash Get hash of best block. curl -H 'content-type: application/json' --data-binary '{"jsonrpc": "2.0", "method": "getbestblockhash", "params": [], "id":1 }' localhost:8332 ##### getblockcount Get height of best block. curl -H 'content-type: application/json' --data-binary '{"jsonrpc": "2.0", "method": "getblockcount", "params": [], "id":1 }' localhost:8332 ##### getblockhash Get hash of block at given height. curl -H 'content-type: application/json' --data-binary '{"jsonrpc": "2.0", "method": "getblockhash", "params": [0], "id":1 }' localhost:8332 ##### getdifficulty Get proof-of-work difficulty as a multiple of the minimum difficulty curl -H 'content-type: application/json' --data-binary '{"jsonrpc": "2.0", "method": "getdifficulty", "params": [], "id":1 }' localhost:8332 ##### getblock Get information on given block. curl -H 'content-type: application/json' --data-binary '{"jsonrpc": "2.0", "method": "getblock", "params": ["000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b60a8ce26f"], "id":1 }' localhost:8332 ##### gettxout Get details about an unspent transaction output. curl -H 'content-type: application/json' --data-binary '{"jsonrpc": "2.0", "method": "gettxout", "params": ["4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b", 0], "id":1 }' localhost:8332 ##### gettxoutsetinfo Get statistics about the unspent transaction output set. curl -H 'content-type: application/json' --data-binary '{"jsonrpc": "2.0", "method": "gettxoutsetinfo", "params": [], "id":1 }' localhost:8332 #### Miner The Parity-bitcoin `miner` data interface. ##### getblocktemplate Get block template for mining. curl -H 'content-type: application/json' --data-binary '{"jsonrpc": "2.0", "method": "getblocktemplate", "params": [{"capabilities": ["coinbasetxn", "workid", "coinbase/append"]}], "id":1 }' localhost:8332 #### Raw The Parity-bitcoin `raw` data interface. ##### getrawtransaction Return the raw transaction data. curl -H 'content-type: application/json' --data-binary '{"jsonrpc": "2.0", "method": "getrawtransaction", "params": ["4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b"], "id":1 }' localhost:8332 ##### decoderawtransaction Return an object representing the serialized, hex-encoded transaction. curl -H 'content-type: application/json' --data-binary '{"jsonrpc": "2.0", "method": "decoderawtransaction", "params": ["01000000010000000000000000000000000000000000000000000000000000000000000000ffffffff4d04ffff001d0104455468652054696d65732030332f4a616e2f32303039204368616e63656c6c6f72206f6e206272696e6b206f66207365636f6e64206261696c6f757420666f722062616e6b73ffffffff0100f2052a01000000434104678afdb0fe5548271967f1a67130b7105cd6a828e03909a67962e0ea1f61deb649f6bc3f4cef38c4f35504e51ec112de5c384df7ba0b8d578a4c702b6bf11d5fac00000000"], "id":1 }' localhost:8332 ##### createrawtransaction Create a transaction spending the given inputs and creating new outputs. curl -H 'content-type: application/json' --data-binary '{"jsonrpc": "2.0", "method": "createrawtransaction", "params": [[{"txid":"4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b","vout":0}],{"1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa":0.01}], "id":1 }' localhost:8332 ##### sendrawtransaction Adds transaction to the memory pool && relays it to the peers. curl -H 'content-type: application/json' --data-binary '{"jsonrpc": "2.0", "method": "sendrawtransaction", "params": ["01000000010000000000000000000000000000000000000000000000000000000000000000ffffffff4d04ffff001d0104455468652054696d65732030332f4a616e2f32303039204368616e63656c6c6f72206f6e206272696e6b206f66207365636f6e64206261696c6f757420666f722062616e6b73ffffffff0100f2052a01000000434104678afdb0fe5548271967f1a67130b7105cd6a828e03909a67962e0ea1f61deb649f6bc3f4cef38c4f35504e51ec112de5c384df7ba0b8d578a4c702b6bf11d5fac00000000"], "id":1 }' localhost:8332 ## 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 --segwit ``` `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 --segwit ``` ## 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 ```