🏭Upgrade Tessellation Guide

Introduction

This document will guide you through step-by-step instructions for upgrading your node to the latest version of Tessellation.

---

1

SSH Into Your VPS

How to SSH into a VPS

ssh -i /path/to/ssh/private/key nodeadmin@<vps_ip_address> -p <port>

2

Issue the Upgrade Command

sudo nodectl upgrade

3

Migration Considerations

In some cases, when a new feature is introduced, it may require updating nodectl’s main configuration file, cn-config.yaml.

If the upgrade in progress does not require this step, you will not see any messages and can skip to the next step.

The migration ensures that nodectl can support the new features while preserving your existing configuration settings.

We can press Enter to accept the default y.

Attempt update and migrate configuration file? [y]: y

You will see nodectl backup your current configuration before continuing.

Backing up cn-config yaml ..................... complete

DANGER

If you did not encrypt you p12 keystore passphrase within the nodectl configuration file, the backup configuration yaml file MAY CONTAIN A CLEAR TEXT P12 PASSPHRASE.

FOR SECURITY PURPOSES, PLEASE REMOVE AS NECESSARY!

It is recommended to backup your p12 after the migration and upgrade completes.

Backup P12 Keystore

4

Confirm upgrade

We will be asked if we are sure we want to continue the installation. We can hit the enter key to accept the default y or type in y + enter to confirm.

Are you sure you want to continue this upgrade? [y]: y

5

Environment Confirmation

We will see what environment is being upgraded.

Using environment ............................. mainnet

or

Using environment ............................. integrationnet

6

Configuration Backup

A backup of our configuration will commence and output:

Backing up configuration ......................complete
Backup Date: YYYY-MM-DD-HH:MM:SSZ
Backup Location: /var/tessellation/backups/
Backup File Name: backup_cn-config_YYY-MM-DD-HH:MM:SSZ

7

Verify Node Upgrade

The nodectl utility will begin by verifying that the upgrade path is valid.

---- * VERIFY NODE UPGRADE * -----
Verify upgrade paths .......................... complete

If the upgrade path not valid, you will be met with the following message:

Check permissions & versioning ................ warning
This is not a current stable version of nodectl.
Recommended to:
    - Cancel this upgrade of Tessellation.
    - Issue: sudo nodectl upgrade_nodectl
    - Restart this upgrade of Tessellation.
WARNING non-interactive mode was detected, developer mode, or extra parameters were supplied to this upgrade.
It will continue at the node Operator's own risk and decision.

It is recommended upgrade nodectl after the upgrade is complete using the correct upgrade paths.

8

Determine p12 details

The nodectl utility will:

• Validate the p12 usage for all profiles.

• Determine if nodectl is using global references.

• Obtain the nodeid from the p12 file.

Verify upgrade paths .......................... complete
p12 validated [dag-l0] ........................ using global
p12 validated [dag-l1] ........................ using global
Global p12 validated .......................... True
Obtaining node ID from p12 [global] ........... 11111....11111
Node IP address ............................... 113.113.113.113

9

Select Tessellation Version

The nodectl utility will attempt to identify the current version of Tessellation running on your node, as well as the latest version available on the cluster.

In most cases, you may simply press Enter to accept the default version.

Press enter to accept the default value between [] brackets.
Please enter version to upgrade to.........[v3.0.0] :

Already on latest warning

If you attempt an upgrade to a version of Tessellation you are already running on your node, you may be presented with a warning message. If you intent is to upgrade to the same version over itself, you may press Enter to continue. Otherwise, you may take another action as desired.

WARNING Tessellation is already on the latest known version.
If you are only upgrading the node's internal components because your node is exhibiting undesirable or unexpected behavior, you should accept the default and upgrade your node's version to the same version level by simply hitting <enter> here.

10

Understanding Environments

The nodectl utility organizes your configured profiles into logical groups called environments.

Each environment typically represents a specific network cluster, such as:

• MainNet

• IntegrationNet

• TestNet

• DOR

