Joining Heimdall v2

Polygon Mainnet (PoS)
1

Hey Polygon community :waving_hand:

With the Heimdall v1 → v2 migration completed (for Amoy), any new contributor is free to join the Heimdall v2 network.

If you are running your system in a containerized fashion (e.g., via Docker, Kubernetes, etc…), proceed to this section, otherwise just go ahead.

The process is designed fairly simple and to a certain degree infrastructure-agnostic, just like with Heimdall v1. That said, you’ll still need to manually replace the genesis.json file due to the stateful nature of the migration (we retained application data from Heimdall-v1). Improvements to streamline this in the future are being explored.

Prerequisites

Before starting, ensure your system meets the minimum requirements to run a Polygon PoS node (and that you have a bor node running v2.2.8, or erigon v3.0.14) for amoy or mainnet. Also, please backup your current v1 HEIMDALL_HOME folder (if you are running it already…) and anything you might need later (service files, configs, data etc…)

Quickstart Guide

Follow these steps to spin up a Heimdall v2 node:

  1. Install Heimdall v2

    Use the following script to automatically install the correct binary:

    curl -L <https://raw.githubusercontent.com/maticnetwork/install/heimdall-v2/heimdall-v2.sh> | sudo bash -s -- v0.2.8 <NETWORK> <NODE_TYPE>

    Replace <NETWORK> with amoy or mainnet (only amoy supported atm), and <NODE_TYPE> with either validator or sentry.

    Just like in Heimdall v1, the script detects your system’s architecture and operating system, installs the appropriate .deb, .rpm, or .tar.gz package, and configures the systemd service unit files automatically.

  2. Edit Configuration

    Navigate to:

    /var/lib/heimdall/config

Here you can review or customize:

  • app.toml
  • config.toml
  • client.toml

Templates for each supported network are available here:

:link: https://github.com/0xPolygon/heimdall-v2/tree/develop/packaging/templates/config

Make sure to configure your Ethereum and Bor connection parameters based on your infrastructure.

  1. Download the genesis.json file and place it under /var/lib/heimdall/config/

    Use the following commands based on your target network:

    cd /var/lib/heimdall/config
curl -fsSL <BUCKET_URL> -o genesis.json

    Where BUCKET_URL is

    :warning: This manual step is required for now, since the migration retained the application state (checkpoints, accounts, state syncs, milestones etc.) from Heimdall v1. Future versions of the install process may eliminate (or simplify) this step.

  2. Check Installed Version

    Confirm the installed version of Heimdall:

    heimdalld version

    It should return: v0.2.8

  3. Start the Heimdall Service

    Launch the node:

    sudo service heimdalld start

    Once started, your node will begin syncing from the v2_initial_block (specified in the genesis.json, which is equal to v1_last_block + 1) all the way up to the current tip of the chain.

Containerized Start

docker pull 0xpolygon/heimdall-v2:0.2.8
  • Create the HEIMDALL_HOME directory if doesn’t exist
mkdir -p "<HEIMDALL_HOME>"

Where HEIMDALL_HOME is by default /var/lib/heimdall
Init heimdall-v2

docker run --rm -v "<HEIMDALL_HOME>:/var/lib/heimdall" 0xpolygon/heimdall-v2:0.2.8 init <MONIKER> --chain-id <CHAIN_ID>

Where MONIKER is the name of your node and CHAIN_ID is heimdallv2-80002 for amoy and heimdallv2-137 for mainnet.

  • Download the genesis file and place it under HEIMDALL_HOME/config/genesis.json (replacing the one potentially already present there)
curl -L -o "<HEIMDALL_HOME>/config/genesis.json" <BUCKET_URL>

where URL is https://storage.googleapis.com/amoy-heimdallv2-genesis/migrated_dump-genesis.json for amoyand https://storage.googleapis.com/mainnet-heimdallv2-genesis/migrated_dump-genesis.json for mainnet

:light_bulb: Replace HEIMDALL_HOME with the actual path to your Heimdall-v2 home directory.

Please note that the genesis file size is around 50MB for amoy and expected to be 4-5GB for mainnet . Hence, the download might take a while, and it’s recommended to use a stable and fast connection.

Then, you can customize the configs under HEIMDALL_HOME/config (app.toml, client.toml, config.toml), based on your setup.

Templates for each supported network are available here:

:link: https://github.com/0xPolygon/heimdall-v2/tree/develop/packaging/templates/config

Make sure to configure your Ethereum and Bor connection parameters based on your infrastructure.

At this point, you can simply run the container

docker run -d --name heimdall-v2 \
  -v "$HEIMDALL_HOME:/var/lib/heimdall \
  -p 26656:26656 -p 26657:26657 -p 1317:1317 \
  0xpolygon/heimdall-v2:0.2.8 \
  start

:light_bulb: The command might be adjusted based on your setup/configs

:books: References & Docs

If you encounter any issues, feel free to reach out via the Forum or Discord. We’re here to help!

Thanks for building with us :folded_hands:

— The Polygon PoS Core Team

1 Like
2

In my testing, this heimdalld init doesn’t work that way: You can’t download the genesis file, then run heimdalld init. It’ll fail because genesis.json exists, with message genesis.json file already exists: <home-dir>/config/genesis.json

What’s more, init writes mainnet into custom.chain in app.toml. I’ve suggested to bring the --chain parameter back, to copy the correct genesis in as well as write the correct custom.chain parameter, here: https://github.com/0xPolygon/heimdall-v2/issues/314

In my testing, what works is to run init on an empty config/, then to copy the right genesis.json in, and adjust parameters in app.toml and config.toml, including custom.chain.

3

Thanks for the valuable feedback @yorick
We’ll update the docs accordingly.
Just one thing: despite the init throws an error for the already existing genesis file, the config files get generated correctly

4

According to the docker documentation, only this information is returned after startup, and the blocks will not be synchronized. If gensis is not downloaded, the blocks will be synchronized, but the situation looks like a stand-alone chain

6:16AM INF starting gRPC server... address=localhost:9090 module=grpc-server
6:16AM INF starting API server... address=tcp://0.0.0.0:1317 module=api-server
6:16AM INF serve module=api-server msg="Starting RPC HTTP server on [::]:1317"
Received non-OK HTTP status: 503
Received non-OK HTTP status: 500
Received non-OK HTTP status: 500
5

Yes, this is mostly true. For Amoy, the init sets custom.chain to mainnet in app.toml, that needs to be corrected. As other parameters also need to be set, that’s fine

If config/ is not empty, init doesn’t write v2-compliant config files in my testing. It’s best to start with an empty config/ directory.

6

Thanks, all should be correct now. Please get back to us for more feedback

7

Hi, thanks for your feedback. The instructions are correct now, thank you.
The issue was the absence of seeds and persistent peers in the configs.

8

Hi，If the mainnet is upgraded from Heimdall v1 to v2, must I re-download the genesis.json file through https://storage.googleapis.com/mainnet-heimdallv2-genesis/migrated_dump-genesis.json?
If I start the docker container, can I use the 0xpolygon/heimdall:1.6.0 image, or must I use the 0xpolygon/heimdall-v2:0.2.7 image?
Do other configuration files need to be modified? I don’t have a client.toml file now. Do I need to re-init all configuration files?

9

Yes, you need to download the v2 genesis (the URL you pasted)
Also only use 0xpolygon/heimdall-v2:0.2.7 image and init heimdalld as explained in the post to get the default config (which you can also find here for mainnet