v0.55 Upgrade Guide

​

Table of Contents

• Breaking Changes
  • CometBFT Upgrade
  • Removed: x/params
  • Removed: x/protocolpool
  • Removed: SIGN_MODE_TEXTUAL
  • Mempool Interface Changes
  • Staking: Key Rotation Wiring and Interface Changes
  • genutil: ExportGenesisFileWithTime Signature
  • Upgrade Handler and Store Migrations
• Upgrading from v0.53.x
• New Features and Non-Breaking Changes
  • Validator Consensus Key Rotation
  • ML-DSA-65 Validator Consensus Keys
  • ML-DSA-65 Account Keys
  • secp256k1eth Validator Consensus Keys
  • Block-STM Configuration
• Behavior Changes Affecting Dapps and Indexers

​

Breaking Changes

​

CometBFT Upgrade

• Expanded MaxSignatureSize and per-validator MaxCommitSigBytes to accommodate post-quantum (ML-DSA-65) signatures.
• A fix for the application-side mempool (mempool.type = "app", supported since CometBFT v0.39.2 / SDK v0.54.3): the default socket transport was missing the InsertTx / ReapTxs cases, causing node self-kill (cometbft#5958). Chains using an app-side mempool over the socket transport need v0.40.0.
• Updated DefaultBlockParams (cometbft#5987). This changes defaults for new chains only; existing chains keep their on-chain consensus params.

​

Removed: x/params

1. If your app still imports x/params (a paramskeeper.Keeper, per-module Subspaces, or the legacy gov proposal handler), remove that wiring. If the params store is still mounted, delete it in your store upgrades (see Upgrade Handler and Store Migrations). Chains that have not yet migrated legacy subspace params to module-managed params must complete that migration before upgrading to v0.55 — the migration code is gone.
2. Drop the trailing exported.Subspace argument (typically passed as nil) from the module constructors that carried it for legacy migrations:

// Before                                                          // After
auth.NewAppModule(cdc, accountKeeper, randGenAccountsFn, nil)      auth.NewAppModule(cdc, accountKeeper, randGenAccountsFn)
bank.NewAppModule(cdc, bankKeeper, accountKeeper, nil)             bank.NewAppModule(cdc, bankKeeper, accountKeeper)
gov.NewAppModule(cdc, &govKeeper, accountKeeper, bankKeeper, nil)  gov.NewAppModule(cdc, &govKeeper, accountKeeper, bankKeeper)
mint.NewAppModule(cdc, mintKeeper, accountKeeper, nil, nil)        mint.NewAppModule(cdc, mintKeeper, accountKeeper, nil)
slashing.NewAppModule(cdc, keeper, ak, bk, sk, nil, registry)      slashing.NewAppModule(cdc, keeper, ak, bk, sk, registry)
distr.NewAppModule(cdc, keeper, ak, bk, stakingKeeper, nil)        distr.NewAppModule(cdc, keeper, ak, bk, stakingKeeper)
staking.NewAppModule(cdc, keeper, ak, bk, nil)                     staking.NewAppModule(cdc, keeper, ak, bk)

​

Removed: x/protocolpool

1. Remove all protocolpool wiring from app.go: the imports, the ProtocolPoolKeeper field and its NewKeeper call, the protocolpooltypes.ModuleName and protocolpooltypes.ProtocolPoolEscrowAccount entries in maccPerms, the module manager entry, and its entries in the begin-block, end-block, init-genesis, and export orders.
2. Remove distrkeeper.WithExternalCommunityPool(app.ProtocolPoolKeeper) from your distrkeeper.NewKeeper call.
3. Delete the protocolpool store in your store upgrades (see Upgrade Handler and Store Migrations).
4. Balances held by the protocolpool module accounts are bank state and are not migrated automatically. Decide where those funds go and move them in your upgrade handler — e.g. transfer them to the x/distribution community pool so community-pool spend proposals keep working.

​

Removed: SIGN_MODE_TEXTUAL

• x/tx/signing/textual/ — all renderers, the CBOR encoder, test data, and internal protos
• x/auth/tx/textual.go and ConfigOptions.TextualCoinMetadataQueryFn
• Ledger + SIGN_MODE_TEXTUAL integration in client/ flags and tx factory

1. Remove TextualCoinMetadataQueryFn from your tx.ConfigOptions:
   // Before
   txConfig, err := tx.NewTxConfigWithOptions(cdc, tx.ConfigOptions{
       TextualCoinMetadataQueryFn: ...,
   })
   
   // After — field removed, omit it
   txConfig, err := tx.NewTxConfigWithOptions(cdc, tx.ConfigOptions{...})
   
2. Remove any SIGN_MODE_TEXTUAL cases from signing mode handler switch statements.
3. Remove Ledger wiring that depended on SIGN_MODE_TEXTUAL. Client-side root command wiring that constructed a textual-enabled tx config for online mode (as v0.54 SimApp did in simd/cmd/root.go) should be deleted as well.

​

Mempool Interface Changes

• Insert gains an InsertOption parameter carrying the ante-reported gas: Insert(context.Context, sdk.Tx, InsertOption) error.
• Iterator.Tx() now returns a PooledTx ({Tx sdk.Tx; GasWanted uint64}) instead of sdk.Tx.
• ExtMempool.SelectBy’s callback now receives a PooledTx: SelectBy(context.Context, [][]byte, func(PooledTx) bool).
• ExtMempool.RemoveWithReason and the RemoveReason type, introduced in v0.54, are unchanged.

​

Staking: Key Rotation Wiring and Interface Changes

maccPerms = map[string][]string{
    // ...existing entries...
    stakingtypes.KeyRotationFeePoolName: {authtypes.Burner},
}

• The StakingHooks interface gains AfterValidatorConsKeyUpdated(ctx context.Context, oldConsAddr, newConsAddr sdk.ConsAddress, valAddr sdk.ValAddress) error, called when a rotation is applied. Custom StakingHooks implementations must add this method (returning nil is fine if you don’t need the notification).
• The staking keeper adds ValidatorByHistoricalConsAddr(ctx, consAddr), which resolves a validator from a consensus address it used before a rotation. Modules that map consensus addresses to validators can no longer assume that mapping is immutable — see Validator Consensus Key Rotation.

​

genutil: ExportGenesisFileWithTime Signature

// Before
func ExportGenesisFileWithTime(genFile, chainID string, validators []cmttypes.GenesisValidator,
    appState json.RawMessage, genTime time.Time) error

// After — build the AppGenesis yourself; everything you set on it is preserved
func ExportGenesisFileWithTime(genFile string, appGenesis *types.AppGenesis, genTime time.Time) error

​

Upgrade Handler and Store Migrations

​

Module Migrations

• x/staking 5 → 6: adds the key_rotation_fee param, defaulting to 1000000 of the bond denom (#26485). Params.Validate requires the fee denom to equal bond_denom (#26613).
• x/auth 6 → 7: adds the SigVerifyCostMlDsa65 param with its default value (#26472).

​

Reference Upgrade Handler

const UpgradeName = "v054-to-v055"

func (app SimApp) RegisterUpgradeHandlers() {
    app.UpgradeKeeper.SetUpgradeHandler(
        UpgradeName,
        func(ctx context.Context, _ upgradetypes.Plan, fromVM module.VersionMap) (module.VersionMap, error) {
            return app.ModuleManager.RunMigrations(ctx, app.Configurator(), fromVM)
        },
    )

    upgradeInfo, err := app.UpgradeKeeper.ReadUpgradeInfoFromDisk()
    if err != nil {
        panic(err)
    }

    if upgradeInfo.Name == UpgradeName && !app.UpgradeKeeper.IsSkipHeight(upgradeInfo.Height) {
        storeUpgrades := storetypes.StoreUpgrades{
            Added:   []string{},
            Deleted: []string{"protocolpool"},
        }
        app.SetStoreLoader(upgradetypes.UpgradeStoreLoader(upgradeInfo.Height, &storeUpgrades))
    }
}

​

Upgrading from v0.53.x

• CometBFT v0.38.x → v0.39.x (LibP2P, AdaptiveSync); from v0.53 you jump straight to the v0.40.0 release v0.55 pins.
• Consolidation of cosmossdk.io/x/* vanity modules into github.com/cosmos/cosmos-sdk/x/*, plus the Log v2 and Store v2 moves.
• x/gov keeper-initialization and GovHooks interface changes, x/epochs and x/bank wiring updates, and the x/circuit / x/nft / x/crisis deprecations.
• IBC v11 (if your chain uses IBC).

• Skip transient wiring. Don’t adopt v0.54 reference-app wiring that v0.55 removes in the same hop: the SIGN_MODE_TEXTUAL tx-config setup, x/protocolpool (if your v0.53 app didn’t already wire it), and distrkeeper.WithExternalCommunityPool. Go straight to the v0.55 forms shown in this guide.
• Module constructors. v0.54’s constructor signatures still carried the legacy exported.Subspace arguments; use the v0.55 signatures from Removed: x/params directly.
• Custom mempools. Implement the v0.55 Mempool interface (Mempool Interface Changes) directly; don’t bother with the v0.54 shape.
• Module migrations are cumulative. RunMigrations walks each module from its v0.53 consensus version to the v0.55 target in one pass (x/auth 5 → 6 → 7, x/staking 5 → 6). No manual intervention is needed beyond the standard upgrade handler.
• Store upgrades. The v0.53 → v0.54 hop required no store additions or deletions, so the combined store upgrade is exactly the snippet in Upgrade Handler and Store Migrations: delete protocolpool only if your v0.53 app had wired it, and params if its store was still mounted (more likely on a v0.53-era app). Use a single upgrade name, e.g. v053-to-v055.

​

New Features and Non-Breaking Changes

​

Validator Consensus Key Rotation

• Fee. Each rotation charges the key_rotation_fee staking param (default 1000000 of the bond denom) from the operator account; the fee is burned via the key_rotation_fee_pool module account.
• Rate limit. One rotation per validator per unbonding period.
• Applied in the end blocker. The rotation is scheduled by the msg server and applied at the end of the block; CometBFT is informed through a validator-set update.
• Evidence and slashing. Equivocation evidence against a rotated-away (historical) consensus address remains attributable to the validator until the evidence is no longer admissible — i.e. until both evidence.max_age_num_blocks and evidence.max_age_duration have elapsed since the rotation, which can be later than the unbonding time (#26481, #26616). Slashing signing info is migrated to the active consensus key. Governance changes that extend the evidence-age params after a rotation’s expiry has been computed are not retroactively applied; chains should account for this when tuning evidence params.
• Genesis. Rotation history and pending-rotation state are included in staking genesis import/export (#26471); genesis export tooling that parses staking genesis JSON should expect the new fields.
• Events. rotate_cons_pubkey is emitted when a rotation is scheduled (including apply height, maturity time, evidence-expiry time/height, and the burned fee) and apply_cons_pubkey_rotation when it is applied (validator, old and new consensus addresses) (#26619).

​

ML-DSA-65 Validator Consensus Keys

​

ML-DSA-65 Account Keys

​

secp256k1eth Validator Consensus Keys

​

Block-STM Configuration

stores := make([]storetypes.StoreKey, 0, len(keys))
for _, k := range keys {
    stores = append(stores, k)
}
blockexec.Apply(bApp, appOpts, stores, txConfig.TxDecoder(),
    func(storetypes.MultiStore) string { return sdk.DefaultBondDenom },
)

​

Behavior Changes Affecting Dapps and Indexers

• Block selection uses ante-reported gas. Proposals are packed using the gas wanted returned by the ante handler at CheckTx time rather than the tx-declared gas limit (#25338). Block composition can differ for txs whose ante-reported gas diverges from their declared limit.
• Staking emits key-rotation events (rotate_cons_pubkey, apply_cons_pubkey_rotation), and validator consensus addresses can change over time (#26619).
• x/gov proposal_messages event attribute no longer has a leading comma (#26353).
• x/authz prunes at most 200 expired grants per begin block (#26588); mass-expiry cleanup now spreads across blocks.
• x/distribution reward withdrawals to blocked addresses during begin/end block fall back to the delegator/validator owner and then the community pool instead of failing (#26406). User-initiated withdrawals to blocked addresses still return ErrUnauthorized.
• x/feegrant Allowances and AllowancesByGranter queries now honor PageRequest.offset and count_total correctly (#26596); clients that compensated for the old off-by-page results should re-check.