BitShares-Core  4.0.0
BitShares blockchain implementation and command-line interface software
BitShares Core

BitShares Core is the BitShares blockchain implementation and command-line interface. The web browser based wallet is BitShares UI.

Visit BitShares.org to learn about BitShares and join the community at BitSharesTalk.org.

Information for developers can be found in the BitShares Developer Portal. Users interested in how BitShares works can go to the BitShares Documentation site.

Getting Started

Build instructions and additional documentation are available in the Wiki.

Build

We recommend building on Ubuntu 16.04 LTS (64-bit)

Build Dependencies:

sudo apt-get update
sudo apt-get install autoconf cmake make automake libtool git libboost-all-dev libssl-dev g++ libcurl4-openssl-dev doxygen

Build Script:

git clone https://github.com/bitshares/bitshares-core.git
cd bitshares-core
git checkout master # may substitute "master" with current release tag
git submodule update --init --recursive
mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
make

Upgrade Script: (prepend to the Build Script above if you built a prior release):

git remote set-url origin https://github.com/bitshares/bitshares-core.git
git checkout master
git remote set-head origin --auto
git pull
git submodule update --init --recursive # this command may fail
git submodule sync --recursive
git submodule update --init --recursive

NOTE:

Run the node software

After Building, the node software witness_node can be launched with:

./programs/witness_node/witness_node

The node will automatically create a witness_node_data_dir directory with some config files. The blockchain data will be stored in the directory too. It may take several hours to fully synchronize the blockchain.

You can exit the node using Ctrl+C. Please be aware that the node may need some time (usually a few minutes) to exit cleanly, please be patient.

IMPORTANT: By default the node will start in reduced memory mode by using some of the commands detailed in Memory reduction for nodes. In order to run a full node with all the account histories (which is usually not necessary) you need to remove partial-operations and max-ops-per-account from your config file. Please note that currently(2018-10-17) a full node will need more than 160GB of RAM to operate and required memory is growing fast. Consider the following table as minimal requirements before running a node:

Default Full Minimal ElasticSearch
150G HDD, 16G RAM 640G SSD, 64G RAM * 120G HDD, 4G RAM 1TB SSD, 32G RAM

To use the command-line wallet or other wallets / clients with the node, the node need to be started with RPC connection enabled, which can be done by starting the node with the --rpc-endpoint parameter, E.G.

./programs/witness_node/witness_node --rpc-endpoint=127.0.0.1:8090

or configure it in the config file by editing witness_node_data_dir/config.ini as follows:

rpc-endpoint = 127.0.0.1:8090

You can run the program with --help parameter to see more info:

./programs/witness_node/witness_node --help

Run the command-line wallet software

To start the command-line wallet, in a separate terminal you can run:

./programs/cli_wallet/cli_wallet

IMPORTANT: The cli_wallet or API interfaces to the witness node wouldn't be fully functional unless the witness node is fully synchronized with the blockchain. The cli_wallet command info will show result head_block_age which will tell you how far you are from the live current block of the blockchain.

To check your current block:

new >>> info

To query the blockchain, E.G. get info about an account:

new >>> get_account <account_name_or_id>

If you need to transact with your account but not only query, firstly set your initial password and unlock the wallet:

To be able to transact with your account, import the corresponding private keys:

unlocked >>> import_key <ACCOUNT_NAME> <WIF_KEY>

The private keys will be encrypted and stored in the wallet file, the file name is wallet.json by default. The private keys are accessible when the wallet is unlocked.

unlocked >>> dump_private_keys

Use lock command to make the private keys inaccessible. There is no auto-lock feature so far.

unlocked >>> lock

To import your initial (genesis) balances, import the private keys corresponding to the balances:

unlocked >>> import_balance <ACCOUNT_NAME> [<WIF_KEY> ...] true

Use help to see all available wallet commands.

>>> help

Use gethelp <COMMAND> to see more info about individual commands. E.G.

>>> gethelp get_order_book

The definition of all commands is available in the wallet.hpp souce code file. Corresponding documentation can be found in the Doxygen documentation.

You can run the program with --help parameter to see more info:

./programs/cli_wallet/cli_wallet --help

There is also some info in the Wiki.

Support

Technical support is available in the BitSharesTalk technical support subforum.

BitShares Core bugs can be reported directly to the issue tracker.

BitShares UI bugs should be reported to the UI issue tracker.

Up to date online Doxygen documentation can be found at Doxygen.BitShares.org.

Using the API

Node API

The witness_node software provides several different API's, known as node API.

Each API has its own ID and a name. When running witness_node with RPC connection enabled, initially two API's are available:

Here is an example using wscat package from npm for websockets:

