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.

⚠️ Guide Usage

This guide assumes that you have properly created and connected to your VPS successfully and installed the nodectl utility.

Build Your Node💽The nodectl utility

🧰 Prerequisites

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.

---

🔐 SSH Into Your VPS

Use the following command to connect to your VPS via SSH:

ssh -i /path/to/ssh/private/key root@<vps_ip_address>

SSH Remote Access

---

📄 Verify Your Node Is on the Seed List

To confirm that your node is recognized by the network, run:

sudo nodectl check_seedlist -p dag-l0

Expected Output:

NODE ID FOUND ON SEED LIST
True

🛑 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.

---

⬆️ Perform a Node Upgrade

Use the upgrade command to prepare your node for the cluster connection:

sudo nodectl upgrade -ni

The -ni flag enables non-interactive mode, accepting default values automatically.

---

⚙️ For Single Layer1 Nodes

If you're operating a Layer1-only Metagraph Validator, you may skip directly to the Join Layer1 step at the bottom of this guide.

---

🧬 For Hybrid Nodes

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

---

📥 Monitor for DownloadInProgress State

After upgrading, verify your node has reached the correct syncing phase:

sudo nodectl status -p dag-l0

Expected Output:

JOIN STATE
DownloadInProgress

If you see SessionStarted, continue running the command periodically until it transitions to DownloadInProgress.

---

⏳ Wait for Ready State

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.

---

🚀 Optional: Execute Starchiver to Speed Up Sync

To accelerate snapshot syncing:

sudo nodectl execute_starchiver -p dag-l0 --restart

👀 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.

---

📊 Verify Node Status

Once your node has completed downloading the snapshot chain, it will enter the Ready state and begin participating in consensus.

To verify:

sudo nodectl status -p dag-l0

Look for the following:

Layer0
JOIN STATE       Ready
IN CONSENSUS     True

For Layer1:

Layer1
JOIN STATE       ReadyToJoin

🔄 To monitor the transition in real time:

sudo nodectl status -p dag-l0 -w 120

Use the q key to exit the watch command gracefully.

---

🔗 Join Layer1 (For Hybrid Nodes Only)

If Layer1 displays ReadyToJoin, you may initiate the join process:

sudo nodectl join -p dag-l1

If your node is in any other state, restart the profile before retrying:

sudo nodectl restart -p dag-l1

---

Once the above steps are complete and your node is fully synced and participating in consensus, your first-time connection process is complete.