Heimdall-v2 v0.3.0 release for mainnet

Announcements
1

Hello All,

We have released a new version of heimdall-v2 v0.3.0 for Polygon mainnet.

This is a hardfork release, scheduled for September 16th 2025, at around 14:00 UTC (block number 28913694)

It mainly contains the following changes.

Breaking changes:

  • a permanent fix for the recent outage requiring a hardfork, hence all nodes operators are required to upgrade ahead of time.

  • the deletion of bridge as standalone process. This means the bridge can’t run now as a separate process, but will always be embedded in heimdalld as a child process via the -bridge flag. All validators (hence running the bridge) will need to adapt and use heimdalld start --bridge --all --rest-server (or variants of this commands based on their setup) to start the bridge within heimdalld service.

New features, improvements and bug fixes:

  • Improvements to the bridge service and rest-server connection

  • Validation of bor_chain_id during checkpoints workflow at side_server level against the chain parameters

  • bump of dependencies

  • replace nhooyr.io library with github.com/coder ws as per https://github.com/0xPolygon/heimdall-v2/pull/421 (thanks @DaveWK for your contribution)

  • Fix some functions’ comments as per https://github.com/0xPolygon/heimdall-v2/pull/383 (thanks @stellrust for your contribution)

  • Expose proposer transfer event during EndBlocker as per https://github.com/0xPolygon/heimdall-v2/pull/376 (thanks @haiyanghe for your contribution).

  • Replace matic-cli with kurtosis for CI e2e tests

  • additional metrics for side_msgs and ABCI handlers

  • Removal of spans backfill logic post v1->v2 migration

  • Fix the generate-keystore command

  • Various minor improvements

Steps for upgrading Heimdall:

  1. Stop heimdalld service

    sudo service heimdalld stop

  2. Install heimdall with a version tag, network name (mainnet), and node type (sentry or validator).

    # Replace the network and node type
curl -L <https://raw.githubusercontent.com/0xpolygon/install/heimdall-v2/heimdall-v2.sh> | bash -s -- v0.3.0 <network> <node_type>

  3. Check heimdall version

    /usr/bin/heimdalld version

# It should print
# 0.3.0

  4. Restart heimdall service

    sudo service heimdalld start

  5. Restart the telemetry services

    sudo service telemetry restart

What’s Changed

V0.3.0 candidate by @marcello33 in #449, including the following PRs:

Full Changelog: https://github.com/0xPolygon/heimdall-v2/compare/v0.2.17…v0.3.0

Docker Images

You can find the latest docker images here:

Heimdall:https://hub.docker.com/r/0xpolygon/heimdall-v2/tags

Thanks,

Polygon Team