Heimdall v2 Migration

1

Heimdall v2 Migration Approaching

Node Operators, It’s Time to Prepare

Hey Polygon community :waving_hand:

We’re nearing the start of the long-anticipated Heimdall v1 → v2 migration, and this post is your first official heads-up to begin preparing — especially if you are operating validator or sentry nodes.

Rollout Plan

The migration will begin soon:

  • First on Amoy testnet, on Tuesday, June 24th, 2025, between 06.30 PM and 09.30 PM UTC
  • Then on Mainnet, on Thursday, July 10th, 2025, between 2.00 PM and 5.00 PM UTC

While we finalize the exact schedule, we urge all node operators to begin familiarizing themselves with the migration process, tooling, and requirements.

Heimdall-v2 docs

All information about Heimdall-v2 are published (and will be continuously updated) in the official docs:

Polygon PoS Docs:
https://docs.polygon.technology/pos/heimdall_v2/introduction/
Under the new Heimdall-v2 section you can find:

  • New APIs for heimdall-v2 (please adapt any 3rd party code relying on such endpoints in time…)
  • New APIs for cosmos-sdk (please adapt any 3rd party code relying on such endpoints in time…)
  • Modules description and READMEs
  • Changes from v1
  • Much more…

Migration Resources

The official migration logic, scripts, and runbook are live in the Heimdall v2 repository:

Heimdall v2 repo:
https://github.com/0xPolygon/heimdall-v2
Migration folder:
https://github.com/0xPolygon/heimdall-v2/tree/develop/migration

Please pay particular attention to:

Note: The script is tested on Linux/Ubuntu systems.

What’s New in Heimdall v2

  • All custom modules (bor, chainmanager, checkpoint, clerk, milestone, stake, topup) live in the Heimdall v2 repo
  • All other modules (auth, bank, gov) are in the Polygon Cosmos SDK fork (based on v0.50.x)
  • Heimdall v2 uses its own CometBFT fork (based on v0.38.x) instead of Tendermint

Key Technical Facts

  • Expected migration duration:
    The estimated time for script execution (not including potential troubleshooting or preparation) is
    • ~10 minutes on Amoy
    • ~30 minutes on Mainnet
  • Finality:
    • Heimdall-v2 should bring a significant drop in finality, from 90s to 4–6s
  • Block time:
    • Block time is expected to reduce from 5–6s to ~2s
  • Requirements:
    • At least 20GB free RAM at time of migration
    • At least 2× the size of HEIMDALL_HOME in disk space (in case you want to have a backup - which can be deleted later)
  • What gets migrated:
    • Application data: checkpoints, state syncs, balances, accounts, supply, milestones, etc…
  • What does not get migrated:
    • Blockchain history. Keep a v1 RPC node running if you need to serve old block data.
  • Heimdall v2 will have a new chain ID and its initial block at genesis will be the last block committed from heimdall-v1 + 1
  • Bor will continue operating throughout the migration process, so the Polygon PoS chain itself will not experience downtime. Only Heimdall will pause temporarily, which means cross-chain operations, such as checkpoint submissions, deposits, and withdrawals, will be suspended during the migration window.

Important PIPs

What’s Next?

In the coming days, we will be publishing:

All node operators are called to test early, and prepare accordingly. Your timely readiness will ensure a smooth upgrade across the ecosystem.

Thanks for building with us :folded_hands:
— The Polygon PoS Core Team

3 Likes
2

Thanks for the detailed update, marcell033. A quick question for anyone here, for those running Heimdall in a containerized setup (Docker/Kubernetes), is there any community feedback yet on adapting the migration scripts? I noticed the note about needing to modify them, just wondering if anyone has shared experiences or tips so far.

3

Hi @grapoly,
If you prefer not to adjust the script based on the architecture, you can follow the manual steps outlined in the README and RUNBOOK (keep in mind that some commands need to be adjusted anyway…).
That said, having an automated script will definitely make things easier, faster, and less error-prone. Just pointing out the manual path as an alternative.

Thanks!

4

Thanks for the detailed update! Node operators should start preparing now for the Heimdall v1 → v2 migration, beginning soon on Amoy testnet and then mainnet. Key changes include new APIs, a CometBFT fork, and faster finality (~4–6s) with reduced block time (~1s). Make sure to review the migration scripts, runbook, and system requirements (20GB RAM, ample disk space). Note that blockchain history won’t migrate, so keep v1 RPC nodes if needed. Early testing is crucial for a smooth transition.

5

In case you don’t have that yet for your k8s: I just did it for our Compose. You can take a look and crib for your own init / migration pods. https://github.com/CryptoManufaktur-io/polygon-docker/blob/main/polygon/docker-entrypoint-heimdalld.sh

The main thing that differs from the instructions at https://github.com/0xPolygon/heimdall-v2/blob/develop/migration/README.md#containerized-migration:

You can’t run init on an existing config directory. Not only will genesis.json be in the way, you’ll also run into issues with the existing toml files not having the right content.

