# Upgrade Tessellation Guide

## Introduction

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

***

{% stepper %}
{% step %}

## SSH Into Your VPS

### [<kbd>How to SSH into a VPS</kbd>](https://docs.constellationnetwork.io/run-a-node/references/ssh-remote-access/how-to-ssh-into-vps)&#x20;

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

{% endstep %}

{% step %}

### Issue the Upgrade Command

```
sudo nodectl upgrade
```

{% endstep %}

{% step %}

### Migration Considerations

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

**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 <kbd>Enter</kbd> 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
```

{% hint style="danger" %}
**DANGER**&#x20;

If you did not encrypt you p12 keystore passphrase within the nodectl configuration file, the backup configuration `yaml` file <mark style="color:red;">MAY CONTAIN A CLEAR TEXT P12 PASSPHRASE.</mark>

FOR SECURITY PURPOSES, PLEASE REMOVE AS NECESSARY!
{% endhint %}

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

[<kbd>Backup P12 Keystore</kbd>](https://docs.constellationnetwork.io/run-a-node/validator-node-guides/operational-guides/backup-restore-a-p12-keystore)&#x20;
{% endstep %}

{% step %}

### Confirm upgrade <a href="#confirm-upgrade" id="confirm-upgrade"></a>

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

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

{% endstep %}

{% step %}

### Environment Confirmation <a href="#environment-confirmation" id="environment-confirmation"></a>

We will see what environment is being upgraded.

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

or

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

{% endstep %}

{% step %}

### 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
```

{% endstep %}

{% step %}

### Verify Node Upgrade <a href="#verify-node-upgrade" id="verify-node-upgrade"></a>

The `nodectl` utility will begin by verifying that the upgrade path is valid.&#x20;

```
---- * 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.
{% endstep %}

{% step %}

### Determine p12 details <a href="#determine-p12-details" id="determine-p12-details"></a>

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
```

{% endstep %}

{% step %}

### 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 <kbd>Enter</kbd> to accept the default version.

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

<mark style="color:orange;">Already on latest warning</mark>

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 <kbd>Enter</kbd> 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.
```

{% endstep %}

{% step %}

### Understanding Environments

The `nodectl` utility organizes your configured profiles into logical groups called **environments**.&#x20;

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
```

{% endstep %}

{% step %}

### 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.
{% endstep %}

{% step %}

### 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.
{% endstep %}

{% step %}

### Clean up backups

{% hint style="warning" %}
Backup files may contain plaintext P12 keystore passphrases. If you have not encrypted your P12 keystore, please keep this in mind.
{% endhint %}

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
```

{% endstep %}

{% step %}

### 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
```

{% endstep %}

{% step %}

### Clean up logs

Similar to **backups**, you may have accumulated a large number of **log** files.&#x20;

Over time, these logs can consume significant disk space on your node.&#x20;

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

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
```

{% endstep %}

{% step %}

### 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
```

{% endstep %}

{% step %}

### 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
```

{% hint style="success" %}
Currently, it is expected that the `dag-l1` (Hypergraph Currency DAG L1) profile has a disabled seed list.
{% endhint %}
{% endstep %}

{% step %}

### 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.&#x20;

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

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]:
```

{% endstep %}

{% step %}

### 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
```

{% endstep %}

{% step %}

### 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.
{% endstep %}

{% step %}

### 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.
{% endstep %}

{% step %}

### 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.
{% endstep %}

{% step %}

### 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.
{% endstep %}

{% step %}

### 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**.
{% endstep %}

{% step %}

### 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.
{% endstep %}

{% step %}

### 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. &#x20;

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**:

   ```bash
   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:

     ```bash
     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.
{% endstep %}

{% step %}

### 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.
{% endstep %}
{% endstepper %}