$ npm install -g wscat
$ wscat -c ws://127.0.0.1:8090
> {"id":1, "method":"call", "params":[0,"get_accounts",[["1.2.0"]]]}
< {"id":1,"result":[{"id":"1.2.0","annotations":[],"membership_expiration_date":"1969-12-31T23:59:59","registrar":"1.2.0","referrer":"1.2.0","lifetime_referrer":"1.2.0","network_fee_percentage":2000,"lifetime_referrer_fee_percentage":8000,"referrer_rewards_percentage":0,"name":"committee-account","owner":{"weight_threshold":1,"account_auths":[],"key_auths":[],"address_auths":[]},"active":{"weight_threshold":6,"account_auths":[["1.2.5",1],["1.2.6",1],["1.2.7",1],["1.2.8",1],["1.2.9",1],["1.2.10",1],["1.2.11",1],["1.2.12",1],["1.2.13",1],["1.2.14",1]],"key_auths":[],"address_auths":[]},"options":{"memo_key":"GPH1111111111111111111111111111111114T1Anm","voting_account":"1.2.0","num_witness":0,"num_committee":0,"votes":[],"extensions":[]},"statistics":"2.7.0","whitelisting_accounts":[],"blacklisting_accounts":[]}]}

We can do the same thing using an HTTP client such as curl for API's which do not require login or other session state:

$ curl --data '{"jsonrpc": "2.0", "method": "call", "params": [0, "get_accounts", [["1.2.0"]]], "id": 1}' http://127.0.0.1:8090/
{"id":1,"result":[{"id":"1.2.0","annotations":[],"membership_expiration_date":"1969-12-31T23:59:59","registrar":"1.2.0","referrer":"1.2.0","lifetime_referrer":"1.2.0","network_fee_percentage":2000,"lifetime_referrer_fee_percentage":8000,"referrer_rewards_percentage":0,"name":"committee-account","owner":{"weight_threshold":1,"account_auths":[],"key_auths":[],"address_auths":[]},"active":{"weight_threshold":6,"account_auths":[["1.2.5",1],["1.2.6",1],["1.2.7",1],["1.2.8",1],["1.2.9",1],["1.2.10",1],["1.2.11",1],["1.2.12",1],["1.2.13",1],["1.2.14",1]],"key_auths":[],"address_auths":[]},"options":{"memo_key":"GPH1111111111111111111111111111111114T1Anm","voting_account":"1.2.0","num_witness":0,"num_committee":0,"votes":[],"extensions":[]},"statistics":"2.7.0","whitelisting_accounts":[],"blacklisting_accounts":[]}]}

When using an HTTP client, the API ID can be replaced by the API name, E.G.

$ curl --data '{"jsonrpc": "2.0", "method": "call", "params": ["database", "get_accounts", [["1.2.0"]]], "id": 1}' http://127.0.0.1:8090/

The definition of all node API's is available in the source code files including database_api.hpp and api.hpp. Corresponding documentation can be found in Doxygen:

Wallet API

The cli_wallet program can also be configured to serve all of its commands as API's, known as wallet API.

Start cli_wallet with RPC connection enabled:

$ ./programs/cli_wallet/cli_wallet --rpc-endpoint=127.0.0.8091

Access the wallet API using an HTTP client:

$ curl --data '{"jsonrpc": "2.0", "method": "info", "params": [], "id": 1}' http://127.0.0.1:8091/rpc
$ curl --data '{"jsonrpc": "2.0", "method": "get_account", "params": ["1.2.0"], "id": 1}' http://127.0.0.1:8091/rpc

Note: The syntax to access wallet API is a bit different than accessing node API.

Important:

Accessing restrictable node API's

You can restrict node API's to particular users by specifying an api-access file in config.ini or by using the --api-access /full/path/to/api-access.json startup node command. Here is an example api-access file which allows user bytemaster with password supersecret to access four different API's, while allowing any other user to access the three public API's necessary to use the node:

{
   "permission_map" :
   [
      [
         "bytemaster",
         {
            "password_hash_b64" : "9e9GF7ooXVb9k4BoSfNIPTelXeGOZ5DrgOYMj94elaY=",
            "password_salt_b64" : "INDdM6iCi/8=",
            "allowed_apis" : ["database_api", "network_broadcast_api", "history_api", "network_node_api"]
         }
      ],
      [
         "*",
         {
            "password_hash_b64" : "*",
            "password_salt_b64" : "*",
            "allowed_apis" : ["database_api", "network_broadcast_api", "history_api"]
         }
      ]
   ]
}

Passwords are stored in base64 as salted sha256 hashes. A simple Python script, saltpass.py is avaliable to obtain hash and salt values from a password. A single asterisk "*" may be specified as username or password hash to accept any value.

With the above configuration, here is an example of how to call add_node from the network_node API:

{"id":1, "method":"call", "params":[1,"login",["bytemaster", "supersecret"]]}
{"id":2, "method":"call", "params":[1,"network_node",[]]}
{"id":3, "method":"call", "params":[2,"add_node",["127.0.0.1:9090"]]}

Note, the call to network_node is necessary to obtain the correct API identifier for the network API. It is not guaranteed that the network API identifier will always be 2.

The restricted API's are accessible via HTTP too using basic access authentication. E.G.

$ curl --data '{"jsonrpc": "2.0", "method": "call", "params": ["network_node", "add_node", ["127.0.0.1:9090"]], "id": 1}' http://bytemaster:[email protected]:8090/

Our doxygen documentation contains the most up-to-date information about API's for the node and the wallet.

FAQ

License

BitShares Core is under the MIT license. See LICENSE for more information.