During an upgrade process, nodectl allows you to upgrade one environment at a time. This ensures consistency and reduces risk when applying updates across network types.

Most validator nodes only have one environment configured, making the process straightforward.

When you initiate an upgrade, nodectl will display a summary showing:

• The environment name

• The list of associated profiles under that environment

Review this printout carefully before proceeding to ensure you’re upgrading the correct environment.

Example) dag-l1 profile.

====================
PROFILE:     dag-l1
ENVIRONMENT: mainnet
METAGRAPH:   hypergraph

Cluster mainnet for profile dag-l1 using v3.0.0

11

Leave the cluster & Stop your node

Gracefully leaving the cluster is highly recommended before performing upgrades, maintenance, or reboots. This practice helps:

• Prevent snapshot corruption

• Reduce unnecessary load on the rest of the cluster

• Maintain overall network health and stability

The nodectl utility automates this process by:

1. Issuing an internal API call to gracefully leave the cluster

2. Stopping the service(s) associated with the selected profile(s)

3. Bringing the node offline in a controlled and orderly fashion

This ensures your node exits the cluster cleanly and avoids disrupting consensus or data synchronization.

12

Upgrade Node Internal Elements

The nodectl utility will begin the upgrade process by performing several important housekeeping and system preparation steps:

1. Clean up abandoned utility-specific files

   • Removes outdated or unused internal files from previous versions

2. Rebuild essential configuration and support files

   • Ensures that all components are aligned with the latest version's requirements

3. Apply system-level updates

   • Installs the latest updates available for your current distribution

   • ⚠️ Note: This does not upgrade the entire Linux distribution

4. Install or update required 3rd-party utilities

   • Adds or refreshes tools that nodectl depends on for proper operation

These steps help ensure that your node environment is clean, consistent, and fully prepared to run the latest version of nodectl effectively.

13

Clean up backups

Backup files may contain plaintext P12 keystore passphrases. If you have not encrypted your P12 keystore, please keep this in mind.

In most cases it is a good idea to clear your backups. If you are in the mist of troubleshooting, you may want to retain your backups.

Are you sure you want to clear the selected backups? [n]: y

14

Clean up uploads

Similar to the backups you may have some files that were created in order to upload for diagnostics, logging, accounting, etc. We can clean up these files as well.

In the event that your node has files located in this special directory, you will be given a list of the files that will be removed and a confirmation prompt.

In most cases it is a good idea to clear your uploads. If you are in the mist of troubleshooting, you may want to retain these files.

Are you sure you want to clear the selected uploads? [n]: y

15

Clean up logs

Similar to backups, you may have accumulated a large number of log files.

Over time, these logs can consume significant disk space on your node.

Since your node also stores incremental history data and the tip of the blockchain, maintaining sufficient disk space is essential.

In most cases, it is a good idea to clear old logs; however, if you are actively troubleshooting an issue, you may want to retain these files.

Are you sure you want to clear the selected logs? [n]: y

16

Upgrade Tessellation Binaries

The nodectl utility will download the necessary packages that will upgrade your node to the latest version.

--------- * HANDLE PACKAGES * ----------

Download Tessellation Binaries................. running
backup files .................................. complete

Download version .............................. v3.0.0
Fetch [cl-keytool.jar -> global] .............. complete
Fetch [cl-wallet.jar -> global] ............... complete
Fetch [cl-node.jar -> dag-l0] ................. complete
Fetch [cl-dag-l1.jar -> dag-l1] ............... complete

17

Update Seed List

It is crucial that your node's seed list matches the latest seed list recognized by the cluster. If there is not an exact match, the node will fail to connect to the network.

Fetch [mainnet-seedlist -> dag-l0] ............ completed
Fetch [seedlist for -> dag-l1] ................ disabled

Currently, it is expected that the dag-l1 (Hypergraph Currency DAG L1) profile has a disabled seed list.

18

P12 Keystore Passphrase Encryption

The nodectl utility will attempt to determine whether the passphrase for your P12 keystore is encrypted within the cn-config.yaml configuration file.

