README
¶
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
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 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.
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/erc20module 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
- Cosmos SDK - A framework for building applications in Golang
- The Inter-Blockchain Communication Protocol (IBC) - A blockchain interoperability protocol that allows blockchains to transfer any type of data encoded in bytes.
- CometBFT - High-performance, 10k+ TPS configurable BFT consensus engine.
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type EvmApp ¶
type EvmApp interface {
ibctesting.TestingApp
runtime.AppI
InterfaceRegistry() types.InterfaceRegistry
ChainID() string
GetEVMKeeper() *evmkeeper.Keeper
GetErc20Keeper() *erc20keeper.Keeper
SetErc20Keeper(erc20keeper.Keeper)
GetGovKeeper() govkeeper.Keeper
GetSlashingKeeper() slashingkeeper.Keeper
GetEvidenceKeeper() *evidencekeeper.Keeper
GetBankKeeper() bankkeeper.Keeper
GetFeeMarketKeeper() *feemarketkeeper.Keeper
GetAccountKeeper() authkeeper.AccountKeeper
GetAuthzKeeper() authzkeeper.Keeper
GetDistrKeeper() distrkeeper.Keeper
GetStakingKeeper() *stakingkeeper.Keeper
GetMintKeeper() mintkeeper.Keeper
GetPreciseBankKeeper() *precisebankkeeper.Keeper
GetFeeGrantKeeper() feegrantkeeper.Keeper
GetConsensusParamsKeeper() consensusparamkeeper.Keeper
GetCallbackKeeper() keeper.ContractKeeper
GetTransferKeeper() transferkeeper.Keeper
SetTransferKeeper(transferKeeper transferkeeper.Keeper)
DefaultGenesis() map[string]json.RawMessage
GetKey(storeKey string) *storetypes.KVStoreKey
GetAnteHandler() sdk.AnteHandler
MsgServiceRouter() *baseapp.MsgServiceRouter
GetMempool() mempool.ExtMempool
}
EvmApp defines the interface for an EVM application.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
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/precisebank/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. |
|
crypto
|
|
|
ethereum
|
|
|
evmd
module
|
|
|
example_chain
module
|
|
|
txpool/legacypool
Package legacypool implements the normal EVM execution transaction pool.
|
Package legacypool implements the normal EVM execution transaction pool. |
|
precompiles
|
|
|
tests
|
|
|
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. |
|
wallets
|
|
|
x
|
|
|
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. |
|
feemarket/types
Package types is a reverse proxy.
|
Package types is a reverse proxy. |
|
precisebank/types
Package types is a reverse proxy.
|
Package types is a reverse proxy. |
|
vm/types
Package types is a reverse proxy.
|
Package types is a reverse proxy. |
|
vm/wrappers/testutil
Package testutil is a generated GoMock package.
|
Package testutil is a generated GoMock package. |