EOS EVM Bridge Contracts v0.2.0

This release of EOS EVM Bridge Contracts enhances the bridge contract to allow upon first deployment for the bridge contract to be associated with different EVM account and different gas token other than default values of eosio.evm and the native EOS token, respectively. It also allows admins to change the gas limits for the underlying EVM transactions generated by the bridge contract.

Changes

init action

The init action initializes the contract using the specified values for the EVM Contract account name and the EOS symbol (with precision) that is used as the gas token. Once these two parameters are set for the contract, they are immutable and cannot be changed again for the remainder of the contract.

The init action also takes two parameters to set the initial gas limits: one to use for EVM transactions that deploy a new proxy contract for a newly registered token; and, the second to use for EVM transactions that move tokens from the EOS Native environment to the EOS EVM environment.

Theinit action must be called before registering any token. The init action can only be called once during the lifetime of the contract.

setgaslimit action

While the init action cannot be called more than once, the two gas limits specified in the init action can be modified as many times as desired using the setgaslimit action.

Building, compatibility, and upgrading

Building

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

Upgrading

If a previous version of EOS EVM Bridge Contracts was already deployed, then immediately after upgrading to this version, the init action must be called using the default values for the EVM Contract account name (eosio.evm) and the gas token symbol (EOS with a precision of 4). The two gas limit values are allowed to be any valid value desired.

Until the init action is called, existing functionality may stop functioning. So it is recommended to call the init action immediately after the setcode and setabi actions that upgrade the contract within the same atomic transaction. After the init action is called, future upgrades of the contract should not call the init action again.

Further details on changes since last release

Contributors

• @arhag
• @taokayan
• @spoonincode

Full list of changes since last release

PRs

• (27) [0.1->main] Update README to prescribed particular solcjs version
• (30) set inline action size to 4KB in tests
• (34) [0.1->main] add unregtoken for emergency purpose
• (36) use leap-dev from 5.0.x release; update README; upload builddir as artifact
• (41) configurable to support a different gas token
• (44) init & setgaslimit action
• (51)[0.2] use spring in cicd
• (50)[0.2] Bump 0.2.0 version

Full Changelog: v0.1.1...v0.2.0

EOS EVM Bridge Contracts v0.2.0-rc1

Introduction

This release enhances the bridge contract to allow upon first deployment for the bridge contract to be associated with different EVM account and different gas token other than default values of eosio.evm and the native EOS token, respectively. It also allows admins to change the gas limits for the underlying EVM transactions generated by the bridge contract.

Changes

init action

The init action initializes the contract using the specified values for the EVM Contract account name and the EOS symbol (with precision) that is used as the gas token. Once these two parameters are set for the contract, they are immutable and cannot be changed again for the remainder of the contract.

The init action also takes two parameters to set the initial gas limits: one to use for EVM transactions that deploy a new proxy contract for a newly registered token; and, the second to use for EVM transactions that move tokens from the EOS Native environment to the EOS EVM environment.

Theinit action must be called before registering any token. The init action can only be called once during the lifetime of the contract.

setgaslimit action

While the init action cannot be called more than once, the two gas limits specified in the init action can be modified as many times as desired using the setgaslimit action.

Building, compatibility, and upgrading

Building

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

Upgrading

If a previous version of EOS EVM Bridge Contracts was already deployed, then immediately after upgrading to this version, the init action must be called using the default values for the EVM Contract account name (eosio.evm) and the gas token symbol (EOS with a precision of 4). The two gas limit values are allowed to be any valid value desired.

Until the init action is called, existing functionality may stop functioning. So it is recommended to call the init action immediately after the setcode and setabi actions that upgrade the contract within the same atomic transaction. After the init action is called, future upgrades of the contract should not call the init action again.

Further details on changes since last release

Contributors

• @arhag
• @taokayan
• @spoonincode

Full list of changes since last release

PRs

• (27) [0.1->main] Update README to prescribed particular solcjs version
• (30) set inline action size to 4KB in tests
• (34) [0.1->main] add unregtoken for emergency purpose
• (36) use leap-dev from 5.0.x release; update README; upload builddir as artifact
• (41) configurable to support a different gas token
• (44) init & setgaslimit action

Full Changelog: v0.1.1...v0.2.0-rc1

EOS EVM Bridge Contracts v0.1.1

This patch release introduces the new action, unregtoken, in order to void erroneous or problematic token contracts introduced. This feature was introduced during a testing phase prior to the release of EOS EVM v0.6.0 when a symbol error was uncovered related to the initial introduction of the EOS EVM USDT Token Contract Address. Using this action, the problematic token contract address was removed and a correct new address was introduced via MSIG prior to official release.

Please note that these updates have been available as part of the release made available to the public on October 16, 2023 and there is no change in user experience or functionality. No user tokens have been impacted.

Changes

unregtoken action

The EOS EVM Bridge Contracts now possess the ability to unregister problematic tokens for emergency situations.

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:

• @taokayan

Full list of changes since last release

PRs

• (32) [0.1] add unregtoken for emergency purpose

Full Changelog: v0.1.0...v0.1.1

EOS EVM Bridge Contracts v0.1.0

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:

• @yarkinwho
• @oschwaldp-oci
• @arhag
• @taokayan
• @elmato

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 releas...

EOS EVM Bridge Contracts v0.1.0-rc1

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:

• @yarkinwho
• @oschwaldp-oci
• @arhag
• @taokayan
• @elmato

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 releas...