evm

package module
v0.7.0-beta.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 27, 2026 License: Apache-2.0 Imports: 27 Imported by: 7

README

Cosmos EVM - A plug-and-play solution that adds EVM compatibility and customizability to your chain

What is Cosmos EVM?

Cosmos EVM is a plug-and-play solution that adds EVM compatibility and customizability to your Cosmos SDK chain. Cosmos EVM is used by Ondo, Mezo, Mantra, XRP sidechain, Telegram Application Chain (TAC), Stable, and others. Cosmos EVM equips Cosmos chains with complete Ethereum capabilities: Solidity smart contracts, Ethereum JSON-RPC, native support for the EVM wallet/token/user experience, and access to the entire Ethereum developer ecosystem. Its precompiles and extensions allow developers to leverage modules like IBC with EVM and get native ERC-20 support for tokens on Cosmos.

Cosmos EVM is customizable for your business use case, chain architecture, and performance needs.

Please note: This repo is undergoing changes while the code is being audited and tested. For the time being we will be making v0.x releases. Some breaking changes might occur. Cosmos Labs will only mark the Cosmos EVM repository as stable with a v1 release after the audit, key stability features and benchmarking are completed.

Visit the official documentation for Cosmos EVM: evm.cosmos.network

Integration

Cosmos EVM can be integrated into your existing chain or added during the development of your upcoming chain launch by importing Cosmos EVM as a go module library.

Robust defaults

Cosmos EVM’s modules come out of the box with defaults that enable rapid VM deployment. Integrating all available modules into a blockchain provides:

  • Exposed JSON-RPC endpoints for connectivity with EVM tooling like wallets such as MetaMask and Rabby, and block explorers like Blockscout.
  • EVM extensions that allow functionality that is native to Cosmos SDK modules to be accessible from Solidity smart contracts Solidity smart contracts.
  • Use of any IBC asset in the EVM.

All modules can be controlled by on-chain governance.

Extensive customizability

Based on these robust defaults, the feature set is highly customizable:

  • Permissioned EVM- Implement customized access controls to either blacklist or whitelist individual addresses for calling and/or creating smart contracts on the network.
  • EVM Extensions - Use custom EVM extensions to write custom business logic for your use case.
  • Single Token Representation v2 & ERC-20 Module - The Single Token Representation v2 and our x/erc20 module to aligns IBC and ERC-20 token representation to simplify and improve user experience.
  • EIP-1559 Fee Market Mechanism - Customize fee structures and transaction surge management with the self-regulating fee market mechanism based on EIP-1559 fee market.
  • JSON-RPC Server - There is full control over the exposed namespaces and JSON-RPC server. Configurable parameters include custom timeouts for EVM calls or HTTP requests, maximum block gas, open connections, and more.
  • EIP-712 Signing - Integrate the EIP-712 signature implementation to allow Cosmos SDK messages to be signed with EVM wallets like MetaMask. This supports structured data signing for arbitrary messages.
  • Custom Improvement Proposals (Opcodes) - Any Cosmos EVM user is provided the opportunity to customize bits of their EVM opcodes and add new ones. Read more on custom operations here.

Compatibility with Ethereum

Is Cosmos EVM "Ethereum equivalent"? Ethereum-equivalence describes any EVM solution that is identical in transaction execution to the Ethereum client. On the other hand, Ethereum-compatible means that the EVM implementation can run every transaction that is valid on Ethereum, while also handling divergent transactions that are not valid on Ethereum.

We describe Cosmos EVM as forward-compatible with Ethereum. It can run any valid smart contract from Ethereum and also implement new features that are not yet available on the standard Ethereum VM, thus moving the standard forward.

Getting started

To run the example evmd chain, run the script using ./local_node.sh from the root folder of the repository.

Migrations

We provide upgrade guides here for upgrading your chain from various Cosmos EVM versions.

Testing

All test scripts are found in Makefile in the root of the repository. Listed below are the commands for various tests:

Unit Testing
make test-unit
Coverage Test

This generates a code coverage file filtered_coverage.txt and prints out the covered code percentage for the working files.

make test-unit-cover
Fuzz Testing
make test-fuzz
Solidity Tests
make test-solidity
Benchmark Tests
make benchmark

Open-source License & Credits

Cosmos EVM is fully open-source under the Apache 2.0 license. It is a fork of evmOS. The Interchain Foundation funded evmOS developers Tharsis to open-source the original evmOS codebase. Tharsis and evmOS performed the foundational work for EVM compatibility and interoperability in Cosmos.

