Releases: eosnetworkfoundation/eos-evm-contract
EOS EVM v0.5.0-rc1 Release Notes
This release contains changes to all major components of the EOS EVM.
Components
EOS EVM Contract
Action to execute read-only transactions
The EOS EVM contract now has a new action called exec which allows the caller to execute EVM code and get the return value. No side-effects will be committed to state and this action is intended to be used for read-only executions, e.g. calling Solidity view functions.
There are two ways of getting the return value. If no callback is specified in the arguments of the exec action, then the EVM contract message call return value will be included as part of the return value of the exec action. Otherwise, if a callback (of the form of a contract account name and action name) is specified, the EOS EVM Contract will deliver the return value as an inline action call made to contract specified in the callback.
This feature is a necesssary component for Yield+ integration with the EOS EVM.
Increased stack size to allow deeper nested calls
The EOS EVM Contact has a limit on the stack used within WASM linear memory. This puts a limit to how deeply nested EVM contract calls can get within the EVM implementation before it runs out of stack.
The stack limit in prior releases allow nested calls to get to a depth of 5. Optimizations in the EOS EVM Contract implementation have allowed for almost doubling the stack size which has correspondingly increased the EVM call depth limit by a significant amount thus enabling contract use cases that may have been rejected before.
Other improvements to the EOS EVM Contract
PRs
The inevm table now shows up in the ABI which should allow for easy exploration of the total sum of the EOS balances within the EVM environment using an EOS block explorer. Note that this balance does not include any of the other balances held by the EOS EVM Contract on the EOS side, e.g. the accumulated gas fees in the eosio.evm balances or the balances of miners who have explicitly opened an account in the contract using the open action.
The withdraw action has been modified to take an optional extra argument called to. Normally, when to is not specified, the funds beloging to the owner are withdraw to the balance within the eosio.token contract belonging to owner. If to is specified, then the funds are instead sent to the to account.
The EOS EVM Contract will now reject any non-EOS tokens, e.g. USDT, that are sent to it. As a reminder, the trustless bridge does not yet support any tokens other than EOS.
A more descriptive error message is now returned if validation of a pushed EVM transaction fails.
EOS EVM Node and RPC
Various bug fixes
PRs
A bug in the history index of EOS EVM Node was fixed. This bug caused the block explorer to show incorrect records. To resolve this issue in an already deployed instance, it is necessary to replay the EOS EVM Node and then it is necessary to re-index the block explorer that used data from the buggy EOS EVM Node.
Additional bugs in EOS EVM RPC were fixed. An eth_call request without an explicit from value specified now works correctly. Gas estimation now returns expected responses under certain error conditions.
TX-Wrapper
Configurable permission and expiration
Prior to this release, TX-Wrapper had a hard-coded expiration for the EOS wrapped transaction set to 50 minutes in the future. In this release, the expiration time is configurable with the optional EXPIRE_SEC parameter (takes the expiration duration in seconds). If not specified, the expiration time will default to 5 minutes.
TX-Wrapper also now requires an additional parameter EOS_PERMISSION to set the permission to use for the miner's authorization of the pushtx action. To maintain existing behavior, ensure this parameter is set to "active". The permission can be changed to a custom permission on the account specified by EOS_SENDER. However, ensure that linkauth is used to allow that custom permission to satisfy the pushtx action of the EOS EVM Contract, otherwise TX-Wrapper will not function correctly.
Building, compatibility, and upgrading
Building
The README in the eos-evm repository contains instructions on how to build the components.
Compatibility and upgrading
The components can be upgraded from any prior 0.4.x release.
The EOS EVM Contract is simply upgrading by deploying the WASM and ABI.
EOS EVM Node needs to replay from genesis. Block explorers leveraging data from EOS EVM Node are recommended to re-index.
The .env file used by TX-Wrapper should first ensure the line EOS_PERMISSION="active" is added before starting the new TX-Wrapper to ensure it can start up and behave the same way as before.
Further details on changes since last release
Contributors
Special thanks to the contributors that submitted patches for this release:
Full list of changes since last release
PRs
- (505) [0.4 -> main] Bring recent 0.4.x changes into main. Bump version to 0.5.0
- (508) [0.4 -> main] add missing nginx log settings
- (511) Update README to include links to EOS EVM docs and evm-public-docs
- (503) configurable permission in tx_wrapper
- (522) Remove flask_proxy
- (532) evmone version
- (534) [0.4 -> main] Enable keep alive to read and test endpoint
- (538) [0.4 -> main] fix silkworm stability
- (521) fix #465 #451 extra param for withdraw, inevm table abi
- (544) Reject non eos token in bridging
- (546) add some additional tests for invalid addresses in EOS->EVM bridge memos
- (550) more briging tests
- (474) Remove advanced execution to increase nested call level
- (553) eth_call: use default from address when not specified
- (555) Fix Wrong History Index
- (557) Fix gas estimation return value
- (541) Return error number and more descriptive message when validation failed
- (547) Add read-only transaction execution support to EVM contract
Full Changelog: v0.4.2...v0.5.0-rc1
Contributors
Assets 2
EOS EVM v0.4.2 Release Notes
This release fixes a critical security vulnerability discovered in EOS EVM. The components EOS EVM Contract, EOS EVM Node, and EOS EVM RPC must all be upgraded.
Components
EOS EVM Contract
The security vulnerability is related to the state objects tracking the reserved addresses of the trustless bridge and how they were not properly being undone in the case of an EVM execution context being reverted. If exploited, it could potentially allow an attacker to illegitimately drain all of the EOS stored by the EOS EVM Contract across the trustless bridge.
This vulnerability has already been patched in the deployment of EOS EVM on the EOS mainnet. It has also been patched in the deployment of EOS EVM on the Jungle4 testnet.
EOS EVM Node and RPC
The patch to the security vulnerability is in the silkworm engine shared by both the EOS EVM Contract and the EOS EVM Node. So the patched EOS EVM Node must also be deployed alongside the updated EOS EVM Contract to ensure consistency between the two components.
While it is sufficient to update the EOS EVM Contract to prevent any loss of funds, it is important to also update the EOS EVM Node otherwise the exploit could be used to take down the EOS EVM Node and EOS EVM RPC.
An additional stability improvement to EOS EVM Node is also included as part of this same release.
Building, compatibility, and upgrading
Compatibility
The fix to the security vulnerability is technically a breaking change to EOS EVM. However, the vulnerability does not appear to have been exploited on either the EOS EVM testnet or mainnet. Therefore, it becomes possible to treat the fix as simpler retroactive change of the EVM.
Upgrading
Upgrading EOS EVM Contract from v0.4.1 simply requires a setcode of the v0.4.2 contract. There are no changes to the ABI.
Upgrading EOS EVM Node and EOS EVM RPC from v0.4.1 only requires restarting the services with the updated binaries.
Further details on changes since last release
Contributors
Special thanks to the contributors that submitted patches for this release:
Full list of changes since last release
PRs
Full Changelog: v0.4.1...v0.4.2
Contributors
Assets 2
EOS EVM v0.4.1 Release Notes
This release contains changes to all major components of the EOS EVM, however no functional changes have been introduced to the EOS EVM Contract. Relative to deployments of v0.4.0-rc1, a significant bug fix to the fork handling logic of EOS EVM Node means that historical block hashes may change.
Components
EOS EVM Contract
There have been no functional changes to the EOS EVM Contract, however, due to the version bump, the compiled contract is not expected to be exactly the same as the v0.4.0 version of the contract.
EOS EVM Node and RPC
Fixes to fork handling in EOS EVM Node
Bugs were found in the fork handling logic of EOS EVM Node that could be triggered by microforks of the underlying Antelope blockchains. Additionally, the fork handling logic had an additional issue that caused it to calculate incorrect block hashes. These identified problems have been fixed as of this release.
Note that block hashes accessible from contracts are not impacted by these changes. In fact, these changes to not introduce any functional differences to the EOS EVM Contract. The fixes are localized to the behavior of the EOS EVM Node and also the EOS EVM RPC that depends on the state generated by the EOS EVM Node. However, due to changes to historical block hashes that could be introduced by this bug fix, any clients that depended on block hash values retrieved from the EOS EVM RPC prior to this release will need to investigate how changes to the block hashes may impact their operations.
Improvements to EOS EVM RPC
PRs
The results of eth_getLogs will now return correct results if the null topic is specified. There is still a known issue remaining with the results of eth_getLogs when a non-null topic is specified. That issue is tracked in #394.
EOS EVM RPC will reject eth_sendRawTransaction and eth_sendTransaction requests since these mutating requests and EOS EVM RPC is only designed to handle read requests for now. The eth_sendRawTransaction request is instead handled by TX-Wrapper. EOS EVM RPC will additionally reject eth_gasPrice requests since it does not currently support it; the eth_gasPrice requests should instead go to TX-Wrapper which is built to properly handle those requests for the EOS EVM network.
TX-Wrapper
Support multiple Leap endpoints
The EOS_RPC variable in the .env file which configures TX-Wrapper can now support multiple Leap endpoints separated by |. This allows for a deployment to have higher availability by falling back to other Leap nodes if the primary one becomes unavailable.
Building, compatibility, and upgrading
Building
The README in the eos-evm repository contains instructions on how to build the components.
Compatibility and upgrading
Since there were no functional changes introduced to the EOS EVM Contract with this release, there is no need to upgrade the contract from v0.4.0 (or even v0.4.0-rc1) to v0.4.1. However, if an upgrade is desired, it is as simple as doing a setcode and setabi with the new WASM and ABI files, respectively.
If this version is replacing an existing v0.4.0-rc1 deployment, then reindexing of the EOS EVM Node and RPC is required to resolve a bug with the fork handling which may have caused invalid block hashes to be reported by the RPC. If this version is replacing an existing v0.4.0 deployment, then EOS EVM Node and EOS EVM RPC programs can simply be replaced and restarted.
Further details on changes since last release
Contributors
Special thanks to the contributors that submitted patches for this release:
Full list of changes since last release
Due to a late tag of the official v0.4.0 release which was waiting on some renaming within the repository prior to open sourcing, and the fact that v0.4.0-rc1 was the version of the Contract and other components that was initially deployed to the EOS mainnet, the list below also includes PRs that were merged in after the v0.4.0-rc1 tag but before the v0.4.0 tag. This is an exceptional situation and going forward only one changelog comparison should be necessary for each release.
PRs
- (390) health_helper initial commit
- (388) Fix eth_getLogs result for null topic
- (385) Nginx proxy update
- (441) Fix leap fork handling in block_conversion_plugin
- (430) Prevent calls to eth_sendRawTransaction and eth_gasPrice
- (412) update flask_proxy
- (431) Implement graceful shutdown for tx_wrapper
- (414) Remove debug access_log
- (443) remove unused (and removed in Leap's
main) WAVM header from contract tests - (446) script tweaks
- (447) support multiple endpoints in tx_wrapper
- (459) Update README.md
- (485) Update silkworm
- (489) Bump version to 0.4.1
- (491) proxy cors
- (490) Repo cleanup and EOS EVM rename
- (500) Add MIT license for contract
- (502) Bring changes from 0.4-hotfix into release/0.4 branch
- (506) add missing nginx log settings
Full Changelog from v0.4.0: v0.4.0...v0.4.1
Full Changelog from v0.4.0-rc1: v0.4.0-rc1...v0.4.1
Contributors
Assets 2
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:
- EOS EVM Contract
- EOS EVM Node and RPC
- 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. 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, 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 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 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.
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, ther...