Awesome

POA TokenBridge

The TokenBridge is deployed on specified validator nodes (only nodes whose private keys correspond to addresses specified in the smart contracts) in the network. It connects to two chains via a Remote Procedure Call (RPC) and is responsible for:

• listening to events related to bridge contracts
• sending transactions to authorize asset transfers

Following is an overview of the TokenBridge and instructions for getting started.

POA General Bridge Overview

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

Bridge Elements

1. The TokenBridge contained in this repository.
2. Solidity smart contracts. Used to manage bridge validators, collect signatures, and confirm asset relay and disposal.
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.

Network Definitions

Bridging occurs between two networks.

• Home - or Native - is a network with fast and inexpensive operations. All bridge operations to collect validator confirmations are performed on this side of the bridge.

• Foreign can be any chain; generally it refers to the Ethereum mainnet.

Operational Modes

The POA TokenBridge provides three operational modes:

• Native-to-ERC20 Coins on a Home network can be converted to ERC20-compatible tokens on a Foreign network. Coins are locked on the Home side and the corresponding amount of ERC20 tokens are minted on the Foreign side. When the operation is reversed, tokens are burnt on the Foreign side and unlocked in the Home network. More Information: POA-to-POA20 Bridge
• ERC20-to-ERC20 ERC20-compatible tokens on the Foreign network are locked and minted as ERC20-compatible tokens (ERC677 tokens) on the Home network. When transferred from Home to Foreign, they are burnt on the Home side and unlocked in the Foreign network. This can be considered a form of atomic swap when a user swaps the token "X" in network "A" to the token "Y" in network "B". More Information: ERC20-to-ERC20
• ERC20-to-Native: Pre-existing tokens in the Foreign network are locked and coins are minted in the Home network. In this mode, the Home network consensus engine invokes Parity's Block Reward contract to mint coins per the bridge contract request. More Information: xDai Chain

Architecture

Native-to-ERC20

ERC20-to-ERC20 and ERC20-to-Native

Watcher

A watcher listens for a certain event and creates proper jobs in the queue. These jobs contain the transaction data (without the nonce) and the transaction hash for the related event. The watcher runs on a given frequency, keeping track of the last processed block.

If the watcher observes that the transaction data cannot be prepared, which generally means that the corresponding method of the bridge contract cannot be invoked, it inspects the contract state to identify the potential reason for failure and records this in the logs.

There are three Watchers:

• Signature Request Watcher: Listens to UserRequestForSignature events on the Home network.
• Collected Signatures Watcher: Listens to CollectedSignatures events on the Home network.
• Affirmation Request Watcher: Depends on the bridge mode.
  • Native-to-ERC20: Listens to UserRequestForAffirmation raised by the bridge contract.
  • ERC20-to-ERC20 and ERC20-to-Native: Listens to Transfer events raised by the token contract.

Sender

A sender subscribes to the queue and keeps track of the nonce. It takes jobs from the queue, extracts transaction data, adds the proper nonce, and sends it to the network.

There are two Senders:

• Home Sender: Sends a transaction to the Home network.
• Foreign Sender: Sends a transaction to the Foreign network.

RabbitMQ

RabbitMQ is used to transmit jobs from watchers to senders.

Redis DB

Redis is used to store the number of blocks that were already inspected by watchers, and the NOnce (Number of Operation) which was used previously by the sender to send a transaction.

For more information on the Redis/RabbitMQ requirements, see #90. We also provide useful commands for development.

How to Use

Installation and Deployment

Note: The following steps detail the bridge deployment process for development and testing. For deployment in a production environment we recommend using the Bridge Deployment Playbooks.

Deploy the Bridge Contracts

1. Deploy the bridge contracts

