Cross Bridge V1

💡

TLDR: Cross Bridge V1 is a trustless peg-in/peg-out bridge that allows users to easily hop between Ethereum (ERC20) and Binance Smart Chain (BEP20). This approach also works with other EVM networks.

Table of Contents

Cross Bridge Introduction

The purpose of Cross Bridge is to create a peg-in/peg-out bridge that will allow users to lock their ERC20 tokens into a smart contract on the Ethereum network and in turn receive an equal amount of BEP20 tokens on Binance Smart Chain.

The system includes several distinct modules:

  1. A set of smart contracts that guarantees the security of the system;
  2. A set of validators that act as the off-chain bridge between smart contracts on Ethereum and Binance Smart Chain;
  3. A web-based decentralized application (dapp) that acts as the interaction point between the user and the system;
  4. And a DevOps infrastructure that allows off-chain services with high availability.

High Level Architecture

Below is a high level architecture of the system. Each component runs in different environments. More specifically, the following environments are utilized:

  1. Ethereum Bridge Smart Contracts
  2. Binance Smart Chain Bridge Smart Contracts
  3. VM Running the Validator Processes
  4. Web Environment

High Level Architecture of Cross Bridge V1
High Level Architecture of Cross Bridge V1

Ethereum Bridge Smart Contracts

A set of smart contracts are deployed to the Ethereum blockchain. The core functionality of this part of the system is to allow users to lock their ERC20 tokens into a secure vault and later unlock them, thus establishing the peg-in/peg-out bridge described earlier. The process of pegging in is described in the diagrams below, however at a basic level it includes a step in which a user deposits any amount of ERC20 tokens into a smart contract via the bridge dapp.

Binance Smart Chain Bridge Smart Contracts

A similar set of smart contracts reside on Binance Smart Chain. The purpose of these contracts is to mint and transfer an equal amount of BEP20 tokens based on the size of the funds locked on the ETH side. That is, if Alice locks 100 ERC20 $TOKENS on Ethereum, an equal amount of 100 BEP20 $TOKENS will be minuted and transferred to Alice's account on Binance Smart Chain.

At the same time, Alice is able to return the full amount or part of the 100 BEP20 $TOKENS and receive back the original locked ERC20 tokens. The smart contract location is transparent and the total balances on both blockchains, ETH and EVM networks, will be visible to the user via the dapp.

Validators

This is the off-chain set of processes that will apply the bridging logic. It a well-known that Ethereum and BSC, although both EVM networks, cannot directly communicate with each other. This implies that the logic of the peg-in/peg-out we have described above cannot be solely performed by just these two environments. We need external, off-chain trusted services that will relay messages from one blockchain to another.

Validators play exactly this role in our system. They utilize event mechanism on both blockchain to accept user requests and relay those requests to the opposite side. This whole process is done via cryptographic communication protocols and can be freely audited by any external party.

Any message from one blockchain to another is executed when a quorum is met. That is, N out of M validators would need to sign the execution of a request before it is be completed. The core involvement is during the following two use cases:

  1. Listening to requests from the Ethereum blockchain. More specifically, each validator listens to a specific event that signifies the intent of a user to lock an amount of ERC20 tokens and mint out BEP20 tokens. The validators would need to complete the second part of that process by triggering the minting of an equal amount of tokens on Binance Smart Chain that would be transferred to the user's wallet.
  2. Listening to events on Binance Smart Chain and triggering the unlocking tokens on the Ethereum blockchain. In essence, users would burn off their BEP20 tokens in order to receive ERC20 tokens back over on Ethereum. (This applies to all EVM networks, not just BSC.)

📌

Note that validators do not have any control over the ERC20 tokens that run through Cross Bridge. They are in a vault (smart contract) that are handled in a trustless manner. The sole purpose of the validator is to relay the intent of a user from one blockchain to another.

Users are not compelled to burn off full amounts of their BEP20 balances to hop back over to ERC20. Cross Bridge also ensures that no user will receive more ERC20 tokens during a peg-out (burn) on Binance Smart Chain. At the same time, it must be made clear that if someone purchases more BEP20 tokens on Binance Smart Chain than they ever had on Ethereum, they are freely able to move those back over to Ethereum during a peg-out. In essence, the ERC20 and BEP20 supplies should always be in balance on both blockchains, thus avoiding double spending or erroneously claiming more tokens than one possesses on either chain during a peg-in/peg-out.

Web Environment (dapp)

This refers to the dapp which users access in order to peg-in/peg-out of ERC20 tokens and other EVM networks. Granular details about the dapp layer of Cross Chain are provided below.

System Requirements

Functional requirements for each part of the system are described below.

Ethereum Bridge Smart Contracts

  • It should securely store ERC20 tokens and not allow any unauthorized access to those tokens;
  • It should be written in a modern version of Solidity;
  • It should use well-tested and audited community-helper smart contracts if needed;
  • It should be upgradeable to allow for future improvements and bug fixes;
  • It should have an owner. That is, certain actions like adding new or removing old validators will need to be done by an owner address;
  • It should be pausable. This means that the owner of the contracts can pause the execution of a critical function if needed;
  • It should follow the best practices and common Solidity design patterns as defined in various sources and official ConsenSys philosophies and guidelines;
  • It should be protected against known attacks and follow security guidelines for writing smart contracts;
  • It should not allow users to send ETH into the Cross Bridge smart contracts that will result in a loss os funds. For the same reason, it should allow the withdrawal of other tokens than ERC20 tokens for which bridges are designed in case users make mistakes (e.g. users sending $TOKENB into a bridge made for $TOKENA);
  • And it should be implemented for gas optimization.

