Update README.md
This commit is contained in:
parent
a0193c024d
commit
080356a21a
209
README.md
209
README.md
|
@ -3,11 +3,214 @@ 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][doc-url]
|
||||
|
||||
- [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 it
|
||||
|
||||
```
|
||||
./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 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 <IP> Connect only to the specified node
|
||||
-d, --data-dir <PATH> Specify the database & configuration directory PATH
|
||||
--jsonrpc-apis <APIS> Specify the APIs available through the JSONRPC interface. APIS is a comma-delimited list of API name.
|
||||
--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> The port portion of the JSONRPC API server
|
||||
--only-net <NET> Only connect to nodes in network <NET> (ipv4 or ipv6)
|
||||
--port <PORT> Listen for connections on PORT
|
||||
-s, --seednode <IP> 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`
|
||||
|
|
Loading…
Reference in New Issue