Developer Community and Support

The issue list of this repo is exclusively for bug reports and feature requests. We have active, helpful communities on Discord, Telegram, and Slack.

| Need Help? | Support & Community: Discord - Telegram - Talk to an Expert - Join the #Cosmos-tech Slack Channel |

Maintainers

Cosmos Labs maintains the core components of the stack: Cosmos SDK, CometBFT, IBC, Cosmos EVM, and various developer tools and frameworks. The detailed maintenance policy can be found here. In addition to developing and maintaining the Cosmos Stack, Cosmos Labs provides advisory and engineering services for blockchain solutions. Get in touch with Cosmos Labs.

Cosmos Labs is a wholly-owned subsidiary of the Interchain Foundation, the Swiss nonprofit responsible for treasury management, funding public goods, and supporting governance for Cosmos.

The Cosmos Stack is supported by a robust community of open-source contributors.

Contributing to Cosmos EVM

We welcome open source contributions and discussions! For more on contributing, read the guide.

Key Contributors to Cosmos EVM

We would like to thank our key contributors at B-Harvest and Mantra for contributing to and helping us drive the development of Cosmos EVM.

Documentation and Resources

Documentation

Visit the official documentation for Cosmos EVM: evm.cosmos.network

Cosmos Stack Libraries

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type AccountKeeperProvider added in v0.7.0 

type AccountKeeperProvider interface {
	GetAccountKeeper() authkeeper.AccountKeeper
}

Keeper provider interfaces allow tests to depend on the exact subset of keepers they need without requiring a fully fledged evmd application.

type AnteHandlerProvider added in v0.7.0 

type AnteHandlerProvider interface {
	GetAnteHandler() sdk.AnteHandler
}

Keeper provider interfaces allow tests to depend on the exact subset of keepers they need without requiring a fully fledged evmd application.

type AnteIntegrationApp added in v0.7.0 

type AnteIntegrationApp interface {
	IntegrationNetworkApp
	FeeGrantKeeperProvider
	IBCKeeperProvider
}

type BankKeeperProvider added in v0.7.0 

type BankKeeperProvider interface {
	GetBankKeeper() bankkeeper.Keeper
}

Keeper provider interfaces allow tests to depend on the exact subset of keepers they need without requiring a fully fledged evmd application.

type BankPrecompileApp added in v0.7.0 

type BankPrecompileApp interface {
	TestApp
	BankKeeperProvider
	Erc20KeeperProvider
}

Precompile-focused application interfaces describe the exact keepers that a given precompile test suite requires. External chains can implement only the interfaces relevant to the suites they wish to run.

type Bech32PrecompileApp added in v0.7.0 

type Bech32PrecompileApp interface {
	TestApp
}

type CallbackKeeperProvider added in v0.7.0 

type CallbackKeeperProvider interface {
	GetCallbackKeeper() keeper.ContractKeeper
}

Keeper provider interfaces allow tests to depend on the exact subset of keepers they need without requiring a fully fledged evmd application.

type ChainIDProvider added in v0.7.0 

type ChainIDProvider interface {
	ChainID() string
}

Keeper provider interfaces allow tests to depend on the exact subset of keepers they need without requiring a fully fledged evmd application.

type ConsensusParamsKeeperProvider added in v0.7.0 

type ConsensusParamsKeeperProvider interface {
	GetConsensusParamsKeeper() consensusparamkeeper.Keeper
}

Keeper provider interfaces allow tests to depend on the exact subset of keepers they need without requiring a fully fledged evmd application.

type DistrKeeperProvider added in v0.7.0 

type DistrKeeperProvider interface {
	GetDistrKeeper() distrkeeper.Keeper
}

Keeper provider interfaces allow tests to depend on the exact subset of keepers they need without requiring a fully fledged evmd application.

type DistributionPrecompileApp added in v0.7.0 

type DistributionPrecompileApp interface {
	TestApp
	DistrKeeperProvider
	StakingKeeperProvider
}

type Erc20IntegrationApp added in v0.7.0 

type Erc20IntegrationApp interface {
	IntegrationNetworkApp
	TransferKeeperProvider
	IBCKeeperProvider
}

type Erc20KeeperProvider added in v0.7.0 

type Erc20KeeperProvider interface {
	GetErc20Keeper() *erc20keeper.Keeper
}

