🚋Migrate V1 to V2 - P12 Keystore

Convert a Version 1 p12 keystore to Version 2 for operations on Constellation Network.

Constellation Network has introduced a new version 2 standard for .p12 keystore files. These updated keystores are now required to access the Hypergraph and metagraph clusters.

Version 1 .p12 files are no longer supported.

---

📌 Purpose of This Guide

This guide is intended to help Node Operators still using version 1 .p12 files migrate their private key to the updated version 2 format, ensuring compatibility with current network requirements.

---

🛠️ Setup Requirements

	Option	Description
1	Live Constellation Validator Node	Utilize an existing Constellation Network validator node with all components already installed.
2	Ephemeral VPS with nodectl	Build a temporary VPS, install nodectl, use its utility to migrate your p12 from version 1 to version 2.
3	Load utilities necessary only	Use an existing or build a temporary VPS and only install the utilities necessary to complete this guide.

Option 1: Use an Existing Node With nodectl

If you already have nodectl running:

• Upload your version 1 .p12 file using the restore process.

  • Refer to platform-specific steps:

    • Restore .p12 from macOS

    • Restore .p12 from Windows

⚠️ Caution: Do not overwrite an existing or active .p12 file in a running Validator node environment.

---

Option 2: Create a Temporary VPS

If you don’t have an existing node:

1. Provision a new Linux VPS (Debian-based preferred).

2. Upload your version 1 .p12 file.

3. Install nodectl following the official documentation.

💡 Note: This VPS will not be used to run a Validator node. Its purpose is solely to install the required tools for migration.

✅ Minimum Requirements:

• 30GB of disk space

• Internet connectivity

• SSH access

---

Option 3: Manual Setup

Alternatively, install the required components manually:

• java

• haveged

• cl-keytool.jar

• cl-wallet.jar

📎 Still ensure the VPS or machine has at least 30GB of available disk space.

---

🔄 Begin the Conversion Process

Once setup is complete, proceed with the following steps.

---

Step 1: Upload Your .p12 File

Place your original version 1 .p12 file (from macOS or Windows) into the working directory of your VPS.

Example path:

/home/nodeadmin/tessellation/

---

Step 2: Set Environment Variables

Export the following environment variables using your .p12 file details. Be precise—use double quotes and match spacing exactly.

export CL_KEYALIAS="myConstellationAlias"
export CL_KEYSTORE="/home/nodeadmin/tessellation/myconstellation.p12"
export CL_PASSWORD="my_password"
export CL_STOREPASS="my_storepass_passphrase"
export CL_KEYPASS="my_keystore_passphrase"

Confirm the exports:

env | grep CL_

Expected output:

CL_KEYALIAS=myConstellationAlias
CL_KEYSTORE=/home/nodeadmin/tessellation/myconstellation.p12
CL_PASSWORD=my_password
CL_STOREPASS=my_storepass_passphrase
CL_KEYPASS=my_keystore_passphrase

---

Step 3: Run the Migration Command

Run the following command to migrate the .p12 file to version 2 format:

java -jar /var/tessellation/cl-keytool.jar migrate

✅ If successful, no output will appear. If there's an issue, an error will be printed.

---

Step 4: Verify the New File

List the directory to verify that a new version 2 .p12 file has been created:

ls -l

Expected output (example):

-rw-r--r-- 1 nodeadmin nodeadmin 1094 May 26 12:17 myconstellation_v2.p12

---

Step 5: Test the New .p12 File

Update your CL_KEYSTORE variable to point to the new file:

export CL_KEYSTORE="/home/nodeadmin/tessellation/myconstellation_v2.p12"

Now display the public key to confirm the file is valid:

java -jar /var/tessellation/cl-wallet.jar show-public-key

Example output:

EC Public Key [ee:ff:aa:bb:cc:dd:ee:ff:11:22:33:44:55:66:77:88:99:aa:bb:cc]
  X: abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890
  Y: 111222333444555666777888999101010111111121212131313141414151515a

---

✅ Completion

Your .p12 file is now migrated from version 1 to version 2.

🔒 Important: Store the original version 1 file in a secure, offline (air-gapped) location temporarily.

---

🧪 Final Testing

To fully validate your new .p12 file:

• Connect to the appropriate Constellation cluster (Layer0 or Layer1).

• Export and verify the private key.

• Use the new file in your validator setup or wallet integration.

---

🔁 Optional: Rename the New File

If you want to use the original filename, rename your new file:

mv /home/nodeadmin/tessellation/myconstellation_v2.p12 /home/nodeadmin/tessellation/myconstellation.p12

---

⚙️ nodectl Configuration (If Applicable)

If you're using nodectl and kept the _v2 filename, make sure to update the configuration:

sudo nodectl configure

This ensures nodectl references the correct .p12 file for all future operations.

---

You have now successfully migrated and verified your .p12 keystore to the latest version, ensuring your validator remains compatible with Constellation Network's current infrastructure.