Skip to main content
Sign in MENU

[In-Depth Guide] Casper Node Set-up, Deep Dive, Tips & Troubleshooting

Taylor
  • Updated

Who's this guide for?

This guide is for anyone who is a prospective Casper node operator, either with intentions to operate as a validator on the network to earn CSPR rewards, or as a "listen-only" node, providing an endpoint to interact with the Casper network.

 

Casper Node System Requirements

The casper node software requires closer to industry-standard database server specifications. At present, CasperLabs recommends prospective node operators stand up a node with the following specifications:

  • 4 Cores
  • 32 GB Ram
  • 2 TB SSD or network SSD backed disk
  • Linux machine running Ubuntu 18.04 or 20.04 (preferred)

NOTES: 

  • SSD is required because HDD cannot perform random writes at the performance needed to keep in sync with the full speed of the network.
  • For non-archival nodes, disc usage will drop once data recovery is implemented. It is safe to slowly increase the disc space as needed while monitoring on a server capable of this.

For more information, see our hardware specifications here.

Basic Node Set-up

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 casper-client

For documentation to install the casper-node to RedHat / CentOS, please see our official guide over on GitHub here.

 

Common File Locations and Contents

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.

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.

 

/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

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

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.

 

Building Contracts​

  1. Clone the casper-node repository.
git clone https://github.com/casper-network/casper-node

  1. To build contracts, set up Rust and install all dependencies, see Installing Rust in the Developer Guide.

  2. Use the following commands to build the contracts in release mode:

cd casper-node
make setup-rs
make build-client-contracts

These commands will build all the necessary WASM files. You can use these contracts for bonding, retrieving rewards and unbonding:

  • activate_bid.wasm - reactivates an ejected validator
  • add_bid.wasm - enables bonding for validator stake
  • delegate.wasm - delegates stake
  • undelegate.wasm - undelegates stake
  • withdraw_bid.wasm - enables unbonding for validator stake

Update the Trusted Hash​

The node's config.toml needs to be updated with a recent trusted hash.

Retrieving a Trusted Hash​

Visit a /status endpoint of a validating node to obtain a fresh trusted block hash. The default port is usually 8888. Retrieve the last_added_block_info: hash.

# This will return JSON and we want result.block.hash
casper-client get-block --node-address http://<NODE_IP_ADDRESS>:7777 -b 20

# If jq is installed we can pull it from the JSON return directly with
casper-client get-block --node-address http://<NODE_IP_ADDRESS>:7777 -b 20 | jq -r .result.block.hash

If your node becomes stuck with downloading blocks while synchronizing, you can force the node to attempt to continue syncing by updating the trusted hash of the currently running version's `config.toml` located in `/etc/casper/m_n_p/config.toml`. For a node that has progressed through the synchronization to version 1.4.8 for example, you can force the node to try to resume syncing by updating the trusted hash with the hash of a block ~20 blocks above the height your node has stopped synchronizing :

export CASPER_VERSION=1.4.8 
export OTHER_PEER_IP_ADDRESS=<other_peer_ip_address>
export BLOCK_HEIGHT=$(curl -s http://localhost:8888/status | jq -r .last_added_block_info.height) + 20 # this command does not work copy/paste!

sed -i "/trusted_hash =/c\trusted_hash = '$(sudo -u casper casper-client get-block --node-address http://$OTHER_PEER_IP_ADDRESS:7777 -b $BLOCK_HEIGHT | jq -r .result.block.hash | tr -d '\n')'" /etc/casper/$CASPER_VERSION/config.toml

 

For more information on trusted hash, see Trusted Hash for Synchronizing.

 

 

Known Addresses​

For the node to connect to a network, the node needs a set of trusted peers for that network. For Mainnet, these are listed in the config.toml as known_addresses. For other networks, locate and update the list to include at least two trusted IP addresses for peers in that network. Here is an example configuration. The casper-protocol-release repository stores configurations for various environments, which you can also use as examples.

 

Stage all network upgrades

This command will download and stage all available node upgrades to your machine so they are prepped when the node is turned on, and will automatically execute the upgrade and the required time. $CASPER_NETWORK should be set to either casper (mainnet) or casper-test (testnet):

 

sudo -u casper /etc/casper/node_util.py stage_protocols $CASPER_NETWORK.conf

 

Start the Node​

The Debian package installs a casper-node service for systemd. Start the node with:

sudo systemctl start casper-node-launcher

For more information, visit GitHub.

Confirm the Node is Synchronized​

While the node is synchronizing, the /status endpoint is available. You will be able to compare this to another node's status endpoint era_id and height to determine if you are caught up. You will not be able to perform any casper-client calls to your 7777 RPC port until your node is fully caught up.

 

You can monitor the peer count and blocks downloaded by your node by executing this command:

/etc/casper/node_util.py watch

If you have any concerns, questions, or issues, please submit a request to our support team here:

https://support.casperlabs.io/hc/en-gb/requests/new

Related articles

Comments

0 comments

Please sign in to leave a comment.

Powered by Zendesk