PIP:-44: Upgrade cosmos-sdk in Heimdall

Polygon Improvement Proposals Canonical PIPs
1

Authors: Marcello Ardizzone , Sergio Mena, [Greg Szabo]((https://github.com/greg-szabo)

Type: Core

Table of Contents:

  • Abstract
  • Motivation
  • Specification
  • Backward Compatibility
  • Security considerations

Abstract

Currently, Heimdall uses a fork of cosmos-sdk, which has been modified to support the specific needs of Polygon PoS, and is based on version v0.37.4. We propose a refactoring that will upgrade such dependency to target version v0.50.x.

Motivation

The primary motivation for such an upgrade is to remove tech debt currently anchoring Heimdall to an outdated cosmos-sdk version released around four years ago. v0.37.4 is also no longer supported by the team that stewards the Cosmos SDK (EOL version).

Specification

This proposal integrates ABCI v2.0 (a.k.a. ABCI++) into Heimdall, enhancing the interaction between the consensus layer (CometBFT) and the application layer. ABCI v2.0 introduces a more granular interface that allows the application to interact with the consensus process during block proposal, voting, and finalization phases, providing significant improvements in flexibility, performance, and security.

Overview of ABCI v2.0

ABCI (Application Blockchain Interface) is the protocol layer between CometBFT and the application. In the current system (ABCI v0.17), the application passively processes finalized blocks through three main calls:

  1. BeginBlock: Initializes block processing.
  2. DeliverTx: Executes transactions.
  3. EndBlock: Finalizes the block state.

ABCI v2.0 extends this model by enabling the application to actively participate in multiple phases of the block lifecycle:

  1. Block Proposal Phase:
    During this phase, the application can inspect and validate proposed blocks, as well as modify the transactions to be proposed, before blocks are finalized.

  2. Voting Phase:
    Validators vote in two sub-phases:

    • Prevote: Validators signal preliminary agreement on the block.
    • Precommit: Validators confirm their agreement.

  3. The application can provide custom validation logic during these phases.

  4. Finalization Phase:
    After consensus is reached, the finalized block is committed to the chain, and the application finalizes state transitions.

ABCI++ functions
ABCI++ functions1336Ă—776 135 KB

Backward Compatibility

The upgrade is incompatible with the current Heimdall chain. This means that launching a newer version of cosmos-sdk within Polygon PoS will only be possible by migrating Heimdall to a brand new chain. We will be able to export the current state of Heimdall into the genesis for the new Heimdall chain. History at the CometBFT level (transactions, blocks, validator sets, etc) cannot persist via the upgrade workflow. To mitigate this, archive nodes can be made available so that the community can access CometBFT (actually, Peppermint) history before the migration point. Those archive nodes are simply non-validating full nodes running the current version of Heimdall.

Security Considerations

The upgrade involves a complete refactoring of the Heimdall codebase. Hence, Heimdall will undergo a meticulous phase of tests, audits, and performance reviews. Despite the many new functionalities offered by the new library, this migration will be—at first—a 1:1 migration, keeping intact the Heimdall capabilities and utilities.

3 Likes
2

This is a necessary proposal as the current tendermint fork heimdall relies on still uses the initial IAVL spec, making state proofs from hemidall susceptible to the binance bridge hack of 2022.

This makes it difficult building a trustless bridge to Polygon POS.

https://x.com/samczsun/status/1578172227400310786?lang=en

https://github.com/cosmos/iavl/blob/de0740903a67b624d887f9055d4c60175dcfa758/proof_iavl_value.go
https://github.com/bnb-chain/bsc/blob/master/core/vm/lightclient/v1/multistoreproof.go

1 Like
3

These are some comments on behalf of the CometBFT team, who are assisting with Polygon’s PoS migration:

We are fully aligned with the description @marcell033 posted above. What follows is some complementary information to some parts of the post:

Some comments to bullet 5 of the Specification section:

  • in SDK v0.37.4, migrations in the DB layout (i.e., the IAVL tree) were not handled automatically upon upgrade of the SDK version
  • that is partly the reason why the Cosmos Hub Stargate upgrade had to spawn a new chain (from chain ID cosmoshub-3 to cosmoshub-4), just like the process proposed in this PIP
  • once Heimdall migration to SDK v0.50.x in completed, the Upgrade module included in the SDK will make any change in the DB layout originated by upstream changes in the SDK transparent during the corresponding Heimdall upgrade. (As long as it does not collide with the changes made in Polygon’s SDK fork.)

Some comments on the last bullet of the Security Considerations section:

  • CometBFT’s start command in v0.38.x contains flag --genesis_hash
  • It will become important for operators to use this flag when starting the chain with the new genesis file, as a protection mechanism against corruption/tampering of the JSON genesis file
  • The value to be passed to --genesis_hash can be the “ceremonial” checksum of the genesis file mentioned in bullet 5 of the Security Considerations section.

As explained in the original post above, the new version of Heimdall will be using a fork of SDK v0.50.x. The changes in this fork will be kept to a minimum. A summary of the changes:

  • Usage of Ethereum-compatible hex addresses, instead of Bech32 addresses as defined in BIP-0173 and BIP-0350 and adopted by the Cosmos SDK.
  • Disabling new features existing in Cosmos SDK v0.50.x but currently not used by Heimdall. These changes are strongly aligned with the 1:1 migration principle mentioned in the Security Considerations section of @marcell033’s post above.
  • Enabling the Ethereum-compatible crypto (uncompressed secp256k1) also used by Polygon’s CometBFT fork: both peppermint (currently in production), and the new fork based on v0.38.x.
4 Likes
4

We validate on a number of Cosmos SDK chains as well as Polygon for a few years, and are fully supportive of this upgrade, as well as PIP-43. Life is much better for operators and users on a modern Cosmos/ CometBFT stack and this would be a major improvement to the Polygon software.

The coordinated upgrade is slightly more painful / risky from a node operator standpoint, but we’ve done it many times before with other Cosmos based chains, and this should be a one time event.

3 Likes