graphene freezed fork binaries for prosume blockchain. require the creation of 2 UIA in bitshares (PRS and TFT) for prosume-cli to work
Pierluigi Maori 321ff86ffa initial release 1 year ago
docs initial release 1 year ago
genesis initial release 1 year ago
pytools initial release 1 year ago
tools initial release 1 year ago
All_data.txt initial release 1 year ago
README.html initial release 1 year ago
README.md initial release 1 year ago
base58.py initial release 1 year ago
chainid initial release 1 year ago
cli_wallet initial release 1 year ago
delayed_node initial release 1 year ago
deriveKey.sh initial release 1 year ago
genUser.exp initial release 1 year ago
genprivkey.sh initial release 1 year ago
genuser.sh initial release 1 year ago
get_dev_key initial release 1 year ago
givemoney.sh initial release 1 year ago
issue_UIA.py initial release 1 year ago
prosume-cli-systemd.conf initial release 1 year ago
witness_node initial release 1 year ago

README.md

PROSUME BitShares Core Binary

Instructions from binary files prosume-bc-bin

==============

Instructions from source file bitshares-core

PROSUME BitShares Core is the PROSUME fork of BitShares blockchain implementation and command-line interface. The wallet is prosume-cli.

Visit BitShares.org to learn about BitShares

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 bin

Download the binary from the Mangrovia gitlab on epsorume-bc-bin

on the root you can find the main programs:

  • witness_node This is the node main binary
  • cli_wallet bitshares default cli_wallet
  • delayed_node this node is use for test purpose
  • chainid This binary return the chainid of the blockchain
  • get_dev_key This binary is used to generate user keys
  • prosumesystemd.conf This binary is used to have the systemd configuration for managing the daemon

By default we create a user to run the blockchain binary with named bcuser

so run:

useradd -m -s /bin/bash bcuser

there is no need to set a password for it.

once done let’s get the genesis file into genesis/my-genesis.json

by default we set all the fees to 0, then you can change some of the values in the genesis according to project needs

"block_interval": 20,
"maintenance_interval": 86400,
"maintenance_skip_slots": 3,
"committee_proposal_review_period": 1209600,
"maximum_transaction_size": 2048,
"maximum_block_size": 2048000000,
"maximum_time_until_expiration": 86400,
"maximum_proposal_lifetime": 2419200,
"maximum_asset_whitelist_authorities": 10,
"maximum_asset_feed_publishers": 10,
"maximum_witness_count": 100,
"maximum_committee_count": 100,
"maximum_authority_membership": 10,
"reserve_percent_of_fee": 2000,
"network_percent_of_fee": 2000,
"lifetime_referrer_percent_of_fee": 3000,
"cashback_vesting_period_seconds": 31536000,
"cashback_vesting_threshold": 10000000,
"count_non_member_votes": true,
"allow_non_member_whitelists": false,
"witness_pay_per_block": 100,
"worker_budget_per_day": "50000000000",
"max_predicate_opcode": 1,
"fee_liquidation_threshold": 10000000,
"accounts_per_fee_scale": 1000,
"account_fee_scale_bitshifts": 4,
"max_authority_depth": 2,
"extensions": []

Then we set the initial accounts in the genesis file

{
    "name": "init0",
    "owner_key": "BTSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "active_key": "BTSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "is_lifetime_member": true
}

the initial assets

"initial_balances": [{
    "owner": "BTSHRf2msE7VUh6E7wrAp3F7piRKHDVbqcz5",
    "asset_symbol": "BTS",
    "amount": "1000000000000000"
    }
],

assign it to the user that should own the blockchain

and then define the initial witnesses in

