Polygon is a Layer 2 Blockchain designed to address Ethereum’s scaling challenges. It enables faster transactions and significantly lower costs running alongside Ethereum. By running a Polygon node, you can actively participate in the network and perform various tasks such as development, staking, or simply contributing to decentralization.
This guide provides a step-by-step walkthrough for setting up your own Polygon node. We’ll cover the key terminologies, and the configuration of Heimdall and Bor nodes – the two core components of the Polygon network. By the end of this article, you’ll have a Polygon Node running and syncing with the blockchain network.
What Is a Polygon Node?
A Polygon node is a compute node (machine) that participates in the Polygon network by validating transactions, producing blocks, and securing the network. It interacts with three distinct layers:
- Ethereum: The security layer of Polygon, ensuring everything is safe.
- Heimdall: The Proof of Stake (PoS) layer that syncs state and validator data with Ethereum.
- Bor: The EVM-compatible layer that processes transactions and produces blocks.
By running a node, you help maintain the network while enabling faster and more reliable interaction with Polygon’s infrastructure.
Types of Polygon Nodes
There are two main types of Polygon nodes you can run:
1. Full Node
- Role: Store a copy of the blockchain and validate transactions.
- Sub-types:
- Pruned Nodes: Store only the most recent data (lightweight).
- Archive Nodes: Store all historical blockchain data (storage-intensive).
- Use Case: Ideal for developers or those supporting the network without staking.
2. Validator Node
- Role: Actively participate in consensus, propose, validate, and produce new blocks.
- Requirements: Must stake
MATIC tokens and maintain high computational performance and uptime.
- Use Case: Suitable for those looking to earn staking rewards and secure the network.
For the scope of this tutorial, we’ll be running Polygon Full Node.
Prerequisites
- A Virtual Machine (such as the ones provided by NodeShift) with at least:
- 8 vCPUs
- 32 GB RAM
- 2 TB SSD
- Ubuntu 22.04 VM
Note: The prerequisites for this are highly variable across use cases. One could use a high-end configuration for a large-scale deployment.
Step-by-step process to run Polygon Node
For this tutorial, we’ll use a CPU-powered Virtual Machine by NodeShift, which provides high-compute Virtual Machines at a very affordable cost on a scale that meets GDPR, SOC2, and ISO27001 requirements. Also, it offers an intuitive and user-friendly interface, making it easier for beginners to get started with Cloud deployments. However, feel free to use any cloud provider you choose and follow the same steps for the rest of the tutorial.
Step 1: Setting up a NodeShift Account
Visit app.nodeshift.com and create an account by filling in basic details, or continue signing up with your Google/GitHub account.
If you already have an account, login straight to your dashboard.
Step 2: Request a Custom Quote
A high-compute node is needed to run a blockchain node like Polygon. These nodes are not included by default in the Computes Nodes tab; instead, you can place these types of customized high-end configurations using NodeShift’s Custom Order feature.
After accessing your account, you should see a dashboard (see image), now:
- Navigate to the menu on the left side.
- Click on the Custom Order option.
3. Click on Start to start creating customized node request.
Step 3: Select the configuration for the Required Nodes
- The first option you see is the Region dropdown. This option lets you select the geographical region where you want to launch your VM (e.g., United States).
2. Next, you see the Reliability dropdown, where you can choose the uptime guarantee level you seek for your VM. As of now, we’re going with “High Availability”.
3. Select the time commitment, e.g., 24 hours, 12 months, etc.
4. Most importantly, select the correct specifications for your VM according to your workload requirements by sliding the bars for each option. For the scope of this tutorial, we’ll be requesting a 8vCPUs/64GB/2TB SSD VM which is somewhat similar to our “Prerequisites”.
Step 4: Choose an Image and Place Request
Next, you’ll need to choose an image for your Virtual Machine. We’ll select Ubuntu, as we will run our Polygon Node on Ubuntu 22.04. You may also add any additional comments or information you want the team to know beforehand.
If the configuration looks good, click Request Quote to submit the quote request.
Once the request is placed, the NodeShift team will respond within 24 hours with a quote. You review the quote; if it looks good and receives approval from your end, the team will deploy the requested resources into your account.
Step 5: Connect to the Compute Node with SSH
As soon as you receive the resources in your account, follow the steps outlined below to connect to the VM with the help of SSH:
- Open your local terminal and run the below SSH command:
(replace root with your username and paste the IP of your VM in place of ip)
ssh root@ip
2. In some cases, your terminal may take your consent before connecting. Enter ‘yes’.
3. A prompt will request a password. Type the server’s password (that has been assigned to you), and you should be connected.
Output:
Step 6: Prepare the System for Installation
Before we move on to the actual setup of the Polygon Node, we first need to perform some prerequisite steps to make the system compatible with the installation:
- Update the Ubuntu package source-list to the latest version for security updates and upgrade the softwares.
sudo apt-get update && sudo apt-get upgrade -y
Output:
2. Install build essentials required for compiling the software
sudo apt-get install build-essential -y
Output:
3. Enable the firewall ports to allow the Polygon Node to communicate with the blockchain network.
Run each of these commands one by one:
sudo ufw allow 26656
sudo ufw allow 30303
sudo ufw allow 22/tcp
sudo ufw enable
Output:
Step 7: Install Heimdall
Now, our system is ready to set up the first part of the Polygon Node, i.e. Heimdall.
Let’s install and configure Heimdall.
- Install Heimdall using the following command
Replace:
<heimdall_version>: with the latest version or the version you wish to install.<network_type>: with mainnet or amoy (testnet).<node_type>: with the node type you wish to set up for e.g., a full node like sentry.
curl -L https://raw.githubusercontent.com/maticnetwork/install/main/heimdall.sh | bash -s -- <heimdall_version> <network_type> <node_type>
Output:
2. Use the below command to confirm the installation
heimdalld version --long
Output:
If you download Heimdall binaries for the mainnet, you need to define the seeds after downloading the binaries.
Note: If you’re setting up for testnet (amoy), you can skip these steps and move on with the Bor Installation.
Use the command below to update the seeds in configuration:
sed -i 's|^seeds =.*|seeds = "1500161dd491b67fb1ac81868952be49e2509c9f@52.78.36.216:26656,dd4a3f1750af5765266231b9d8ac764599921736@3.36.224.80:26656,8ea4f592ad6cc38d7532aff418d1fb97052463af@34.240.245.39:26656,e772e1fb8c3492a9570a377a5eafdb1dc53cd778@54.194.245.5:26656,6726b826df45ac8e9afb4bdb2469c7771bd797f1@52.209.21.164:26656"|g' /var/lib/heimdall/config/config.toml
Then change the ownership of the configuration to the Heimdall user:
chown heimdall /var/lib/heimdall
This allows Heimdall users to access and modify the configuration files.
Step 8: Install Bor
Let’s install the other part of our Polygon Full node, i.e. Bor.
- Download and install the Bor binary
Replace:
<bor_version>: with the latest version or the version you wish to install.<network_type>: with mainnet or amoy (testnet).<node_type>: with the node type you wish to set up, e.g., a full node like sentry.
curl -L https://raw.githubusercontent.com/maticnetwork/install/main/bor.sh | bash -s -- <bor_version> <network_type> <node_type>
Output:
2. Use the below command to confirm the installation
bor version
Output:
If you are downloading Bor binaries for the mainnet, you need to define the seeds after downloading the binaries.
Note: If you’re setting up for testnet (amoy), you can skip these steps and move on.
Use the commands below one after another to update the seeds in configuration:
sed -i 's|.*\[p2p.discovery\]| \[p2p.discovery\] |g' /var/lib/bor/config.toml
sed -i 's|.*bootnodes =.*| bootnodes = ["enode://b8f1cc9c5d4403703fbf377116469667d2b1823c0daf16b7250aa576bacf399e42c3930ccfcb02c5df6879565a2b8931335565f0e8d3f8e72385ecf4a4bf160a@3.36.224.80:30303", "enode://8729e0c825f3d9cad382555f3e46dcff21af323e89025a0e6312df541f4a9e73abfa562d64906f5e59c51fe6f0501b3e61b07979606c56329c020ed739910759@54.194.245.5:30303"]|g' /var/lib/bor/config.toml
Then change the ownership to allow Bor user to access the configuration directory.
chown bor /var/lib/bor
3. Update the service permissions
We need to update the necessary service permissions for both Heimdall and Bor so they can run smoothly.
Use the following commands to update the user permissions for both:
sed -i 's/User=heimdall/User=root/g' /lib/systemd/system/heimdalld.service
sed -i 's/User=bor/User=root/g' /lib/systemd/system/bor.service
Step 9: Start the Heimdall Node
Now, it’s time for us to start our Nodes and sync the data from the Polygon Network.
- Start the Heimdall Service
sudo service heimdalld start
2. Check logs
Check the log messages to ensure the Node is running correctly:
journalctl -u heimdalld.service -f
Output:
3. To check if the Heimdall node is syncing as expected, use the following command:
curl localhost:26657/status
Output:
As you can observe in the above image, if you see “catching_up: true” in your output, it indicates that the node is syncing with the network.
Once the sync is complete, this will turn to false. However, syncing a node from scratch may take several days. Hence, to speed up this process, we will use the snapshot method to extract and sync the data from the Polygon network in significantly less time.
The following few steps will outline how to use a snapshot:
4. Stop Heimdall Service
Before we go ahead to download the snapshot, we need to stop the Heimdall node:
sudo service heimdalld stop
5. Download the Snapshot
a) Navigate to the Heimdall data directory
cd /var/lib/heimdall
b) Remove the existing data directory and contents
rm -r ./data
c) Download snapshot
For this tutorial, we are using PublicNode to download the snapshot. However, you can download it from any platform of your choice.
(replace <your_snapshot_link> with your snapshot’s link)
wget <your_snapshot_link>
Output:
6. Use lz4 to extract the snapshot data
First, install lz4 using the following command:
sudo apt install lz4
Output:
Now, decompress and extract the data from the snapshot:
(replace <your_snapshot_filename> with your snapshot’s filename that you can find in the link you’ve used for downloading the snapshot)
lz4 -d <your_snapshot_filename> | tar xvf -
After extracting, update the ownership of the data directory
sudo chown -R heimdall:nogroup /var/lib/heimdall
7. Restart Heimdall Node
Restart the Heimdall service and check the sync status
sudo service heimdalld start
curl localhost:26657/status
Keep checking the status at some intervals until you find the catching_up parameter as false (see image below). Depending on your system resources, it might take a few hours to complete the sync, if not days.
Once it has turned to false, it means the sync is complete and the node is up to date with the Polygon blockchain network. You can now go ahead and start the Bor Node.
Step 10: Start the Bor Node
As our Heimdall Node is finally synced, we can start the Bor Node now, following similar steps as for Heimdall.
- Navigate to the Bor data directory
cd /var/lib/bor
2. Remove any existing data directory or content
rm -r ./chaindata
3. Download the data from the snapshot (we used PublicNode as before)
(replace <your_snapshot_link> with your snapshot’s link)
wget <your_snapshot_link>
Output:
4. Use lz4 to decompress and extract the data from the downloaded snapshot
(replace <your_snapshot_filename> with your snapshot’s filename that you can find in the link you’ve used for downloading the snapshot)
lz4 -d <your_snapshot_filename> | tar xvf -
Output:
5. Start Bor Node
Now that we’ve extracted the data from the snapshot, let’s start Bor Node and check if it is syncing the data.
Start the Node:
sudo service bor start
Check logs:
journalctl -u bor.service -f
Output:
As you can see, our Bor Node is running perfectly and syncing the data as expected.
Conclusion
In this guide we walked you through the steps to set up and run a Polygon node, enabling you to actively engage with one of the leading blockchain networks. Polygon offers powerful tools for scaling Ethereum and building decentralized applications, and running your own node not only helps you leverage its capabilities but also gives you an opportunity to support decentralization. Even though running a Blockchain Node is often considered a heavy-duty task in terms of resources and expenses, with NodeShift, you can make this process simpler and more efficient with its robust compute resources offered at a much more affordable rate. Doesn’t matter if you’re a beginner or an already experienced developer, NodeShift has customized solutions for projects of all scales.
