User guide for running RNode

Introduction

Nodes are the basis for the RChain network. The network layer is the lowest level component in the architecture that will eventually support RChain’s large-scale blockchain operations. Pre-release versions of RNode are available for users to explore. More information about the roadmap, key milestones and release plans is available at https://developer.rchain.coop.

Who is this guide for?

This document is a quick start guide for users to install and run the software for the purpose of evaluating Rholang and/or using the RChain public testnet. Detailed information about the the software for users and developers is available in on https://github.com/rchain/rchain.

Network configuration

By default RNode continuously attempts to connect to other peers. Successful connection to other nodes on the RChain network requires connectivity support from your network. Please see RNode supported network configuration and configure your network.

Installing RNode

We deliver RNode software in a variety of installation packages.  Installation packages are available at both https://developer.rchain.coop and https://github.com/rchain/rchain/releases. We recommend using the latest release.

Note: In the command examples below, you must update based on the version number of RNode you want by replacing "x" with the numbers in your installation version.

Linux

Mac

Windows

RNode does not run in a native build or with Docker. Please see comments in  for full details. The best way to use RNode in Windows is to install Ubuntu/Centos VM in Hyper-V and use the installation instructions for Linux.

Docker

Although it is simple to install RNode in Docker, it is important to have an understanding for working with Docker to successfully run and interface with RNode.  

• If you are brand new to working with Docker, read the Docker get started documentation.
• If you a familiar with Docker, you may find it helpful to review or have ready access to the cheat sheets published at the end of each section of the Docker get started documentation.

ARM

You can run RNode on Raspberry pi. An example of this, including installation and deployment instructions, is available at https://github.com/kayvank/arm-rnode.

Running RNode

Run commands (non-Docker)

To connect to an existing network

• --network ... - Network ID, used to differentiate between multiple RChain networks. The current network ID is posted on RChain public testnet information
• --bootstrap ... - Address of the bootstrap node you want to connect with. The bootstrap node of Public Testnet address is
  rnode://25a48e34b10c5917aa21bdbbf45da56d3e7129c6@node0.testnet.rchain-dev.tk?protocol=40400&discovery=40404.
  the RChain public testnet.
• --map-size 1099511627776 - LMDB map size. This is an interim solution until the sufficient size is set automatically.

To run a standalone node

Run commands (Docker)

Create a RNode network

If this is your first time running RNode, you need to create a Docker network to support RNode operation. Unless you wipe your Docker system, you only need to do this once.

Create the data directory

Running RNode with Docker requires the /var/lib/rnode directory.  Each Docker container has to have its' own data directory.  If you have multiple directories on your system, you can specify them separately in your docker run command.

To connect to an existing network

Note: Docker for Mac will only work with static NAT and port forwarding.  network=host does not work on Mac. See RNode supported network configuration for more information on static NAT and port forwarding.

• Bootstrap address - Enter the address of the bootstrap node you want to connect with. See RNode bootstrap addresses for bootstrap nodes supported by the RChain core development team.
• Validator private key - Insert the key if you are a validator of test net, or if you are creating a private network and have a bonds file included in your genesis block.
• Network configuration - If you want to specify your ports, include --p in the run command. If you want to specify your host, include --host in the run command.

To run a standalone node

Tips for working with RNode in Docker

Naming Containers

Once the network is created, the server container will be put into the network, and then referenced by the client.  It's easier if you give your server container a name.  This is an example of of naming a server 'rnode-server-local'.  

Using the --host flag

If you want to create a local docker network which consists of some nodes and a bootstrap node, you will have to specify the nodes' addresses with the --host flag. Make sure to not use the nodes' IP addresses for the --host flag. Instead use the hostnames. If the network is called 'rnode-net' and you named a docker container 'rnode-server-local', the hostname of that docker container is 'rnode-server-local.rnode-net'.

Sharing directories with containers

To share a directory with a container use the volume command.  You will need to create a directory on your local system that will store all of the RNode related files.  Once the directory is created, you can share this directory with the Docker container by using the volume command.   Below is an example of how the volume parameter can be specified as part of a run command.

