Before setting up the Validator node
We recommend running the Validator node with Sentry. Otherwise, you may encounter security concerns and issues with your Validator node.
Downloading the Snapshot
It is recommended that you keep your snapshots handy before setting up the Validator node. Link to download and extract the snapshots: https://snapshots.polygon.technology/
RPC Endpoint for Node Setup
Validator nodes require an Ethereum-based RPC endpoint. You may use your own Ethereum node or utilize external infrastructure providers in our list. In order to see the list, click on the dropdown menu labeled Infra Providers in the navigation bar.
Open necessary ports
Port 26656 → Heimdall service will connect your node to another node's Heimdall service using this port.
Port 30303 → Bor service will connect your node to another node's Bor service using this port.
Port 22 → for the Validator to be able to SSH from wherever they are.
It is recommended to install the RabbitMQ service before setting up your Validator node. Please utilize the below commands to set up RabbitMQ (if not already installed):
sudo apt-get update
sudo apt install build-essential
sudo apt install erlang
sudo dpkg -i rabbitmq-server_3.10.8-1_all.deb
Mandatory Checklist for Validator Setup
Please follow the below checklist in order to set up your Validator node using Binaries, Ansible or Packages.
Checklist Binaries Ansible Packages Machines Required 2 Machines - Sentry & Validator 3 Machines - Local Machine, Sentry and Validator 2 Machines - Sentry & Validator Install Go Packages Yes No No Install Python No Yes (only on the Local Machine where the Ansible Playbook runs) No Install Ansible No Yes (only on one machine) No Install Bash No No Yes Run Build Essential Yes No No Node Setup Using Binaries Using Ansible Using Packages
Once your Sentry and Validator nodes are synced and running, head over to our Discord server and ask the community to health-check your nodes. You may check the logs by using the following commands:
- Heimdall logs →
journalctl -u heimdalld.service -f
- Bor logs →
journalctl -u bor.service -f
- Heimdall logs →
It is highly recommended to maintain a backup of the key files on your local machine. These might be needed in the situation of migration or outage. You may access the files using the commands below:
Ensure that Bor and Heimdall are on their right versions. Commands to verify the versions are provided below:
It is recommended to always maintain 2 sentries to maximize your node uptime.
Constantly keep checking the peer count on Heimdall and Bor service using the following commands:
curl localhost:26657/net_info? | jq .result.n_peers
bor attach .bor/data/bor.ipcadmin.peers.lengthinfo
For Validators, the output should be only one peer, which has to be a Sentry. Validators should connect only to the Sentry and not with external peers.
Sentry can connect with multiple peers.
1. How to: New node setup
Below are some additional information to the official documentation which might help while setting up a new node.
This document gives some additional details for setting up a new node based on Full Node Deployment guide.
VPN setup is required before proceeding with any of these steps can be done by referring Bastillion user guide.
If you are using Macbook, it has native Python 2.7 available which needs to be replaced by with anything Python 3.x.
Make sure if pip3 packages are installed correctly
If the above 3 steps are not done correctly then even though Ansible is installed, it can’t recognize the Ansible packages. You might face something like the below screenshot:
Also make sure there are no Go packages and any previous setup of Bor or Heimdall.
You can use the below commands to check whether these packages are existing or not;
If anything of that sort, please run the below command to delete and clean the whole setup;
ansible-playbook -l sentry playbooks/clean.yml
Otherwise there will be error like below image whenever you try to run
ansible sentry -m ping
Example of inventory.yml
Sentry Host IP and Validator Host IP have to be the same and colons should be provided at the end of the lines including IPs
Before connecting the remote machine using the below command, you must be added to the remote machine and it will provided by DevOps team
ssh -i <downloaded_key_file.key> <remote_user>@<ip/host>
Once they have confirmed the server access, you should be able to SSH to the remote machine.
You may face this error if there is any issue with Heimdall's config
This can be fixed by following steps:
Run the below commands(inside the 'node-ansible' folder):
git checkout fixing_symlinks_on_clean
git pull https://github.com/maticnetwork/node-ansible/tree/fixing_symlinks_on_
clean.ymlon your machine with clean.yml in the github repo
If there are any differences, replace the one on your machine with the one in the repo
You should be able to run the clean script now and then also be able to run the installation script
moniker=enter unique identifier
- the unique identifier asked as per the document (it can be anything, ex: your name)
eth_rpc_url =insert Infura or any full node RPC URL to Ethereum
For this step, sign in to https://infura.io (signup if you already don't have an account)
Copy the https endpoint provided under ethereum → keys → endpoints
- Provide the copied https endpoint as
- Provide the copied https endpoint as
2. Why do I have to keep ETH in my signer account?
ETH is required on your signer account because for submitting checkpoints to Ethereum, all transactions require ETH to be used as Gas. Hence, ETH is required in your Signer Account.
3. For a Polygon Validator, do I need to setup a Sentry and Validator node or can I just run the Validator node only?
For a Polygon Validator, our ecosystem and architecture demands that you run a Sentry + Validator setup. This is to ensure that your Validator node is not exposed to the public and only your Sentry node is.
Your Sentry node gleans information / blocks from the network and then relays them to the Validator for validation.
4. How to migrate to new nodes and then cut over?
Provision nodes and install all software as per the instructions.
Download the latest Heimdall and Bor snapshots on both nodes.
Move the Key and Keystore files to the new validator.
Shut down the current validator and sentry node.
Start all services on sentry, then the validator.
5. How to check the Heimdall version?
6. Which Private Key should we add when we generate validator key?
The Private key to be used is your Wallet's ETH address where your Matic testnet Tokens are stored. You can complete the setup with one public-private key pair tied to the address submitted on the form.
7. Where can we find Heimdall account info location?
For Linux package:
8. Which file do we add the API key?
Once you have created the API key, you need to add the API key in
9. Which file do we add the
You can add the
persistent_peers in the following file:
10. How to stop Heimdall and Bor services?
For Linux packages:
sudo service heimdalld stop
sudo service bor stop or
ps -aux | grep bor. Get the PID for Bor and then run the following command.
sudo kill -9 PID
11. How to remove Heimdall and Bor directories?
For Linux packages:
sudo rm -rf /etc/heimdall/*
sudo rm -rf /etc/bor/*
sudo rm -rf /var/lib/heimdall/
sudo rm -rf /var/lib/bor
12. How to reduce cache in Bor?
Bor supports the
--cache parameter which can reduce the cache to avoid running out of memory.
13. How to delete the Bor DB data?
bor --datadir /var/lib/bor/data removedb
service bor start