Extract general information into root readme (#35)

* Extracted general information from sub-readmes.

* Updated bridge-monitor overview.

* Changed order of sub-repos in Structure.

* Typo.

README.md

@@ -3,7 +3,15 @@
 [![License: LGPL v3.0](https://img.shields.io/badge/License-LGPL%20v3-blue.svg)](https://www.gnu.org/licenses/lgpl-3.0)
 
 # Tokenbridge
-Monorepository for the token bridge.
+Welcome to the **POA Token Bridge** monorepository!
+
+Please note that this repository as a **work in progress**.
+
+## Overview
+
+The POA Token Bridge allows users to transfer assets between two chains in the Ethereum ecosystem. It is composed of several elements which are contained within this monorepository.
+
+For a complete picture of the POA Token Bridge functionality, it is useful to explore each subrepository.
 
 ## Structure
 
@@ -11,7 +19,28 @@ 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 |
+| [Oracle](oracle/README.md) | Oracle responsible for listening to bridge related events and authorizing asset transfers. |
+| [UI](bridge-ui/README.md) | DApp interface to transfer tokens and coins between chains. |
+| [Monitor](bridge-monitor/README.md) | Tool for checking balances and unprocessed events in bridged networks. |
+| [Deployment](deployment-bridge/README.md) | Ansible playbooks for deploying cross-chain bridges. |
+
+Additionally there are [Solidity contracts](https://github.com/poanetwork/poa-bridge-contracts) used to manage bridge validators, collect signatures, and confirm asset relay and disposal.
+
+## 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:
+
+- [x] `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](https://medium.com/poa-network/introducing-poa-bridge-and-poa20-55d8b78058ac)**
+- [x] `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](https://medium.com/poa-network/introducing-the-erc20-to-erc20-tokenbridge-ce266cc1a2d0)**
+- [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)**
 
 ## Building, running, linting & tests
 
@@ -23,7 +52,7 @@ Running linter for all projects:
 
 `yarn lint`
 
-Running run tests for all projects:
+Running tests for all projects:
 
 `yarn test`
 

bridge-monitor/README.md

@@ -1,11 +1,14 @@
-# Bridge Monitor
+# POA Token Bridge / Monitor
-Deployed version:
+Tool for checking balances and unprocessed events in bridged networks.
-https://bridge-monitoring.poa.net/
 
-This tools allows you to spin up node.js server to monitor for 2 contracts on
+## Overview
-Home and Foreign Eth networks to check for balance difference.
+Please refer to the [POA Token Bridge](../README.md) overview first of all.
-On Home network it checks for `HOME_BRIDGE_ADDRESS` balance.
+
-On Foreign network it checks for the `ERC20 token` total supply for the `FOREIGN_BRIDGE_ADDRESS`.
+- Deployed version: https://bridge-monitoring.poa.net/
+
+This tool allows you to spin up a NODE.JS server to monitor for health of the Token Bridge contracts: check for the balance difference, discover inconsistency in the validators list, catch unhandled transactions.
+
+## Examples
 
 Example of an API 
 

bridge-ui/README.md

@@ -1,26 +1,13 @@
-# POA Bridge - User Interface (UI) Application
+# POA Token Bridge / UI
+DApp interface to transfer tokens and coins between chains.
 
 [![Build Status](https://travis-ci.org/poanetwork/bridge-ui.svg?branch=master)](https://travis-ci.org/poanetwork/bridge-ui)
 [![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)
 [![Coverage Status](https://coveralls.io/repos/github/poanetwork/bridge-ui/badge.svg?branch=master)](https://coveralls.io/github/poanetwork/bridge-ui?branch=master)
 [![dependencies Status](https://david-dm.org/poanetwork/bridge-ui/status.svg)](https://david-dm.org/poanetwork/bridge-ui)
 
-Welcome to the POA Bridge! Following is an overview of the POA Bridge and Bridge UI Application, as well as [basic instructions for getting started](#getting-started).
+## Overview
-
+Please refer to the [POA Token Bridge](../README.md) overview first of all.
-## POA 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. 
-
-For a complete picture of the POA Bridge functionality, it is useful to explore each repository.
-
-**Bridge Elements**
-1. Bridge UI Application. A DApp interface to transfer tokens and coins between chains, located in this repository.
-2. [Bridge Smart Contracts](https://github.com/poanetwork/poa-bridge-contracts). Solidity contracts used to manage bridge validators, collect signatures, and confirm asset relay and disposal.
-3. [Token Bridge](https://github.com/poanetwork/token-bridge). The token bridge oracle written in NodeJS.
-4. [Bridge Monitor](https://github.com/poanetwork/bridge-monitor). A tool for checking balances and unprocessed events in bridged networks.
-5. [Bridge Deployment Playbooks](https://github.com/poanetwork/deployment-bridge). Manages configuration instructions for remote deployments and allows you to deploy separate bridge instances for validators.
-
-## Bridge UI Application
 
 The UI provides an intuitive interface for assets transfer between networks running the Bridge smart contracts. Users can connect to a web3 wallet such as [Nifty Wallet](https://github.com/poanetwork/nifty-wallet) or [MetaMask](https://metamask.io/) and complete the transfer through a web browser.
 

deployment-bridge/README.md

@@ -1,18 +1,8 @@
-# Ansible playbooks for deploying cross-chain bridges
+# POA Token Bridge / Deployment
+Ansible playbooks for deploying cross-chain bridges.
 
-## Bridge Overview
+## Overview
-
+Please refer to the [POA Token Bridge](../README.md) overview first of all.
-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. Deployment Playbooks. Configuration management instructions for validator nodes contained in this repository.
-2. [Bridge Smart Contracts](https://github.com/poanetwork/poa-bridge-contracts). Solidity contracts used to manage bridge validators, collect signatures, and confirm asset relay and disposal.
-3. [Token Bridge](https://github.com/poanetwork/token-bridge). The token bridge oracle written in NodeJS.
-4. [Bridge UI Application](https://github.com/poanetwork/bridge-ui). A DApp interface to transfer tokens and coins between chains.
-5. [Bridge Monitor](https://github.com/poanetwork/bridge-monitor). A tool for checking balances and unprocessed events in bridged networks.
-
-
-## Playbooks Overview
 
 These playbooks are designed to automate the deployment process for cross-chain bridges on bridge validator nodes. This process installs the bridge as a service and sets .env configurations on a remote server. Playbooks for the current token-bridge deployment are located in the [bridge-nodejs](bridge-nodejs) folder.
 

oracle/README.md

@@ -1,39 +1,13 @@
+# POA Token Bridge / Oracle
+Oracle responsible for listening to bridge related events and authorizing asset transfers.
 
-# POA Token Bridge - Oracle
+## Overview
+Please refer to the [POA Token Bridge](../README.md) overview first of all.
 
-The Token Bridge Oracle 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:
+The Oracle 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](#how-to-use).
-
-## 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](https://github.com/poanetwork/poa-bridge-contracts). Used to manage bridge validators, collect signatures, and confirm asset relay and disposal.
-3. [Bridge UI Application](https://github.com/poanetwork/bridge-ui). A DApp interface to transfer tokens and coins between chains.
-4. [Bridge Monitor](https://github.com/poanetwork/bridge-monitor). A tool for checking balances and unprocessed events in bridged networks.
-5. [Bridge Deployment Playbooks](https://github.com/poanetwork/deployment-bridge). 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:
-
-- [x] `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](https://medium.com/poa-network/introducing-poa-bridge-and-poa20-55d8b78058ac)**
-- [x] `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](https://medium.com/poa-network/introducing-the-erc20-to-erc20-tokenbridge-ce266cc1a2d0)**
-- [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)**
-
 ## Architecture
 
 ### Native-to-ERC20