Skip to main content

Run a full node with Binaries

This tutorial guides you through starting and running a full node using binaries. For the system requirements, see the Minimum Technical Requirements guide.

note

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.

Prerequisites

  • Minimum hardware requirements:
    • 4-8+ core CPU
    • 16-32GB RAM
    • 2TB+ SSD free storage space
  • Build-essential packages
  • Golang version 1.18+

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.2.11, contains enhancements such as:

  1. Restricting data size in state sync txs to:
    • 30Kb when represented in bytes
    • 60Kb when represented as string
  2. 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
# Mainnet: git checkout v0.2.11-mainnet
# Testnet: git checkout v0.2.1-mumbai
git checkout <TAG OR BRANCH>
make install

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.2.16
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="[email protected]:26656,[email protected]:26656"

    # Testnet:
    seeds="[email protected]:26656,[email protected]:26656"
    • Change the value of Pex to true
    • Change the value of Prometheus to true
    • Set the max_open_connections value to 100

    Make sure you keep the proper formatting when you make the above changes.

  • 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://0cb82b395094ee4a2915e9714894627de9ed8498fb881cec6db7c65e8b9a5bd7f[email protected]44.232.55.71:30303,enode://88116f4295f5a31538ae409e4d44ad40d22e44ee9342869e7d68bdec55b0f83c1[email protected]159.203.9.164:30303"

    # Testnet:
    --bootnodes "enode://320553cda00dfc003f499a3ce9598029f364fbb3ed1222fdc20a94d97dcc4d8ba[email protected]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

  1. On the remote machine/VM, run curl localhost:26657/status
  2. 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.