Skip to content

EOS EVM Bridge Contracts v0.1.0
Compare
Choose a tag to compare
@stephenpdeos stephenpdeos released this 29 Sep 01:28
· 28 commits to release/0.1 since this release
v0.1.0
bbb40b3
This commit was created on GitHub.com and signed with GitHub’s verified signature. The key has expired.
GPG key ID: 4AEE18F83AFDEB23
Expired
Learn about vigilant mode.

EOS EVM Bridge Contracts is a collection of Solidity and Antelope smart contracts that work together in conjunction with EOS EVM Contract to enable advanced functions of the EOS EVM Trustless Bridge such as moving EOS tokens, starting with USDT, to the EOS EVM as an ERC-20 compatible token and back to the EOS Native network.

Components

ERC-20 Token Contract

The ERC-20 Token Contract is a ERC-20 compatible Solidity contract that works with the EOS EVM Trustless Bridge.

The contract provides the implementation of an ERC-20 token and is meant to be used with Proxy Upgrade Pattern to support multiple ERC-20 token deployments.

The Solidity contract has the following important changes from a typical ERC-20 token contract:

  • The reserved address in the EOS EVM which maps to the eosio.erc2o EOS account is allowed to mint new tokens and call a new function setFee that sets the value of a variable called egressFee.
  • A token transfer (whether via transfer or transferFrom) to EOS EVM reserved addresses is not allowed.
  • A new function bridgeTransfer is introduced to transfer tokens to reserved addresses with an accompanying memo string. In fact, those are the only addresses bridgeTransfer can be used to send tokens to. It will use the new bridge message mechanism of the EOS EVM to signal the ERC-20 Bridge Contract on the EOS side to send an inline transfer action to the EOS account that is mapped to by the specified reserved address. The quantity and memo will also be determined by the values specified in the bridgeTransfer function. Note that unlike a regular transfer, the bridgeTransfer function may expect the call to be done with an accompanying non-zero value; the value must be exactly the quantity of EOS specified by the egressFee variable of the contract, otherwise the function will revert.

ERC-20 Bridge Contract

The ERC-20 Bridge Contract is an Antelope contract that implements most of the logic needed to transport tokens across the EOS EVM Trustless Bridge between the EVM and EOS environments.

The contract allows for tokens on the EOS side such as USDT to be easily registered through regtoken action. The regtoken action will automatically deploy a new Solidity Proxy contract (following the Proxy Upgrade Pattern) that points to the one implementation of the ERC-20 Token Contract that is already deployed on the EOS EVM and tracked by the ERC-20 Bridge Contract. The new contract address of the deployed Proxy contract is tracked by the ERC-20 Token Contract and associated with the EOS token specified in the regtoken action.

That association then allows the ERC-20 Bridge Contract to automatically handle transfers of registered tokens sent to it (aka deposits) assuming the memo also encodes the EVM address that is the intended destination of the token transfer. The ERC-20 Bridge Contract, which should be deployed on the eosio.erc2o account, makes the appropriate call into the EOS EVM Contract under the authority of the reserved address that maps to the eosio.erc2o account to mint new tokens corresponding to the token to be transferred and deliver those new tokens to the destination EVM account specified by the address in the memo.

Additionally, the ERC-20 Bridge Contract is set up to receiver of EOS EVM bridge messages. It will correctly interpret onbridgemsg actions sent to it by the EOS EVM Contract, particularly on behalf of each of the deployed Proxy contract accounts representing distinct tokens on the EOS side, to carry out the withdrawal of the tokens from the EVM back to the EOS side.

Deposit Proxy Contract

The Deposit Proxy Contract is a very simple Antelope contract that receives tokens and then as part of the notification handler for the incoming transfer, it sends an inline transfer action with the same data from the incoming transfer action but to the appropriate destination account. It does also validate that the memo of the incoming transfer action is an EVM address.

The destination account for the inline transfer generated by the Deposit Proxy Contract is determined based on the token being transferred. In the initial release of the Deposit Proxy Contract, the rule is very simple: if the token is EOS, the destination account is eosio.evm; otherwise, the destination account is eosio.erc2o.

The Deposit Proxy Contract allows for unifying the interface needed to deposit tokens into the EOS EVM regardless of which token is transferred. Users do not need to be concerned about details like EOS should be sent to the eosio.evm account while USDT should be sent to the eosio.erc2o account. They can always send their tokens to the eosio.evmin account, which is the account expected to host the Deposit Proxy Contract, and know that it will be routed to the most commonly accepted appropriate place.

Trustless Bridge USDT (EOS) support