"initial_witness_candidates": [{
    "owner_name": "init0",
    "block_signing_key": "BTSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
    },{

that should reflect the active key of the initial account

add then all the users in the initial_committee_candidates

"initial_committee_candidates": [{
    "owner_name": "init0"
},{

adjust then the immutable parameters

"immutable_parameters": {
    "min_committee_member_count": 5,
    "min_witness_count": 5,
    "num_special_accounts": 0,
    "num_special_assets": 0
}

If you want you can recompile the binaries with the genesis embedded, follow the instruction in Getting Started

Create the users

This part helps you to generate new users to be defined as initial accounts or as new users for the blockchain.

This can be done with cli_wallet or with get_dev_key

using cli_wallet launch

./cli_wallet --suggest-brain-key

with response:

{
    "brain_priv_key": "BEAMING PHENYL SEAMER PLOCE SHETH UNMOOR PICCOLO RILE ISOTOPE LALL VAGINAL TASTILY VISUAL REMILL AROON VITALIC",
    "wif_priv_key": "5K7hHsr8vfL1D6kVYfz5qEJVQWGjsUWg4XpzsUG98Tn3EoTfP6a",
    "pub_key": "BTS7WsATEi1CW1kN7njenfCjAJRpnYUR6cSAVFt6ZrkVQvVxCBfu2"
}

use the pub_key as owner_key and save the wif_priv_key as it’s the private of it and the brain_priv_key as a way to recover the keys if lost.

using get_dev_key launch

./get_dev_key PREFIXSEED user1 user2 user3

with response like:

[{"private_key":"5KJZnAJLuCNnGV7McZ4FB6D2Q4ntA1XjVLd6u1k7a9C36mJEEdh","public_key":"TEST6YoHyPyqeHgbs6zXd3eZHVheeT4F2BVD5PGr7VRg7koUCWvHYE","address":"TESTAJoKZqnpD6XzwNZ9gpk3KrE33QbaNqz1M"},
{"private_key":"5JJP3BcaaydsdF7anQjSa4vvbTyjKHZWnvwHupQGZepoq6XANXB","public_key":"TEST7T5XdWo3dzvGtzqinixjYYCjbbgmyABJC1PEKijP4apLG4NgJ8","address":"TESTPj31YZiuGUjGzFDw2pb6mcqF7U2tqh5Fw"},
{"private_key":"5J2AQyM68u7T69HUY143zSZk1frWwsWg7sBHg2X39NsnB4gz7bG","public_key":"TEST51sWsPC17ZeQF5G1yZNZ8hJUdWWLRA9dryq4PYf7F6ucCMULvG","address":"TESTHjEUZvjUEEhYpwJ9P8qB35pe9fareR7Wa"},
{"private_key":"5JEPUkGTJkbCmB4Yd7jEKbey6sBaosXjVWDey4FWcRcE73pgcxd","public_key":"TEST8ESMESfyoQZJRuPHH9ipjqQx5ub48DbLg4sFtRea7njZ6CZ1mH","address":"TESTM22mSafknaPoFfheuy2NLMVKtsdxgPd2P"},
{"private_key":"5JLJM1uGLT4YhnFtf55Q9pmeVaik3MpdRVnG3dHrU4NF9ApvooC","public_key":"TEST8C8qWTyFjSeMEpKbSVe3JWjWaT2GFiNvBLap4L3xwAEoL54thh","address":"TESTGNQ8U2R6Jw5WGz8MnzcnyCy3ZshnYybx9"},
{"private_key":"5HtEFk44oxqwzgisXXZdqVtFVZi7MtRb6zSqGCtf2batXeGiwna","public_key":"TEST7darzT9LVBVm5ppyS6smFbbpC7J5whfSRjwxqeUvZPFt57K7E7","address":"TEST6MQccyUo3G4uVFHgjGZyno8mCCBV2Zxyk"}]

get_dev_key use the combination of the seed and the username to generate a valid hash with the private key / public key pair and user address to be used for each user.

Create the assets

as Prosume, we don’t use the default asset (BTS) but we generate 2 UIA (User Issued Assets) to be used as Payment token and Transaction Info token

The Payment token (usually PRS == Prosume) is used to pay the energy consumption or production, this asset must have a fixed convertion rate with the FIAT money that the company (utility) has to define. The utility will allow always to covert the PRS against the FIAT

The transaction token (usually TFT == Transaction Fee Token) is used instead for system communications, each meter reading, price update, eventually exchange offer or order of payment, are transfered to the users using the TFT, with a fixed amount (usually 1) and it use the transaction MEMO as information carrier, encrypting it always for the TO and the FROM (sender and receiver) of the command. Usually all the TFT communication are always between someone and the utility.

to generate the UIA we have 2 methods, using the web ui logging into it with the nathan user or the utility account

the second method is using the cli_wallet

log into the cli_wallet as nathan or utility account, unlock the user and launch this command

create_asset init0 PRS 4 { “max_supply”: “1000000000”, “market_fee_percent”: 0, “max_market_fee”: “10”, “issuer_permissions”: 0, “flags”: 0, “core_exchange_rate”: { “base”: { “amount”: 100, “asset_id”: “1.3.0” }, “quote”: { “amount”: 100, “asset_id”: “1.3.1” } }, “whitelist_authorities”: [], “blacklist_authorities”: [], “whitelist_markets”: [], “blacklist_markets”: [], “description”: “Prosume Payment Token”, “extensions”: {} } null true

create_asset init0 TFT 4 { “max_supply”: “1000000000”, “market_fee_percent”: 0, “max_market_fee”: “10”, “issuer_permissions”: 0, “flags”: 0, “core_exchange_rate”: { “base”: { “amount”: 100, “asset_id”: “1.3.0” }, “quote”: { “amount”: 100, “asset_id”: “1.3.1” } }, “whitelist_authorities”: [], “blacklist_authorities”: [], “whitelist_markets”: [], “blacklist_markets”: [], “description”: “Prosume Transaction Token”, “extensions”: {} } null true

then issue the asset to the utility user

issue_asset evolvere 1000000000 PRS "Initial Assignment" true
issue_asset evolvere 1000000000 TFT "Initial Assignment" true

Getting Started

Build instructions and additional documentation are available in the wiki.

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

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
cmake -DCMAKE_BUILD_TYPE=RelWithDebInfo .
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: Versions of Boost 1.57 through 1.69 are supported. Newer versions may work, but have not been tested. If your system came pre-installed with a version of Boost that you do not wish to use, you may manually build your preferred version and use it with BitShares by specifying it on the CMake command line.

Example: cmake -DBOOST_ROOT=/path/to/boost .

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

NOTE: BitShares now supports Ubuntu 18.04 LTS

NOTE: BitShares now supports OpenSSL 1.1.0

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. 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 mode by using some of the commands detailed in Memory reduction for nodes.

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

PROSUME BitShares Core is mantained by Prosume s.r.l. and developed by Mangrovia Blockchain Solutions.