XRPL EVM v9.0.0: Migration from Evmos to Cosmos EVM v0.4.1

Overview

The XRPL EVM sidechain chain upgrade v9.0.0 is ready to migrate Evmos—an unmaintained dependency—to Cosmos EVM v0.4.1, a fully supported fork of Evmos.

This is more than just a technical upgrade. By moving to Cosmos EVM, the XRPL EVM ecosystem gains:

• Long-term sustainability: Evmos had become unsupported, leaving chains that depended on it without a clear upgrade path. Cosmos EVM is actively maintained, ensuring compatibility with the broader Cosmos and Ethereum ecosystems.

• Future-proof development: Cosmos EVM continuously integrates Ethereum standards (EIPs) and protocol upgrades. This ensures that XRPL EVM applications remain interoperable with Ethereum tooling.

• Extended functionality: The migration introduces new ERC-20 capabilities such as mint, burn, and ownership transfer—giving developers and token projects more flexibility.

• Alignment with the Cosmos ecosystem: By standardizing on Cosmos EVM, XRPL EVM can more easily integrate with other Cosmos SDK chains, IBC modules, and upcoming interoperability upgrades.

Newly Supported EIPs and Opcodes

With Cosmos EVM v0.4.1, XRPL EVM now supports several new Ethereum Improvement Proposals (EIPs), introducing fresh opcodes and functionality:

Shanghai Upgrade

• ✅ EIP-3855: PUSH0 instruction

• ✅ EIP-3860: Initcode limits and metering

• ⚠️ EIP-3651: Coinbase address warm (partial support)

Cancun Upgrade

• ✅ EIP-1153: Transient storage opcodes

• ✅ EIP-5656: MCOPY memory copying instruction

• ✅ EIP-7516: BLOBBASEFEE opcode

• ⚠️ EIP-6780: Restricts SELFDESTRUCT (partial support)

Prague Upgrade

• ✅ EIP-2537: Precompile for BLS12-381 curve operations

This means XRPL EVM developers can now rely on the latest Ethereum execution features, making smart contracts more efficient and interoperable with modern Ethereum tooling.

Technical details

Cosmos SDK

As part of the migration to Cosmos/EVM v0.4.1, the XRPL EVM node was also upgraded to Cosmos SDK v0.53.4. This SDK bump was not the primary goal of the release, but a required dependency in order to align with the supported Cosmos/EVM fork.

The official upgrade guide can be found here: Cosmos SDK v0.53 Upgrade Guide.

Applied Changes

The only required modification for compatibility was related to app wiring. Specifically, the x/auth module needed to be registered as a pre-blocker within the application’s module manager. This ensures that authentication logic executes at the correct stage of the block lifecycle, which is critical for transaction validation and account management.

