0) Prep
- Create a branch:
git switch -c upgrade/evm-v0.5
. - Ensure a clean build + tests green pre-upgrade.
- Snapshot your current params/genesis for comparison later.
1) Dependency bumps (go.mod)
- Bump
github.com/cosmos/evm
to v0.5.0 and run:
2) Fix "github.com/cosmos/evm/types" imports
v0.5.0
removes github.com/cosmos/evm/types
and moves files to their folders, respective to function.
For a complete list of changes, refer to this PR. The
following list includes references within evmd
that have been moved.
Summary of import changes in evmd
:
Removed import:
Detailed mapping of moved items:
-
AttoPowerReduction
→ moved to"github.com/cosmos/evm/utils"
-
HasDynamicFeeExtensionOption
→ moved to"github.com/cosmos/evm/ante/types"
-
Address Codec functions → new package
"github.com/cosmos/evm/encoding/address"
Useevmaddress.NewEvmCodec()
for address codec initialization: -
Bip44CoinType
,BIP44HDPath
→ moved to"github.com/cosmos/evm/crypto/hd"
-
GenesisState
→ removed as a duplicate object can be found in theevmd
folder and a testing version is in"github.com/cosmos/evm/testutil"
3) App wiring in app.go
Mempool
Minimal setups: nothing to change
If you use the default mempool wiring (no custom pools), your existing code continues to work. IfBlockGasLimit
is 0, it defaults to 100_000_000
. If BroadCastTxFn
is not set, it’s also set to a default value.
Advanced setups: migrate your customizations
PR #496 replaced pre-built pools with configs inEVMMempoolConfig
:
- Replace pools with configs
- Removed:
TxPool *txpool.TxPool
,CosmosPool sdkmempool.ExtMempool
- Added:
LegacyPoolConfig *legacypool.Config
,CosmosPoolConfig *sdkmempool.PriorityNonceMempoolConfig[math.Int]
- Removed:
New Configuration Options
PR #698 adds new configuration options for the EVM mempool that can be set viaapp.toml
or CLI flags. These options allow fine-tuning of the EVM legacy pool behavior.
Configuration via app.toml
The following mempool configuration options are now available in app.toml
under the [evm.mempool]
section:
Configuration via CLI Flags
These options can also be set via CLI flags:--evm.mempool.price-limit
(default: 1)--evm.mempool.price-bump
(default: 10)--evm.mempool.account-slots
(default: 16)--evm.mempool.global-slots
(default: 5120)--evm.mempool.account-queue
(default: 64)--evm.mempool.global-queue
(default: 1024)--evm.mempool.lifetime
(default: 3h0m0s)
Cosmos Mempool Max Transactions
A new flag--mempool.max-txs
allows limiting the maximum number of transactions in the Cosmos mempool. Set to 0 or -1 for unbounded (default: 0).
Simplified Mempool Setup
The mempool configuration can now be handled by a helper function. If you prefer to use the configuration fromapp.toml
and CLI flags, you can refactor your mempool setup:
appOpts
and applies defaults where needed. Note that NewExperimentalEVMMempool
now takes an additional cosmosPoolMaxTx
parameter.
Default Precompiles
Default precompiles have been moved to/evm/precompiles/types/defaults.go
and the function name was
changed to DefaultStaticPrecompiles
. The function signature has also changed, and now takes pointers
as inputs for the Erc20Keeper
and TransferKeeper
. Finally, the WithStaticPrecompiles
builder
function can now happen alongside the keeper instantiation, and not after. The new wiring is shown below:
Denom Configs
#661 removes the instantiation of chain configs via app.go and moves them to state or genesis. It is critical to remove any use of EvmAppOptions as calling the configurator will panic the chain at runtime during startup.EVM Chain ID
The EVM chain ID is now retrieved directly fromappOpts
instead of being passed as a parameter. In app.go
, the chain ID is obtained using:
evmd/app.go:216
for the reference implementation.
Function Signature Changes
Inapp.go
, remove evmChainID and evmAppOptions from the NewApp signature.
app.go
root.go
evmd_config.go
, chain_id.go
, config.go
, constants.go
have been moved to
github.com/cosmos/evm/config
and may be removed to your repo.
UpgradeHandler
As the configs have been moved to state and genesis, you must include an UpgradeHandler if your chain does not satisfy the following conditions.- Your EVM Denom set in the
x/vm
params must haveDenomMetadata
registered for it inx/bank
. - Your EVM Denom must have a display denom associated with it in
DenomMetadata
.- The display denom for the EVM Denom must have an accurate decimal value (i.e. for
uatom
,atom
must have a decimal value of 6.
- The display denom for the EVM Denom must have an accurate decimal value (i.e. for
- Your chain is an 18-decimal chain.
- If your chain does not have DenomMetadata set for the EVM Denom, you must include it.
- If your chain’s EVM denom is not 18 decimals, you must add ExtendedDenomOptions to your
x/vm
params.
4) Build & quick tests
- Send a few EVM txs; confirm promotion/broadcast (or your
BroadCastTxFn
). - Send Cosmos txs; confirm ordering reflects your
CosmosPoolConfig
(if customized).