Skip to main content

Basic Node Setup

A node is normally run by executing the casper-node-launcher. This app executes the casper-node as a child process and handles upgrades of it.

Casper Node Launcher

The casper-node-launcher can be installed via a Debian package, which also creates the casper user, creates directory structures, and sets up a systemd unit and logging.

The casper-node-launcher Debian package can be obtained from https://repo.casperlabs.io. You only need to run the steps detailed there once.

Then, proceed to install the casper-node-launcher by running these commands:

sudo apt update
sudo apt install casper-node-launcher

You can also build from source. However, all the setup and pull of casper-node releases will be manual.

File Locations

The casper-node-launcher Debian install creates the directories and files needed for running casper-node versions and performing upgrades. A casper user and casper group is created during install and used to run the software. Two main folders are relevant for our software: /etc/casper and /var/lib/casper.

The casper-node install version

Each version of the casper-node install is located based on the semantic version with underscores. For example, version 1.0.3 is represented by a directory named 1_0_3. This convention applies to both binary and configuration file locations. Versioning with [m_n_p] represents the major, minor, and patch of a semantic version.

note

Multiple versioned folders will exist on a system when upgrades are set up.

The following is the state of the filesystem after installing the casper-client and casper-node-launcher Debian packages, and also after running the command sudo -u casper /etc/casper/node_util.py stage_protocols casper.conf (Use casper-test.conf if on testnet).

/usr/bin/

The default location for executables from the Debian package install is /usr/bin.

  • casper-client - A client for interacting with the Casper network
  • casper-node-launcher - The launcher application which starts the casper-node as a child process

/etc/casper/

This is the default location for configuration files. It can be overwritten with the CASPER_CONFIG_DIR environment variable. The paths in this document assume the default configuration file location of /etc/casper. The data is organized as follows:

  • delete_local_db.sh - Removes *.lmdb* files from /var/lib/casper/casper-node
  • pull_casper_node_version.sh - Pulls bin.tar.gz and config.tar.gz from genesis.casperlabs.io for a specified protocol version and extracts them into /var/lib/bin/<protocol_version> and /etc/casper/<protocol_version>
  • config_from_example.sh - Gets external IP to replace and create the config.toml from config-example.toml
  • node_util.py - A script that will be replacing other scripts and is the preferred method of performing the actions of pull_casper_node_version.sh, config_from_example.sh, and delete_local_db.sh. Other scripts will be deprecated in future releases of casper-node-launcher.
  • casper-node-launcher-state.toml - The local state for the casper-node-launcher which is created during the first run
  • validator_keys/ - The default folder for node keys, containing:
    • README.md - Instructions on how to create validator keys using the casper-client
    • secret_key.pem - Secret key used by the validator node to sign blocks and peer-to-peer messages
    • public_key.pem - Public key associated with the secret key above, stored in PEM format
    • public_key_hex - Public key associated with the secret key above, stored in hex format
  • 1_0_0/ - Folder for genesis configuration files, containing:
    • accounts.toml - Contains the genesis validators and delegators
    • chainspec.toml - Contains invariant network settings, with the activation_point (network start time) as a timestamp
    • config-example.toml - Example for creating a config.toml file
    • config.toml - Contains variable node configuration settings, created by a node operator manually or by running config_from_example.sh 1_0_0
  • m_n_p/ - Folder for each installed upgrade package's configuration files, containing:
    • chainspec.toml - Contains invariant network settings, with the activation_point as an era ID (the era at which this protocol version of the node became or will become active)
    • config-example.toml - As per 1_0_0/config-example.toml, but compatible with the m.n.p version of the node
    • config.toml - As per 1_0_0/config.toml, but compatible with the m.n.p version of the node

/var/lib/casper/

