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, in the 2:00 PM - 5:00 PM UTC time window
  • Then on Mainnet, shortly after (around 1-2 week, exact date TBC)

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. As you see here, we have an alternative solution for containerized environments (e.g. docker, kubernetes etc…). Yet, if node operators want, they can execute the migration manually, or adapt the script to their infrastructure if using other non-supported setups (e.g. Windows).

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 ~1s or below
  • Requirements:
    • At least 20GB free RAM at time of migration
    • At least 2× the size of HEIMDALL_HOME in disk space (backups 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

2 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.