tokenbridge/README.md

110 lines
4.9 KiB
Markdown
Raw Normal View History

2020-09-02 17:43:48 +03:00
![tokenbridge](https://github.com/poanetwork/tokenbridge/workflows/tokenbridge/badge.svg?branch=master)
[![Gitter](https://badges.gitter.im/poanetwork/poa-bridge.svg)](https://gitter.im/poanetwork/poa-bridge?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
[![License: LGPL v3.0](https://img.shields.io/badge/License-LGPL%20v3-blue.svg)](https://www.gnu.org/licenses/lgpl-3.0)
# Tokenbridge
2019-07-19 10:18:51 +03:00
Welcome to the **POA TokenBridge** monorepository!
Please note that this repository as a **work in progress**.
## Overview
2019-07-19 10:18:51 +03:00
The POA TokenBridge allows users to transfer assets between two chains in the Ethereum ecosystem. It is composed of several elements which are contained within this monorepository.
2019-07-19 10:18:51 +03:00
For a complete picture of the POA TokenBridge functionality, it is useful to explore each subrepository.
## Structure
Sub-repositories maintained within this monorepo are listed below.
| Sub-repository | Description |
| --- | --- |
| [Oracle](oracle/README.md) | Oracle responsible for listening to bridge related events and authorizing asset transfers. |
| [Monitor](monitor/README.md) | Tool for checking balances and unprocessed events in bridged networks. |
| [Deployment](deployment/README.md) | Ansible playbooks for deploying cross-chain bridges. |
| [Oracle-E2E](oracle-e2e/README.md) | End to end tests for the Oracle |
| [Monitor-E2E](monitor-e2e/README.md) | End to end tests for the Monitor |
| [Deployment-E2E](deployment-e2e/README.md) | End to end tests for the Deployment |
| [Commons](commons/README.md) | Interfaces, constants and utilities shared between the sub-repositories |
2019-06-04 11:28:12 +03:00
| [E2E-Commons](e2e-commons/README.md) | Common utilities and configuration used in end to end tests |
2020-06-04 19:15:39 +03:00
| [ALM](alm/README.md) | DApp interface tool for AMB Live Monitoring |
| [Burner-wallet-plugin](burner-wallet-plugin/README.md) | TokenBridge Burner Wallet 2 Plugin |
Additionally there are [Smart Contracts](https://github.com/poanetwork/tokenbridge-contracts) used to manage bridge validators, collect signatures, and confirm asset relay and disposal.
## Available deployments
| **Launched by POA** | **Launched by 3rd parties** |
| ---------- | ---------- |
2019-07-19 10:18:51 +03:00
| [POA20 Bridge](https://bridge.poa.net/) | [Ocean TokenBridge](https://bridge.oceanprotocol.com/) |
| [xDai Bridge](https://dai-bridge.poa.network/) | [Thunder bridge](https://ui.stormdapps.com/) |
2019-07-19 10:18:51 +03:00
| [WETC Bridge](https://wetc.app/) | [Volta TokenBridge](https://vt.volta.bridge.eth.events/) & [DAI bridge to Volta Chain](https://dai.volta.bridge.eth.events/) |
| | [Artis Brige](https://bridge.artis.network/) |
| | [Tenda bridge](https://bridge-mainnet.tenda.network) & [xDai-to-Tenda bridge](https://bridge-xdai.tenda.network/) |
## 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
2019-09-18 22:45:13 +03:00
The POA TokenBridge provides four operational modes:
- [x] `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](https://wiki.parity.io/Block-Reward-Contract.html) to mint coins per the bridge contract request. **More Information: [xDai Chain](https://medium.com/poa-network/poa-network-partners-with-makerdao-on-xdai-chain-the-first-ever-usd-stable-blockchain-65a078c41e6a)**
2019-09-18 22:45:13 +03:00
- [x] `Arbitrary-Message`: Transfer arbitrary data between two networks as so the data could be interpreted as an arbitrary contract method invocation.
## Initializing the monorepository
Clone the repository:
```bash
git clone https://github.com/poanetwork/tokenbridge
```
2021-04-16 12:31:12 +03:00
If there is no need to build docker images for the TokenBridge components (oracle, monitor), initialize submodules, install dependencies, compile the Smart Contracts:
```
yarn initialize
```
Then refer to the corresponding README files to get information about particular TokenBridge component.
## Linting
Running linter for all JS projects:
```
yarn lint
```
## Tests
Running tests for all projects:
```
yarn test
```
2021-04-16 12:31:12 +03:00
Additionally there are end-to-end tests for [Oracle](oracle-e2e/README.md) and [Monitor](monitor-e2e/README.md).
For details on building, running and developing please refer to respective READMEs in sub-repositories.
## Building, running and deploying
Please refer to the instructions in sub-directories.
Consistent variable naming (#198) * Add console.table * First steps in validate script * env rename * Added parameter names * Descriptions * Print and configuration * Added more parameters * Rename gas oracle to gas supplier * More changes * Removed env examples for now * RPC rename * Bridge address rename * More changes * jobs * Renames * Typo * jobs * Changes * jobs * Changes * Monitor changes * jovs * Typo * Changes * REACT_APP_ env prefix * Typo * Rollback changes * Oracle deployment * Defaults * Monitor * Naming * Typo * Typo * Envs * ui deployment * ALl jobs * Vars in ultimate * Lint * Lint * Lint * Another way to add REACT_APP prefixing * Unnecessary mapping * No output timeout * No output timeout * Got rid of ERC20_TOKEN_ADDRESS * Configuration readme * Configuration * Prefixes * timeout * Docs * Docs * docs * docs * docs * Roll back ERC20_TOKEN_ADDRESS for erc-to-erc * Typo * lint * Rollback * ROllback validator * Rollback yarn.lock * dai and wetc update * Rollback ERC20_TOKEN_ADDRESS * erc to native * examples * all jobs * roll back * roll back ERC20_TOKEN_ADDRESS: "0xdbeE25CbE97e4A5CC6c499875774dc7067E9426B" * ui env example * typo * Allow rpc for ultimate * Test * ERC20_TOKEN_ADDRESS rollback * Specify port * React port * All jobs * cosmetics * Values * Restore erc20 token * Rearrange example for easier comparision * Rearrange ultimate for easier comparision * Rearrange for easier comparision * Refactor * Conditional app styles * Loading environment variables in react app * Add missing vars for UI in wetc and dai * Bring back test parameters readme * Readme for monitor vars * Reading environment variables in e2e-commons (#207)
2019-09-13 10:11:38 +03:00
Configuration details are available [here](./CONFIGURATION.md).
## Contributing
See the [CONTRIBUTING](CONTRIBUTING.md) 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](LICENSE) file for details.
## References
2019-05-06 16:30:44 +03:00
2020-09-01 22:56:54 +03:00
* [TokenBridge Documentation](https://docs.tokenbridge.net/)