Skip to main content

First Time Connection Quick Start Guide

This guide is specifically for connecting a validator node to a Constellation Network Hypergraph or metagraph cluster for the first time.

◽ Prerequisites

Please review the checklist and profile descriptions for a better understanding of how this document works.

We will use dag-l0 as our profile name throughout the guide. When necessary, this should be changed to match your node's profile.

◽ SSH into Your VPS

Review your notes for the connection string.

ssh -i /path/to/ssh/private/key nodeadmin@vps_ip_address

Refer to SSH Explanation, Mac SSH Guide, and Windows SSH Guide for detailed understanding.

◽ Verify you are on the seed list

sudo nodectl check_seedlist -p dag-l0
NODE ID FOUND ON SEED LIST
True

If you are not on the seed list, please 🛑 stop here and contact a Discord Administrator Team Lead from the Constellation Network Official Discord server.

You must wait for the next network cluster restart that includes a seed list update.

◽ Preform an upgrade

Utilizing the upgrade command, we can take care of most of the necessary items to ensure our node can join the cluster properly.

sudo nodectl upgrade -ni

The -ni will run the upgrade in non-interactive mode, using all the default values.

◽ Single Layer1 Nodes

Layer1 metagraph validators SHOULD skip to this step at the time.

◽ Hybrid Nodes

Hybrid nodes must be in Ready state on layer0 before completing a full connection cluster join.

EXPECTED FAILURE

After your node finishes connection steps to join the layer0 Hypergraph, you will see your Node attempt to connect to the layer1 profile and fail. This is expected, and can be ignored.

A new node must go through the process of obtaining the entire snapshot chain from the cluster. Layer1 is not allowed on the cluster until the layer0 cluster has its entire chain.

During this stage, your node will transition into SessionStarted and then transition again to DownloadInProgress state.

There are other states that the node may transition into; however, these two states are the most obvious to see.

◽ DownloadInProgress

After the upgrade completes, our goal is to see that our node has reached DownloadInProgress state. We will verify this by issuing this command.

sudo nodectl status -p dag-l0
JOIN STATE
DownloadInProgress

Repeat the command if you see SessionStarted until you reach DownloadInProgress.

◽ Wait for Ready

Our node now has to wait several days to complete the process of downloading all snapshots before it transitions itself into Ready state.

You may continue to the next optional step to speed this process up or you should bookmark this page and return to continue your first time connection, after you reach Ready state.

Our node now needs to wait several days to complete the process of downloading all snapshots before it transitions into the Ready state.

You may proceed to the next optional step to speed up this process, or bookmark this page and return once your node reaches the Ready state to continue your first-time connection.

◽ Execute Starchiver (optional)

To reduce the time to obtain your entire snapshot chain considerably, so you may join the cluster properly, you can utilize the starchiver utility.

sudo nodectl execute_starchiver -p dag-l0 --restart

While the Starchiver utility is running, you should keep a diligent eye on your node to make sure it completes successfully.

🚧 Caution

Starchiver is not a Constellation Network supported Utility. For troubleshooting or other needs, you can reach out to the owner of the project through the Github Repository. You may also contact the developers through the Constellation Network Official Discord server.

Use at your own risk

◽ Verify your status

Once your node has completed downloading the snapshot chain, it will transition from DownloadInProgess to Ready by going through several intermediary stages.

You can review your node's status by issuing the status command. We are looking for two main status output values:

  1. JOIN STATE
  2. IN CONSENSUS
sudo nodectl status -p dag-l0

Layer0

JOIN STATE
Ready
IN CONSENSUS
True

Layer1

JOIN STATE
ReadyToJoin

If your node has not reached the Ready stage, you can continuously watch the node's status by utilizing the -w (watch) option.

Make sure when you are done watching, you use the q to gracefully exit the status command.

sudo nodectl status -p dag-l0 -w 120

◽ Join layer1

If your node is in ReadyToJoin:

sudo nodectl join -p dag-l1

If your node is in any state other than Ready:

sudo nodectl restart -p dag-l1

Contents