HIVE SONs Installation Guide - Manual Install
How to set up a HIVE Sidechain Operator Node (SON) by building the source code
The process of manually installing a HIVE SON is similar to installing a Witness Node. This is a step-by-step guide for setting up a new HIVE SON and having it running on Peerplays blockchain.
SONs are valuable as they allow the transfer of assets between the Peerplays and HIVE.
We ask that you review the requirements for setting up a SON before proceeding and running a manual installation following this guide.
Here’s an outline of the steps for installing a HIVE-enabled SON:
  1. 1.
    Preparing the Environment
  2. 2.
    Build Peerplays
  3. 3.
    Connect to the HIVE Network and Generate an Address
  4. 4.
    Create a SON Account
  5. 5.
    Configure the SON
  6. 6.
    Start the SON
  7. 7.
    (Optional) Automatically Start the Node as a Service
In order to set up a SON node, you must have 110 PPY. This amount covers the upgraded account (which costs 5 PPY) and funds two vesting balances (50 PPY each). The remaining funds are for paying the various transaction fees while setting up the node. Please see Obtaining Your First Tokens for more information.
Note that these fees will likely change over time as recommended by the Committee of Advisors.

1. Preparing the Environment

1.1. Hardware Requirements

Please review the general SON hardware requirements.
For the manual install, we'll be using a self-hosted HIVE node. The requirements that we'll need for this guide would be as follows (as per the hardware requirements doc):
HIVE node type
CPU
Memory
Storage
Bandwidth
OS
Self-Hosted, Reduced Storage
2 Cores
16GB
150GB SSD
1Gbps
Ubuntu 20.04
This table shows the bare minimum memory requirements for operating the node. If you run into some errors, chances are, you need more memory. We ask that you review Installing vs Operating for more details.

1.2. Installing the required dependencies

The following dependencies are important for a clean install on Ubuntu 20.04 LTS:
1
sudo apt update
2
sudo apt install -y apt-utils autoconf bash build-essential ca-certificates \
3
cmake dnsutils doxygen expect git graphviz libboost1.67-all-dev libbz2-dev \
4
libcurl4-openssl-dev libncurses-dev libreadline-dev libsnappy-dev \
5
libssl-dev libtool libzip-dev libzmq3-dev locales mc nano net-tools \
6
ntp openssh-server pkg-config perl python3 python3-jinja2 sudo wget
Copied!

2. Build Peerplays

Now you must build Peerplays with the official source code from GitLab.
1
cd $HOME
2
git clone https://gitlab.com/PBSA/peerplays.git
3
cd peerplays
4
git checkout master # --> replace with most recent tag
5
git submodule update --init --recursive
6
git submodule sync --recursive
7
mkdir build
8
cd build
9
cmake -DCMAKE_BUILD_TYPE=Release ..
10
make -j4 cli_wallet witness_node
Copied!
Note: "master" can be replaced with the most recent release tag.
For example:
git checkout 1.5.13
where 1.5.13 is the latest production release tag as of July 2021. The list of releases is located here.
Note: Your binaries will be located at:
  • $HOME/peerplays/build/programs/cli_wallet/cli_wallet
  • $HOME/peerplays/build/programs/witness_node/witness_node
Copy them to an empty directory:
1
mkdir $HOME/peerplays-mainnet
2
cp $HOME/peerplays/build/programs/cli_wallet/cli_wallet $HOME/peerplays-mainnet/
3
cp $HOME/peerplays/build/programs/witness_node/witness_node $HOME/peerplays-mainnet/
Copied!

2.1. Start the node to generate the config.ini file

We start the SON Node with the witness_node command even though we want to set up this node as a HIVE SON. This is because the same program is used to operate different types of nodes depending on how we configure the program. For more information on this, see Peerplays Node Types.
If you have installed the blockchain following the above steps, the HIVE node can be started as follows:
1
cd $HOME/peerplays-mainnet/
2
./witness_node
Copied!
Running the witness_node program will create a config.ini file with some default settings. We'll need to edit the config file so we'll stop the program for now. Stop the program with ctrl + c.

2.2. Editing the config file