The components mentioned above work together to support moving compatible tokens from the EOS side into the EOS EVM and back. Initially, the ERC-20 Bridge Contract will be intentionally restricted such that not just anyone can register a new token with the regtoken action. Only those with the authority of the eosio.erc2o account will be able to register a new token. Upon launch of these Bridge Contracts, the authority will be used at first to register the USDT token. A future release of the Bridge Contracts intend to relax this restriction to allow any compatible token issuer to register their own token.

Deposit USDT (EOS) to an EOS EVM Address

Users can deposit USDT (EOS) from their EOS Accounts and Centralized Exchange Accounts to their EOS EVM Address. While the actions to perform a deposit take place either via a wallet or exchange that supports USDT (EOS), the Trustless Bridge Frontend can be used as an instructional guide for these functions.

Transfers are sent to the EOS EVM Contract Account with a memo to specify the destination EOS EVM Address.

  • EOS EVM Contract Account: eosio.evmin
  • memo: destination EOS EVM Address

Note: The Trustless Bridge requires that the memo field be populated with the destination EOS EVM Address. Failure to specify a memo will cause the transaction to be rejected by the contract with no transfer having taken place.

Note: The destination EOS EVM Address will receive the transferred tokens less an ingress fee denominated in USDT.

Depositing from a Centralized Exchange Account

The ability to deposit USDT (EOS) to an EOS EVM Address directly from a centralized exchange removes user onboarding friction by eliminating the need for a user to possess or create an EOS Account. This is helpful for users unfamiliar with the EOS Account creation process, resource management conventions, and the cost of EOS Account creation.

Depositing from an EOS Account

Users that already possess an EOS Account may deposit USDT (EOS) to an EOS EVM Address by sending to the EOS EVM Contract Account and populating the memo field with the intended destination EVM Address.

Withdraw USDT (EOS) from EOS EVM Address

Users can withdraw USDT (EOS) from their EOS EVM Address to their external EOS accounts by using the bridge with a connected EOS EVM Wallet. Once connected, the user may specify the balance of USDT they wish to send along with the intended destination EOS Account. Use of the memo field for this function varies by the nature of the destination EOS Account.

Note: While the destination EOS Account will receive the full balance of USDT specified in the transfer, an egress fee denominated in EOS is charged for the withdrawal. The egress fee is paid by providing a non-zero value in the EVM transaction that calls the bridgeTransfer function of the ERC-20 compatible token contract for USDT within the EOS EVM. The function will be reverted if the exact egress fee is not provided as value alongside the function call.

Withdrawing to an EOS Account

Withdrawing to an EOS Account only requires the destination EOS Account and a specified balance of tokens to send. The memo field can still be specified and will be included as part of the token transfer, but it is not required.

Withdrawing to a Centralized Exchange Account

Withdrawing to a Centralized Exchange Account requires both the destination EOS Account of the exchange and the appropriate memo field used as a unique identifier within their system of record. Exchanges that support EOS will supply users with both the EOS Account (sometimes referred to as "EOS Address") and memo (sometimes referred to as "EOS memo"). In order to access these values, navigate to the "Receive EOS" option within your exchange of choice.

Note: Both an EOS Account and EOS memo are required to receive tokens. If you send tokens without an EOS memo they may not be credited to your account.

Note: The Trustless Bridge requires that an exchange recognizes inline actions generated within a transaction to successfully withdraw from an EOS EVM Address. Utilizing an exchange that does not support inline actions may lead to a temporary loss of tokens requiring manual intervention by the customer support team of the exchange

Building, compatibility, and upgrading

Building

The README in the evm-bridge-contracts repository contains instructions on how to build the components.

Further details on the initial release

Contributors

Special thanks to the contributors that submitted patches for this release:

Full list of changes since last release

This is the first release of EOS EVM Bridge Contracts, so a GitHub link to compare all changes since a prior release cannot be provided. But the list of all PRs merged in the new repository is provided below.

PRs

  • (2) Some preliminary work
  • (3) Create stub workflow for CICD build and test
  • (4) Improve build process. Update README. Improve efficiency of embedded bytecode.
  • (7) Use bytes instead of static-sized arrays in contract tables
  • (6) Add CI to evm-bridge-contracts - Implement build & test workflow.
  • (13) Install nodejs and solc dependencies in docker base image.
  • (14) Pull in eos evm contract for use in testing in cicd.
  • (5) eosio.erc2o contract implementation
  • (15) Allow set egress fee in EVM end by an action from EOS end
  • (17) withdrawfee and setingressfee
  • (20) Add upgradeto action
  • (21) Add token deposit proxy contract
  • (18) IT framework
  • (22) Address review comments in PR #21
  • (25) [0.1] Update README to prescribed particular solcjs version


Contributors

elmato, arhag, and 3 other contributors
Assets 2
Loading