Hey Polygon community
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 or are willing to setup a bor
node) 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:
-
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.4 <NETWORK> <NODE_TYPE>
Replace
<NETWORK>
withamoy
ormainnet
(onlyamoy
supported atm), and<NODE_TYPE>
with eithervalidator
orsentry
.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.
-
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:
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.
-
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
ishttps://storage.googleapis.com/amoy-heimdallv2-genesis/migrated_dump-genesis.json
for amoyhttps://storage.googleapis.com/mainnet-heimdallv2-genesis/migrated_dump-genesis.json
for mainnet (not available yet until)
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.
-
Check Installed Version
Confirm the installed version of Heimdall:
heimdalld version
It should return: v0.2.4 after some logs
-
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 thegenesis.json
, which is equal tov1_last_block + 1
) all the way up to the current tip of the chain.
Containerized Start
- Pull the
heimdall-v2
v0.2.4
image from https://hub.docker.com/r/0xpolygon/heimdall-v2/tags
docker pull 0xpolygon/heimdall-v2:0.2.4
- 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.4 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 amoy
and https://storage.googleapis.com/mainnet-heimdallv2-genesis/migrated_dump-genesis.json for mainnet
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:
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.4 \
start
The command might be adjusted based on your setup/configs
References & Docs
- Main repo: https://github.com/0xPolygon/heimdall-v2
- Config templates: https://github.com/0xPolygon/heimdall-v2/tree/develop/packaging/templates/config
- Official docs: https://docs.polygon.technology/pos/architecture/heimdall_v2/introduction/
- Docker hub: https://hub.docker.com/r/0xpolygon/heimdall-v2/tags
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
— The Polygon PoS Core Team