Manual Install
Set up a Sidechain Operator Node (SON) by building the source code
The process of manually installing a SON is similar to installing a Witness Node. This is an introduction for new SONs to get up to speed on the Peerplays blockchain. It is intended for SONs planning to join a live, already deployed, blockchain.
This tutorial will take you through the steps required to have an operating SON. Since SONs serve the purpose of facilitating transfers of assets between the Peerplays blockchain and other blockchains, we'll need to connect to another chain to be of any use...
Let's use Bitcoin!
😎
Please review the Requirements for setting up a SON before continuing to run a manual install following this guide.
The following steps outline the manual installation of a (Bitcoin enabled) SON.
  1. 1.
    Preparing the Environment
  2. 2.
    Build Peerplays
  3. 3.
    Connect to the Bitcoin 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
Before we begin, to set up a SON node requires about 110 PPY. This is to pay for an upgraded account (5 PPY) and to fund two vesting balances (50 PPY each). The remaining funds are to pay for various transaction fees while setting up the node. Please see Obtaining Your First Tokens for more info.
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 see the general SON hardware requirements.
For the manual install, we'll be using a self-hosted Bitcoin node. The requirements that we'll need for this guide would be as follows (as per the hardware requirements doc):
Bitcoin node type
CPU
Memory
Storage
Bandwidth
OS
Self-Hosted, Reduced Storage
2 Cores
16GB
⚠
150GB SSD
1Gbps
Ubuntu 18.04
The memory requirements shown in the table above are adequate to operate the node. Building and installing the node from source code (as with this manual installation guide) will require more memory. You may run into errors during the build and install process if the system memory is too low. See Installing vs Operating for more details.

1.2. Installing the required dependencies

The following dependencies are necessary for a clean install on Ubuntu 18.04 LTS:
1
sudo apt-get update
2
sudo apt-get -y install vim autoconf bash build-essential ca-certificates cmake \
3
dnsutils doxygen git graphviz libbz2-dev libcurl4-openssl-dev \
4
libncurses-dev libreadline-dev libssl-dev libtool libzmq3-dev \
5
locales ntp pkg-config wget autotools-dev libicu-dev python-dev
Copied!

1.3. Build Boost 1.67.0

Boost is a C++ library that handles common program functions like generating config files and basic file system i/o. Peerplays uses Boost to handle such functions. Since Boost is a dependency, we must build it here.
1
mkdir $HOME/src
2
cd $HOME/src
3
export BOOST_ROOT=$HOME/src/boost_1_67_0
4
sudo apt-get update
5
sudo apt-get install -y autotools-dev build-essential libbz2-dev libicu-dev python-dev
6
wget -c 'http://sourceforge.net/projects/boost/files/boost/1.67.0/boost_1_67_0.tar.bz2/download'\
7
-O boost_1_67_0.tar.bz2
8
tar xjf boost_1_67_0.tar.bz2
9
cd boost_1_67_0/
10
./bootstrap.sh "--prefix=$BOOST_ROOT"
11
./b2 install
Copied!

2. Build Peerplays

Now we build Peerplays with the official source code from GitHub.
1
cd $HOME/src
2
export BOOST_ROOT=$HOME/src/boost_1_67_0
3
git clone https://github.com/peerplays-network/peerplays.git
4
cd peerplays
5
git checkout 1.5.16 # --> replace with most recent release's tag
6
git submodule update --init --recursive
7
git submodule sync --recursive
8
cmake -DBOOST_ROOT="$BOOST_ROOT" -DCMAKE_BUILD_TYPE=Release
9
# the following command will install the executable files under /usr/local
10
make install
11
​
12
# the following isn't required if you ran the "make install" command above.
13
# If you prefer, the "make -j$(nproc)" command will install the programs under /home/ubuntu/src/peerplays/programs
14
make -j$(nproc)
Copied!
Note: "1.5.16" can be replaced with the most recent release tag. For example: git checkout 1.5.16 where 1.5.16 is the latest production release tag as of December 2021. The list of releases is located here.

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

We start the SON Node with the witness_node command although we are only intending to set up this node as a 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 we have installed the blockchain following the above steps, the node can be started as follows:
1
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.

3. Connect to Bitcoin Network and Generate an Address

There are two options available to connect to the Bitcoin network.
  1. 1.
    Run a Bitcoin node yourself
  2. 2.
    Find an open Bitcoin node to connect to
