Skip to content

Latest commit

 

History

History
207 lines (146 loc) · 8.33 KB

run-a-paratime-client-node.md

File metadata and controls

207 lines (146 loc) · 8.33 KB
Raw
description
This page describes how to run a ParaTime client node on the Oasis Network.

Run a ParaTime Client Node

{% hint style="info" %} These instructions are for setting up a ParaTime client node which only observes ParaTime activity and can submit transactions. If you want to run a ParaTime node instead, see the instructions for running a ParaTime node. Similarly, if you want to run a validator or a non-validator node instead, see the instructions for running a validator node or instructions for running a non-validator node. {% endhint %}

{% hint style="success" %} If you are looking for some concrete ParaTimes that you can run, see the list of ParaTimes and their parameters. {% endhint %}

{% hint style="success" %} Oasis Core refers to ParaTimes as runtimes internally, so all configuration options will have runtime in their name. {% endhint %}

This guide will cover setting up your ParaTime client node for the Oasis Network. This guide assumes some basic knowledge on the use of command line tools.

Prerequisites

Before following this guide, make sure you've followed the Prerequisites and Run a Non-validator Node sections and have:

  • Oasis Node binary installed and configured on your system.
  • The chosen top-level /node/ working directory prepared. In addition to etc and data directories, also prepare the following directories:
    • bin: This will store binaries needed by Oasis Node for running the ParaTimes.
    • runtimes: This will store the ParaTime binaries and their corresponding signatures (if they are running in a Trusted Execution Environment).

{% hint style="success" %} Feel free to name your working directory as you wish, e.g. /srv/oasis/.

Just make sure to use the correct working directory path in the instructions below. {% endhint %}

  • Genesis file copied to /node/etc/genesis.json.

{% hint style="success" %} Reading the rest of the ParaTime node setup instructions may also be useful. {% endhint %}

{% hint style="info" %} To speed up bootstraping your new node, we recommend copying node's state from your existing node or syncing it using state sync. {% endhint %}

{% hint style="success" %} Running a ParaTime client node doesn't require registering an entity or its nodes.

It also doesn't require having any stake. {% endhint %}

{% hint style="success" %} Running a client node for a ParaTime that runs in a Trusted Execution Environment (TEE) doesn't require having the same TEE available on the ParaTime client node.

For example, running a ParaTime client node for an SGX-enabled ParaTime like Cipher doesn't require having SGX on the ParaTime client node. {% endhint %}

The ParaTime Identifier and Binary

In order to run a ParaTime node you need to obtain the following pieces of information first, both of these need to come from a trusted source:

  • ****The ParaTime Identifier is a 256-bit unique identifier of a ParaTime on the Oasis Network. It provides a unique identity to the ParaTime and together with the genesis document's hash serves as a domain separation context for ParaTime transaction and cryptographic commitments.

    It is usually represented in hexadecimal form, for example:
    8000000000000000000000000000000000000000000000000000000000000000\

  • The ParaTime Binary contains the executable code that implements the ParaTime itself. It is executed in a sandboxed environment by Oasis Node and its format depends on whether the ParaTime is running in a Trusted Execution Environment (TEE) or not.\

    For ParaTime client nodes, one does not need to run the SGXS binary, even for ParaTimes running in a TEE. ParaTime client node always runs the regular Linux executable (an ELF binary, usually without an extension).

{% hint style="danger" %} Like the genesis document, make sure you obtain these from a trusted source. {% endhint %}

{% hint style="warning" %}

Compiling the ParaTime Binary from Source Code

In case you decide to build the ParaTime binary from source yourself, make sure that you follow our guidelines for deterministic compilation to ensure that you receive the exact same binary. {% endhint %}

Install ParaTime Binary

For each ParaTime, you need to obtain its binary and install it to runtimes subdirectory of your node's working directory.

Install Bubblewrap Sandbox (at least version 0.3.3)

ParaTime client nodes execute ParaTime binaries inside a sandboxed environment provided by Bubblewrap. In order to install it, please follow these instructions, depending on your distribution:

{% tabs %} {% tab title="Ubuntu 18.10+" %}

sudo apt install bubblewrap

{% endtab %}

{% tab title="Fedora" %}

sudo dnf install bubblewrap

{% endtab %}

{% tab title="Other Distributions" %} On other systems, you can download the latest source release provided by the Bubblewrap project and build it yourself.

Make sure you have the necessary development tools installed on your system and the libcap development headers. On Ubuntu, you can install them with:

sudo apt install build-essential libcap-dev

After obtaining the Bubblewrap source tarball, e.g. bubblewrap-0.4.1.tar.xz, run:

tar -xf bubblewrap-0.4.1.tar.xz
cd bubblewrap-0.4.1
./configure --prefix=/usr
make
sudo make install

{% hint style="warning" %} Note that Oasis Node expects Bubblewrap to be installed under /usr/bin/bwrap by default. {% endhint %} {% endtab %} {% endtabs %}

Ensure you have a new enough version by running:

bwrap --version

{% hint style="warning" %} Ubuntu 18.04 LTS (and earlier) provide overly-old bubblewrap. Follow Other Distributions section on those systems. {% endhint %}

Configuration

In order to configure the ParaTime client node, create the /node/etc/config.yml file with the following content:

datadir: /node/data

log:
  level:
    default: info
    tendermint: info
    tendermint/context: error
  format: JSON

genesis:
  file: /node/etc/genesis.json

consensus:
  tendermint:    
    p2p:
      # List of seed nodes to connect to.
      # NOTE: You can add additional seed nodes to this list if you want.
      seed:
        - "{{ seed_node_address }}"

runtime:
  supported:
    # List of ParaTimes that the node should support.
    - "{{ runtime_id }}"

  paths:
    # Paths to ParaTime non-SGX binaries for all of the supported ParaTimes.
    "{{ runtime_id }}": {{ non-sgx_runtime_bin_path }}

worker:

  storage:
    enabled: true
    checkpoint_sync:
      disabled: true
  
  p2p:
    # External P2P configuration.
    enabled: true

Before using this configuration you should collect the following information to replace the variables present in the configuration file:.

Starting the Oasis Node

You can start the node by running the following command:

oasis-node --config /node/etc/config.yml

Checking Node Status

To ensure that your node is properly connected with the network, you can run the following command after the node has started:

oasis-node control status -a unix:/node/data/internal.sock