Binance Smart Chain Bridge Smart Contracts

  • It should use the ERC677 specification to digitize the BEP20 tokens;
  • It should prepare signatures for validators that allow a user to receive ERC20 tokens back on ETH;
  • It should be written in a modern version of Solidity;
  • It should use well-tested and audited community-helper smart contracts if needed;
  • It should be upgradeable to allow for future improvements and bug fixes;
  • It should have an owner. That is, certain actions like adding new or removing old validators will need to be done by an owner address;
  • It should be pausable. This means that the owner of the contracts can pause the execution of a critical function if needed;
  • It should follow the best practices and common Solidity design patterns as defined in various sources and official ConsenSys philosophies and guidelines;
  • It should be protected against known attacks and follow security guidelines for writing smart contracts;
  • It should not allow users to send BNB into the Cross Bridge smart contracts that will result in a loss os funds. For the same reason, it should allow the withdrawal of other tokens than BEP20 tokens for which bridges are designed in case users make mistakes (e.g. users sending $TOKENB into a bridge made for $TOKENA);
  • And it should be implemented for gas optimization.

Validators

  • It should be written in Node.js. The choice is purely based on the libraries and the community support that allows a seamless integration with many EVM networks;
  • It should be able to utilize cryptographic material to sign messages;
  • It should listen to events and send transactions to both Ethereum and Binance Smart Chain;
  • It should be highly available such that no requests are missed and if they are then quickly and seamlessly identified and processed;
  • It should be easy to deploy to various environments that are not difficult to run;
  • And it will run as a Docker container.

Web Environment (dapp)

  • It should be publicly accessible on a specific URL;
  • It should be built using modern front-end frameworks such as React;
  • It should be as simple as possible without overcomplicating the user journey;
  • And it should work well with MetaMask on web and Trust Wallet on mobile within reason.

💡

Note that ongoing wallet support is something that we are tackling via Cross Connect. This includes hardware wallet support where possible.

One of the most important parts of the dapp is to show rich data about the status of both blockchains. More specifically, the following information will be needed:

  • The node that is used to send requests;
  • The smart contract addresses of bridge contracts on both blockchains;
  • Corresponding ERC20 and BEP20 smart contract addresses;
  • ERC20 and BEP20 token balances;
  • The amount of ERC20 tokens locked into the bridge's smart contract;
  • And the total amount of BEP20 minted on the Binance Smart Chain bridges. This should be in sync with the previous figure.

📌

There can never be more BEP20 in existence than the amount of ERC20 tokens locked in the bridge's smart contracts.

The Cross Bridge User Journey

Below we present the sequence diagram that shows the steps taken during pegging and unpegging ERC20 tokens.

Ethereum to EVM Network (BSC)

The sequence diagram below illustrates the process of Alice locking 100 ERC20 tokens on the Ethereum blockchain (pegging in) and receiving an equal amount of BEP20 tokens on an EVM Network, in this case Binance Smart Chain. There are intermediary steps that are not depicted in the abstracted sequence diagram below; however, the core steps are clearly illustrated and are as follows:

User Journey from Ethereum to another EVM Network, in this case BSC.
User Journey from Ethereum to another EVM Network, in this case BSC.

  1. Alice visits the dapp using a web3-compatible browser;
  2. Alice connects to an Ethereum RPC node;
  3. The dapp presents a simple UI that Alice can employ to transfer ERC20 tokens into the ETH bridge (she will receive the same amount on the corresponding EVM network);
  4. When Alice clicks transfer (and if she has enough ERC20 tokens), she will be prompted to accept the transfer of her ERC20 tokens into the bridge's smart contract;
  5. While this is occurring, validators listening to blockchain events prepare the process of relaying a mint out request to a corresponding EVM network, in this case BSC;
  6. If proper validator conditions are met then BEP20 tokens will be minted and transferred to Alice's wallet;
  7. Finally, if Alice now switches to the corresponding EVM network in her wallet she should be able to interact with the tokens that have been minted.

EVM Network (BSC) To Ethereum

The sequence diagram below illustrates the process of Alice burning off (pegging out) 100 BEP20 tokens on an EVM network (in this case BSC) and receiving an equal amount of ERC20 tokens on Ethereum. There are intermediary steps that are not depicted in the abstracted sequence diagram below; however, the core steps are clearly illustrated and are as follows:

User Journey from another EVM Network to Ethereum, in this case BSC.
User Journey from another EVM Network to Ethereum, in this case BSC.

  1. Alice visits the dapp using a web3-compatible browser;
  2. Alice connects to an EVM network RPC (in this case BSC);
  3. The dapp recognizes the current blockchain and present a simple UI form containing an input box where Alice can enter the amount of BEP20 tokens she would like to burn on the non-ETH chain and thus receive the ERC20 she locked earlier in the ETH bridge;
  4. Alice enters the amount of BEP20 that she would like to peg out and clicks on Request;
  5. The request will be transmitted to the EVM network chain and the transferAndCall method of the EVM network smart contract. Tokens will be transferred to the bridge smart contract and the requestUnlock function will be called during the same transaction;
  6. The EVM network smart contract will ensure that the BEP20 (or EVM network) tokens are burnt;
  7. Validators will listen to the event emitted from the bridge smart contract and will sign and send a message;
  8. When enough signatures have been sent from validators and quorum met, the EVM network smart contract will emit an event dignifying that anyone can now use the message id and call the unlock function on the ETH bridge smart contract;
  9. The ETH bridge smart contract will receive the signatures and cryptographically verify them;
  10. And finally the locked bridge tokens will be transferred back to Alice (pegged out).