First Time Cluster Connection
This guide walks you through connecting a Validator Node to a Constellation Network Hypergraph or metagraph cluster for the first time.
Last updated
Was this helpful?
This guide walks you through connecting a Validator Node to a Constellation Network Hypergraph or metagraph cluster for the first time.
Last updated
Was this helpful?
This guide assumes that you have properly created and connected to your VPS successfully and installed the nodectl utility.
Before beginning, ensure you’ve reviewed the full checklist and profile documentation.
This guide uses dag-l0
as the profile name.
Replace dag-l0
with your node’s actual profile name if it differs.
For example dor-dl1
for Dor data layer1 validator nodes.
Use the following command to connect to your VPS via SSH:
To confirm that your node is recognized by the network, run:
Expected Output:
🛑 If you are not on the seed list, stop here and contact a Discord Administrator Team Lead via the Constellation Network Official Discord. You must wait for the next cluster restart that includes a seed list update before continuing.
Use the upgrade command to prepare your node for the cluster connection:
The
-ni
flag enables non-interactive mode, accepting default values automatically.
If you're operating a Layer1-only Metagraph Validator, you may skip directly to the Join Layer1 step at the bottom of this guide.
Hybrid nodes must reach a Ready state on Layer0 before joining Layer1.
⚠️ Expected Behavior:
After your node completes Layer0 connection steps, it will attempt to join the Layer1 profile and fail. This is expected and not a concern at this stage.
This happens because Layer1 participation is blocked until your node fully syncs the Layer0 snapshot chain.
During this period, your node will transition through the following statuses:
SessionStarted
DownloadInProgress
After upgrading, verify your node has reached the correct syncing phase:
Expected Output:
If you see SessionStarted
, continue running the command periodically until it transitions to DownloadInProgress
.
Your node will now download the entire snapshot chain from the Layer0 cluster. This process may take several days.
You have two options:
Wait for your node to reach the Ready
state.
Proceed to the optional next step to speed up the snapshot process using the Starchiver utility.
To accelerate snapshot syncing:
👀 Monitor your node closely to ensure the process completes without error.
🚧 Caution:
Starchiver
is a community-supported tool and not officially supported by Constellation Network. Use at your own risk. For issues, contact the tool's maintainer via GitHub or seek help on the Constellation Discord.
Once your node has completed downloading the snapshot chain, it will enter the Ready
state and begin participating in consensus.
To verify:
Look for the following:
For Layer1:
🔄 To monitor the transition in real time:
Use the q
key to exit the watch command gracefully.
If Layer1 displays ReadyToJoin
, you may initiate the join process:
If your node is in any other state, restart the profile before retrying:
Once the above steps are complete and your node is fully synced and participating in consensus, your first-time connection process is complete.