Welcome to our official guide for setting up a Zenon Network Pillar. This comprehensive manual will walk you through selecting the right hosting provider, configuring your server, installing necessary dependencies, and deploying the Zenon controller. Whether you're a seasoned developer or new to blockchain infrastructure, this guide will ensure a smooth and secure setup process.
Technical
Welcome to the Zenon technical documentation. Please email [email protected] if you'd like to contribute to its maintenance.
You can change the default DataPath using znnd --data "value"
Folder Structure
The Zenon Node has the following folder structure:
.
├── config.json - config file used by znnd
├── consensus - consensus DB used by znnd
├── genesis.json - genesis config file. Used to create the genesis Momentum
├── log - logs generated by znnd
│ ├── error - only error logs generated by znnd
│ │ └── zenon.error.log - latest logs - maxes out at 100MB
│ └── zenon.log - latest logs - maxes out at 100MB
├── network - network DB used by znnd
├── network-private-key - network identity
├── nom - nom DB used by znnd
├── syrius - syrius files
└── wallet - folder cointaining all keyFiles
├── user-1 - keyFile with custom name
└── z1qpnq2hl2... - keyFile with no custom name
Migration Guide (On Pillar)
This guide outlines the steps to migrate an existing orchestrator from one Pillar virtual machine (VM) to another, preserving its ability to participate in the HyperCore bridge’s Threshold Signature Scheme (TSS) signer set. It builds on the Orchestrator Setup Guide on Pillar.
Table of Contents
1) Prerequisites
Old VM Access: Ensure the original VM (old Pillar) is still accessible and running the orchestrator.
New VM Setup: The new VM should have a working Pillar node synced with the Zenon Network of Momentum (NoM), as per the .
Backup: Back up the old VM’s orchestrator directory (/root/.orchestrator) and producer keystore before proceeding.
2) Set Up the Orchestrator on the New VM
If the orchestrator isn’t already installed on the new VM, follow the initial setup steps from the first.
3) Transfer the Orchestrator Configuration
Copy the entire .orchestrator folder from the old VM to the new VM. This includes the old /producer folder and old config.json:
4) Set Up and Start the Orchestrator Service
Follow of the Setup Guide.
5) Verify Migration
Confirm the orchestrator is functioning and recognized by the bridge.
a) Check Logs:
View recent logs for errors:
b) Test Health Check:
Query the orchestrator’s API:
Expected output includes version info, e.g.,
Node Deployment
There are 3 types of nodes: Pillar, Sentinel, Full Node.
Pillar
For the Pillar deployment process one will need access to both a local and a remote machine. The local machine is represented by the controller wallet, where you create the Pillar Slot and register the Pillar on the network. The remote machine is usually represented by a VPS with some minimum recommended specs and a public IP that is actively participating in the consensus protocol.
You will need to generate 3 distinct addresses for the Pillar creation tutorial:
SSH Access: You need SSH access to both the old and new VMs with sufficient permissions (e.g., root or sudo).
pillarAddress = address from which the Pillar is registered that contains the necessary funds (15,000 ZNN that will be locked and can be recovered after you disassemble the Pillar and 150,000 QSR + additional 10,000 QSR for every new Pillar Slot in the network that will be burned and cannot be recovered)
pillarRewardsAddress = address used to collect the Pillar rewards
producerAddress = address used to produce the momentums that is stored on the remote machine; must be generated from a different seed than your local wallet keyStore for security purposes
Sentinel
The Sentinel deployment process is similar to the Pillar deployment process.
Controller Wallet
The latest version of the s y r i u s wallet is recommended to be used as controller wallet. Advanced users can use the znn-cli instead.
Remote Machine
These commands should be issued from your remote machine (e.g. VPS). If you won't use a VPS provider, you will need an
additional setup including enabling port forwarding. This tutorial is intended for a VPS with some minimum recommended specs and a public IP.
Minimum Requirements
Hardware:
CPU >= 4 cores
RAM >= 4 GB
Storage >= 40 GB free space
>100Mbps network dedicated bandwidth
Software:
Linux distros e.g. Ubuntu 20.04 LTS/Debian 11
Recommended NTP configuration*
Recommended Watchdog service*
(*) Included if the setup is performed using the znn-controller
Before proceeding with the update, ensure you have the following:
Access Credentials: SSH access to your server with sudo privileges.
Basic Knowledge: Familiarity with command-line interfaces and server management.
Backup: It's recommended to back up your current configuration and controller files before performing the update.
2) Stop the znnd Service
Access Your Server via SSH:
Open your terminal and connect to your server using SSH:
Replace username with your server's username (commonly root) and your_server_ip with your server's IP address.
Stop the znnd Service:
Run the znn-controller executable and select the option to Stop Service the znnd service.
Interactive Prompt:
Action:
Enter 4 and press Enter to stop the running the znnd service.
Note: Ensure the service has completely stopped before proceeding to the next step. You can enter 2 and press Enter to verify the Status of the znnd service.
3) Download the Latest znn-controller
Identify the Latest Release URL:
Visit the Zenon Network GitHub Repository to find the latest version of the znn-controller. Copy the download URL for the x86/64 Linux release.
Download the Latest Controller:
Replace YOUR_LATEST_URL with the actual URL of the latest znn-controller release.
Example:
4) Replace the Existing znn-controller File
Extract the Downloaded ZIP File:
-o Flag: Overwrites existing files without prompting.
Remove the ZIP File:
5) Deploy the Updated Controller
Run the Updated znn-controller:
Deployment Options:
Upon execution, you will be presented with deployment options:
Select Deploy Option:
Action: Enter 1 and press Enter to deploy the updated controller.
Continue Using Existing Configuration:
Prompt:
Action: Enter Y and press Enter to confirm.
6) Verify the Update
Check the Status of the Controller:
Run the znn-controller and select the status option to verify that the update was successful.
Interactive Prompt:
Action: Enter 2 and press Enter to view the current status.
The Zenon Alphanet (Phase 0) binaries are available for Linux, macOS and Windows x86_64 CPU architecture operating systems.
Ubuntu 20.04 LTS was used for this tutorial.
1. Download the Binaries
Download znnd, znn-cli and znn-controller from their respective GitHub repos. Please note that znn-controller is only available for Linux at the moment.
2. Verification (depreciated)
Import the Zenon Testnet PGP key from hkps.pool.sks-keyservers.net
If you don't have gpg installed, please use sudo apt install gnupg
Verify the signature. The same command can be used on macOS:
3. Start the Node Daemon
If you are on a Linux machine, use the znn-controller option 1) Deploy:
Otherwise use:
4. Verify Node RPC Communication
Inspect the config.json file using your favorite text editor.
Navigate to ~/.znn/config.json.
Check if the http, websocket entries are enabled (true). By default, all Endpoints are public.
The default HTTPPort is 35997 and WSPort is 35998.
You can also disable the RPC communication viaznn-cli:
5. Generate a ZNN Alphanet Address (optional)
6. Check for Pending Funds (optional)
If you have pending funds you should see messages like these:
7. Receive the Pending Funds (optional)
In order to receive the ZNN you need to issue the command receive with the corresponding hash:
If you don't have Plasma, you'll need to generate it via PoW, please wait.
Similarly, you'll receive the QSR by issuing the command receive with the corresponding hash:
8. Check Your Balance (optional)
9. Deploy a Pillar, Sentinel or Full Node
Follow these instructions to deploy a Pillar or Sentinel.
10. Stop the Node Daemon
You can use the stop command from znn-cli if znnd is located at the same working directory:
If you deployed via znn-controller please use option 4 (Stop service)
Otherwise use:
ssh username@your_server_ip
unzip -o znn_controller-linux-x86_64.zip
./znn-controller
1) Deploy
2) Status
3) Start service
4) Stop service
5) Resync
6) Help
7) Quit
Select an option from the ones listed above
Continue using the existing configuration? (Y/N):
./znn-controller
1) Deploy
2) Status
3) Start service
4) Stop service
5) Resync
6) Help
7) Quit
Select an option from the ones listed above
Unreceived 15000.00000000 ZNN from z1qqjr86g6220kmhn2jrelwhtk7u0mp4r5amjwf2.
Use hash b3e51142119174f8af3ea793a7353ec8b5b4e2208f9ebe50549ead5440fd6b49 to receive.
Unreceived 15000.00000000 QSR from z1qqjr86g6220kmhn2jrelwhtk7u0mp4r5amjwf2.
Use hash c68c674c81d4d9abc2b7a20c999352c21a8128033f9b34105b3616119f116e3c to receive.
Basic Knowledge: Familiarity with command-line interfaces and server management.
Access Credentials: SSH access to your chosen server with sudo privileges.
2) Choosing a Hosting Provider
Selecting a reliable hosting provider is crucial for the stability and performance of your Zenon Pillar. Consider the following factors when choosing a provider:
Reliability and Uptime: Ensure the provider offers high uptime guarantees (99.9% or higher).
Performance: Look for providers with robust CPU and RAM options to handle blockchain operations.
Scalability: Ability to upgrade resources as your node grows.
Popular Hosting Providers:
DigitalOcean
Amazon Web Services (AWS)
Hetzner
Choose a provider that best fits your requirements and budget.
3) Minimum Hardware Requirements
To ensure optimal performance and stability of your Zenon Pillar, your server should meet the following minimum hardware specifications:
Component
Minimum Requirement
4) Choosing the Operating System
For optimal performance and compatibility with the Zenon controller, it is recommended to use a Linux distribution. The x86/64 znn_controller-linux release is compatible with several distros, including:
Ubuntu 22.04 LTS (Recommended)
Debian 11
CentOS 8
5) Server Setup and Configuration
Accessing the Server
Obtain SSH Credentials:
After setting up your server with your chosen provider, retrieve the SSH IP address, username, and password/key.
Connect via SSH:
Replace username with your server's username (commonly root) and your_server_ip with your server's IP address.
Updating the System
Ensure your server's package lists and installed packages are up to date by running the command individually:
apt update: Updates the package index.
apt upgrade -y: Upgrades all installed packages to their latest versions.
Installing Required Packages
Install unzip and other necessary utilities:
unzip: Required for extracting the Zenon controller ZIP file.
wget: Facilitates downloading files from the internet.
6) Installing the Zenon Controller
Download the Zenon Controller:
Execute the following command to download and extract the Zenon controller:
Visit the official Zenon Network Github repository for the latest znn_controller_dart release:
wget -O: Downloads the file and saves it with the specified name.
7) Configuring Automatic Restarts with Cron
For the initial sync of your Zenon Pillar, it's recommended to configure automatic restarts. This ensures that the controller restarts hourly, speeding up the sync process.
Open Crontab Editor:
Add Cron Job:
Press i
Once your Pillar catches up to the latest height, disable the automatic restart cron by commenting out the line:
# 0 * * * * /usr/bin/sudo /usr/sbin/service go-zenon restart
8) Deploying the Pillar
Start the Zenon Controller:
Deployment Options:
Upon running the controller, you will be presented with deployment options. To deploy your pillar:
9) Post-Deployment Steps
After your pillar has successfully synced to the latest height, it's crucial to remove the cron job so that the Pillar doesn't miss momentums unnecessarily:
Comment Out the Cron Job:
Prevent the automatic restart to avoid interrupting the controller's operation.
Re-open Crontab Editor:
10) Useful Commands
Watch the Pillar's logs in real-time:
Verify the Sync / Height Status:
Replace the PRIVATE-IP with your Pillar's Private IP address:
You will receive a response:
When the state goes from 1 to 2, then your Pillar is fully synced.
Setup Guide (On Pillar)
By setting up a Zenon Pillar, you play a pivotal role in enhancing the decentralization, security, and overall robustness of the Zenon ecosystem.
This setup guide is for operators looking to setup the Orchestrator binary on the same server as their Pillar. If you're looking to setup on a remote server (not on the Pillar), then please follow the following: Setup Guide (Remote).
Table of Contents
Migration Guide
If you're looking to migrate your Pillar to a new hosting provider.
Security: Features like DDoS protection, firewalls, and regular backups.
Support: 24/7 customer support can be invaluable.
Cost: Balance between features and your budget.
Google Cloud Platform (GCP)
Microsoft Azure
Vultr
Linode
Fedora 36
Switch to Root User:
This command grants you root privileges for the installation process.
unzip -o: Extracts the ZIP file, overwriting existing files if necessary.
rm: Removes the ZIP file after extraction to save space.
Verify Installation:
Ensure the znn-controller executable is present:
You should see the znn-controller file listed.
to enter insert mode.
Navigate to the end of the file.
Add the following line to schedule a restart every hour:
Save and Exit:
Press Esc to exit insert mode.
Type :wq and press Enter to save and quit.
Select option 1) Deploy
Monitoring Synchronization:
The controller will begin syncing to the latest block height of the Zenon network. This process may take some time (even days) depending on network conditions and server performance. To monitor the status of your sync:
Basic Knowledge: Familiarity with command-line interfaces and server management.
Access Credentials: SSH access to your chosen server with sudo privileges.
BNB and Ethereum Nodes: Access to a BNB and Ethereum node provider like Alchemy to obtain WebSocket (WSS) endpoints.
Producer Passphrase: The passphrase for your Producer Key File, retrievable via the znn-controller.
QSR Tokens: At least 120 QSR tokens fused to the Pillar Producer Address.
2) Opening Required Firewall Ports
To facilitate communication and health checks, ensure the following ports are open on your server’s firewall:
1. Port 55055 (TCP): Open for gossip communication between nodes.
2. Port 55000 (TCP): Open for API health checks.
Steps to Open Ports:
Assuming you’re using ufw (Uncomplicated Firewall) on Ubuntu:
Note: If you’re using a different firewall management tool, adjust the commands accordingly.
3) Obtaining a Binance Smart Chain and Ethereum Node from Alchemy
To interact with the Binance Smart Chain and Ethereum network, you need access to a Binance Smart Chain and Ethereum node. Alchemy provides reliable node services.
It's recommend leaving your existing Pillar online during the migration if it's still producing momentums. The migration is seemless, the only difference between the Setup Guide and this Migration Guide, is that you will copy your new Pillar's producer address and update it in your syrius wallet for the Pillar's reward address. Details are provided in Step 9) Update Producer Address.
1) Prerequisites
Before proceeding, ensure you have the following:
Basic Knowledge: Familiarity with command-line interfaces and server management.
Access Credentials: SSH access to your chosen server with sudo privileges.
2) Choosing a Hosting Provider
Selecting a reliable hosting provider is crucial for the stability and performance of your Zenon Pillar. Consider the following factors when choosing a provider:
Reliability and Uptime: Ensure the provider offers high uptime guarantees (99.9% or higher).
Performance: Look for providers with robust CPU and RAM options to handle blockchain operations.
Scalability: Ability to upgrade resources as your node grows.
Security: Features like DDoS protection, firewalls, and regular backups.
Support: 24/7 customer support can be invaluable.
Cost: Balance between features and your budget.
Popular Hosting Providers:
DigitalOcean
Amazon Web Services (AWS)
Hetzner
Google Cloud Platform (GCP)
Microsoft Azure
Vultr
Linode
Choose a provider that best fits your requirements and budget.
3) Minimum Hardware Requirements
To ensure optimal performance and stability of your Zenon Pillar, your server should meet the following minimum hardware specifications:
Component
Minimum Requirement
CPU
≥ 4 cores (ideally 8 CPU for the initial sync)
RAM
≥ 4 GB (ideally 16 GB for the initial sync)
Storage
≥ 40 GB free space
Network
4) Choosing the Operating System
For optimal performance and compatibility with the Zenon controller, it is recommended to use a Linux distribution. The x86/64 znn_controller-linux release is compatible with several distros, including:
Ubuntu 22.04 LTS (Recommended)
Debian 11
CentOS 8
Fedora 36
5) Server Setup and Configuration
Accessing the Server
Obtain SSH Credentials:
After setting up your server with your chosen provider, retrieve the SSH IP address, username, and password/key.
Connect via SSH:
Replace username with your server's username (commonly root) and your_server_ip with your server's IP address.
Switch to Root User:
This command grants you root privileges for the installation process.
Updating the System
Ensure your server's package lists and installed packages are up to date by running the command individually:
apt update: Updates the package index.
apt upgrade -y: Upgrades all installed packages to their latest versions.
Installing Required Packages
Install unzip and other necessary utilities:
unzip: Required for extracting the Zenon controller ZIP file.
wget: Facilitates downloading files from the internet.
6) Installing the Zenon Controller
Download the Zenon Controller:
Execute the following command to download and extract the Zenon controller:
wget -O: Downloads the file and saves it with the specified name.
unzip -o: Extracts the ZIP file, overwriting existing files if necessary.
rm: Removes the ZIP file after extraction to save space.
Verify Installation:
Ensure the znn-controller executable is present:
You should see the znn-controller file listed.
7) Configuring Automatic Restarts with Cron
For the initial sync of your Zenon Pillar, it's recommended to configure automatic restarts. This ensures that the controller restarts hourly, speeding up the sync process.
Open Crontab Editor:
Add Cron Job:
Press i to enter insert mode.
Navigate to the end of the file.
Add the following line to schedule a restart every hour:
Save and Exit:
Press Esc to exit insert mode.
Type :wq and press Enter to save and quit.
Once your Pillar catches up to the latest height, disable the automatic restart cron by commenting out the line:
# 0 * * * * /usr/bin/sudo /usr/sbin/service go-zenon restart
8) Deploying the Pillar
Start the Zenon Controller:
Deployment Options:
Upon running the controller, you will be presented with deployment options. To deploy your pillar:
Select option 1) Deploy
Monitoring Synchronization:
The controller will begin syncing to the latest block height of the Zenon network. This process may take some time (even days) depending on network conditions and server performance. To monitor the status of your sync:
Select option 2) Status
And compare it to the latest height in your syrius wallet, or trusted Zenon Network explorers:
9) Update Producer Address
Once and ONLY once your new Pillar has synced up to the latest height, should you proceed with this step of the migration. If you update your producer address prior to a full sync, you will miss rewards as your Pillar will not be participating in the network until it's fully caught up.
Therefore if your new Pillar reached the latest height:
Select the address of the Pillar you're migrating.
Click on Pillars in the navigation bar.
Click on +Update Pillar
For the Pillar producer address field, paste the new Pillar's Producer Address, and press Next and Update until it saves the new address. Steps to get your new Pillar's Address are written below.
Start the Zenon Controller:
Deployment Options:
Upon running the controller, you will be presented with deployment options. To deploy your pillar:
Select option 2) Status
Copy Producer Address
Use this new Pillar Producer Address to update in the syrius wallet.
10) Post-Deployment Steps
After your pillar has successfully synced to the latest height and you've updated your Pillar's Producer Address in your syrius wallet, it's crucial to remove the cron job so that the Pillar doesn't miss momentums unnecessarily:
Comment Out the Cron Job:
Prevent the automatic restart to avoid interrupting the controller's operation.
Re-open Crontab Editor:
Locate the Cron Job:
Add a # at the Beginning:
This comments out the line, disabling the scheduled restart.
Save and Exit:
Press Esc to exit insert mode.
Type :wq and press Enter to save and quit.
Shut down old Pillar on old Hosting Provider:
Once the above steps have been completed, you can shut down your server which hosted your old Pillar. It is recommended that you delete the server only after you've successfully collected your Pillar rewards in the syrius wallet (using the new Pillar's Producer Address). You can wait until the next reward distribution for this (the next day, depending at which hour of the day you've migrated).
11) Useful Commands
Watch the Pillar's logs in real-time:
Verify the Sync / Height Status:
Replace the PRIVATE-IP with your Pillar's Private IP address:
You will receive a response:
When the state goes from 1 to 2, then your Pillar is fully synced.
