Bridge for the EVM compatible chains for ERC20 tokens

• The bridge is currently available and deployed on the Sepolia and Mumbai chains.

• Bridge supports ERC20 Permits (EIP2612)

• Related projects EVMBridge Client and EVMBridge Validator

Table of Contents

• Table of Contents
• Overview
• Deployments
• Bridge structure
  • Bridge parts
  • Bridge order
  • NatSpec
  • Bidirectional
• User flow diagram
• Install
• Usage
• .ENV file
• Deploy scripts
• Notes

Overview

The Bridge smart contract provides a bidirectional transfer of ERC20 tokens between EVM-compatible chains. This means that users can move their tokens from Chain A to Chain B and vice versa with ease. Additionally, the Bridge supports the ERC20 Permit standard (ERC2612), enabling gasless transactions by pre-approving token transfers. With the Bridge, users have greater flexibility and control over their tokens, eliminating the need to rely on centralized exchanges or custodians for transfers between chains.

The contracts in this project are used by the EVMBridge Client. You can use the client to visualize the interaction with the bridge. A guide on how to interact with the client can be found in the respective project.

Deployments by EVM Chain

Network	Bridge	ERC20 Safe	Validator
Ethereum Sepolia	0xce56e2D1e03e653bc95F113177A2Be6002068B7E	0x268653b20B3a3aE011A42d2b0D6b9F97eC42ca2d	0xb564990E0fD557345f4e87F10ECA0F641a557671
Polygon Mumbai	0xce56e2D1e03e653bc95F113177A2Be6002068B7E	0x268653b20B3a3aE011A42d2b0D6b9F97eC42ca2d	0xb564990E0fD557345f4e87F10ECA0F641a557671

Bridge structure

Bridge consists of 3 main parts:

• Bridge - The main contract contains basic functions such as deposit, release, withdraw, and burn, along with their respective events. The Bridge contract does not contain the logic of locking or transferring assets. Instead, it simply wraps all the functions from the Validator and ERC20Safe contracts and calls them in the correct order (i.e. verifying the signature before releasing tokens). Some validations are performed before calling Bridge functions, such as checking that the Validator and ERC20Safe contracts are set.
• ERC20 Safe Handler - The contract is built on top of ERC20Safe and performs all actions related to the token bridging. It contains all necessary mappings with the information about tokens that go through the contract. This contract is responsible for token wrapping.
• Validator - The contract is responsible for verifying signatures from the trusted validator using EIP712

Each contract implements its respective interface, so you can implement the logic of the bridge on your own.

Order of the contracts

The order of the contracts is as follows:

1. Bridge is deployed
2. ERC20 Safe Handler is deployed with Bridge address as the constructor args.
3. Validator deployed
4. Bridge sets ERC20 Safe Handler address
5. Bridge sets Validator address

If the Validator or ERC20 Safe are not set, users will not be able to use the bridge.

NatSpec

❗All of the contracts in this project have NatSpec comments, providing more detailed information about their functionality. For more specific information about a function's performance, please refer to the relevant contract.

Bidirectional

❗❗The EVMBridge contract works bidirectionally, allowing assets to be transferred between two EVM-compatible blockchains. This means that users can transfer assets from one chain to the other and vice versa.

User Flow Diagram

Install

git clone https://github.com/joYyHack/EVMBridge.git
npm install
npx hardhat clean
npx hardhat compile

Usage

To run hardhat tests written in typescript:

npx hardhat test

To run hardhat coverage:

npx hardhat coverage --config ./hardhat-coverage.config.ts

.ENV file

In order to deploy contracts to the EVM network or verify them, you need to set up the .env file with the specified API keys and private keys. Here is an example .env file:

IS_ENV_SET=false

ALCHEMY_SEPOLIA_API_KEY="api-key"
ALCHEMY_MUMBAI_API_KEY="api-key"

ALICE_PRIV_KEY="priv-key"
BRIDGE_OWNER_PRIV_KEY="priv-key"
VALIDATOR_OWNER_PRIV_KEY="priv-key"

ETHEREUM_ETHERSCAN_API_KEY="api-key"
POLYGON_ETHERSCAN_API_KEY="api-key"

If you have set the .env file don't forget to switch IS_ENV_SET to true

Deploy

To deploy Bridge with all dependencies:

npx hardhat run .\scripts\deploy.ts

To deploy ERC20 token and ERC20 permit token:

npx hardhat run .\scripts\deployERC20.ts

Notes

• Custom errors are not used in the contracts because require provided more clear way of writing code (in my opinion). To use custom errors some if condition must be provided.
• The Bridge contract supports ERC20 Permits if the contract implements the EIP165 interface and if the 0x9d8ff7da selector is supported.