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
Platform | Package type | Installation information |
---|---|---|
Debian 9 Stretch Ubuntu 16.04 LTS Ubuntu 16.04 LTS | Debian Package (.deb) | First time installation: Re-installation: |
Fedora 27 Fedora 28 | RPM Package (.rpm) | First time installation: Re-installation: |
Other Linux distributions | Tarball (.tgz) | Prerequisites
First time installation: |
Mac
Platform | Package type | Installation information |
---|---|---|
Mac | Tarball (.tgz) | Prerequisites
First time installation: Note: The macos_install.sh script installs the Homebrew package manager on your machine and then installs libsodium. |
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 isthe RChain public testnet.rnode://25a48e34b10c5917aa21bdbbf45da56d3e7129c6@node0.testnet.rchain-dev.tk?protocol=40400&discovery=40404
.--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.
Option | Description | Syntax | Argument Format |
---|---|---|---|
Host Server | The IP address of the server that will receive the call | --grpc-host | 100.10.25.75 |
Host Server port | The port for the gRPC API on the server listening for calls | --grpc-port | 40401 |
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
Instruction | Example/illustration |
---|---|
Run the program in RNode | |
Observe the generation of the graph text and copy the output | |
To see the visualization, past output in http://viz-js.com/ | |
To add graph to a Jira ticket save as a .txt file and attach to the ticket |