Skip to content

docs: Update README.md #638

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Sep 22, 2025
+77 −122
Merged

docs: Update README.md #638

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
25341a9
docs: Update README.md
merkletreeibc Sep 19, 2025
14280c1
add repo header
vladjdk Sep 19, 2025
7d39d30
Update README.md
merkletreeibc Sep 22, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
179 changes: 57 additions & 122 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,145 +1,54 @@
<img
src="repo_header.png"
src="repo_header.svg"
alt="Cosmos EVM - A plug-and-play solution that adds EVM compatibility and customizability to your chain"
/>

**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. While the original evmOS repo is currently being used in
production on a few chains without fault, Interchain Labs will only mark the Cosmos EVM repository as stable with a v1
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](https://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 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](https://github.com/cosmos/ibc-go) with EVM and get native ERC-20 support for tokens on Cosmos.

- Build an app-chain with the control and extensibility of the Cosmos SDK
- With native support for EVM as VM and seamless EVM<>Cosmos wallet / token / user experience.
- Leverage IBC with EVM, native support of ERC20 on Cosmos, and more with extensions and precompiles.
Cosmos EVM is customizable for your business use case, chain architecture, and performance needs.

Cosmos EVM is a fork of [evmOS](https://github.com/evmos/OS), maintained by Interchain Labs and the Interchain Foundation
after the latter funded Tharsis to open-source the original codebase.

**Cosmos EVM is fully open-source under the Apache 2.0 license.** With this open-sourced version, you can get:
## Integration

- Full access to Cosmos EVM's modules and updates
- Smooth onboarding experience for an existing or new Cosmos chain
- Full access to product partnerships (block explorers, RPCs, indexers etc.)
- Continuous upgrades, access to product and engineering support

**Want to use Cosmos EVM but want to discuss it with an expert first? [Contact the Interchain Labs team](https://share-eu1.hsforms.com/2g6yO-PVaRoKj50rUgG4Pjg2e2sca).**

For live discussions or support regarding advisories, join the #cosmos-tech channel in Slack.
[Get a Slack invite here](https://forms.gle/A8jawLgB8zuL1FN36) or join the [Telegram Group](https://t.me/cosmostechstack)

## Plug-in Cosmos EVM into your chain

### Integration

Cosmos EVM can easily be integrated into your existing chain
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.
The Interchain Labs team provides you with integration guides and core protocol support depending on your needs and configurations.
**Updated documentation will be releasing soon!**

### Configurations

Cosmos EVM solution is engineered to provide unique flexibility,
empowering you to tailor every aspect of your Ethereum Virtual Machine (EVM) environment.
Whether you're launching a new blockchain or optimizing an existing one,
the Cosmos EVM offers a suite of features designed to meet the unique demands of your project.

#### Powerful defaults

Cosmos EVM’s modules come out of the box with defaults that will get you up and running instantly.

When integrating all available modules you will get a *permissionless EVM-enabled* blockchain
that *exposes JSON-RPC* endpoints for connectivity with all EVM tooling
like wallets ([MetaMask](https://metamask.io/), [Rabby](https://rabby.io/), and others)
or block explorers ([Blockscout](https://docs.blockscout.com/) and others).
You will have access to *all of Cosmos EVM’ extensions*,
which enable access to chain-native functionality
through [Solidity](https://docs.soliditylang.org/en/v0.8.26/) smart contracts.
Your chain provides a *seamless use of any IBC asset in the EVM*
without liquidity fragmentation between wrapped and unwrapped tokens.
Transaction surges are handled by the *self-regulating fee market mechanism* based on EIP-1559
and EIP-712 allows for *structured data si gning* for arbitrary messages.

*Everything* can be controlled by on-chain governance
to create alignment between chain teams and their communities.

#### Extensive customizations

Based on these powerful defaults, the feature set is easily and highly customizable:

- *Permissioned/Restricted EVM*

Maintain control over your network with permissioned or restricted EVM capabilities.
Implement customized access controls to either blacklist or whitelist individual addresses for calling
and/or creating smart contracts on the network.

- *EVM Extensions*

Extend the capabilities of your EVM!
These EVM extensions allow functionality
that is native to Cosmos SDK modules to be accessible from Solidity smart contracts.
We provide a selection of plug-and-play EVM extensions that are ready to be used *today*.

Push the boundaries of what’s possible with fully custom EVM extensions.
Develop the business logic that sets your chain apart from others with the mature tooling for the Go language
and offer its functionality to the masses of Solidity smart contract developers
to integrate in their dApps.

- *Single Token Representation v2 & ERC-20 Module*
### Robust defaults

Simplify token management with Single Token Representation v2
and our `x/erc20` module to elevate the user experience on your chain.
Align IBC coins and ERC-20s and say goodbye to fragmented liquidity.
One balance. In every tool.
Cosmos EVM’s modules come out of the box with defaults that enable rapid VM deployment. Integrating all available modules into a blockchain provides:

- *EIP-1559 Fee Market Mechanism*
- Exposed JSON-RPC endpoints for connectivity with EVM tooling like wallets such as [MetaMask](https://metamask.io/) and [Rabby](https://rabby.io/), and block explorers like [Blockscout](https://docs.blockscout.com/).
- EVM extensions that allow functionality that is native to Cosmos SDK modules to be accessible from Solidity smart contracts [Solidity](https://docs.soliditylang.org/en/v0.8.26/) smart contracts.
- Use of any IBC asset in the EVM.

Take control of transaction costs with our
ready-to-use [EIP-1559 fee market](https://eips.ethereum.org/EIPS/eip-1559) solution.
Tailor fee structures to suit your network’s specific needs,
balancing user affordability with network sustainability.
Or disable it altogether.
All modules can be controlled by on-chain governance.

- *JSON-RPC Server*
### Extensive customizability

There is full control over the exposed namespaces and fine-grained control of the
[JSON-RPC server](https://cosmos-docs.mintlify.app/docs/api-reference/ethereum-json-rpc).
Adjust the configuration to your liking,
including custom timeouts for EVM calls or HTTP requests,
maximum block gas, the number of maximum open connections, and more.
Based on these robust defaults, the feature set is highly customizable:

- *EIP-712 Signing*
- **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](https://eips.ethereum.org/EIPS/eip-1559).
- **JSON-RPC Server** - There is full control over the exposed namespaces and [JSON-RPC server](https://cosmos-docs.mintlify.app/docs/api-reference/ethereum-json-rpc). 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](https://eips.ethereum.org/EIPS/eip-712) 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](https://cosmos-docs.mintlify.app/docs/documentation/smart-contracts/custom-improvement-proposals#custom-improvement-proposals).

You have the option to integrate our [EIP-712 signature](https://eips.ethereum.org/EIPS/eip-712) implementation,
which allows Cosmos SDK messages to be signed with EVM wallets like MetaMask.
## Compatibility with Ethereum

- *Custom Improvement Proposals (Opcodes)*
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.

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](https://cosmos-docs.mintlify.app/docs/documentation/smart-contracts/custom-improvement-proposals#custom-improvement-proposals).

### Forward-compatibility with Ethereum

Ethereum-equivalence describes any EVM solution,
that is identical in transaction execution to the Ethereum client.
It does not more, but also not less than that.
Ethereum-compatible means,
that the EVM can be set up to run every transaction that is valid on Ethereum,
while the handling of the transactions can diverge in e.g. result or cost.

We like to coin the term **forward-compatible**
as a description of our EVM solution,
meaning that any Cosmos EVM chain can run any valid smart contract
from Ethereum but can also implement new features that are
not (yet) available on the standard Ethereum VM,
thus moving the standard forward.
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

Expand Down Expand Up @@ -188,17 +97,43 @@ make test-solidity
make benchmark
```

## Contributing

We welcome open source contributions and discussions! For more on contributing, read our [guide](./CONTRIBUTING.md).

## Open-source License & Credits

Cosmos EVM is open-source under the Apache 2.0 license, an extension of the license of the original codebase (https://github.com/evmos/OS)
created by Tharsis and the evmOS team - who conducted the foundational work for EVM compatibility and
Cosmos EVM is fully open-source under the Apache 2.0 license. It is a fork of [evmOS](https://github.com/evmos/OS). The Interchain Foundation funded [evmOS developers](https://github.com/evmos/OS) Tharsis to open-source the original evmOS codebase. Tharsis and evmOS performed the foundational work for EVM compatibility and
interoperability in Cosmos.

### Key Contributors
## 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](https://discord.com/invite/interchain) - [Telegram](https://t.me/CosmosOG) - [Talk to an Expert](https://cosmos.network/interest-form) - [Join the #Cosmos-tech Slack Channel](https://forms.gle/A8jawLgB8zuL1FN36) |**


## Maintainers
[Cosmos Labs](https://cosmoslabs.io/) maintains the core components of the stack: Cosmos SDK, CometBFT, IBC, Cosmos EVM, and various developer tools and frameworks. 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](https://www.cosmoslabs.io/contact).

Cosmos Labs is a wholly-owned subsidiary of the [Interchain Foundation](https://interchain.io/), the Swiss nonprofit responsible for treasury management, funding public goods, and supporting governance for Cosmos.

We at ICL want to thank our key contributors at [B-Harvest](https://bharvest.io/) and
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](./CONTRIBUTING.md).

### Key Contributors to Cosmos EVM

We would like to thank our key contributors at [B-Harvest](https://bharvest.io/) and
[Mantra](https://www.mantrachain.io/) 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](https://evm.cosmos.network/)

### Cosmos Stack Libraries

- [Cosmos SDK](https://github.com/cosmos/cosmos-sdk) - A framework for building
applications in Golang
- [The Inter-Blockchain Communication Protocol (IBC)](https://github.com/cosmos/ibc-go/) - A blockchain interoperability protocol that allows blockchains to transfer any type of data encoded in bytes.
- [CometBFT](https://github.com/cometbft/cometbft) - High-performance, 10k+ TPS configurable BFT consensus engine.
Binary file removed repo_header.png
View file
Open in desktop
Binary file not shown.
Loading
Loading