RNG API documentation
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.
Not predictable
Verifiable
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.