Intermediate

 

How to run a full node with Binaries on Polygon network

This tutorial guides you through starting and running a full node on the Polygon network using binaries. The process of syncing the Heimdall and Bor services can take several days, but you can also use a maintained snapshot to reduce the sync time to a few hours. Steps include installing build-essential, Go, Heimdall and Bor binaries, setting up services, configuring the full node machine, starting the full node machine and checking the node’s health with the community. Make sure you follow the outlined sequence of actions in the correct order to avoid issues.

Technical Requirements

Minimum Hardware Configuration​

This is the minimum hardware configuration required to setup a full node:

RAM: 16-32 GB

CPU: 4-8 core CPU (For AWS: t3.2xlarge)

Storage: 2.5TB to 5TB SSD (make sure it is extendable)

TIP

The minimum storage requirements will change over time as the network grows. It is recommended to use more than the minimum requirements to run a robust full node.

While we do not favor any operating system, more secure and stable Linux server distributions (like CentOS) should be preferred over desktop operating systems (like Mac OS and Windows).

Run a full node with Binaries

This tutorial guides you through starting and running a full node using binaries.

Steps in this guide involve waiting for the Heimdall and Bor services to fully sync. This process takes several days to complete.

Alternatively, you can use a maintained snapshot, which will reduce the sync time to a few hours. For detailed instructions, see Snapshot Instructions for Heimdall and Bor.

For snapshot download links, see the Polygon Chains Snapshots page.

Overview​

• Prepare the machine

• Install Heimdall and Bor binaries on the full node machine

• Set up Heimdall and Bor services on the full node machine

• Configure the full node machine

• Start the full node machine

• Check node health with the community

 

NOTE

You have to follow the exact outlined sequence of actions, otherwise you will run into issues.

Install build-essential​

This is required for your full node. In order to install, run the below command:

sudo apt-get update
sudo apt-get install build-essential

 

Install GO​

This is also required for running your full node. Installing v1.18 or above is recommended.

wget https://raw.githubusercontent.com/maticnetwork/node-ansible/master/go-install.sh
bash go-install.sh
sudo ln -nfs ~/.go/bin/go /usr/bin/go

 

Install Binaries​

Polygon node consists of 2 layers: Heimdall and Bor. Heimdall is a tendermint fork that monitors contracts in parallel with the Ethereum network. Bor is basically a Geth fork that generates blocks shuffled by Heimdall nodes.

Both binaries must be installed and run in the correct order to function properly.

Heimdall​

Install the latest version of Heimdall and related services. Make sure you checkout to the correct release version. Note that the latest version, Heimdall v.0.3.0, contains enhancements such as:

Restricting data size in state sync txs to:

30Kb when represented in bytes

60Kb when represented as string

Increasing the delay time between the contract events of different validators to ensure that the mempool doesn’t get filled very quickly in case of a burst of events which can hamper the progress of the chain.

The following example shows how the data size is restricted:

Data - "abcd1234"
Length in string format - 8
Hex Byte representation - [171 205 18 52]
Length in byte format - 4

 

To install Heimdall, run the below commands:

 

cd ~/
git clone https://github.com/maticnetwork/heimdall
cd heimdall

# Checkout to a proper version, for example
git checkout v0.3.0
git checkout <TAG OR BRANCH>
make install
source ~/.profile

 

That will install the heimdalld and heimdallcli binaries. Verify the installation by checking the Heimdall version on your machine:

 

heimdalld version --long

 

Bor​

Install the latest version of Bor. Make sure you git checkout to the correct released version.

cd ~/
git clone https://github.com/maticnetwork/bor
cd bor

# Checkout to a proper version
# For e.g: git checkout 0.3.3
git checkout <TAG OR BRANCH>
make bor-all
sudo ln -nfs ~/bor/build/bin/bor /usr/bin/bor
sudo ln -nfs ~/bor/build/bin/bootnode /usr/bin/bootnode

 

That will install the bor and bootnode binaries. Verify the installation by checking the Bor version on your machine:

 

bor version

 

Configure Node Files​

Fetch launch repo

 

cd ~/
git clone https://github.com/maticnetwork/launch

 

Configure launch directory​

To set up the network directory, the network name and type of node are required.

Available networks: mainnet-v1 and testnet-v4

Node type: sentry

TIP

For Mainnet and Testnet configuration, use appropriate <network-name>. Use mainnet-v1 for Polygon mainnet and testnet-v4 for Mumbai Testnet.