If it detects the passphrase in plaintext, you will be prompted to encrypt it to enhance your node's security.

While encrypting your P12 passphrase is optional, it is strongly recommended.

Do you want to encrypt the passphrase in your cn-config.yaml configuration file?
Enable encrypt? [y]:

19

Updating Services

Now that your node is ready to rejoin the cluster with its newly updated components, the following services will be restarted:

• Protocol services

• Auto-restart services

• Versioning services

Reload the Node's services .................... complete
Starting versioning updater ................... complete

20

Start Protocol Services

You will see the node start the layer0 profile (for a Hybrid node) or the Data Layer 1 service for a Dor metagraph (or any other single-layer metagraph node).

Start request initiated [node_l0] ............. complete
Fetching Status [dag-l0] ......................

You will a status update confirming your node is in ReadyToJoin status.

21

ReadyToJoin

The configured layer0 profile will rejoin the network. In this case the profile dag-l0 is configured as the layer0 and will attempt to join.

22

SessionStarted

After some initial setup behind the scenes, your node will reach SessionStarted and wait for an opportunity to issue a join against one of the peers of the cluster that is in a state that will allow you to join with the node and become a member of the cluster.

23

DownloadInProgress

Once a successful join is achieved, the node will begin catching up on any historical snapshots that were created while it was offline. It will complete the accumulation of historical data and retrieve the tip of the blockchain, ensuring the node's current state aligns with the cluster.

24

Ready

After your node completes the DownloadInProgress stage, it will transition through several additional states as it finalizes synchronization and prepares to join the network consensus rounds.

The typical progression is as follows:

1. WaitingForObserving

2. Observing

3. WaitingForReady

---

✅ Final Goal: Ready

Once your node completes these transitional stages, it will enter the Ready state.

At this point, your node is fully integrated into the network and eligible to begin participating in consensus and earning rewards.

25

Hybrid Nodes

A hybrid node includes both a Layer 1 (L1) and a Layer 0 (L0) profile running on the same VPS or server.

• Layer0: DAG L0 global hypergraph layer0

• Layer1 : DAG L1 currency layer

In this configuration, it's recommended to link the L1 profile to the local L0 profile. This is beneficial because, in a trustless environment, you can confidently trust the L0 node you control; essentially trusting yourself.

---

By linking locally in this way, you take advantage of trusted internal communication between layers while maintaining protocol integrity and minimizing external risk.

26

Joining Layer1 on a Hybrid Node

During the upgrade process, the system will attempt to join the DAG L1 (currency layer) profile to the cluster.

As explained in the previous step, the Layer 1 profile is configured to link to your local Layer 0 (dag-l0) profile. In order for this to succeed, your Layer 0 profile must first reach the Ready state.

---

Timing Considerations

In most cases, the Layer 0 profile takes longer to complete its startup and synchronization steps.

This means:

• The Layer 1 profile may not detect the Layer 0 profile as Ready in time

• As a result, it may fail to join automatically during the upgrade window

How nodectl Handles This

To accommodate this, nodectl will:

• Present a menu prompt asking whether you’d like to continue waiting or

• Skip the join process and allow the upgrade to complete without joining Layer 1

If You Choose to Skip:

You can manually complete the join process later:

1. Use the following command to check the Layer 0 status:

   sudo nodectl status -p dag-l0

   Wait until it reaches Ready.

2. Once ready, you can either:

   • Run a manual join command for Layer 1:

     sudo nodectl join -p dag-l1

   • Or rely on auto_restart (if enabled) to detect readiness and automatically join Layer 1 when conditions are met

---

This flexible design ensures your node upgrades cleanly, even if the timing of the Layer 0 readiness introduces delays.

27

Final Steps

After the join process completes, nodectl will:

1. Display summary metrics related to the upgrade operations

2. Restart the auto_restart feature, if it was enabled prior to the upgrade

   • This ensures your node continues to be monitored and automatically maintained moving forward

This final step confirms that your upgrade and cluster rejoin were successful, and your node is once again operating in a self-managed, resilient state.