For the purposes of this guide, I'll discuss how to run a node yourself as that will be a more reliable connection for now. Either way you go, you'll need to collect the following information to use in the config.ini file:
  • The IP address of a Bitcoin node you can connect to (127.0.0.1 if self-hosting)
  • ZMQ port of the Bitcoin node (default is 1111)
  • RPC port of the Bitcoin node (default is 8332)
  • Bitcoin RPC connection username (default is 1)
  • Bitcoin RPC connection password (default is 1)
  • Bitcoin wallet label (default is son-wallet)
  • Bitcoin wallet password
  • A new Bitcoin address
  • The Public key of the Bitcoin address
  • The Private key of the Bitcoin address

3.1. Install Bitcoin-core

First we'll download and install one of the official Bitcoin Core binaries:
1
cd ~
2
wget https://bitcoincore.org/bin/bitcoin-core-0.21.1/bitcoin-0.21.1-x86_64-linux-gnu.tar.gz
3
# Or if you're using ARM architecture...
4
# wget https://bitcoincore.org/bin/bitcoin-core-0.21.1/bitcoin-0.21.1-aarch64-linux-gnu.tar.gz
5
​
6
tar xzf bitcoin-0.21.1-x86_64-linux-gnu.tar.gz
7
sudo install -m 0755 -o root -g root -t /usr/local/bin bitcoin-0.21.1/bin/*
Copied!
The official Bitcoin Core binaries can be found here: https://bitcoincore.org/en/download/​
The latest version is 0.21.1 as of July 2021. You may want to find and download the latest version of the binaries just like you would for the 0.21.1 version above.
Then we make a config file to manage the settings of our new Bitcoin node.
1
cd ~
2
mkdir .bitcoin
3
cd .bitcoin
4
vim bitcoin.conf
Copied!
in the Vim text editor we'll set the following:
1
# This config should be placed in following path:
2
# /home/ubuntu/.bitcoin/bitcoin.conf
3
​
4
# [core]
5
# Only download and relay blocks - ignore unconfirmed transaction
6
blocksonly=1
7
# Run in the background as a daemon and accept commands.
8
daemon=1
9
# Set database cache size in megabytes; machines sync faster with a larger cache. Recommend setting as high as possible based upon machine's available RAM.
10
dbcache=1024
11
# Reduce storage requirements by only storing most recent N MiB of block. This mode is incompatible with -txindex and -rescan. WARNING: Reverting this setting requires re-downloading the entire blockchain. (default: 0 = disable pruning blocks, 1 = allow manual pruning via RPC, greater than 550 = automatically prune blocks to stay under target size in MiB).
12
prune=10000
13
​
14
# [network]
15
# Bind to given address and always listen on it. (default: 0.0.0.0). Use [host]:port notation for IPv6. Append =onion to tag any incoming connections to that address and port as incoming Tor connections
16
bind=0.0.0.0
17
# Listen for incoming connections on non-default port.
18
port=8333
19
​
20
# [rpc]
21
# Accept command line and JSON-RPC commands.
22
server=1
23
# Accept public REST requests.
24
rest=1
25
# Bind to given address to listen for JSON-RPC connections. This option is ignored unless -rpcallowip is also passed. Port is optional and overrides -rpcport. Use [host]:port notation for IPv6. This option can be specified multiple times. (default: 127.0.0.1 and ::1 i.e., localhost, or if -rpcallowip has been specified, 0.0.0.0 and :: i.e., all addresses)
26
rpcbind=0.0.0.0
27
# Listen for JSON-RPC connections on this port
28
rpcport=8332
29
# Allow JSON-RPC connections from specified source. Valid for <ip> are a single IP (e.g. 1.2.3.4), a network/netmask (e.g. 1.2.3.4/255.255.255.0) or a network/CIDR (e.g. 1.2.3.4/24). This option can be specified multiple times.
30
rpcallowip=0.0.0.0/32
31
rpcuser=1
32
rpcpassword=1
33
​
34
# [zeromq]
35
# Enable publishing of block hashes to <address>.
36
zmqpubhashblock=tcp://0.0.0.0:11111
37
# Enable publishing of transaction hashes to <address>.
38
zmqpubhashtx=tcp://0.0.0.0:11111
39
# Enable publishing of raw block hex to <address>.
40
zmqpubrawblock=tcp://0.0.0.0:11111
41
# Enable publishing of raw transaction hex to <address>.
42
zmqpubrawtx=tcp://0.0.0.0:11111
43
​
44
​
45
# [Sections]
46
# Most options automatically apply to mainnet, testnet, and regtest networks.
47
# If you want to confine an option to just one network, you should add it in the relevant section.
48
# EXCEPTIONS: The options addnode, connect, port, bind, rpcport, rpcbind and wallet
49
# only apply to mainnet unless they appear in the appropriate section below.
50
​
51
# Options only for mainnet
52
[main]
53
​
54
# Options only for testnet
55
[test]
56
​
57
# Options only for regtest
58
[regtest]
Copied!
Save and quit the Vim editor.
The settings in the config file above are set to reduce the requirements of the server. Block pruning and setting the node to Blocks Only save network and storage resources. For more information, see https://bitcoin.org/en/full-node#reduce-storage.
Lastly we'll set a Cron job to ensure the Bitcoin node starts up every time the server starts.
1
cd ~
2
crontab -e
Copied!
At the bottom of the crontab file, add the following:
1
PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
2
@reboot bitcoind -daemon
Copied!
Save and quit the crontab file. Now we're ready to fire up the Bitcoin node!
1
bitcoind -daemon
Copied!
If successful, you'll see Bitcoin Core starting. As an extra check to see if everything is working, try the bitcoin-cli -version or bitcoin-cli getblockchaininfo commands.
Your Bitcoin node should now be downloading the Bitcoin blockchain data from other nodes. This might take a few hours to complete even though we cut down the requirements with block pruning. It's a lot of data after all.

3.2. Use the bitcoin-cli program to make a new wallet and Bitcoin address

We'll need a wallet to store the new Bitcoin address.
1
bitcoin-cli createwallet "son-wallet"
2
​
3
# To create a wallet with a password, you'd do it like this:
4
# bitcoin-cli createwallet "son-wallet" false false "mycoolpassword"
5
# Note the two false parameters in the line above.
6
# For more information on this command, see https://developer.bitcoin.org/reference/rpc/createwallet.html.
Copied!
Now we will create a Bitcoin address.
1
bitcoin-cli -rpcwallet="son-wallet" getnewaddress
2
​
3
# This will return something like:
4
# bc1qsx7as3r9d92tjvxrgwue7z66f2r3pw04j67lht
Copied!
Then we'll use this address to get its keys.
1
bitcoin-cli -rpcwallet="son-wallet" getaddressinfo bc1qsx7as3r9d92tjvxrgwue7z66f2r3pw04j67lht
2
​
3
# This returns a lot of info but what we're looking for is the "pubkey".
4
# In this case, it's "pubkey": "023b907586045625367ecd62c5d889591586c87e57fa49be21614209489f00f1b9"
Copied!
Now we get the private key.
1
bitcoin-cli -rpcwallet="son-wallet" dumpprivkey bc1qsx7as3r9d92tjvxrgwue7z66f2r3pw04j67lht
2
​
3
# This returns the private key like this:
4
# KzD2WHeG49aYhYVcxBwfknm58YqDc7WEg7aWWU8P8BJ8gp1g3AuD
Copied!

3.3. A quick recap

That was a lot to go over. Let's collect our data.
1
Bitcoin Address for the SON Account = bc1qsx7as3r9d92tjvxrgwue7z66f2r3pw04j67lht
2
The public key = 023b907586045625367ecd62c5d889591586c87e57fa49be21614209489f00f1b9
3
the private key = KzD2WHeG49aYhYVcxBwfknm58YqDc7WEg7aWWU8P8BJ8gp1g3AuD
4
​
5
And we'll convert this info into a tuple ["Bitcoin public key", "Bitcoin private key"]
6
["023b907586045625367ecd62c5d889591586c87e57fa49be21614209489f00f1b9","KzD2WHeG49aYhYVcxBwfknm58YqDc7WEg7aWWU8P8BJ8gp1g3AuD"]
Copied!
Keep this tuple handy. We'll need it in the Peerplays config file.

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

4.1. Becoming a 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 Bitcoin address created for the SON account
  • 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 Bitcoin address as a sidechain address for the SON account

4.2. Running the cli_wallet program

We can run the Peerplays cli wallet connecting to the Peerplays node we have set up so far. Before we can do that we'll need to make a quick edit to the config.ini file.
1
cd /home/ubuntu/witness_node_data_dir
2
vim config.ini
Copied!
in the first section of the config.ini file is the rpc-endpoint setting. We have to open our rpc-endpoint so we can use the Peerplays cli wallet. We'll enter the following:
1
# Endpoint for websocket RPC to listen on
2
rpc-endpoint = 127.0.0.1:8090
Copied!
Save the file and quit.
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
witness_node
2
​
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)
1
cli_wallet --server-rpc-endpoint=wss://api.eifos.org
Copied!
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
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://devs.peerplays.tech/api-reference/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
​
3
get_private_key_from_password <put your username here> active <put your password here>
4
​
5
# For example:
6
# get_private_key_from_password mynew-son active LExu4QtSapqzdEaly2RwMugul3GhedTf234IiF2zzzfU4nuKXow8
7
​
8
# The program will return a tuple of the public and private keys for your account.
9
# That will look something like this:
10
# [
11
# "PPY...random.numbers.and.letters...",
12
# "...random.numbers.and.letters..."
13
# ]
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
​
3
create_vesting_balance mynew-son 50 PPY son true
4
create_vesting_balance mynew-son 50 PPY normal true
5
get_vesting_balances mynew-son
6
​
7
# The return here will show us the IDs of the vesting balances.
8
# For example:
9
# [{
10
# "id": "1.13.79",
11
# "owner": "1.2.58",
12
# ...
13
# },{
14
# "id": "1.13.80",
15
# "owner": "1.2.58",
16
# ...
17
# }
18
# ]
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.

5. Peerplays SON Configuration

The generated config.ini file will be located at /home/ubuntu/witness_node_data_dir/config.ini. We'll begin by editing this config file.
1
cd /home/ubuntu/witness_node_data_dir
2
vim config.ini
Copied!
This file will be rather large so let's focus on the important part for configuring a SON node:
1
# ==============================================================================
2
# peerplays_sidechain plugin options
3
# ==============================================================================
Copied!
This section contains all the SON related configuration. Ensure the following config settings are in the config.ini file under the peerplays_sidechain plugin options.
1
# ID of SON controlled by this node (e.g. "1.27.5", quotes are required)
2
son-id = "1.27.16"
3
​
4
# IDs of multiple SONs controlled by this node (e.g. ["1.27.5", "1.27.6"], quotes are required)
5
# son-ids =
6
​
7
# Tuple of [PublicKey, WIF private key] (may specify multiple times)
8
peerplays-private-key = ["PPY7SUmjftH3jL5L1YCTdMo1hk5qpZrhbo4MW6N2wWyQpjXkT7ByB", "5JKvPJkerMNVEubsbKN8Xd8wGaU1ifhv7xAwy9gFJP6yMEoTkSd"]
9
​
10
# IP address of Bitcoin node
11
bitcoin-node-ip = 127.0.0.1
12
​
13
# ZMQ port of Bitcoin node
14
bitcoin-node-zmq-port = 11111
15
​
16
# RPC port of Bitcoin node
17
bitcoin-node-rpc-port = 8332
18
​
19
# Bitcoin RPC user
20
bitcoin-node-rpc-user = 1
21
​
22
# Bitcoin RPC password
23
bitcoin-node-rpc-password = 1
24
​
25
# Bitcoin wallet
26
bitcoin-wallet = son-wallet
27
​
28
# Bitcoin wallet password
29
bitcoin-wallet-password =
30
​
31
# Tuple of [Bitcoin public key, Bitcoin private key] (may specify multiple times)
32
bitcoin-private-key = ["023b907586045625367ecd62c5d889591586c87e57fa49be21614209489f00f1b9","KzD2WHeG49aYhYVcxBwfknm58YqDc7WEg7aWWU8P8BJ8gp1g3AuD"]
Copied!
We're almost done, we also have to make sure the peerplays_sidechain plugin is listed in the plugins. Find the plugins setting in the first section of the config.ini file. If it's not already there, add the peerplays_sidechain plugin to the list. Like so:
1
# Space-separated list of plugins to activate
2
plugins = witness account_history market_history accounts_list affiliate_stats bookie peerplays_sidechain
Copied!
Save the file and quit. Configuration of the Peerplays SON node is complete!
πŸ˜…

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 SON is born! (pun intended)
But seriously, that was no small feat. Congratulations on this accomplishment!
🎊

7. What's Next?

7.1. Auto-starting your node

Up until this point we have been running the node in the foreground which is fragile and inconvenient. So let's start the node as a service when the system boots up instead.

7.2. Creating a backup node

After that, it would be smart to create a backup server to enable you to make software updates, troubleshoot issues with the node, and otherwise take your node offline without causing service outages.

7.3. Configure more sidechains

Why stop at Bitcoin?

7.4. Fire up another node
πŸ”₯

Now you have a SON, but have you thought about becoming a Witness? It will be a piece of cake for you since you've already set up a SON.

7.5. Enable SSL to encrypt your node traffic

If you have a node that is accessible from the internet (for example, an API or Seed node) it would be wise to enable SSL connections to your 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​