Evmos is the canonical EVM chain on Cosmos and the flagship implementation of evmOS — a Cosmos SDK + CometBFT stack that exposes a fully Ethereum-compatible JSON-RPC, Solidity smart contracts, and EIP-1559 fees, while remaining IBC-native. Cosmos modules and EVM contracts share state via precompiles, so Solidity contracts can call IBC, staking, and bank natively.
- 01Solidity dApps that need IBC connectivity
- 02Cosmos chains adopting EVM via the evmOS stack
- 03EVM apps using Cosmos staking/governance via precompiles
- 04EIP-1559 fee markets on a Cosmos chain
- 05porting Ethereum tooling (Hardhat, Foundry, viem, ethers) to Cosmos
- pnpm add viem ethers @cosmjs/stargate @cosmjs/proto-signing
| Variable | Scope | Description |
|---|---|---|
| EVMOS_EVM_RPC_URL | Client | Evmos JSON-RPC endpoint (e.g., `https://evmos-evm.publicnode.com`, chainId `9001` mainnet / `9000` testnet). Used by viem/ethers/wagmi. |
| EVMOS_COSMOS_RPC_URL | Client | Evmos Tendermint RPC endpoint (e.g., `https://rpc.evmos.org`). Used by CosmJS for IBC, staking, and governance ops not exposed via precompiles. |
On the EVM side (chainId `9001`), treat Evmos as a standard EVM chain in viem: `createPublicClient({ chain: { id: 9001, name: 'Evmos', nativeCurrency: { symbol: 'EVMOS', decimals: 18 } }, transport: http(process.env.EVMOS_EVM_RPC_URL) })`. For Cosmos-native ops (IBC transfers, staking) use `@cosmjs/stargate` with `SigningStargateClient.connectWithSigner(rpcEndpoint, signer, { gasPrice: GasPrice.fromString('25000000000aevmos') })`. Solidity contracts can invoke Cosmos modules through PRECOMPILES at fixed addresses: e.g., the staking precompile at `0x0000000000000000000000000000000000000800` (`delegate(string validatorAddress, uint256 amount)`), the bank precompile at `0x0000000000000000000000000000000000000804`, the IBC transfer precompile at `0x0000000000000000000000000000000000000802` (`transfer(string sourcePort, string sourceChannel, string denom, uint256 amount, address sender, string receiver, ...)`). One private key controls both the `0x...` EVM address and the `evmos1...` bech32 address (Eth-Secp256k1).
- ⚑Single key, two address formats: the SAME private key produces an `evmos1...` bech32 AND a `0x...` hex address that map to the same account. UX must show both and warn users not to send EVM tokens to a bech32 address (they'll be lost / require module rescue).
- ⚑Native EVMOS is 18 decimals (`aevmos`, where 1 EVMOS = 10^18 aevmos). IBC-routed assets keep their original decimals (e.g., 6 for ATOM). Always read decimals from the bank precompile or `x/bank` query, never hard-code.
- ⚑Precompile ABIs change between chain upgrades — Evmos has rev'd staking, distribution, and IBC precompiles multiple times. Pin precompile interface to the current chain version (`docs.evmos.org/protocol/modules/evm/precompiles`) and bump after upgrades.
- ⚑Chain upgrades: Evmos has had aggressive upgrade cadence (v15 → v18 → v20 → v22 era) with breaking changes to fee market and EVM module configs. CI-pin viem chain config and re-test after each governance-passed upgrade.
- ⚑IBC channel maintenance: Evmos is IBC-connected; light-client expiry (14-day trusting period) freezes IBC. Solidity contracts calling the IBC precompile during a frozen channel will revert — handle and retry. Resolve channels via `chain-registry`, never hard-code.
- ⚑Slashing on EVMOS validators: 5% double-sign, downtime params per chain config; affects staked EVMOS only, not EVM contract balances. Choose validators carefully when delegating via the staking precompile.
- ⚑EIP-1559: base fee on Evmos is governed by chain params and may not match Ethereum mainnet dynamics — fee estimators that assume Ethereum's base-fee curve over- or under-pay. Query `eth_feeHistory` from Evmos directly.
- ⚑CosmWasm version compatibility: some evmOS-based chains add CosmWasm; pin `cosmwasm-std` to the version listed in chain release notes. Evmos itself focused on EVM and may not always run wasmd.
- ⚑Gas token is `aevmos` for Cosmos-side txs and EVMOS (18-dec) for EVM-side; users without gas can use the fee-grant module on Cosmos side, but EVM-side requires native EVMOS — prefund or sponsor via account-abstraction relays.