RNG API documentation

Owned by Bobinson Bobby
Last updated: Sept 17, 2020
4 min read

1. Introduction

Random numbers and random number generators play a crucial role in the modern world. True random numbers are required in a variety of domains varying from the ethernet ports of our computers to betting houses across the globe. Achieving non-predictable true randomness is a difficult problem to solve. The Peerplays blockchain has managed to develop a true random number generator as one of the offshoots of the blockchain technology. The provably fair RNG algorithm ensures the following characteristics.

  1. Not predictable

  2. Verifiable

  3. Non-disputable

In addition to that, the Peerplays blockchain RNG has a uniform probability distribution characteristic, which is what is sort in most of the cases.

2. Building RNG Server on Ubuntu 18.04 LTS and Installation Instructions

If you already have access to a Peerplays node with RNG, then you can jump to section 3.

System Requirements

The following table lists what should be considered the minimum system requirements for running a witness node:

CPU

Memory

Storage

Bandwidth

OS

8 Cores

64GB

300GB SSD

1Gbps

Ubuntu 18.04

These requirements are, as of the time of writing, so consider deploying a server with specs slightly higher than the ones listed above in order to "future proof" your server in case the minimum requirements grow in the future.

Dependencies

The following dependencies are necessary for a clean install of Ubuntu 18.04 LTS and install them with the following command.

sudo apt-get -y install gcc g++ cmake make libbz2-dev libdb++-dev libdb-dev libssl-dev openssl libreadline-dev autoconf libtool git libcurl4-openssl-dev

Build Boost 1.67.0

mkdir $HOME/src cd $HOME/src export BOOST_ROOT=$HOME/src/boost_1_67_0 sudo apt-get update sudo apt-get install -y autotools-dev build-essential libbz2-dev libicu-dev python-dev wget -c 'http://sourceforge.net/projects/boost/files/boost/1.67.0/boost_1_67_0.tar.bz2/download' -O boost_1_67_0.tar.bz2 tar xjf boost_1_67_0.tar.bz2 cd boost_1_67_0/ ./bootstrap.sh "--prefix=$BOOST_ROOT" ./b2 install

Building Peerplays RNG Server

cd $HOME/src export BOOST_ROOT=$HOME/src/boost_1_67_0 git clone https://github.com/peerplays-network/peerplays.git cd peerplays git checkout feature/rng git submodule update --init --recursive git submodule sync --recursive cmake -DBOOST_ROOT="$BOOST_ROOT" -DCMAKE_BUILD_TYPE=Release make -j$(nproc) sudo make install # this can install the executable files under /usr/local # Input passwrod upon need

Starting the Peerplays Witness Node

If we have installed the blockchain following the above steps, the node can be started as follows:

Launching the Witness creates the required directories.

Next, stop the witness node before continuing and make the following changes in the config.ini file.

To stop the witness use ctrl + c

Leave other lines to the defaults.

Start the Witness node again.

witness_node

The Random Number Generator is running and exposed through the port 8090 now. You may skip the following witness as a service for the time being and test the RNG. For testing RNG, skip to the API specifications section. Once RNG is found working, come back and set the witness as a service and make changes necessary to run it on startup as given below.

Starting the witness as a service

We can add the peerplays blockchain node as a service using the following steps.

under, /etc/systemd/system create a file with the following content. It’s assumed that “ubuntu” is the name of your home folder. If not replace with proper home folder name judiciously.

Auto-Starting the Witness Node

It's important for your Witness node to start when your system boots up. The filepaths here assume that you installed your witness into /home/ubuntu

Step 1. Create a log file to hold your stdout/err logging

Step 2. Save this file in your Peerplays directory. vi /home/ubuntu/start.sh

Step 3. Make it executable

Step 4. Create this file: sudo vi /etc/systemd/system/peerplays.service

Note: Check the path for start.sh, if necessary, change it to match where your start.sh file actually is.

Step 5. Enable the service

Important: Make sure you don't get any errors.

Step 6. Stop your Witness node, if it's currently running, then start it with the service.

Step 7. Check your logfile for entries

3. API Specifications

The API is exposed at the URL: HTTP://<IP of the RNG server>:8090/ws. The API supports post request method over HTTP for generating and fetching random numbers from the blockchain. The parameters of the post method are

Where

min: Lowest number in the random sequence, lower permitted value is 0 max: Highest number in the random sequence will be max - 1 count: Number of random numbers to be pulled, the maximum permitted limit is 100,000. repeat: true/false Can there be repetition in the random numbers pulled? “true” means numbers are repeated and “false” means numbers are not repeated.

And it returns

The result, random numbers are under the key “result”.

Examples

Curl

Which returns

Node.js

Python

PHP

Go-LANG

4. Accessing used numbers on the blockchain

This is work in progress and the explorer API will be completed and the details will be updated here.