PIP-62: Heimdall v2 Migration


PIP: 62
Title: Heimdall v2 Migration
Author: Marcello Ardizzone (@marcello33), Harry Rook (@hrook1)
Description: Proposes Heimdall v.1 → v.2 Migration
Status: Draft
Type: Core
Date: 2025-04-02

Abstract

This proposal specifies deprecating Heimdall v.1 and activating Heimdall v.2 features on the Polygon PoS network.

Motivation

This proposal specifies the migration to Heimdall v.2, which refactors Heimdall to target Cosmos-sdk version v0.50.x and replaces Tendermint with CometBFT v0.38.x.

Specification

The migration will enable the following upgrades:

Activation

  • Activation block (halt_height):
    • For Amoy - TBC
    • For Mainnet - TBC

Backward Compatibility

This upgrade is not backward compatible with the current implementation of Heimdall and will require migration to a completely new chain. Due to the upgrade from Tendermint to CometBFT, the block history will not be preserved. Therefore, in case RPC providers are willing to keep that data, node operators would need to keep running Heimdall v1 service, which would only serve as a source of data for all the blocks previous to the halt_height before the migration takes place (in a read-only mode). When it comes to application data, it will be preserved by performing the migration itself, during which data will be exported from v1, and injected at genesis into Heimdall v.2, after proper modifications. This means that information such as checkpoints, milestones and state-syncs are preserved within Heimdall-v2.

Security Considerations

Downtime is expected while migrating from v1 to v2. Execution clients will be made independent of Heimdall v.1, so the side chains will continue to work as expected, but bridge operations (and everything concerning cross-chain data between L1 and L2) will be paused. The migration expected time will be driven by the time taken from Heimdall v.1 to export its genesis.

Copyright

All copyrights and related rights in this work are waived under CC0 1.0 Universal.

Could you please edit your post. The highlighted text, for instance after “Cosmos-sdk version”, is rendering as a black text on a very dark grey background, and hence can not be read easily.

1 Like

@H_Rook could you please explain a bit more, what data it is, that is not being preserved?

You wrote

Due to the upgrade from Tendermint to CometBFT, the block history will not be preserved

But further down you wrote, regarding the “application data”

This means that information such as checkpoints, milestones and state-syncs are preserved within Heimdall-v2.

And second, does that mean, that everyone would have to migrate from Heimdall v1 to v2 exactly at the “Activation block” or could we just run Heimdall v2 before the Activation block height?

Could you detail the proposed modifications to the chain state?

Heimdall v2 will be “activated” with a cosmos-sdk coordinated upgrade.
This means that every node operator must run the migration at the same time.
With regards to data:

  • blocks history from v1 will be lost, hence whoever wants to keep that data will need to preserve v1 rpc nodes (which will not be connected to v2)
  • application data will be preserved, meaning everything related to the app store (checkpoints, state syncs, milestones etc…)

These modifications must be applied mostly to genesis and config files, to make it compatible with the new comet and cosmos-sdk versions

@marcell033 Do I understand this correct? On Heimdall Activation block (halt_height) all decentral running Heimdall v1 instances should be stopped and should export their genesis, then some modifications on these files should be done and then Heimdall v2 should use these files as input?

Correct, @MrFreezeDZ.
halt_height will correspond to the last committed block on Heimdall v1.
All node operators will export the genesis (application data) from the already stopped Heimdall v1 instance.

Alternatively, they may download the genesis.json file from a trusted source (with checksum verification and distribution via official communication channels—TBD).

After that, node operators will need to update this file, along with other configuration files. These updated files will be used to initialize Heimdall v2, which will begin from halt_height + 1.

Please note: the migration script will automate this entire process. However, since not all operating systems are supported—and some node operators may prefer manual migration—we will also publish detailed step-by-step instructions.

2 Likes

Sounds good to us, awesome thank you Marcell :flexed_biceps: