ParaTime Client Node
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.
If you are looking for some concrete ParaTimes that you can run, see the list of ParaTimes and their parameters.
Oasis Core refers to ParaTimes as runtimes internally, so all configuration options will have runtime in their name.
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 toetc
anddata
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 bundles.
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.
- Genesis file copied to
/node/etc/genesis.json
.
Reading the rest of the ParaTime node setup instructions may also be useful.
To speed up bootstraping your new node, we recommend copying node's state from your existing node or syncing it using state sync.
Running a ParaTime client node doesn't require registering an entity or its nodes.
It also doesn't require having any stake.
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.
The ParaTime Bundle
In order to run a ParaTime node you need to obtain an active ParaTime bundle,
see the Network Parameters page (Mainnet, Testnet). The bundle (.orc
extension that stands for Oasis Runtime Container) contains all the needed
ParaTime binaries together with the identifier and version metadata to ease
deployment.
When the ParaTime is running in a trusted execution environment (TEE) the bundle will also contain all the required artifacts (e.g. SGXS version of the binary and any enclave signatures).
Like the genesis document, make sure you obtain these from a trusted source.
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.
Install ParaTime Bundle
For each ParaTime, you need to obtain its bundle and install it to the
runtimes
subdirectory of your node's working directory.
For example, for the Cipher ParaTime,
you would have to obtain the cipher-paratime.orc
bundle and install it to
/node/runtimes/cipher-paratime.orc
.
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:
- Ubuntu 18.10+
- Fedora
- Other Distributions
sudo apt install bubblewrap
sudo dnf install bubblewrap
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
Note that Oasis Node expects Bubblewrap to be installed under /usr/bin/bwrap
by default.
Ensure you have a new enough version by running:
bwrap --version
Ubuntu 18.04 LTS (and earlier) provide overly-old bubblewrap
. Follow Other Distributions section on those systems.
Configuration
In order to configure the ParaTime client node, create the /node/etc/config.yml
file with the following content:
mode: client
common:
data_dir: /node/data
log:
format: JSON
level:
cometbft: info
cometbft/context: error
default: info
genesis:
file: /node/etc/genesis.json
p2p:
seeds:
# List of seed nodes to connect to.
# NOTE: You can add additional seed nodes to this list if you want.
- {{ seed_node_address }}
runtime:
# Paths to ParaTime bundles for all of the supported ParaTimes.
paths:
- {{ runtime_orc_path }}
Before using this configuration you should collect the following information to replace the variables present in the configuration file:.
{{ seed_node_address }}
: The seed node address in the formID@IP:port
.{{ runtime_orc_path }}
: Path to the ParaTime bundle of the form/node/runtimes/foo-paratime.orc
.
Make sure the consensus
port (default: 26656
) and p2p.port
(default: 9200
) are exposed and publicly
accessible on the internet (for TCP
and UDP
traffic).
Configuring TEE Paratime Client Node
If your node requires the ability to issue queries that can access confidential
data, start by following the Configuration section to create
the /node/etc/config.yml
file. Once the file is set up, add the following
content to the runtime
part within the /node/etc/config.yml
file:
# ... sections not relevant are omitted ...
runtime:
# Paths to ParaTime bundles for all of the supported ParaTimes.
paths:
- {{ runtime_orc_path }}
environment: sgx
sgx_loader: /node/bin/oasis-core-runtime-loader
Before using this configuration you should collect the following information to replace the variables present in the configuration file:
{{ runtime_orc_path }}
: Path to the ParaTime bundle of the form/node/runtimes/foo-paratime.orc
.
Enabling Expensive Queries
In case you need to issue runtime queries that may require more resources to
compute (e.g. when running a Web3 Gateway), you need to configure the following
in your node's /node/etc/config.yml
file:
# ... sections not relevant are omitted ...
runtime:
paths:
- {{ runtime_orc_path }}
environment: sgx
config:
{{ runtime_id }}:
estimate_gas_by_simulating_contracts: true
allowed_queries:
- all_expensive: true
{{ runtime_id}}
: You can find theruntime_id
in the Network Parameters chapter (Mainnet, Testnet){{ runtime_orc_path }}
: Path to the ParaTime bundle of the form/node/runtimes/foo-paratime.orc
.
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
See also
📄️ Web3 Gateway
Web3 gateway for Emerald and Sapphire ParaTimes