This is the location for larger and variable data for the casper-node, organized in the following folders and files:

  • bin/ - The parent folder for storing the versions of casper-node executables. This location can be overwritten with the CASPER_BIN_DIR environment variable. The paths in this document assume the default of /var/lib/casper/bin/.

    • 1_0_0/ - Folder for genesis binary files, containing:
      • casper-node - The node executable - defaults to the Ubuntu 18.04 compatible binary
      • README.md - Information about the repository location and the Git hash used for compilation to allow a rebuild on other platforms
    • m_n_p/ - Folder for each installed upgrade package, containing:
      • casper-node - As per 1_0_0/casper-node, but the m.n.p version of the node
      • README.md - As per 1_0_0/README.md, but compatible with the m.n.p version of the node
  • casper-node/<NETWORK NAME> - Folder containing databases and related files produced by the node binary. For MainNet, the network name is casper and for TestNet it is casper-test.

    • data.lmdb - Persistent global state store of the network
    • data.lmbd-lock - Lockfile for the data.lmdb database
    • storage.lmdb - Persistent store of all other network data, primarily Blocks and Deploys
    • storage.lmdb-lock - Lockfile for the storage.lmdb database
    • unit_files/ - Folder containing transient caches of consensus information

Node Version Installation

Included with casper-node-launcher is node_util.py for installing casper-node versions. To stage all current casper-node versions we would run:

sudo -u casper /etc/casper/node_util.py stage_protocols <NETWORK_CONFIG>

For <NETWORK_CONFIG>, We use casper.conf for MainNet and casper-test.conf for TestNet. This will install all currently released protocols in one step.

This is invoked with the release version in underscore format such as:

sudo -u casper /etc/casper/pull_casper_node_version.sh 1_0_2

This command will do the following:

  • Create /var/lib/casper/bin/1_0_2/ and expand the bin.tar.gz containing at a minimum casper-node
  • Create /etc/casper/1_0_2/ and expand the config.tar.gz containing chainspec.toml, config-example.toml, and possibly accounts.csv and other files
  • Remove the archive files and run /etc/casper/config_from_example.sh 1_0_2 to create a config.toml from the config-example.toml

Client Installation

The Prerequisites page lists installation instructions for the Casper client.

Create and Fund Keys

The Rust client generates keys via the keygen command. The process generates 2 pem files and 1 text file. To learn about options for generating keys, include --help when running the keygen command. The following command will create the keys in the /etc/casper/validator_keys folder. For details on funding your accounts, see Prerequisites.

sudo -u casper casper-client keygen /etc/casper/validator_keys
note

It is recommended to save your keys in a secure location, preferably offline.

More about keys and key generation can be found in /etc/casper/validator_keys/README.md if casper-node-launcher was installed from the Debian package. You can also find for more information on keys, in the Accounts and Cryptographic Keys section.

Config File

One config.toml file exists for each casper-node version installed. It is located in the /etc/casper/[m_n_p]/ directory, where m_n_p is the current semantic version. This can be created from config-example.toml by using /etc/casper/config_from_example.sh [m_n_p] where [m_n_p] is replaced current version with underscores.

Below are some fields in the config.toml that you may need to adjust.

Trusted Hash for Synchronizing

The Casper network is a permissionless, proof of stake network - which implies that validators can come and go from the network. The implication is that, after a point in time, historical data could have less security if it is retrieved from 'any node' on the network. Therefore, joining the network has to be from a trusted source, a bonded validator. The system will start from the hash from a recent block and then work backward from that block to obtain the deploys and finalized blocks from the linear block store. Here is the process to get the trusted hash:

  • Find a list of trusted validators
  • Query the status endpoint of a trusted validator (http://<NODE_IP_ADDRESS>:8888/status)
  • Obtain the hash of a block from the status endpoint
  • Update the config.toml for the node to include the trusted hash. There is a field dedicated to this near the top of the file

Secret Keys

Provide the path to the secret keys for the node. This is set to etc/casper/validator_keys/ by default.

Networking and Gossiping

The node requires a publicly accessible IP address. The config_from_example.sh and node_util.py both allow IP for network address translation (NAT) setup. Specify the public IP address of the node. If you use the config_from_example.sh external services are called to find your IP and this is inserted into the created config.toml.

Default values are specified in the file if you want to change them:

  • Specify the port that will be used for status and deploys
  • Specify the port used for networking
  • Known_addresses - these are the bootstrap nodes (no need to change these)