Random Number Generator (RNG)
Other Documentation
Manual Install
Setup SONs by building the source code

1. Overview

The process of manually installing a SON Node 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.
The following repository should be used in support of this document:
Please review the Requirements for setting up a SON Node before continuing to run a manual install following this guide.
The following steps outline the manual installation of a SON Node.
  1. 1.
    Build from Source Code
  2. 2.
    Connect to the Bitcoin Network and Generate an Address
  3. 3.
    Create a SON Account
  4. 4.
    Configure the SON Node
  5. 5.
    Start the SON Node
  6. 6.
    (Optional) Automatically Start the Node as a Service

2. Build Peerplays from Source Code

2.1. Install dependencies on Ubuntu 18.04 LTS

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!

2.1.1. 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.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 master # --> replace with most recent tag
6
git submodule update --init --recursive
7
git submodule sync --recursive
8
cmake -DBOOST_ROOT="$BOOST_ROOT" -DCMAKE_BUILD_TYPE=Release
9
make -j$(nproc)
10
11
# Optional:
12
make install
13
14
# make install will install the executable files under /usr/local
Copied!
Note: master can be replaced with the most recent release tag.

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

If we have installed the blockchain following the above steps, the node can be started as follows.
Note: 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.
1
./programs/witness_node/witness_node
2
3
# If you need the logs, the following can be helpful
4
# ./programs/witness_node/witness_node 2>&1 peerplays.log
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 ~/src
2
wget https://bitcoincore.org/bin/bitcoin-core-0.21.0/bitcoin-0.21.0-x86_64-linux-gnu.tar.gz
3
# Or if you're using ARM architecture...
4
# wget https://bitcoincore.org/bin/bitcoin-core-0.21.0/bitcoin-0.21.0-aarch64-linux-gnu.tar.gz
5
6
tar xzf bitcoin-0.21.0-x86_64-linux-gnu.tar.gz
7
sudo install -m 0755 -o root -g root -t /usr/local/bin bitcoin-0.21.0/bin/*
Copied!
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.
Note: 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
@reboot bitcoind -daemon
Copied!
Save and quit the crontab file. Now we're ready to fire up the Bitcoin node!
1
bitcoind -daemon
Copied!
Note: 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/src/peerplays/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
cd ~/src/peerplays
2
./programs/witness_node/witness_node
3
4
# If there is an error, try adding the --resync-blockchain or --replay-blockchain flags...
5
# ./programs/witness_node/witness_node --replay-blockchain
Copied!
Note: 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 elses node. Simply pass the IP address of the other node like so.
1
./programs/cli_wallet/cli_wallet --server-rpc-endpoint=wss://api.eifos.org
Copied!
Note: 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!
Note: 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
# "5...random.numbers.and.letters..."
13
# ]
Copied!
The key beginning with "PPY" is the public key. The key beginning with "5" 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" 5...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.
Note: At the time of writing this guide, this costs 5 PPY to perform this operation. You'll need that in your account first!
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/src/peerplays/witness_node_data_dir/config.ini. We'll begin by editing this config file.
1
cd /home/ubuntu/src/peerplays/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 Node

After setting up the config.ini file for SON operation, we'll start the node back up.
1
./programs/witness_node/witness_node
Copied!
Your SON node is configured, up and running. But there's still more to do.

6.1. Next steps

  • Automate the SON node to run when the server starts.
  • Create a backup SON node to help prevent downtime.
  • Get voted in as an operating SON node.

7. Setting Up the SON Node as a Service

Automating the node to start when the server starts will help minimize downtime, allow the program to run in the background, and aid in making updates to the node software.
Note: This part is optional, but highly recommended!
First we'll create a simple shell script and set the file permissions to allow the system to access and run the script. Then we'll make a service file that uses the shell script.

7.1. Make a shell script with logging

First make a log file to store our outputs.
1
sudo touch /var/log/peerplays.log
Copied!
From our /home/ubuntu/src/peerplays directory, create a file named start.sh. For example:
1
cd /home/ubuntu/src/peerplays
2
vim start.sh
Copied!
Use the Vim editor (or your text editor of choice) to create the start.sh file as follows.
1
#!/bin/bash
2
3
cd /home/ubuntu/src/peerplays
4
./programs/witness_node/witness_node &> /var/log/peerplays.log
Copied!
Save and exit the file. Now we'll set the file permissions.
1
chmod 744 /home/ubuntu/src/peerplays/start.sh
Copied!

7.2. Make a system service file

Now that we have the shell file good to go we'll create a service file. Navigate to /etc/systemd/system and create a file named peerplays.service as below.
1
cd /etc/systemd/system
2
vim peerplays.service
Copied!
Inside the peerplays.service file we'll enter:
1
[Unit]
2
Description=Peerplays Node
3
After=network.target
4
5
[Service]
6
ExecStart=/home/ubuntu/src/peerplays/start.sh
7
Restart=always
8
RestartSec=3
9
10
[Install]
11
WantedBy=multi-user.target
Copied!
Save the file and quit.

7.3. Enable the service

1
sudo systemctl enable peerplays.service
Copied!
Important: Make sure you don't get any errors.
1
sudo systemctl status peerplays.service
Copied!
If your node is running, stop it with ctrl + c, then start it back up with the service.
1
sudo systemctl start peerplays.service
Copied!
Lastly, check the log file to ensure the node is running properly.
1
tail -f /var/log/peerplays.log
Copied!
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.
An independent server operator which produces blocks for the blockchain. These blocks contain the operations and transactions that happen on the chain. See Becoming a Witness for more information on installing Witness Nodes. What is a Peerplays Witness for more information on Peerplays Witnessing.
There are many types of nodes in the Peerplays ecosystem. (Witness, SON, Seed, API, Full, BOS...) All Peerplays nodes, no matter which type, are running the witness_node program. The difference is mostly in how the program is configured. Different configuration settings will allow the node to offer different services. For example, Witness nodes produce blocks, SONs facilitate sidechain transfers, Full nodes store the entire transaction history of the chain, etc.
Vim is a text editing program available for Ubuntu 18.04. See vim.org
Service files are used in Ubuntu to start programs in the background upon startup.