diff --git a/README.md b/README.md index 317d4daa..6460bed9 100644 --- a/README.md +++ b/README.md @@ -3,11 +3,224 @@ The Parity Bitcoin client [![Build Status][travis-image]][travis-url] -[Internal Documentation][doc-url] +- [Install guide](#install-guide) -![Graph][graph] +- [Running tests](#running-tests) -[graph]: https://github.com/ethcore/parity-bitcoin/blob/master/tools/graph.svg +- [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/ethcore/parity-bitcoin.svg?token=DMFvZu71iaTbUYx9UypX&branch=master [travis-url]: https://travis-ci.com/ethcore/parity-bitcoin [doc-url]: https://ethcore.github.io/parity-bitcoin/pbtc/index.html + +## Install guide + +As for now `pbtc` can be installed only from source. It requires `rustc` and `cargo`. + +Minimal supported version is `rustc 1.13.0 (2c6933acc 2016-11-07)` + +#### Install rustc and cargo + +Both `rustc` and `cargo` are a part of rust toolchain. + +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). + +#### Clone and build pbtc + +Now let's clone `pbtc` and enter it's directory + +``` +git clone git@github.com:ethcore/parity-bitcoin.git +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` + +## Running tests + +`pbtc` has internal unit tests and it conforms to external integration tests + +#### Running unit tests + +Assuming that repo is already cloned, we can run unit tests with this command: + +``` +./tools/test.sh +``` + +#### Running external integration tests + +Running integration tests is automated, as regtests repo 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 mainnet, just start the client + +``` +./target/release/pbtc +``` + +To start syncing the testnet + +``` +./target/release/pbtc --testnet +``` + +To print syncing progress add `--print-to-console` flag + +``` +./target/release/pbtc --print-to-console +``` + +## Importing bitcoind database + +It it is possible to import existing bitcoind database: + +``` +# where $BITCOIND_DB is path to your bitcoind database eg. "/Users/marek/Library/Application Support" +./target/release/pbtc --print-to-console import "$BITCOIND_DB/Bitcoin/blocks" +``` + +By default import verifies imported the blocks. You can disable this, by adding `--skip-verification flag. + +``` +./target/release/pbtc --print-to-console 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 bitcoin client + +USAGE: + pbtc [FLAGS] [OPTIONS] [SUBCOMMAND] + +FLAGS: + --db-cache Sets db cache size + -h, --help Prints help information + --no-jsonrpc Disable the JSON-RPC API server + --print-to-console Send sync info to console + --regtest Use private network for regtest + --testnet Use the test network + -V, --version Prints version information + +OPTIONS: + -c, --connect Connect only to the specified node + -d, --data-dir Specify the database & configuration directory PATH + --jsonrpc-apis Specify the APIs available through the JSONRPC interface. APIS is a comma-delimited list of API name. + --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 The port portion of the JSONRPC API server + --only-net Only connect to nodes in network (ipv4 or ipv6) + --port Listen for connections on PORT + -s, --seednode Connect to a node to retrieve peer addresses, and disconnect + +SUBCOMMANDS: + help Prints this message or the help of the given subcommand(s) + import Import blocks from bitcoin core database +``` + +## JSON-RPC + +TODO + +## Logging + +This is a section only for dev / power users. + +You can enable detailed client logging by setting env variable `RUST_LOG` + +eg. + +``` +RUST_LOG=verification=info ./target/release/pbtc +``` + +`pbtc` started with this env variable will print all logs comming from `verification` module with verbosity `info` or higher + +Available log levels: + +- `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 +``` + +*note* `RUST_LOG` does not work together with command line option `--print-to-console` + +## Internal documentation + +Once released, `pbtc` documentation will be available [here][doc-url]. Meanwhile it's only possible to build it locally: + +``` +cd parity-bitcoin +cargo doc +open target/doc/pbtc/index.html +``` diff --git a/verification/src/accept_header.rs b/verification/src/accept_header.rs index 69765fbb..426fa712 100644 --- a/verification/src/accept_header.rs +++ b/verification/src/accept_header.rs @@ -84,7 +84,7 @@ impl<'a> HeaderRule for HeaderWork<'a> { if work == self.header.raw.bits { Ok(()) } else { - Err(Error::Difficulty) + Err(Error::Difficulty { expected: work, actual: self.header.raw.bits }) } } } diff --git a/verification/src/error.rs b/verification/src/error.rs index 8a28bec9..abd053c0 100644 --- a/verification/src/error.rs +++ b/verification/src/error.rs @@ -1,4 +1,4 @@ -use primitives::hash::H256; +use primitives::{H256, Compact}; #[derive(Debug, PartialEq)] /// All possible verification errors @@ -20,7 +20,7 @@ pub enum Error { /// One of the transactions is invalid (corresponding index and specific transaction error) Transaction(usize, TransactionError), /// nBits do not match difficulty rules - Difficulty, + Difficulty { expected: Compact, actual: Compact }, /// Invalid merkle root MerkleRoot, /// Coinbase spends too much