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