2. Open bridgeDeploymentResults.json or copy the JSON output generated by the bridge contract deployment process.

   Native-to-ERC20 mode example:

   {
       "homeBridge": {
           "address": "0xc60daff55ec5b5ce5c3d2105a77e287ff638c35e",
           "deployedBlockNumber": 123321
       },
       "foreignBridge": {
           "address": "0x3f5ce5fbfe3e9af3971dd833d26ba9b5c936f0be",
           "deployedBlockNumber": 456654,
           "erc677": {
               "address": "0x41a29780309dc2582f080f6af89953be3435679a"
           }
       }
   }
   

   ERC20-to-ERC20 mode example:

   {
       "homeBridge": {
           "address": "0x765a0d90e5a5773deacbd94b2dc941cbb163bdab",
           "deployedBlockNumber": 789987,
           "erc677": {
               "address": "0x269f57f5ae5421d084686f9e353f5b7ee6af54c2"
           }
       },
       "foreignBridge": {
           "address": "0x7ae703ea88b0545eef1f0bf8f91d5276e39be2f7",
           "deployedBlockNumber": 567765
       }
   }
   

Configuration

1. Create a .env file: cp .env.example .env

2. Fill in the required information using the JSON output data. Check the tables with the set of parameters below to see their explanation.

Run the Processes

There are two options to run the TokenBridge processes:

1. Docker containers. This requires Docker and Docker Compose. If you are on Linux, it's also recommended that you create a docker group and add your user to it, so that you can use the CLI without sudo.
2. NodeJs Package Manager (NPM).

Docker

• While running the bridge containers for the first time use VALIDATOR_ADDRESS=<validator address> VALIDATOR_ADDRESS_PRIVATE_KEY=<validator address private key> docker-compose up -d --build
• For further launches use VALIDATOR_ADDRESS=<validator address> VALIDATOR_ADDRESS_PRIVATE_KEY=<validator address private key> docker-compose up --detach

All watcher & sender services launch when docker-compose is called.

Redis and RabbitMQ data are placed in ~/bridge_data directory. In case you need to reset your bridge or setup a new one (with different configuration) you must delete this directory to prevent old data from being read.

Note: To view the Docker logs:

• chdir to the directory containing the docker-compose.yml file used to run the bridge instance
• View the logs : docker-compose logs

NPM

• redis-server starts Redis. redis-cli ping will return a pong if Redis is running.
• rabbitmq-server starts RabbitMQ. Use rabbitmqctl status to check if RabbitMQ is running.
• npm run watcher:signature-request
• npm run watcher:collected-signatures
• npm run watcher:affirmation-request
• npm run sender:home
• npm run sender:foreign

Bridge UI

See the Bridge UI installation instructions to configure and use the optional Bridge UI.

Rollback the Last Processed Block in Redis

If the bridge does not handle an event properly (i.e. a transaction stalls due to a low gas price), the Redis DB can be rolled back. You must identify which watcher needs to re-run. For example, if the validator signatures were collected but the transaction with signatures was not sent to the Foreign network, the collected-signatures watcher must look at the block where the corresponding CollectedSignatures event was raised.

Execute this command in the bridge root directory:

for NPM installation:

bash ./reset-lastBlock.sh <watcher> <block num>

for Docker installation:

docker-compose exec bridge_affirmation bash ./reset-lastBlock.sh <watcher> <block num>

where the watcher could be one of:

• signature-request
• collected-signatures
• affirmation-request

Configuration parameters

Useful Commands for Development

RabbitMQ

Redis

Use redis-cli

Testing

npm test

E2E tests

See the E2E README for instructions.

Notice: for docker-based installations do not forget to add docker-compose exec bridge_affirmation before the test commands listed below.

Native-to-ERC20 Mode Testing

When running the processes, the following commands can be used to test functionality.

• To send deposits to a home contract run node scripts/native_to_erc20/sendHome.js <tx num>, where <tx num> is how many tx will be sent out to deposit.

• To send withdrawals to a foreign contract run node scripts/native_to_erc20/sendForeign.js <tx num>, where <tx num> is how many tx will be sent out to withdraw.

ERC20-to-ERC20 Mode Testing

• To deposit from a Foreign to a Home contract run node scripts/erc20_to_erc20/sendForeign.js <tx num>.

• To make withdrawal to Home from a Foreign contract run node scripts/erc20_to_erc20/sendHome.js <tx num>.

ERC20-to-Native Mode Testing

• To deposit from a Foreign to a Home contract run node scripts/erc20_to_native/sendForeign.js <tx num>.

• To make withdrawal to Home from a Foreign contract run node scripts/erc20_to_native/sendHome.js <tx num>.

Configuration parameters for testing

Contributing

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

License

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

References

• Additional Documentation
• POA20 Bridge FAQ