Keeper provider interfaces allow tests to depend on the exact subset of keepers they need without requiring a fully fledged evmd application.

type Erc20KeeperSetter added in v0.7.0 

type Erc20KeeperSetter interface {
	SetErc20Keeper(erc20keeper.Keeper)
}

Keeper provider interfaces allow tests to depend on the exact subset of keepers they need without requiring a fully fledged evmd application.

type Erc20PrecompileApp added in v0.7.0 

type Erc20PrecompileApp interface {
	TestApp
	AccountKeeperProvider
	BankKeeperProvider
	Erc20KeeperProvider
	TransferKeeperProvider
}

type EvidenceKeeperProvider added in v0.7.0 

type EvidenceKeeperProvider interface {
	GetEvidenceKeeper() *evidencekeeper.Keeper
}

Keeper provider interfaces allow tests to depend on the exact subset of keepers they need without requiring a fully fledged evmd application.

type EvmApp 

type EvmApp interface {
	TestApp
	AccountKeeperProvider
	AnteHandlerProvider
	CallbackKeeperProvider
	ConsensusParamsKeeperProvider
	DistrKeeperProvider
	EvidenceKeeperProvider
	Erc20KeeperProvider
	Erc20KeeperSetter
	FeeGrantKeeperProvider
	FeeMarketKeeperProvider
	GovKeeperProvider
	KeyProvider
	MempoolProvider
	MintKeeperProvider
	MsgServiceRouterProvider
	SlashingKeeperProvider
	TransferKeeperProvider
	TransferKeeperSetter
}

EvmApp defines the interface for an EVM application.

type FeeGrantKeeperProvider added in v0.7.0 

type FeeGrantKeeperProvider interface {
	GetFeeGrantKeeper() feegrantkeeper.Keeper
}

Keeper provider interfaces allow tests to depend on the exact subset of keepers they need without requiring a fully fledged evmd application.

type FeeMarketKeeperProvider added in v0.7.0 

type FeeMarketKeeperProvider interface {
	GetFeeMarketKeeper() *feemarketkeeper.Keeper
}

Keeper provider interfaces allow tests to depend on the exact subset of keepers they need without requiring a fully fledged evmd application.

type GovKeeperProvider added in v0.7.0 

type GovKeeperProvider interface {
	GetGovKeeper() govkeeper.Keeper
}

Keeper provider interfaces allow tests to depend on the exact subset of keepers they need without requiring a fully fledged evmd application.

type GovPrecompileApp added in v0.7.0 

type GovPrecompileApp interface {
	TestApp
	GovKeeperProvider
}

type IBCApp added in v0.7.0 

type IBCApp interface {
	EvmApp
	IBCKeeperProvider
}

type IBCCallbackIntegrationApp added in v0.7.0 

type IBCCallbackIntegrationApp interface {
	IntegrationNetworkApp
	CallbackKeeperProvider
	IBCKeeperProvider
}

type IBCIntegrationApp added in v0.7.0 

type IBCIntegrationApp interface {
	IntegrationNetworkApp
	TransferKeeperProvider
	IBCKeeperProvider
}

type IBCKeeperProvider added in v0.7.0 

type IBCKeeperProvider interface {
	GetIBCKeeper() *ibckeeper.Keeper
}

Keeper provider interfaces allow tests to depend on the exact subset of keepers they need without requiring a fully fledged evmd application.

type IBCTestApp added in v0.7.0 

type IBCTestApp interface {
	TestApp
	ibctesting.TestingApp
}

type ICS20PrecompileApp added in v0.7.0 

type ICS20PrecompileApp interface {
	TestApp
	ChainIDProvider
	BankKeeperProvider
	StakingKeeperProvider
	TransferKeeperProvider
	IBCKeeperProvider
}

type IntegrationNetworkApp added in v0.7.0 

type IntegrationNetworkApp interface {
	TestApp
	AccountKeeperProvider
	DistrKeeperProvider
	Erc20KeeperProvider
	FeeMarketKeeperProvider
	GovKeeperProvider
	MintKeeperProvider
	SlashingKeeperProvider
	EvidenceKeeperProvider
}

Base interface required by the integration network helpers. Any app used by evm/testutil/integration must satisfy these keeper providers so the shared network setup can access the necessary modules.

type KeyProvider added in v0.7.0 

