BitShares Blockchain implementation and command-line interface
C++ CMake Other
Switch branches/tags
Clone or download
Pull request Compare This branch is 1364 commits ahead of cryptonomex:master.
abitmore Merge pull request #1167 from bitshares/update-readme
Update README.md for master branch
Latest commit 58969c2 Jul 27, 2018
Permalink
Failed to load latest commit information.
.github/ISSUE_TEMPLATE Add: Build Error Template Jun 6, 2018
CMakeModules Clean up CMake modules Jan 13, 2017
docker [docker] Properly use --plugins from environment Jan 10, 2018
docs @ bd792d0 Update submodules Jun 4, 2017
libraries Set MAINNET hard fork time to 2018-07-19T14:02:00Z Jun 11, 2018
programs Remove rpc log level descrption from config.ini May 16, 2018
tests Added unit test for TEMP_ACCOUNT fix Jun 10, 2018
.gitignore Add genesis.json to .gitignore to exclude from git grep Jan 17, 2017
.gitmodules Update submodules Jan 17, 2017
.travis.yml Fixup: build icons & Remove: tests from build script Mar 21, 2018
CMakeLists.txt Replace readline library, Issue 673 (#685) Mar 9, 2018
CONTRIBUTORS.txt Placeholder to list contributors May 21, 2017
Dockerfile Modified Dockerfile to work with new docker cloud version Jun 6, 2018
Doxyfile sync project description in doxyfile Jun 15, 2018
LICENSE.txt Placeholder to list contributors May 21, 2017
README-docker.md update baseimage Jun 6, 2018
README.md Merge pull request #1167 from bitshares/update-readme Jul 27, 2018
Vagrantfile added Vagrantfile - automates dev env creation; contains Ubuntu 14.04… Jul 22, 2015
genesis.json checking in the gensis file Oct 13, 2015
gui_version Update gui_version May 22, 2017
testnet-shared-accounts.txt Save more values for testnet genesis Aug 17, 2015
testnet-shared-balances.txt Share some private keys for testnet balances Jul 8, 2015
testnet-shared-committee-members.txt Save more values for testnet genesis Aug 17, 2015
testnet-shared-private-keys.txt Share some private keys for testnet balances Jul 8, 2015
testnet-shared-vesting-balances.txt Add test vesting balances to copy into testnet genesis Aug 14, 2015
testnet-shared-witnesses.txt Save more values for testnet genesis Aug 17, 2015

README.md

BitShares Core

Build Status:

master develop hardfork testnet bitshares-fc

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

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

NOTE: The official BitShares git repository location, default branch, and submodule remotes were recently changed. Existing repositories can be updated with the following steps:

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 sync --recursive
git submodule update --init --recursive

Getting Started

Build instructions and additional documentation are available in the wiki.

We recommend building on Ubuntu 16.04 LTS (64-bit), and the build dependencies may be installed with:

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

To build after all dependencies are installed:

git clone https://github.com/bitshares/bitshares-core.git
cd bitshares-core
git checkout <LATEST_RELEASE_TAG>
git submodule update --init --recursive
cmake -DCMAKE_BUILD_TYPE=RelWithDebInfo .
make

NOTE: BitShares requires an OpenSSL version in the 1.0.x series. OpenSSL 1.1.0 and newer are NOT supported. If your system OpenSSL version is newer, then you will need to manually provide an older version of OpenSSL and specify it to CMake using -DOPENSSL_INCLUDE_DIR, -DOPENSSL_SSL_LIBRARY, and -DOPENSSL_CRYPTO_LIBRARY.

NOTE: BitShares requires a Boost version in the range [1.57, 1.65]. Versions earlier than 1.57 or newer than 1.65 are NOT supported. If your system Boost version is newer, then you will need to manually build an older version of Boost and specify it to CMake using DBOOST_ROOT.

NOTE: BitShares requires a 64-bit operating system to build, and will not build on a 32-bit OS.

After building, the witness node can be launched with:

./programs/witness_node/witness_node

The node will automatically create a data directory including a config file. It may take several hours to fully synchronize the blockchain. After syncing, you can exit the node using Ctrl+C and setup the command-line wallet by editing witness_node_data_dir/config.ini as follows:

rpc-endpoint = 127.0.0.1:8090

IMPORTANT: By default the witness node will start in reduced memory ram mode by using some of the commands detailed in Memory reduction for nodes. In order to run a full node with all the account history you need to remove partial-operations and max-ops-per-account from your config file. Please note that currently(2018-07-02) a full node will need more than 100GB of RAM to operate and required memory is growing fast. Consider the following table before running a node:

Default Full Minimal ElasticSearch
20G RAM 120G RAM 4G RAM 200G SSD HD, 16G RAM

After starting the witness node again, in a separate terminal you can run:

./programs/cli_wallet/cli_wallet

Set your inital password:

>>> set_password <PASSWORD>
>>> unlock <PASSWORD>

To import your initial balance:

>>> import_balance <ACCOUNT NAME> [<WIF_KEY>] true

If you send private keys over this connection, rpc-endpoint should be bound to localhost for security.

Use help to see all available wallet commands. Source definition and listing of all commands is available here.

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

Using the API

We provide several different API's. Each API has its own ID. When running witness_node, initially two API's are available: API 0 provides read-only access to the database, while API 1 is used to login and gain access to additional, restricted API's.

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/rpc
{"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":[]}]}