This is a checklist of what you need for successfully running a SON:
  1. 1.
    Your SON ID
  2. 2.
    SON owner Peerplays account active public and private key
  3. 3.
    SON owner Peerplays account should be funded
  4. 4.
    Bitcoin node IP address
  5. 5.
    Bitcoin node RPC port
  6. 6.
    Bitcoin node ZMQ port
  7. 7.
    Encrypted empty bitcoin wallet
  8. 8.
    Bitcoin wallet password
  9. 9.
    Bitcoin public/private keys used by your SON node
  10. 10.
    Hive node RPC endpoint (check the list of available public nodes at https://developers.hive.io/quickstart/)
  11. 11.
    Hive node RPC basic auth user name, if used
  12. 12.
    Hive node RPC basic auth password, if used
  13. 13.
    Hive account name and active private key used by your SON
You can get Hive account here https://signup.hive.io/
Depending on the account provider you choose, the process of obtaining private keys is different. For 3Speak provider, you can get them from your 3Speak account settings
These are the sections of the default config file you need to change:
1
# Space-separated list of plugins to activate
2
plugins = account_history accounts_list affiliate_stats bookie market_history witness
3
4
...
5
# ==============================================================================
6
# peerplays_sidechain plugin options
7
# ==============================================================================
8
# ID of SON controlled by this node (e.g. "1.33.5", quotes are required)
9
# son-id =
10
# IDs of multiple SONs controlled by this node (e.g. ["1.33.5", "1.33.6"], quotes are required)
11
# son-ids =
12
# Tuple of [PublicKey, WIF private key] (may specify multiple times)
13
peerplays-private-key = ["PPY6MRyAjQq8ud7hVNYcfnVPJqcVpscN5So8BhtHuGYqET5GDW5CV","5KQwrPbwdL6PhXujxW37FSSQZ1JiwsST4cqQzDeyXtP79zkvFD3"]
14
# Sidechain retry throttling threshold
15
sidechain-retry-threshold = 150
16
# Outputs RPC calls to console
17
debug-rpc-calls = 0
18
# Bitcoin sidechain handler enabled
19
bitcoin-sidechain-enabled = 0
20
# IP address of Bitcoin node
21
bitcoin-node-ip = 127.0.0.1
22
# ZMQ port of Bitcoin node
23
bitcoin-node-zmq-port = 11111
24
# RPC port of Bitcoin node
25
bitcoin-node-rpc-port = 8332
26
# Bitcoin RPC user
27
bitcoin-node-rpc-user = 1
28
# Bitcoin RPC password
29
bitcoin-node-rpc-password = 1
30
# Bitcoin wallet
31
# bitcoin-wallet =
32
# Bitcoin wallet password
33
# bitcoin-wallet-password =
34
# Tuple of [Bitcoin public key, Bitcoin private key] (may specify multiple times)
35
bitcoin-private-key = ["02d0f137e717fb3aab7aff99904001d49a0a636c5e1342f8927a4ba2eaee8e9772","cVN31uC9sTEr392DLVUEjrtMgLA8Yb3fpYmTRj7bomTm6nn2ANPr"]
36
# Hive sidechain handler enabled
37
hive-sidechain-enabled = 0
38
# Hive node RPC URL [http[s]://]host[:port]
39
hive-node-rpc-url = 127.0.0.1:28090
40
# Hive node RPC user
41
# hive-node-rpc-user =
42
# Hive node RPC password
43
# hive-node-rpc-password =
44
# Tuple of [Hive public key, Hive private key] (may specify multiple times)
45
hive-private-key = ["TST6LLegbAgLAy28EHrffBVuANFWcFgmqRMW13wBmTExqFE9SCkg4","5JNHfZYKGaomSFvd4NUdQ9qMcEAC43kujbfjueTHpVapX1Kzq2n"]
Copied!
This is how you should edit your config file:
1
---> Add peerplays_sidechain to plugins option
2
# Space-separated list of plugins to activate
3
plugins = account_history accounts_list affiliate_stats bookie market_history witness peerplays_sidechain
4
# ==============================================================================
5
# peerplays_sidechain plugin options
6
# ==============================================================================
7
---> Add your son id here
8
# ID of SON controlled by this node (e.g. "1.33.5", quotes are required)
9
# son-id =
10
---> Leave as it is (dev feature, for multiple sons support)
11
# IDs of multiple SONs controlled by this node (e.g. ["1.33.5", "1.33.6"], quotes are required)
12
# son-ids =
13
---> Add your son owner account public/private key pair (account needs to be funded, for paying fees). Public key should be the same one as in SON object's signing_key field
14
# Tuple of [PublicKey, WIF private key] (may specify multiple times)
15
peerplays-private-key = ["PPY6MRyAjQq8ud7hVNYcfnVPJqcVpscN5So8BhtHuGYqET5GDW5CV","5KQwrPbwdL6PhXujxW37FSSQZ1JiwsST4cqQzDeyXtP79zkvFD3"]
16
---> Leave as it is
17
# Sidechain retry throttling threshold
18
sidechain-retry-threshold = 150
19
---> Leave as it is (dev feature, if set to 1, you will see RPC communication in the logs, which is very extensive)
20
# Outputs RPC calls to console
21
debug-rpc-calls = 0
22
---> Set to 1. Enables bitcoin sidechain handler
23
# Bitcoin sidechain handler enabled
24
bitcoin-sidechain-enabled = 0
25
---> Set to your bitcoin node ip address
26
# IP address of Bitcoin node
27
bitcoin-node-ip = 127.0.0.1
28
---> Set to your bitcoin node zmq port
29
# ZMQ port of Bitcoin node
30
bitcoin-node-zmq-port = 11111
31
---> Set to your bitcoin node RPC port
32
# RPC port of Bitcoin node
33
bitcoin-node-rpc-port = 8332
34
---> Set to your bitcoin node RPC user, if needed (for basic http auth)
35
# Bitcoin RPC user
36
bitcoin-node-rpc-user = 1
37
---> Set to your bitcoin node RPC password, if needed (for basic http auth)
38
# Bitcoin RPC password
39
bitcoin-node-rpc-password = 1
40
---> Set to a son bitcoin wallet name (you need to create it on your own)
41
# Bitcoin wallet
42
# bitcoin-wallet =
43
---> Set to a son bitcoin wallet password (you need to set it up on your own)
44
# Bitcoin wallet password
45
# bitcoin-wallet-password =
46
---> Set to your SON node bitcoin public/private key pair. Public key should be the same as one in SON object's sidechain_public_keys map
47
# Tuple of [PublicKey, WIF private key] (may specify multiple times)
48
bitcoin-private-key = ["02d0f137e717fb3aab7aff99904001d49a0a636c5e1342f8927a4ba2eaee8e9772","cVN31uC9sTEr392DLVUEjrtMgLA8Yb3fpYmTRj7bomTm6nn2ANPr"]
49
---> Set to 1. Enables Hive sidechain handler
50
# Hive sidechain handler enabled
51
hive-sidechain-enabled = 0
52
---> Set to your Hive node RPC endpoint. You can also use public ones (https://developers.hive.io/quickstart/)
53
# Hive node RPC URL [http[s]://]host[:port]
54
hive-node-rpc-url = 127.0.0.1:28090
55
---> Set to your Hive node RPC user, if needed (for basic http auth)
56
# Hive node RPC user
57
# hive-node-rpc-user =
58
---> Set to your Hive node RPC password, if needed (for basic http auth)
59
# Hive node RPC password
60
# hive-node-rpc-password =
61
---> Set to your SON node Hive account/active private key. Account name should be the same as one in SON object's sidechain_public_keys map
62
# Tuple of [Hive public key, Hive private key] (may specify multiple times)
63
hive-private-key = ["my-hive-account-name","5JNHfZYKGaomSFvd4NUdQ9qMcEAC43kujbfjueTHpVapX1Kzq2n"]
Copied!
You can always take a look at the Peerplays QA environment, as an example of a fully and properly configured Peerplays runtime environment. However, keep in mind that this is mainly a developer tool, and may differ from the current production software:

4. Use the CLI Wallet to Create a Peerplays SON Account

4.1. Becoming a HIVE SON

Becoming a SON is very similar to becoming a witness. You will need:
  • An active user account, upgraded to lifetime member, which will be the owner of the SON account
  • Create two vesting balances (types "son" and "normal") of 50 PPY, and get their IDs
  • The HIVE account created for the SON account (Follow the instructions here: https://signup.hive.io/)
  • Create the SON account, and get its ID
  • Set the signing key for the SON account (usually, its a signing key of the owner account)
  • Set the HIVE address as a sidechain address for the SON account

4.2. Running the cli_wallet program

Our Peerplays node will have to be completely in sync with the blockchain before we can use the cli wallet so we'll start the node and wait for it to download all the data.
1
mkdir $HOME/peerplays-mainnet
2
./witness_node
3
# If there is an error, try adding the --resync-blockchain or --replay-blockchain flags...
4
# witness_node --replay-blockchain
Copied!
downloading all the transaction and block data will take hours. Unfortunately this is unavoidable the first time the node syncs with the blockchain. You might want to let this run overnight.
If you just can't wait for your node to sync, you can run the cli_wallet program on someone else's node. Simply pass the IP address of the other node like so. (In another command line window)
cli_wallet --server-rpc-endpoint=wss://api.eifos.org
A good resource for server-rpc-endpoints is https://beta.eifos.org/status. They will be listed as API nodes and use the wss:// protocol.

4.3. Using the cli_wallet

Now that we have the cli_wallet running, you'll notice a new prompt.
1
cd $HOME/peerplays-mainnet
2
./cli_wallet
3
new >>>
Copied!
This means we're in a cli_wallet session. First we'll make a new wallet and unlock it.
1
set_password password
2
unlock password
Copied!
A list of CLI wallet commands is available here: https://www.peerplays.tech/api/peerplays-wallet-api/wallet-calls
Assuming we're starting without any account, it's easiest to create an account with the Peerplays GUI Wallet. The latest release is located here https://github.com/peerplays-network/peerplays-core-gui/releases/latest. When you create an account with the GUI wallet, you should have a username and password. We'll need those for the next steps. First we'll get the private key for the new account.
1
# In the cli_wallet...
2
get_private_key_from_password <put your username here> active <put your password here>
3
# For example:
4
# get_private_key_from_password mynew-son active LExu4QtSapqzdEaly2RwMugul3GhedTf234IiF2zzzfU4nuKXow8
5
# The program will return a tuple of the public and private keys for your account.
6
# That will look something like this:
7
# [
8
# "PPY...random.numbers.and.letters...",
9
# "...random.numbers.and.letters..."
10
# ]
Copied!
The key beginning with "PPY" is the public key. The other key is the private key. We'll need to import this private key into the cli_wallet.
1
# In the cli_wallet...
2
3
import_key "mynew-son" ...random.numbers.and.letters...
4
5
# If this is successful, the return is simply
6
# true
Copied!
Next we'll upgrade the account to a lifetime membership.
At the time of writing this guide, this costs 5 PPY to perform this operation. You'll need that in your account first! To this end, see Obtaining Your First Tokens.
1
# In the cli_wallet...
2
3
upgrade_account mynew-son true
Copied!
Next we'll create the vesting balances.
1
# In the cli_wallet...
2
create_vesting_balance mynew-son 50 PPY son true
3
create_vesting_balance mynew-son 50 PPY normal true
4
get_vesting_balances mynew-son
5
# The return here will show us the IDs of the vesting balances.
6
# For example:
7
# [{
8
# "id": "1.13.79",
9
# "owner": "1.2.58",
10
# ...
11
# },{
12
# "id": "1.13.80",
13
# "owner": "1.2.58",
14
# ...
15
# }
16
# ]
Copied!
Now we have all the info we need to create a SON account.
1
# In the cli_wallet...
2
3
create_son mynew-son "https://www.mynew-son.com" 1.13.79 1.13.80 [[bitcoin, 023b907586045625367ecd62c5d889591586c87e57fa49be21614209489f00f1b9]] true
4
5
# The above command is structured like this:
6
# create_son <username> "<SON proposal url>" <son vesting balance ID> <normal vesting balance ID> [[bitcoin, <bitcoin public key>]] true
Copied!
To get the SON ID:
1
# In the cli_wallet...
2
3
get_son mynew-son
4
5
# Which returns:
6
# {
7
# "id": "1.27.16",
8
# ...
9
# }
Copied!
We'll set the signing key using the active key from the owning account:
1
# In the cli_wallet...
2
3
# First we'll get the active key of the owning account.
4
get_account mynew-son
5
6
# In the return, we're looking for the
7
# "active":
8
# ...
9
# { ... "key_auths":
10
# [[ "PPY7SUmjftH3jL5L1YCTdMo1hk5qpZrhbo4MW6N2wWyQpjXkT7ByB",
11
# ...
12
13
# Using the active public key we just found:
14
get_private_key PPY7SUmjftH3jL5L1YCTdMo1hk5qpZrhbo4MW6N2wWyQpjXkT7ByB
15
16
# This will return the private key.
17
# "5JKvPJkerMNVEubsbKN8Xd8wGaU1ifhv7xAwy9gFJP6yMEoTkSd"
18
19
# Then we update the signing key using the public key.
20
update_son mynew-son "" "PPY7SUmjftH3jL5L1YCTdMo1hk5qpZrhbo4MW6N2wWyQpjXkT7ByB" [[bitcoin, 023b907586045625367ecd62c5d889591586c87e57fa49be21614209489f00f1b9]] true
Copied!
Now we have our SON account ID and the public and private keys for the SON account. We'll need this for the config.ini file.

6. Start the SON

After setting up the config.ini file for SON operation, we'll start the node back up.
1
witness_node
Copied!
Your HIVE SON is active! 👏

7. What's Next?

7.1. Auto-starting your node

Starting the node as a service when the system boots up is much better than running the node in the foreground, which is unstable and inconvenient.

7.2. Creating a backup node

It would be wise to create a backup server that will allow you to make software changes/updates, troubleshoot node issues, or take down your node without causing any service outages.

7.3. Configure more sidechains

Why stop at Hive?

7.4. Fire up another node 🔥

Since you’re not a SON, why not become a Witness as it’s relatively easy since you’ve set up a SON.

7.5. Enable SSL to encrypt your node traffic

Consider enabling SSL connections to your node if your node is accessible from the internet (for example, an API node).

8. Glossary

SON: Sidechain Operator Node - An independent server operator which facilitates the transfer of off-chain assets (like Bitcoin or Ethereum tokens) between the Peerplays chain and the asset's native chain.
Witness: An independent server operator which validates network transactions.
Witness Node: Nodes with a closed RPC port. They don't allow external connections. Instead these nodes focus on processing transactions into blocks.
Vim: A text editing program available for Ubuntu 18.04. See vim.org