EOS EVM v0.4.0 Release Notes

--- tags: release --- # EOS EVM v0.4.0 Release Notes EOS EVM is a compatibility layer that can be deployed on top of the EOS blockchain which implements the Ethereum Virtual Machine (EVM). It enables developers to deploy and run their applications on top of the EOS blockchain infrastructure but to build, test, and debug those applications using the common languages and tools they are used to using with other EVM compatible blockchains. It also enables users of such applications to interact with the applications in ways they are familiar with (e.g. using a MetaMask wallet). The EOS EVM consists of multiple components that are tracked across different repositories. The eos-evm repository includes three significant components of EOS EVM which are now officially being introduced as part of this release: 1. EOS EVM Contract 2. EOS EVM Node and RPC 3. TX-Wrapper The EOS EVM Contract is an Antelope contract that implements the main runtime for the EVM. The EOS EVM Node and RPC are two programs based on Silkworm and SilkRPC, `eos-evm-node` and `eos-evm-rpc`, that work together to service most of the read RPC methods within the Ethereum JSON-RPC. TX-Wrapper is a Node.js application which specifically services the `eth_sendRawTransaction` and `eth_gasPrice` RPC methods of the Ethereum JSON-RPC. ## Components ### EOS EVM Contract The EOS EVM Contract implements the main runtime for the EVM and it operates as a contract deployed on the EOS blockchain. It is actually designed to be compatible with any Antelope blockchain assuming all recent protocol features have been activated; however, the contract source code does have a hard-coded, yet easily changeable, assumption that EOS is the native token of the EVM and is the token used by the trustless bridge. The EOS EVM runtime enabled by the EOS EVM Contract is fully compatible with the Ethereum EVM except for some small differences captured in https://docs.eosnetwork.com/docs/latest/eos-evm/compatibility/evm-compatibility. #### Trustless bridge One of those differences between EOS EVM and the Ethereum EVM are a reserved range of addresses that start with a prefix of 12 bytes of `0xbb` (this means externally owned account and contract accounts with addresses start with that prefix cannot be created in the EVM). The reserved addresses enable the EOS EVM trustless bridge which facilitates a way to move EOS tokens between EVM accounts in the internal EVM environment and EOS accounts in the external EOS environment. The EOS tokens held externally by the EOS accounts can conveniently be kept in the `eosio.token` balances as EOS users are accustomed to. Users can seamlessly move EOS tokens to an internal EVM account by transferring tokens to the `eosio.evm` account with the EVM account address specified as the memo; note that a small ingress bridge fee will be deducted from the transfered amount to cover resource costs. Users can seamlessly move EOS tokens back from an internal EVM account to an external EOS account by pushing an EVM transaction that transfers the EOS tokens to a particular EVM address within the reserved address range that maps to the particular EOS account that is intended as the destination of those EOS tokens. The seamless bridge transfer from the EVM environment to the EOS environment comes with the limitation that at most one external EOS account can be the destination of the seamless bridge transfer per each EVM transaction and that external EOS account cannot have a contract deployed on it (unless it is on a special egress allow list). The EOS tokens held externally by an EOS account can alternatively be kept in a balance tracked within the EOS EVM Contract that is controlled by that EOS account. This is an advanced mode that allows users to bypass some of the limitations of the easier seamless mode described earlier. It first requires the EOS account to explicitly `open` the balance. The balance must also be opened before an EOS account is allowed to act as a "miner" for pushing an EVM transaction. #### Miners and collecting gas fees for pushing EVM transactions The `pushtx` action allows an EVM transaction (in rlp encoding) to be pushed into the virtual EVM blockchain managed by the EOS EVM Contract. The `pushtx` action also has an parameter called `miner` which takes an EOS account name. The specified account acts as the "miner" for the pushed EVM transaction which means it collects a portion of the gas fees collected from that transaction. The purpose of this is to compensate the miner who is expected to be covering the CPU and NET costs of the Antelope transaction including the `pushtx` action. The gas calculations for EVM transactions processed by EOS EVM are exactly the same as those of Ethereum prior to the London hardfork which included the changes of [EIP-1559](https://eips.ethereum.org/EIPS/eip-1559). This means none of the gas fees are immediately burned by the EVM and instead those gas fees are first collected by the EOS EVM Contract. Additionally, the EOS EVM Contract will reject the EVM transaction if the gas price specified within it is less than some minimum gas price which is a parameter (called `gas_price`) that is configurable within the EOS EVM Contract. Though the EOS EVM Contract first collects all of the gas fees of any processed transaction as an intermediate step, it does not indefinitely hold on to all of those collected fees. It immediately sends a portion of the collect gas fee (percentage determined by another parameter called `miner_cut` that is configurable within the EOS EVM Contract) to the specified miner's balance within the EOS EVM Contract. The portion of gas fees automatically accumulate over time in that miner's balance and can be withdrawn out by the miner at any time to their `eosio.token` balance using the `withdraw` action. ### EOS EVM Node and RPC The EOS EVM Contract does not implement support for the Ethereum JSON-RPC that is expected by developers building on EVM-compatible blockchains. That RPC is instead supported by other software included as part of the overall EOS EVM project. In particular the `eos-evm-rpc` program, which is a fork of [SilkRPC](https://github.com/torquem-ch/silkrpc), is a daemon that supports nearly all of the Ethereum JSON-RPC for the virtual EVM blockchain managed by the EOS EVM Contract. Two of the RPC methods, `eth_sendRawTransaction` and `eth_gasPrice` are intentionally disabled on this daemon because it is not appropriate for this daemon to handle those methods; instead requests for two of those methods should be routed to the TX-Wrapper which is designed specifically to support those two RPC methods. The `eos-evm-rpc` program does not work by itself. To do its job, it relies on the database managed by an execution client for (virtual) EVM blockchain. In the case of the EOS EVM project, this execution client is the `eos-evm-node` program, which is a fork of [Silkworm](https://github.com/torquem-ch/silkworm) modified to work with the changes to the EVM runtime that were needed to support the EOS EVM, such as the trustless bridge. The `eos-evm-node` needs to exactly reproduce the EVM transaction execution that was first done by the EOS EVM Contract. It needs to reconstruct the virtual EVM blockchain that is managed by the EOS EVM Contract using data extracted from the EOS blockchain. To faciliate this, `eos-evm-node` must connect to a state history plugin (SHiP) endpoint of a [Leap](https://github.com/AntelopeIO/leap) node connected to the EOS blockchain. ### TX-Wrapper As mentioned earlier, the two RPC methods, `eth_sendRawTransaction` and `eth_gasPrice`, that are not implemented by `eos-evm-rpc` are instead implemented by the TX-Wrapper. The primary purpose of the TX-wrapper is to take raw EVM transactions via `eth_sendRawTransaction` and push them to the EOS EVM Contract. It does this by: constructing an Antelope transaction containng the `pushtx` action of the EOS EVM Contract which includes the rlp-encoded EVM transaction; signing the Antelope transaction with the key of an EOS account that acts as the miner of the `pushtx` action and pays the CPU/NET costs of the Antelope transaction; and, sends the signed Antelope transaction to the EOS blockchain via the chain API of a Leap node connected to teh EOS network. TX-wrapper also supports the `eth_gasPrice` RPC method, despite the fact that it is a read method, because its implementation also depends on access to the chain API of a Leap node. In particular, it simply grabs the minimum gas price configured in the EOS EVM Contract from the appropriate table and returns it to the caller. ## Building, compatibility, and upgrading ### Building The README in the eos-evm repository contains instructions on how to build the components. The eos-evm respository is not yet accessible publicly. ### Compatibility and upgrading Version 0.3.0 of EOS EVM introduced significant incompatible changes compared to prior versions with the introduction of the trustless bridge. That version of the EOS EVM Contract was deployed to the Jungle4 test network on a fresh new account, `eosio.evm`, so there were no compatibility or upgrade concerns to consider regarding that component. Going forward upgrades to the deployment of EOS EVM on the test network will need to consider compatibility and upgrading. Version 0.4.0 has minimal changes relative v0.3.0 that should not impact the upgrade of the EOS EVM Contract to v0.4.0. It will require redeployment and reindexing of the EOS EVM Node and RPC to reflect bug fixes made to those components. Upgrading the EOS EVM Contract from v0.3.0 to v0.4.0 is as simple as doing a `setcode` and `setabi` with the new WASM and ABI files, respectively. The only functional difference in the contract is the removal of the `ChainConfig` for an old and now obsolete test network (with chain ID of 15556) and the addition of the `ChainConfig` for mainnet deployment of EOS EVM on the EOS blockchain (chain ID of 17777). Additionally, there have been no functional changes to the EOS EVM Contract from v0.4.0-rc1 to v0.4.0 and so while the compiled v0.4.0 contract may not be exactly the same as the one compiled from v0.4.0-rc1, there is no need to deploy the v0.4.0 EOS EVM Contract to replace an already deployed v0.4.0-rc1 EOS EVM Contract.