type KeyProvider interface {
	GetKey(storeKey string) *storetypes.KVStoreKey
}

Keeper provider interfaces allow tests to depend on the exact subset of keepers they need without requiring a fully fledged evmd application.

type MempoolProvider added in v0.7.0 

type MempoolProvider interface {
	GetMempool() mempool.ExtMempool
}

Keeper provider interfaces allow tests to depend on the exact subset of keepers they need without requiring a fully fledged evmd application.

type MintKeeperProvider added in v0.7.0 

type MintKeeperProvider interface {
	GetMintKeeper() mintkeeper.Keeper
}

Keeper provider interfaces allow tests to depend on the exact subset of keepers they need without requiring a fully fledged evmd application.

type MsgServiceRouterProvider added in v0.7.0 

type MsgServiceRouterProvider interface {
	MsgServiceRouter() *baseapp.MsgServiceRouter
}

Keeper provider interfaces allow tests to depend on the exact subset of keepers they need without requiring a fully fledged evmd application.

type P256PrecompileApp added in v0.7.0 

type P256PrecompileApp interface {
	TestApp
}

type SlashingKeeperProvider added in v0.7.0 

type SlashingKeeperProvider interface {
	GetSlashingKeeper() slashingkeeper.Keeper
}

Keeper provider interfaces allow tests to depend on the exact subset of keepers they need without requiring a fully fledged evmd application.

type SlashingPrecompileApp added in v0.7.0 

type SlashingPrecompileApp interface {
	TestApp
	SlashingKeeperProvider
	StakingKeeperProvider
}

type StakingKeeperProvider added in v0.7.0 

type StakingKeeperProvider interface {
	GetStakingKeeper() *stakingkeeper.Keeper
}

Keeper provider interfaces allow tests to depend on the exact subset of keepers they need without requiring a fully fledged evmd application.

type StakingPrecompileApp added in v0.7.0 

type StakingPrecompileApp interface {
	TestApp
	AccountKeeperProvider
	BankKeeperProvider
	StakingKeeperProvider
}

type TestApp added in v0.7.0 

type TestApp interface {
	servertypes.Application
	runtime.AppI
	InterfaceRegistry() types.InterfaceRegistry
	AppCodec() codec.Codec
	GetTxConfig() client.TxConfig
	LegacyAmino() *codec.LegacyAmino
	ChainID() string
	DefaultGenesis() map[string]json.RawMessage
	GetKey(storeKey string) *storetypes.KVStoreKey
	GetBaseApp() *baseapp.BaseApp
	LastCommitID() storetypes.CommitID
	LastBlockHeight() int64
	GetAnteHandler() sdk.AnteHandler
	MsgServiceRouter() *baseapp.MsgServiceRouter
	GetMempool() mempool.ExtMempool

	// keeper getters
	VMKeeperProvider
	BankKeeperProvider
	StakingKeeperProvider
}

TestApp captures the minimal functionality all test harnesses require.

type TransferKeeperProvider added in v0.7.0 

type TransferKeeperProvider interface {
	GetTransferKeeper() *transferkeeper.Keeper
}

Keeper provider interfaces allow tests to depend on the exact subset of keepers they need without requiring a fully fledged evmd application.

type TransferKeeperSetter added in v0.7.0 

type TransferKeeperSetter interface {
	SetTransferKeeper(*transferkeeper.Keeper)
}

Keeper provider interfaces allow tests to depend on the exact subset of keepers they need without requiring a fully fledged evmd application.

type VMIntegrationApp added in v0.7.0 

type VMIntegrationApp interface {
	IntegrationNetworkApp
	ConsensusParamsKeeperProvider
}

type VMKeeperProvider added in v0.7.0 

type VMKeeperProvider interface {
	GetEVMKeeper() *evmkeeper.Keeper
}

Keeper provider interfaces allow tests to depend on the exact subset of keepers they need without requiring a fully fledged evmd application.

type WERC20PrecompileApp added in v0.7.0 

type WERC20PrecompileApp interface {
	TestApp
	BankKeeperProvider
	Erc20KeeperProvider
	TransferKeeperProvider
}

Source Files

View all Source files

Directories

Path Synopsis
cosmos
evm
interfaces
types
api
cosmos/evm/ante/v1
Code generated by protoc-gen-go-pulsar.
 Code generated by protoc-gen-go-pulsar.
cosmos/evm/crypto/v1/ethsecp256k1
Code generated by protoc-gen-go-pulsar.
 Code generated by protoc-gen-go-pulsar.