cd ~/
mkdir -p node
cp -rf launch/<network-name>/sentry/<node-type>/* ~/node

 

Configure network directories​

Heimdall data setup

cd ~/node/heimdall
bash setup.sh

 

Bor data setup

cd ~/node/bor
bash setup.sh

 

Configure Service Files​

Download service.sh file using appropriate <network-name>. Use mainnet-v1 for Polygon mainnet and testnet-v4 for Mumbai Testnet.

cd ~/node
wget https://raw.githubusercontent.com/maticnetwork/launch/master/<network-name>/service.sh

 

Generate the metadata file:

 

sudo mkdir -p /etc/matic
sudo chmod -R 777 /etc/matic/
touch /etc/matic/metadata

 

Generate .service files and copy them into system directory:

 

cd ~/node
bash service.sh
sudo cp *.service /etc/systemd/system/

 

Setup Config Files​

• Log in to the remote machine / VM

• You will need to add a few details in the config.toml file. To open and edit the config.toml file, run the following command: vi ~/.heimdalld/config/config.toml.

  In the config file, you will have to change Moniker and add seeds information:

moniker=<enter unique identifier>
# For example, moniker=my-sentry-node

# Mainnet:
seeds=”f4f605d60b8ffaaf15240564e58a81103510631c@159.203.9.164:26656,4fb1bc820088764a564d4f66bba1963d47d82329@44.232.55.71:26656″

# Testnet:
seeds=”4cd60c1d76e44b05f7dfd8bab3f447b119e87042@54.147.31.250:26656,b18bbe1f3d8576f4b73d9b18976e71c65e839149@34.226.134.117:26656″

moniker=<enter unique identifier>
# For example, moniker=my-sentry-node

# Mainnet:
seeds="f4f605d60b8ffaaf15240564e58a81103510631c@159.203.9.164:26656,4fb1bc820088764a564d4f66bba1963d47d82329@44.232.55.71:26656"

# Testnet:
seeds="4cd60c1d76e44b05f7dfd8bab3f447b119e87042@54.147.31.250:26656,b18bbe1f3d8576f4b73d9b18976e71c65e839149@34.226.134.117:26656"

 

•   Change the value of Pex to true

• Change the value of Prometheus to true

• Set the max_open_connections value to 100

•  

• Configure the following in ~/.heimdalld/config/heimdall-config.toml:

 

eth_rpc_url=<insert Infura or any full node RPC URL to Goerli>

 

Open the start.sh file for Bor using this command: vi ~/node/bor/start.sh. Add the following flags to start params:

# Mainnet:
--bootnodes "enode://0cb82b395094ee4a2915e9714894627de9ed8498fb881cec6db7c65e8b9a5bd7f2f25cc84e71e89d0947e51c76e85d0847de848c7782b13c0255247a6758178c@44.232.55.71:30303,enode://88116f4295f5a31538ae409e4d44ad40d22e44ee9342869e7d68bdec55b0f83c1530355ce8b41fbec0928a7d75a5745d528450d30aec92066ab6ba1ee351d710@159.203.9.164:30303"

# Testnet:
--bootnodes "enode://320553cda00dfc003f499a3ce9598029f364fbb3ed1222fdc20a94d97dcc4d8ba0cd0bfa996579dcc6d17a534741fb0a5da303a90579431259150de66b597251@54.147.31.250:30303"

 

To enable Archive mode, you can add the following flags in the start.sh file:

 

--gcmode 'archive' \
--ws --ws.port 8546 --ws.addr 0.0.0.0 --ws.origins '*' \

 

Start Services​

Run the full Heimdall node with these commands on your Sentry Node:

sudo service heimdalld start
sudo service heimdalld-rest-server start

 

Now, you need to make sure that Heimdall is synced completely, and then only start Bor. If you start Bor without Heimdall syncing completely, you will run into issues frequently.

To check if Heimdall is synced

On the remote machine/VM, run curl localhost:26657/status

In the output, catching_up value should be false

Once Heimdall is synced, run the below command:

sudo service bor start

 

Logs​

Logs can be managed by the journalctl linux tool. Here is a tutorial for advanced usage: How To Use Journalctl to View and Manipulate Systemd Logs.

Check Heimdall node logs

journalctl -u heimdalld.service -f

 

Check Heimdall Rest-server logs

journalctl -u heimdalld-rest-server.service -f

 

Check Bor Rest-server logs

journalctl -u bor.service -f

 

Ports and Firewall Setup​

Open ports 22, 26656 and 30303 to world (0.0.0.0/0) on sentry node firewall.

You can use VPN to restrict access for port 22 as per your requirement and security guidelines.