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.
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.
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.
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.
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:
|
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. |
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.
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.
docker pull rchain/rnode |
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.
rnode run --network testnet1.1 --store-type v2 --map-size 1099511627776 --bootstrap "rnode://25a48e34b10c5917aa21bdbbf45da56d3e7129c6@node0.testnet.rchain-dev.tk?protocol=40400&discovery=40404" |
--network ...
- Network ID, used to differentiate between multiple RChain networks. The testnet1.1
is ID of current Public Testnet.--bootstrap ...
- Address of the bootstrap node you want to connect with. The bootstrap node of Public Testnet address isrnode://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.--store-type v2
- Selects new RSpace. This is an interim solution until new RSpace becomes default one.rnode run -s |
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.
docker network create rnode-net |
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.
mkdir $HOME/rnode |
docker run -it --rm --network rnode-net --name rnode1 -v $HOME/var/rnode1:/var/lib/rnode rchain/rnode:latest run --bootstrap "<bootstrap node address>" --store-type v2 --map-size 1099511627776 |
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.
docker run -u root -it --network rnode-net --name rnode-server-local -v "$HOME/rnode":/var/lib/rnode rchain/rnode:latest run --standalone |
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'.
docker run --name rnode-server-local rchain/rnode:latest |
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'.
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.
docker run -v "path to local directory":/var |
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:
rnode <API call> |
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
./bin/rnode --grpc-host IP.Address.of.server --grpc-port 40401 repl |
With RNode running, use --help
to see available commands and subcommands.
You can ask RNode to provide its status to report the RNode address, version, and peer count.
curl -s http://localhost:40403/status |
Report status in Docker
sudo docker exec -ti <containername> curl -s http://localhost:40403/status |
Example of a status request response
{"address":"rnode://4fa269b79e781af2c079713772cfc5dbd7dc1569@52.119.8.64?protocol=40400&discovery=40404","version":"RChain Node 0.9.4.git8a4c9939 (8a4c99394c3a22831c2eadef7cdde7dec35238d7)","peers":7,"nodes":44} |
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.
Use this command to show the number of blocks in the DAG according to your node.
rnode show-blocks |
Get a count of blocks in Docker
docker run -it --rm --network rnode-net --name rnode -v $HOME/var/rholang:/var/ rchain/rnode:latest --grpc-host rnode2 show-blocks |
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.
rnode keygen --algorithm secp256k1 --private-key-path <arg> |
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:
--phlo-limit <arg> The amount of phlo to use for the transaction (unused phlo is refunded). Must be positive integer. --phlo-price <arg> The price of phlo for this transaction in units dust/phlo. Must be positive integer. --private-key-path <arg> The deployer's file with encrypted private key. |
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.
rnode --grpc-host <address of known validator> deploy --phlo-limit <value> --phlo-price <value> --private-key-path <path to encrypted private ke> <path to .rho file> |
Deploy a Rholang contract to a known validator in Docker
docker run -it --rm --network rnode-net --name rnode-deploy1 -v $HOME/var/rholang:/var/ rchain/rnode:latest --grpc-host <address of known validator> deploy --from "0x1" --phlo-limit <value> --phlo-price <value> --private-key-path <path to encrypted private key> <path to Rholang file> |
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
root@kelly:~# rnode --grpc-host node1.devnet.rchain-dev.tk deploy --phlo-price 10000000 --phlo-limit 1 --private-key-path /keys tut-philosophers.rho Password for private key file: ****** Response: Success! DeployId is: 3045022100bbabe879eed9194ef371f312b0fa36d402409111d307a1cb01cc8c519fdb741502206051ecfcd79aad31764ab7b65ceec4c537489ea7359fc8f80472e74c819b4cb1 |
Once we hav the DeployID, we can locate the block containing that deploy.
root@kelly:~# rnode --grpc-host node1.devnet.rchain-dev.tk find-deploy --deploy-id 3045022100bbabe879eed9194ef371f312b0fa36d402409111d307a1cb01cc8c519fdb741502206051ecfcd79aad31764ab7b65ceec4c537489ea7359fc8f80472e74c819b4cb1 blockInfo { blockHash: "2b7848babd7ea4bee52bd7e9990a5119a98b9482ac28e5e9b181bbf1a480d8bf" blockSize: "35679" blockNumber: 315 version: 1 deployCount: 2 tupleSpaceHash: "d7aa5b8e0a9a6bf1bbfd3f19715ad08996b5fdde8eb64200763a742d1f348ea7" timestamp: 1560208996576 faultTolerance: -1.0 mainParentHash: "fb17569ab340486e2bcfb33910a87ea30f598288af2c420397f055f03b2687ec" parentsHashList: "fb17569ab340486e2bcfb33910a87ea30f598288af2c420397f055f03b2687ec" parentsHashList: "9100f449f0fa3501fc058eb78534545f27d79503366078033c33625636391604" sender: "0443a5170db3ec242341864617f752a0e54d34213793b96c5708db72ce62a75e1a37af8f1dcb93b208fe807f408a30f6acd343330a5d27b3434c759ac5d231679f" |
If the deploy has not yet been proposed in a block, you will receive the following:
Couldn't find block containing deploy with id:3045022100bbabe879eed9194ef371f312b0fa36d402409111d307a1cb01cc8c519fdb741502206051ecfcd79aad31764ab7b65ceec4c537489ea7359fc8f80472e74c819b4cb1 |
Propose triggers a block proposal to the network. This is a function only available to validating nodes.
root@salt:~# rnode propose 21:52:06.959 [main] INFO c.r.n.configuration.Configuration$ - Starting with profile default Response: Success! Block c0b68d2520... created and added. |
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...).
21:52:08.806 [grpc-default-executor-55] INFO c.rchain.casper.util.comm.CommUtil$ - CASPER: Beginning send of Block #1 (c0b68d2520...) -- Sender ID 3d86379153... -- M Parent Hash 06eb7dc6ab... -- Contents 16d7c61fa6...-- Shard ID rchain to peers... 21:52:08.820 [repl-io-141] INFO c.rchain.casper.util.comm.CommUtil$ - CASPER: Sent c0b68d2520... to peers 21:52:08.820 [repl-io-141] INFO c.rchain.casper.MultiParentCasper$ - CASPER: Added c0b68d2520... 21:52:08.844 [repl-io-141] INFO c.rchain.casper.MultiParentCasper$ - CASPER: New fork-choice tip is block c0b68d2520.... |
Propose a new block in Docker
docker run -it --rm --network rnode-net --name rnode-propose1 -v $HOME/var/rholang:/var/ rchain/rnode:latest --grpc-host rnode1 propose |
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.
You can create your own blockchain network.
You can join the RChain test net. Please see RChain public testnet information for details about the version of software and the bootstrap address.
RNode features integration with Prometheus. These instructions describe a method for getting started with RNode metrics collection and display using Prometheus via Docker-compose.
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.
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.
rnode vdag | dot -Tpng >vdag.png |
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 |