cosmos/evm/eip712/v1
Code generated by protoc-gen-go-pulsar.
 Code generated by protoc-gen-go-pulsar.
cosmos/evm/erc20/v1
Code generated by protoc-gen-go-pulsar.
 Code generated by protoc-gen-go-pulsar.
cosmos/evm/feemarket/v1
Code generated by protoc-gen-go-pulsar.
 Code generated by protoc-gen-go-pulsar.
cosmos/evm/server/v1
Code generated by protoc-gen-go-pulsar.
 Code generated by protoc-gen-go-pulsar.
cosmos/evm/vm/v1
Code generated by protoc-gen-go-pulsar.
 Code generated by protoc-gen-go-pulsar.
block
debug
keys
utils
contrib
x/precisebank
x/precisebank/client/cli
x/precisebank/keeper
x/precisebank/testutil
x/precisebank/types
Package types is a reverse proxy.
 Package types is a reverse proxy.
x/precisebank/types/mocks
crypto
codec
ethsecp256k1
hd
keyring
secp256r1
address
codec
ethereum
eip712
evmd module
internal/heightsync
internal/queue
internal/reaplist
internal/txtracker
miner
mocks
reserver
txpool
txpool/legacypool
Package legacypool implements the normal EVM execution transaction pool.
 Package legacypool implements the normal EVM execution transaction pool.
txpool/legacypool/mocks
txpool/mocks
precompiles
bank
bech32
callbacks
common
common/mocks
distribution
erc20
gov
ics02
ics20
p256
slashing
staking
testutil
testutil/contracts
types
werc20
rpc
backend
backend/mocks
ethereum/pubsub
namespaces/ethereum/debug
namespaces/ethereum/eth
namespaces/ethereum/eth/filters
namespaces/ethereum/eth/filters/mocks
namespaces/ethereum/miner
namespaces/ethereum/net
namespaces/ethereum/personal
namespaces/ethereum/txpool
namespaces/ethereum/web3
stream
types
config
config/migration
flags
types
tests
contracts
integration/ante
integration/eip712
integration/eip7702
integration/eips
integration/indexer
integration/mempool
integration/precompiles/bank
integration/precompiles/bech32
integration/precompiles/common
integration/precompiles/distribution
integration/precompiles/erc20
integration/precompiles/gov
integration/precompiles/ics20
integration/precompiles/p256
integration/precompiles/slashing
integration/precompiles/staking
integration/precompiles/werc20
integration/rpc/backend
integration/wallets
integration/x/erc20
integration/x/feemarket
integration/x/ibc
integration/x/ibc/callbacks
integration/x/vm
jsonrpc/simulator module
systemtests module
app
config
constants
ibc
This file contains the variables, constants, and default values used in the testing package and commonly defined in tests.
 This file contains the variables, constants, and default values used in the testing package and commonly defined in tests.
integration
integration/base/factory
integration/base/grpc
integration/base/network
integration/evm/factory
integration/evm/grpc
integration/evm/network
integration/evm/utils
keyring
tx
types
eth
wallets
accounts
ledger
ledger/mocks
usbwallet
x
erc20
erc20/client/cli
erc20/keeper
erc20/types
Package types is a reverse proxy.
 Package types is a reverse proxy.
erc20/types/mocks
Package mocks is a generated GoMock package.
 Package mocks is a generated GoMock package.
erc20/v2
feemarket
feemarket/client/cli
feemarket/keeper
feemarket/types
Package types is a reverse proxy.
 Package types is a reverse proxy.
ibc/callbacks/keeper
ibc/callbacks/testutil
ibc/callbacks/types
vm
vm/ante
vm/client/cli
vm/keeper
vm/runner
Package runner installs a baseapp TxRunner wrapped with the EVM module's post-execution log-index fix-up (evmtypes.PatchTxResponses).
 Package runner installs a baseapp TxRunner wrapped with the EVM module's post-execution log-index fix-up (evmtypes.PatchTxResponses).
vm/statedb
vm/statedb/mocks
vm/store/snapshotkv
vm/store/snapshotmulti
vm/store/types
vm/types
Package types is a reverse proxy.
 Package types is a reverse proxy.
vm/types/mocks
vm/wrappers
vm/wrappers/testutil
Package testutil is a generated GoMock package.
 Package testutil is a generated GoMock package.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.