omni / tokenbridge-contracts

Smart contracts for TokenBridge
http://docs.tokenbridge.net
GNU General Public License v3.0
230 stars 227 forks source link
bridge bridge-validators solidity

Join the chat at https://gitter.im/poanetwork/poa-bridge Build Status Coverage Status

POA Bridge Smart Contracts

These contracts provide the core functionality for the POA bridge. They implement the logic to relay assests between two EVM-based blockchain networks. The contracts collect bridge validator's signatures to approve and facilitate relay operations.

The POA bridge smart contracts are intended to work with the bridge process implemented on NodeJS. Please refer to the bridge process documentation to configure and deploy the bridge.

Bridge Overview

The POA Bridge allows users to transfer assets between two chains in the Ethereum ecosystem. It is composed of several elements which are located in different POA Network repositories:

Bridge Elements

  1. Solidity smart contracts, contained in this repository.
  2. Token Bridge. A NodeJS oracle responsible for listening to events and sending transactions to authorize asset transfers.
  3. Bridge UI Application. A DApp interface to transfer tokens and coins between chains.
  4. Bridge Monitor. A tool for checking balances and unprocessed events in bridged networks.
  5. Bridge Deployment Playbooks. Manages configuration instructions for remote deployments.

Bridge Smart Contracts Summary

Operations

Currently, the contracts support four types of relay operations:

Components

The POA bridge contracts consist of several components:

Bridge Roles and Responsibilities

Responsibilities and roles of the bridge:

Usage

There are two ways to deploy contracts:

Deployment with NodeJS

Install Dependencies

npm install

Deploy

Please read the README.md in the deploy folder for instructions and .env file configuration

Test

npm test

Run coverage tests

npm run coverage

The results can be found in the coverage directory.

Flatten

Fattened contracts can be used to verify the contract code in a block explorer like BlockScout or Etherscan. The following command will prepare flattened version of the contracts:

npm run flatten

The flattened contracts can be found in the flats directory.

Deployment in the Docker environment

Docker and Docker Compose can be used to deploy contracts without NodeJS installed on the system. If you are on Linux, we recommend you create a docker group and add your user to it, so that you can use the CLI without sudo.

Prepare the docker container

docker-compose up --build

Note: The container must be rebuilt every time the code in a contract or deployment script is changed.

Deploy the contracts

  1. Create the .env file in the deploy directory as described in the deployment README.md.
  2. Run deployment process:
    docker-compose run bridge-contracts deploy.sh

    or with Linux:

    ./deploy.sh

Copy flatten sources (if needed)

  1. Discover the container name:
    docker-compose images bridge-contracts
  2. In the following command, use the container name to copy the flattened contracts code to the current working directory. The contracts will be located in the flats directory.
    docker cp name-of-your-container:/contracts/flats ./

Test contract and run coverage (if needed)

$ docker-compose run bridge-contracts bash
$ npm test
$ npm run coverage

Shutdown the container

If the container is no longer needed, it can be shutdown:

docker-compose down

Gas Consumption

The GAS_CONSUMPTION file includes Min, Max, and Avg gas consumption figures for contracts associated with each bridge mode.

Reward Management

The REWARD_MANAGEMENT file includes information on how rewards are distributed among the validators on each bridge mode.

Testing environment

To test the bridge scripts in ERC20-to-ERC20 mode on a testnet like Sokol or Kovan, you must deploy an ERC20 token to the foreign network. This can be done by running the following command:

cd deploy
node testenv-deploy.js token

or with Docker:

./deploy.sh token

Contributing

See the CONTRIBUTING document for contribution, testing and pull request protocol.

License

License: GPL v3.0

This project is licensed under the GNU General Public License v3.0. See the LICENSE file for details.