Instead, run init without a config or data directory present. If you’re a validator, copy your priv_validator_state.json to data first then run init, but watch out for the format changing - what was previously a string for round now needs to be an integer.

Then copy in the right genesis.json, copy in addrbook.json.

Apply config changes to app.toml and config.toml and you should be good to go. Locations have changed a bit, you can look at the entrypoint script linked above as to what we’re setting and where it is.

Optionally tell Bor to use WS to connect to Heimdall.

1 Like
6

My node synced to 24404500 and stopped the service, and then made changes according to the migration document. When running the heimdalld service again, the following error was reported. How can I solve it? For more details, please refer to: https://github.com/0xPolygon/heimdall-v2/issues/360

7

Hello, I am trying to follow this for heimdall and even try the most recent docker image, using your genesis I always fail to run heimdalld:

error during handshake: error on replay: invalid chain-id on InitChain; expected: heimdallv2-137, got: test-chain-OSvtwq

The documentation is outdated, there is no way to get started, no documentation anywhere, how do I run a simple polygon node please ? Is someone working on the documentation ? when is it expected ?

Thank you all :folded_hands:

8

Hello @kopax
The documentation is not outdated
Have you followed the right steps, especially wrt configs?
It seems like you have some mis-configuration

9

Hello @marcell033 , how can you state the documentation is not outdated ?
I followed step by step about 5 times and couldn’t get a working configuration. I have to go to forum, github issue, and found a bunch of people having the same issue as me.
The link you shared is not even in the documentation.

I think as a user, you can rely on my feedback and in the best world, try to understand and improve the documentation for running a heimdall v2 node without such struggle.

Even the snapshots available on publicnode does not use the heimdall v2, everything is outdated.

I will have another try today using the link you provided, but please. can you please check you getting started documentation and do something about it?

I am willing to help improve it if I can find synchronous support. I’ve been joining the discord, so far only here I got one reply from you, the rest is do on your own.

10

Also, the entry point for newcomers is https://docs.polygon.technology/pos/how-to/full-node/full-node-binaries/

This is where you should consider keeping your documentation up to date imo.

I am reading your link, and it start with a migration check list : https://github.com/0xPolygon/heimdall-v2/blob/develop/migration/containerized/2-MIGRATION.md#containerized-migration

  1. I am starting from v2, is this still valid for me ?
  2. Where can I download snapshot for heimdalld v2 ?
  3. What is the documentation that I am looking for, that you say is up to date ? Perhaps I am blind.

Thanks in advance

11

Hi @kopax
I am sorry you’re facing issues, we are working to keep the docs updated, the migration has been a complex process and involving several stakeholders.
The steps described above are correct for the migration. If you wanna join v2 without migrating from v1, this is the right post: https://forum.polygon.technology/t/joining-heimdall-v2/21073.
You’re actually on the right track but the error you’re getting

error during handshake: error on replay: invalid chain-id on InitChain; expected: heimdallv2-137, got: test-chain-OSvtwq

suggests there’s some kind of issue with the configs.
The link I’ve shared is only the configs-related section, which should help you unblock and run heimdall-v2.
For snapshots, polygon doesn’t maintain official ones, it’s up to the community (e.g. https://services.stakecraft.com/docs/snapshots/polygon-snapshot)

12

I’ve just joined the discord, channel for node operator and it’s quit scary.

Sorry but I don’t get the excuse about the complexity and stakeholders, this looks like a smoke smog. I am myself working on complex projects all the time and serious question : writting a documentation for your seniors enginneers should take less than a day, did they all left the polygon project? Why is it not done yet ? People on discord complain at a maximum level and the polygon team seems to ignore them for weeks now. It takes more time to reply all individuals than to update the documentation once, you should urgently put some priorities here.

One even draft a non official tutorial here https://github.com/0xPolygon/heimdall-v2/issues/416 and shared it on the discord channel, can you imagin the time wast for us?

Could you please urgently raise the issue and write a documentation in a timely manner? I already followed the tutorial you shared without success, I mentioned it somewhere.

Imagin that polygon is a few years active blockchain, well known in the web3 community and host a lots of dapps. That is a non sens, funds are available for the team.

Even berachain which is a recent blockchain provide tools for diagnosees their node, provide active support on their discord for every people wanting to deploy their node, but also updated their documentaton and use user feedback to improve it. BSC which is old blockchain as polygon, their documentation is straightforward despite all the update they did, you just follow the doc and your node is up and running.

Again I don’t want to complain too much with your work, polygon is an awesome layer 2, but this is very scary that’s the reason I must emphasis my feedback so it can be heard by your team as soon as possible. I won’t take screenshots of the people complaining on discord, neither linking all the links that I have found for official/unofficials docs, nor linking all the available threads of node operator asking for help, they are way too many.

Thanks in advance for your understanding and raising the issue, but also solving the problem.

13

Hey @kopax
Totally understand, what I meant is no excuse, jut wanted to help you.
Btw, FYI, I am updating the docs myself. They should be ready in the upcoming days.
Thanks for your patience

14

Docs have been updated here https://docs.polygon.technology/pos.
Thanks for flagging @kopax