RNode requires the path /var/lib/rnode exist on startup.  Each instance of RNode requires its own separate /var/lib/rnode directory.

The RNode user interface

Calling the API

The RNode API is a server side API. To access the local RNode server once you have RNode running, open a new window and invoke the RNode api with:

Calling the API from a remote server

You can call the API of a remote RNode server by specifying the host server and host server port.

This is an example of an API call to a remote server

Available API Calls

With RNode running, use --help to see available commands and subcommands.

Find your node address, version, and peer count

You can ask RNode to provide its status to report the RNode address, version, and peer count.

 Report status in Docker

Example of a status request response

RNode offers two types of counts of peers. peers are the number of nodes you are connected to via the Kademlia protocol and the ones that are able to pass messages such as blocks. nodes are the number of nodes found as part of node discovery.

Get a count of blocks in the DAG

Use this command to show the number of blocks in the DAG according to your node. 

Get a count of blocks in Docker

Generate a public/private key set

You can use the RNode software to generate either a secp256k1 public/private key set to use when deploying Rholang or in other scenarios where providing keys is a requirement. With the release of RNode v0.9.7 the platform uses the secp256k1 algorithm. 

Deploy a Rholang contract

Deploy a Rholang source file to Casper on an existing running node. The deploy will be packaged and sent as a block to the network depending on the configuration of the Casper instance.

The deploy command requires the following specifications in addition to the Rholang file:

Deploy a Rholang contract to a known validator

Unless you are a validator in the RChain network or a private network, you will typically deploy Rholang to a known validator with the intent to add the contract to the blockchain.

Deploy a Rholang contract to a known validator in Docker

Deploy returns a DeployID

A successful deploy returns a DeployID. You can use this ID to locate your deploy in a proposed block.

For example:

Here is a deploy made from an observer node to a validating node on a testnet

Once we hav the DeployID, we can locate the block containing that deploy.

If the deploy has not yet been proposed in a block, you will receive the following:

Propose a block to the blockchain

Propose triggers a block proposal to the network. This is a function only available to validating nodes. 

Example of the propose command on the server side

Here is an example of the console output following the propose. The log shows the new fork-choice from the proposed and added block (c0b68d2520...).

Propose a new block in Docker

Check if a block is finalized

Use this command to check if a block with the given blockhash is finalized

Here is an example of the console output following the is-finalized call.

Bonding to a network to become a validator

To participate in the RChain proof-of-stake consensus protocol, you must stake bond on the network to become a bonded validator. Information about this process is not yet available.

Creating a private blockchain

You can create your own blockchain network. 

Prerequisites for a private blockchain

• 1 bootstrap node
• 2 other node instances running on a network where they can communicate with each other (peers of each other). 
• Keys for the node instances (these will be required for signing and creating the bond.txt file)
• A bond.txt file accessible by all node instances. You can either supply it, or use the system generated bonds file.
• A Rholang file to deploy across the network.

Steps to create a private blockchain

• Start the bootstrap node. This is the 1 node operating in standalone mode.
• Include the address of the bootstrap node in your run command for the peer nodes.

Joining the RChain test net

You can join the RChain test net. Please see RChain public testnet information for details about the version of software and the bootstrap address.

Monitoring the Node

RNode features integration with Prometheus. These instructions describe a method for getting started with RNode metrics collection and display using Prometheus via Docker-compose.

Visualizing the blockchain

To support debugging we have a process to collect information from the node and use it in graphviz to create a visualization of the DAG. Below are instructions for two methods for using this tool.

Visualizing the blockchain when there are >6,000 lines

Once an active network has been running for a few hours, your call to vdag will likely generate >6,000 lines of output. In this scenario, you will need to have installed the Graphviz software and use it to create a .png file. Please see https://www.graphviz.org/download/ for information about installing and running Graphviz.

Once installed use the following command to generate a .png file based on vdag output.

Visualizing the blockchain when there are <6,000 lines