API 0 is accessible using regular JSON-RPC:

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

Accessing restricted API's

You can restrict 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 wallet:

{
   "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.

Since the network_node API requires login, it is only accessible over the websocket RPC. Our doxygen documentation contains the most up-to-date information about API's for the witness node and the wallet. If you want information which is not available from an API, it might be available from the database; it is fairly simple to write API methods to expose database methods.

FAQ

  • Is there a way to generate help with parameter names and method descriptions?

    Yes. Documentation of the code base, including APIs, can be generated using Doxygen. Simply run doxygen in this directory.

    If both Doxygen and perl are available in your build environment, the CLI wallet's help and gethelp commands will display help generated from the doxygen documentation.

    If your CLI wallet's help command displays descriptions without parameter names like signed_transaction transfer(string, string, string, string, string, bool) it means CMake was unable to find Doxygen or perl during configuration. If found, the output should look like this: signed_transaction transfer(string from, string to, string amount, string asset_symbol, string memo, bool broadcast)

  • Is there a way to allow external program to drive cli_wallet via websocket, JSONRPC, or HTTP?

    Yes. External programs may connect to the CLI wallet and make its calls over a websockets API. To do this, run the wallet in server mode, i.e. cli_wallet -s "127.0.0.1:9999" and then have the external program connect to it over the specified port (in this example, port 9999).

  • Is there a way to access methods which require login over HTTP?

    No. Login is inherently a stateful process (logging in changes what the server will do for certain requests, that's kind of the point of having it). If you need to track state across HTTP RPC calls, you must maintain a session across multiple connections. This is a famous source of security vulnerabilities for HTTP applications. Additionally, HTTP is not really designed for "server push" notifications, and we would have to figure out a way to queue notifications for a polling client.

    Websockets solves all these problems. If you need to access Graphene's stateful methods, you need to use Websockets.

  • What is the meaning of a.b.c numbers?

    The first number specifies the space. Space 1 is for protocol objects, 2 is for implementation objects. Protocol space objects can appear on the wire, for example in the binary form of transactions. Implementation space objects cannot appear on the wire and solely exist for implementation purposes, such as optimization or internal bookkeeping.

    The second number specifies the type. The type of the object determines what fields it has. For a complete list of type ID's, see enum object_type and enum impl_object_type in types.hpp.

    The third number specifies the instance. The instance of the object is different for each individual object.

  • The answer to the previous question was really confusing. Can you make it clearer?

    All account ID's are of the form 1.2.x. If you were the 9735th account to be registered, your account's ID will be 1.2.9735. Account 0 is special (it's the "committee account," which is controlled by the committee members and has a few abilities and restrictions other accounts do not).

    All asset ID's are of the form 1.3.x. If you were the 29th asset to be registered, your asset's ID will be 1.3.29. Asset 0 is special (it's BTS, which is considered the "core asset").

    The first and second number together identify the kind of thing you're talking about (1.2 for accounts, 1.3 for assets). The third number identifies the particular thing.

  • How do I get the network_add_nodes command to work? Why is it so complicated?

    You need to follow the instructions in the "Accessing restricted API's" section to allow a username/password access to the network_node API. Then you need to pass the username/password to the cli_wallet on the command line or in a config file.

    It's set up this way so that the default configuration is secure even if the RPC port is publicly accessible. It's fine if your witness_node allows the general public to query the database or broadcast transactions (in fact, this is how the hosted web UI works). It's less fine if your witness_node allows the general public to control which p2p nodes it's connecting to. Therefore the API to add p2p connections needs to be set up with proper access controls.

License

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