app.ModuleManager.SetOrderPreBlockers(
    upgradetypes.ModuleName,
    authtypes.ModuleName, // NEW

👉 Code reference.

Deferred Features

Other changes introduced in Cosmos SDK v0.53.x, such as the ProtocolPool module, the Epochs module, and support for unordered transactions, were not applied in this release. These features are optional and not required for the stability of the XRPL EVM chain. Since the main objective was completing the Evmos → Cosmos EVM migration, we deliberately left these modules out to reduce upgrade complexity. They remain available for consideration in future upgrades once the ecosystem requires them.

IBC Go

The XRPL EVM node has migrated its IBC-Go dependency from version v8.1 to v10.0. The official migration guide can be found here: IBC-Go v8.1 to v10.

Rate-limiting

Because XRPL EVM relies on the rate-limiting module, upgrading IBC-Go enforced a mandatory migration of this module to v10. Unlike other IBC-Go features, there is no dedicated migration guide for the rate-limiting app; instead, we followed the integration documentation.

Key changes applied:

• Middleware integration: Added the rate-limit middleware to the transfer stack (code reference).

• Manager wiring: Registered rate-limit logic in the IBC Manager (code reference).

• Blocker order: Inserted the rate-limit module into SetOrderBeginBlockers, SetOrderEndBlockers, and genesisModuleOrder to ensure proper execution ordering during block lifecycle events (code reference).

• Params integration: Added the rate-limit module into the params keeper subspace to support configuration persistence (code reference).

This ensures that all existing IBC channels with rate-limiting enabled continue functioning correctly after the upgrade.

⚠️Since rate-limiting/v8 and rate-limiting/v10 versions cannot coexists due to dependency conflict, the upgrades/v4 handler has been removed since it added the ratelimit module to the StoreUpgrades .

Since the v4 upgrade is down 4 major versions, there shouldn’t be any problem by removing it.

Deferred Features

Two optional features from the IBC-Go v10 release were not applied in this migration:

• Transfer Stack V2: The chain continues to operate on the stable v1 transfer stack. Migrating to v2 is not required for compatibility and will be considered in a future upgrade.

• WASM Light Clients: XRPL EVM does not currently rely on wasm-based IBC clients, so support was not added at this stage. This feature remains optional and can be introduced later without impacting current IBC operations.

evmos to cosmos/evm

Migrate erc20 custom capabilities

To preserve all XRPL EVM customizations during the migration from Evmos to Cosmos/EVM v0.4.1, we introduced a set of targeted changes in our fork: xrplevm/evm@release/v0.4.1-xrplevm. These changes were isolated to the x/erc20 module and the precompiles/erc20 package, ensuring feature parity with the Evmos fork while aligning with Cosmos/EVM’s architecture.

👉 Full details can be found in the pull request: Add ERC-20 features to v0.4.1.

Extended Capabilities

The following custom ERC-20 capabilities have been ported and re-implemented:

• Mint – allows token creation by authorized accounts.

• Burn – supports token destruction (Burn, Burn0, BurnFrom).

• TransferOwnership – enables ownership transfer of token contracts.

contracts/solidity/precompiles/erc20

This directory now includes updated Solidity interfaces to expose the new precompile functionality.

precompiles/erc20

The ERC-20 precompile has been extended with all XRPL EVM custom features, while maintaining compatibility with Cosmos/EVM defaults:

• Transactions: Mint, Burn, Burn0, BurnFrom, TransferOwnership

• Queries: Owner

• Gas values: All defaults from Cosmos/EVM have been preserved, with the additional cost for TransferOwnership taken directly from the Evmos fork.

• ABI: Updated to reflect new transactions, queries, and events.

Integration tests for these precompiles were moved to tests/integration/precompiles/erc20 to match Cosmos/EVM’s test directory structure.

precompiles/werc20

A new wrapped ERC-20 precompile (werc20) was introduced, extending erc20 functionality. Its ABI and Go interfaces (abi.json, interfaces.go) were updated to reflect dependency inheritance from the base ERC-20 precompile.

proto/cosmos/evm/erc20/v1

All protobuf definitions have been regenerated, incorporating the new transaction types:

• Messages: Mint, Burn, Burn0, BurnFrom, TransferOwnership

• Requests and responses for MsgServer

Testing Infrastructure

• Integration Tests (tests/integration/precompiles/erc20)Adapted from the Evmos fork, these tests now use Cosmos/EVM’s PrecompileTestSuite instead of Evmos’s legacy suite. They validate functionality across both the EVM and Cosmos layers.

make

• Solidity Tests (tests/solidity/suites/precompiles/test)Cosmos/EVM includes a full end-to-end Solidity test framework. We integrated a dedicated ERC-20 test battery here to validate precompiles in a controlled local node environment.

x/erc20 Module Changes

Finally, the Cosmos layer ERC-20 module was expanded to include all custom functionality from the Evmos fork:

• Generated protobuf types.

• Added new keeper methods: MintCoins, BurnCoins, TransferOwnershipProposal, GetTokenPairOwnerAddress, SetTokenPairOwnerAddress.

• Extended MsgServer with Mint, Burn, and TransferContractOwnership.

• Updated error definitions and message types.

• Extended CLI and client transaction/query commands.

Node

Cosmos EVM Breaking Changes

Migrating from Evmos to Cosmos/EVM v0.4.x required significant refactoring across the XRPL EVM node. The following migration guides were used as primary references:

• Adding the EVM Module to a Cosmos SDK Chain

• EVM Mempool Integration

• Migration: v0.3.0 → v0.4.0

• ERC20 Precompiles Migration

These guides highlighted several breaking changes that required deep modifications in the XRPL EVM node to ensure compatibility and backward support for existing state and key types.

Ante Handler

The ante handler was completely refactored:

• ante.go was moved into a dedicated Go package (/app/ante) to improve modularity and separation of concerns.

• The handler was updated to support both CosmosAnteHandler and MonoEVMAnteHandler, which are required to handle Cosmos/EVM’s dual transaction validation model.

• Custom HandlerOptions continue to live in handler_options.go, with new support for PendingTxListener (introduced in the Cosmos/EVM v0.4 migration).

• Legacy key support was preserved: the SigVerificationGasConsumer was extended to handle ethsecp256k1.PubKey from Evmos. This ensures that transactions signed with pre-upgrade keys remain valid after the migration.

EVMAppOptions

Cosmos/EVM introduces the EVMAppOptions function, which enforces eth-format chain IDs and global EVM configuration:

• The XRPL EVM node now maps chain-specific denominations and metadata using a whitelisted chain ID mapping (ChainsCoinInfo).

• Supported environments include mainnet, testnet, devnet, localnet, and simulation.

• Each environment specifies denomination metadata, display denomination, and decimals for both the default token and the wrapped XRP token (axrp).

This enforces consistent denomination handling across all environments and aligns the node with Cosmos/EVM’s chain configuration model.

Encoding and Interface Registry

The node’s codec was previously generated via Evmos’s MakeConfig. This was replaced with Cosmos/EVM’s codec builder, but required compatibility shims to support both pre-upgrade (Evmos) and post-upgrade (Cosmos/EVM) types.

Specifically, the interface registry now includes both implementations for key account and message types:

• Accounts: Legacy EthAccount from Evmos and new Cosmos/EVM EthAccount.

• Keys: Compatibility support for Evmos and Cosmos/EVM PrivKey and PubKey types.

• Messages: Legacy messages from Evmos modules (x/evm, x/feemarket, x/erc20, x/poa) were registered to avoid breaking transaction decoding and replay.

interfaceRegistry.RegisterImplementations((*sdk.Msg)(nil),
    &poalegacytypes.MsgAddValidator{},
    &poalegacytypes.MsgRemoveValidator{},
    &evmlegacytypes.MsgEthereumTx{},
    &evmlegacytypes.MsgUpdateParams{},
    &feemarketlegacytypes.MsgUpdateParams{},
    &erc20legacytypes.MsgConvertERC20{},
    &erc20legacytypes.MsgConvertCoin{},
    &erc20legacytypes.MsgUpdateParams{},
    &erc20legacytypes.MsgTransferOwnership{},
    &erc20legacytypes.MsgMint{},
    &erc20legacytypes.MsgBurn{},
    &erc20legacytypes.MsgRegisterERC20{},
    &erc20legacytypes.MsgToggleConversion{},
)

interfaceRegistry.RegisterImplementations((*sdk.AccountI)(nil),
    &legacytypes.EthAccount{}, // Evmos legacy
)
interfaceRegistry.RegisterImplementations((*authtypes.AccountI)(nil),
    &legacytypes.EthAccount{}, // Evmos legacy

This ensures that transactions already in the chain state, as well as legacy keys/accounts, remain valid post-upgrade.

Genesis FeeMarket Fix

Cosmos SDK introduced a breaking change in its math library (sdkmath). To accommodate this, the genesis state initialization for the feemarket module was patched:

feeMarketState.Params.BaseFee = sdkmath.LegacyNewDec(0

This ensures proper initialization of the BaseFee parameter, preventing runtime errors during chain start.

Precompiles Wiring

Cosmos/EVM uses a different precompile dependency model compared to Evmos. As a result, the node’s NewAvailableStaticPrecompiles implementation was updated to reflect Cosmos/EVM’s expected precompile wiring.

This guarantees that all native and extended precompiles (including ERC-20 and wrapped ERC-20) are available and behave consistently under the new runtime.

EVM Mempool

Cosmos EVM introduces a new evm-mempool package, which provides an alternative transaction mempool implementation optimized for EVM execution semantics. However, at this stage the module is still considered experimental, with limited production exposure and evolving APIs. To avoid introducing potential instability at the consensus and transaction processing layers, the XRPL EVM upgrade deliberately excluded this component. Once the evm-mempool package matures, demonstrates stability under mainnet conditions, and achieves broader adoption within the Cosmos EVM ecosystem, it will be integrated into XRPL EVM in a subsequent upgrade cycle.

Upgrade Handler

The migration from Evmos to Cosmos/EVM v0.4.x required multiple state transitions to ensure that existing chain data could be interpreted correctly by the new modules. To achieve a smooth upgrade, the upgrade handler was extended to perform migrations across the ERC20, EVM, and Auth modules.

ERC20 Module Migration

Cosmos/EVM introduces a different storage model for ERC-20 precompiles compared to Evmos. Specifically, chains that:

• have IBC tokens converted into ERC-20s,

• use token factory assets represented as ERC-20 contracts, or

• store DynamicPrecompiles or NativePrecompiles in state

must explicitly migrate this data to avoid breaking contract resolution post-upgrade.

To accommodate this, the upgrade handler implements a store migration that:

1. Iterates over legacy DynamicPrecompiles and re-inserts them using Cosmos/EVM’s SetDynamicPrecompile method.

2. Iterates over legacy NativePrecompiles and re-inserts them using Cosmos/EVM’s SetNativePrecompile method.

3. Cleans up the legacy store keys after successful migration.

This ensures that any IBC-derived ERC-20s, token factory representations, or precompiles continue functioning under the new runtime.

EVM Module Migration

The EVM module parameter structure diverged significantly between Evmos and Cosmos/EVM. In Evmos, ExtraEIPs were stored as strings (e.g. "ethereum_3855"), whereas Cosmos/EVM expects them as integer values (e.g. 3855). Attempting to query or unmarshal Evmos-style params under Cosmos/EVM causes a panic.

The migration handler addresses this by:

• Unmarshaling legacy Evmos params.

• Sanitizing and converting string-formatted EIPs into integer IDs.

• Rebuilding the AccessControl configuration with Cosmos/EVM’s types.

• Writing a new Params struct compatible with Cosmos/EVM into state.

This ensures that all chain-level EVM configuration (e.g. enabled EIPs, access control, denom settings, static precompiles) is carried forward without breaking queries or transactions.

EthAccounts → BaseAccounts Migration

Under Evmos, EthAccount types embedded both account data and contract CodeHash. Cosmos/EVM decouples these concepts, moving the code hash into the EVM module’s VM store. This allows the account keeper to revert to the standard Cosmos SDK ProtoBaseAccount, simplifying account management and avoiding redundant state.

The upgrade handler performs the following:

1. Iterates through all accounts in state.

2. Identifies legacy EthAccount types.

3. For accounts associated with contracts, extracts the CodeHash and stores it directly in the EVM module via SetCodeHash.

4. Replaces the EthAccount object in the account keeper with the embedded BaseAccount.

This ensures that:

• All contract bytecode references remain intact and queryable by the EVM.

• Accounts no longer depend on the deprecated Evmos-specific EthAccount type.

• The chain fully adopts Cosmos SDK’s ProtoBaseAccount for account storage, aligning with upstream standards.

This migration logic was adapted from Evmos’s own v20 handler and guarantees that smart contract execution and account balances remain valid across the upgrade boundary.

Keys

During the migration we encountered a conflict between the cosmos.evm key types introduced by Cosmos EVM and the legacy evmos key types still present in validator keyrings and user wallets. By default, Cosmos EVM expects keys under the new type definitions (/cosmos.evm.crypto.v1.ethsecp256k1.PubKey), while existing nodes continued to hold /ethermint.crypto.v1.ethsecp256k1.PubKey entries. This mismatch would have forced every validator and end user to manually migrate their keys, introducing operational risk and unnecessary friction. To resolve the issue, we modified the encoding registry to prioritize the legacy Evmos key types over the Cosmos EVM ones, ensuring backward compatibility. This approach allows signatures and key lookups to function transparently with existing key material, avoiding a forced key migration and preserving continuity for all network participants.

Supported EIPs

Shanghai

Deneb

Cancun

Prague

Conclusion

The migration from Evmos to Cosmos EVM v0.4.1 marks a major milestone for the XRPL EVM sidechain. This upgrade ensures long-term sustainability, aligns the network with actively maintained infrastructure, and unlocks critical new capabilities for developers and users.

With expanded ERC-20 functionality (mint, burn, transfer ownership), upgraded IBC support (including rate-limiting under v10), and compatibility with the latest Ethereum standards through newly supported EIPs and opcodes, XRPL EVM is now positioned as a future-proof environment for building scalable, interoperable applications.

By adopting Cosmos EVM, the chain not only strengthens its connection to the Cosmos SDK ecosystem but also remains fully interoperable with the Ethereum developer stack, ensuring that projects can seamlessly leverage tools, standards, and integrations from both worlds.

In short, this upgrade transforms XRPL EVM into a more robust, flexible, and developer-friendly platform—laying the foundation for the next wave of applications and ecosystem growth.