Merge pull request #77 from 0xPolygon/empieichO-docs-review

Update - 'Plasma' mentions removed

docs/pos/concepts/tokens/pol.md

@@ -68,9 +68,9 @@ Yes, the migration contract includes a feature known as "unmigration." This allo
 
 ## Bridging mechanisms
 
-### How does the modified Plasma Bridge function?
+### How does the modified bridge function?
 
-The Plasma Bridge will undergo modifications, with community approval, to change the native token of Polygon PoS to the new POL token. Specifically, the following changes are being proposed:
+The bridge will undergo modifications, with community approval, to change the native token of Polygon PoS to the new POL token. Specifically, the following changes are being proposed:
 
 - Bridging POL to Polygon PoS: if you bridge POL tokens to Polygon PoS, you will receive
 an equal amount of native tokens (POL) on Polygon PoS.

docs/pos/how-to/snapshots.md

@@ -1,6 +1,6 @@
 When setting up a new sentry, validator, or full node server, it is recommended that you use snapshots for faster syncing without having to sync over the network. Using snapshots will save you several days for both Heimdall and Bor.
 
-For the latest snapshot, please visit [Polygon Chains Snapshots](https://snapshot.polygon.technology/).
+For the latest snapshot, please visit [Polygon Chains Snapshots](https://snapshots.polygon.technology/).
 
 !!! warning "Bor snapshots no longer supported"
     We no longer support bor archive snapshots due to unsustainable data growth.

docs/pos/index.md

@@ -1,7 +1,7 @@
 <div class="flex-figure" markdown="1">
 <div class="flex-figure-left" markdown="1">
 # Polygon PoS
-Polygon PoS is an EVM-compatible, hybrid plasma proof-of-stake sidechain for Ethereum, with high throughput and low costs.
+Polygon PoS is an EVM-compatible, proof-of-stake sidechain for Ethereum, with high throughput and low costs.
 </div>
 <div class="flex-figure-right">
 <img src="../img/pos/pos.svg" class="figure figure-right" alt="" />

docs/pos/operate-node/index.md

@@ -0,0 +1 @@
+Guide to operating a full node.

docs/pos/operate-node/operate/full-node-ansible.md

@@ -0,0 +1,132 @@
+
+An [Ansible playbook](https://docs.ansible.com/ansible/latest/user_guide/playbooks_intro.html) is used to
+configure and manage a full node. 
+
+## Prerequisites
+
+- Install Ansible on your local machine with Python3.x. The setup will not work if you have Python2.x.
+    - To install Ansible with Python 3.x, you can use pip. If you do not have pip on your machine,
+      follow the steps outlined [here](https://pip.pypa.io/en/stable/). Run `pip3 install ansible` to install
+      Ansible.
+- Check the [Polygon PoS Ansible repository](https://github.com/maticnetwork/node-ansible#requirements) for
+  requirements.
+- You will also need to ensure that Go is **not installed** in your environment. You will run into issues if you attempt to set up your full node through Ansible with Go installed as Ansible requires specific packages of Go to be installed.
+- You will also need to make sure that your VM / Machine does not have any previous setups for Polygon Validator or Heimdall or Bor. You will need to delete them as your setup will run into issues.
+
+!!!info
+    Heimdall source enhancements
+
+    The latest Heimdall version, **[v1.0.3](https://github.com/maticnetwork/heimdall/releases/tag/v1.0.3)**, contains a few enhancements.
+    The delay time between the contract events of different validators **has been increased** to ensure that the mempool doesn't get filled quickly in case of a burst of events that could hamper the chain's progress.
+
+    Additionally, the data size **has been restricted in state sync txs to 30Kb (when represented in bytes) and 60Kb (when defined as string)**.
+
+    For example:
+
+    ```bash
+    Data - "abcd1234"
+    Length in string format - 8
+    Hex Byte representation - [171 205 18 52]
+    Length in byte format - 4
+    ```
+
+
+## Full node setup
+
+- Ensure you have access to the remote machine or VM on which the full node is being set up.
+  > Refer to [https://github.com/maticnetwork/node-ansible#setup](https://github.com/maticnetwork/node-ansible#setup) for more details.
+- Clone the [https://github.com/maticnetwork/node-ansible](https://github.com/maticnetwork/node-ansible) repository.
+- Navigate into the node-ansible folder: `cd node-ansible`
+- Edit the `inventory.yml` file and insert your IP(s) in the `sentry->hosts` section.
+  > Refer to [https://github.com/maticnetwork/node-ansible#inventory](https://github.com/maticnetwork/node-ansible#inventory) for more details.
+- Check if the remote machine is reachable by running: `ansible sentry -m ping`
+- To test if the correct machine is configured, run the following command:
+
+  ```bash
+  # Mainnet:
+  ansible-playbook playbooks/network.yml --extra-var="bor_version=v1.0.0 heimdall_version=v1.0.3 network=mainnet node_type=sentry" --list-hosts
+
+  # Testnet:
+  ansible-playbook playbooks/network.yml --extra-var="bor_version=v1.1.0 heimdall_version=v1.0.3 network=mumbai node_type=sentry" --list-hosts
+  ```
+
+  <img src={useBaseUrl("img/network/full-node-mumbai.png")} />
+
+- Next, set up the full node with this command:
+
+  ```bash
+  # Mainnet:
+  ansible-playbook playbooks/network.yml --extra-var="bor_version=v1.1.0 heimdall_version=v1.0.3 network=mainnet node_type=sentry"
+
+  # Testnet:
+  ansible-playbook playbooks/network.yml --extra-var="bor_version=v1.0.0 heimdall_version=v1.0.3 network=mumbai node_type=sentry"
+  ```
+
+- In case you run into any issues, delete and clean the whole setup using:
+  ```
+  ansible-playbook playbooks/clean.yml
+  ```
+
+- Once you initiate the Ansible playbook, log in to the remote machine.
+
+- Please **ensure that the value of seeds and bootnodes mentioned below is the same value as mentioned in Heimdall and Bor `config.toml` files**. If not, change the values accordingly.
+
+  - Heimdall seed nodes:
+
+    ```bash
+    moniker=<enter unique identifier>
+
+    # Mainnet:
+    seeds="[email protected]:26656,[email protected]:26656,[email protected]:26656,[email protected]:26656,[email protected]:26656"
+
+    # Testnet:
+    seeds="[email protected]:26656,[email protected]:26656,[email protected]:26656"
+    ```
+  - Bootnodes:
+
+    ```bash
+    # Mainnet:
+    bootnode ["enode://b8f1cc9c5d4403703fbf377116469667d2b1823c0daf16b7250aa576bacf399e42c3930ccfcb02c5df6879565a2b8931335565f0e8d3f8e72385ecf4a4bf160a@3.36.224.80:30303", "enode://8729e0c825f3d9cad382555f3e46dcff21af323e89025a0e6312df541f4a9e73abfa562d64906f5e59c51fe6f0501b3e61b07979606c56329c020ed739910759@54.194.245.5:30303"]
+
+    # Testnet:
+    bootnodes ["enode://bdcd4786a616a853b8a041f53496d853c68d99d54ff305615cd91c03cd56895e0a7f6e9f35dbf89131044e2114a9a782b792b5661e3aff07faf125a98606a071@43.200.206.40:30303", "enode://209aaf7ed549cf4a5700fd833da25413f80a1248bd3aa7fe2a87203e3f7b236dd729579e5c8df61c97bf508281bae4969d6de76a7393bcbd04a0af70270333b3@54.216.248.9:30303"]
+    ```
+
+- To check if Heimdall is synced
+    - On the remote machine/VM, run `curl localhost:26657/status`
+    - In the output, `catching_up` value should be `false`
+
+- Once Heimdall is synced, run
+    - `sudo service bor start`
+
+You have successfully set up a full node with Ansible.
+
+!!!note
+
+    If Bor presents an error of permission to data, run this command to make the Bor user the owner of the Bor files:
+
+    ```bash
+    sudo chown bor /var/lib/bor
+    ```
+
+## Logs
+
+Logs can be managed by the `journalctl` linux tool. Here is a tutorial for advanced usage: [How To Use Journalctl to View and Manipulate Systemd Logs](https://www.digitalocean.com/community/tutorials/how-to-use-journalctl-to-view-and-manipulate-systemd-logs).
+
+**Check Heimdall node logs**
+
+```bash
+journalctl -u heimdalld.service -f
+```
+
+**Check Bor Rest-server logs**
+
+```bash
+journalctl -u bor.service -f
+```
+
+## Ports and Firewall Setup
+
+Open ports 22, 26656 and 30303 to world (0.0.0.0/0) on sentry node firewall.
+
+You can use VPN to restrict access for port 22 as per your requirement and security guidelines.

docs/pos/operate-node/operate/full-node-binaries.md

@@ -0,0 +1,176 @@
+
+This deployment guide walks you through starting and running a full node through various methods. For the system requirements, see the [Minimum Technical Requirements](../validator/validator-node-system-requirements.md) guide.
+
+!!!tip Snapshots
+
+    Steps in these guide involve waiting for the Heimdall and Bor services to fully sync. This process takes several days to complete.
+
+    Please use snapshots for faster syncing without having to sync over the network. For detailed instructions, see [<ins>Snapshot Instructions for Heimdall and Bor</ins>](../../how-to/snapshots.md).
+
+    For snapshot download links, see the [<ins>Polygon Chains Snapshots</ins>](https://snapshots.polygon.technology/) page.
+
+
+## Overview
+
+- Prepare the machine
+- Install Heimdall and Bor binaries on the full node machine
+- Set up Heimdall and Bor services on the full node machine
+- Configure the full node machine
+- Start the full node machine
+- Check node health with the community
+
+!!!note
+
+    You have to follow the exact outlined sequence of actions, otherwise you will run into issues.
+
+
+### Install `build-essential`
+
+This is **required** for your full node. In order to install, run the below command:
+
+```bash
+sudo apt-get update
+sudo apt-get install build-essential
+```
+
+## Install Binaries
+
+Polygon node consists of 2 layers: Heimdall and Bor. Heimdall is a tendermint fork that monitors contracts in parallel with the Ethereum network. Bor is basically a Geth fork that generates blocks shuffled by Heimdall nodes.
+
+Both binaries must be installed and run in the correct order to function properly.
+
+### Heimdall
+
+Install the latest version of Heimdall and related services. Make sure you checkout to the correct [release version](https://github.com/maticnetwork/heimdall/releases). Note that the latest version, [Heimdall v1.0.3](https://github.com/maticnetwork/heimdall/releases/tag/v1.0.3), contains enhancements such as:
+1. Restricting data size in state sync txs to:
+    * **30Kb** when represented in **bytes**
+    * **60Kb** when represented as **string**
+2. Increasing the **delay time** between the contract events of different validators to ensure that the mempool doesn't get filled very quickly in case of a burst of events which can hamper the progress of the chain.
+
+The following example shows how the data size is restricted:
+
+```
+Data - "abcd1234"
+Length in string format - 8
+Hex Byte representation - [171 205 18 52]
+Length in byte format - 4
+```
+
+To install **Heimdall**, run the below commands:
+
+```bash
+curl -L https://raw.githubusercontent.com/maticnetwork/install/main/heimdall.sh | bash -s -- <heimdall_version> <network_type> <node_type>
+```
+
+**heimdall_version**: `valid v1.0+ release tag from https://github.com/maticnetwork/heimdall/releases`
+**network_type**: `mainnet` and `mumbai`
+**node_type**: `sentry`
+
+That will install the `heimdalld` and `heimdallcli` binaries. Verify the installation by checking the Heimdall version on your machine:
+
+```bash
+heimdalld version --long
+```
+
+### Configure heimdall seeds (Mainnet)
+
+```bash
+sed -i 's|^seeds =.*|seeds = "[email protected]:26656,[email protected]:26656,[email protected]:26656,[email protected]:26656,[email protected]:26656"|g' /var/lib/heimdall/config/config.toml
+chown heimdall /var/lib/heimdall
+```
+
+### Configure heimdall seeds (Mumbai)
+
+```bash
+sed -i 's|^seeds =.*|seeds = "[email protected]:26656,[email protected]:26656,[email protected]:26656"|g' /var/lib/heimdall/config/config.toml
+chown heimdall /var/lib/heimdall
+```
+
+### Bor install
+
+Install the latest version of Bor, based on valid v1.0+ [released version](https://github.com/maticnetwork/bor/releases).
+
+```bash
+curl -L https://raw.githubusercontent.com/maticnetwork/install/main/bor.sh | bash -s -- <bor_version> <network_type> <node_type>
+```
+
+**bor_version**: `valid v1.0+ release tag from https://github.com/maticnetwork/bor/releases`
+**network_type**: `mainnet` and `mumbai`
+**node_type**: `sentry`
+
+That will install the `bor` binary. Verify the installation by checking the Bor version on your machine:
+
+```bash
+bor version
+```
+
+### Configure bor seeds (mainnet)
+
+```bash
+sed -i 's|.*\[p2p.discovery\]|  \[p2p.discovery\] |g' /var/lib/bor/config.toml
+sed -i 's|.*bootnodes =.*|    bootnodes = ["enode://b8f1cc9c5d4403703fbf377116469667d2b1823c0daf16b7250aa576bacf399e42c3930ccfcb02c5df6879565a2b8931335565f0e8d3f8e72385ecf4a4bf160a@3.36.224.80:30303", "enode://8729e0c825f3d9cad382555f3e46dcff21af323e89025a0e6312df541f4a9e73abfa562d64906f5e59c51fe6f0501b3e61b07979606c56329c020ed739910759@54.194.245.5:30303"]|g' /var/lib/bor/config.toml
+chown bor /var/lib/bor
+```
+
+### Configure bor seeds (mumbai)
+
+```bash
+sed -i 's|.*\[p2p.discovery\]|  \[p2p.discovery\] |g' /var/lib/bor/config.toml
+sed -i 's|.*bootnodes =.*|    bootnodes = ["enode://bdcd4786a616a853b8a041f53496d853c68d99d54ff305615cd91c03cd56895e0a7f6e9f35dbf89131044e2114a9a782b792b5661e3aff07faf125a98606a071@43.200.206.40:30303", "enode://209aaf7ed549cf4a5700fd833da25413f80a1248bd3aa7fe2a87203e3f7b236dd729579e5c8df61c97bf508281bae4969d6de76a7393bcbd04a0af70270333b3@54.216.248.9:30303"]|g' /var/lib/bor/config.toml
+chown bor /var/lib/bor
+```
+
+### Update service config user permission
+
+```bash
+sed -i 's/User=heimdall/User=root/g' /lib/systemd/system/heimdalld.service
+sed -i 's/User=bor/User=root/g' /lib/systemd/system/bor.service
+```
+
+## Start Services
+
+Run the full Heimdall node with these commands on your Sentry Node:
+
+```bash
+sudo service heimdalld start
+```
+
+Now, you need to make sure that **Heimdall is synced** completely, and then only start Bor. If you start Bor without Heimdall syncing completely, you will run into issues frequently.
+
+**To check if Heimdall is synced**
+  1. On the remote machine/VM, run `curl localhost:26657/status`
+  2. In the output, `catching_up` value should be `false`
+
+Once Heimdall is synced, run the below command:
+
+```bash
+sudo service bor start
+```
+
+## Logs
+
+Logs can be managed by the `journalctl` linux tool. Here is a tutorial for advanced usage: [How To Use Journalctl to View and Manipulate Systemd Logs](https://www.digitalocean.com/community/tutorials/how-to-use-journalctl-to-view-and-manipulate-systemd-logs).
+
+**Check Heimdall node logs**
+
+```bash
+journalctl -u heimdalld.service -f
+```
+
+**Check Heimdall Rest-server logs**
+
+```bash
+journalctl -u heimdalld-rest-server.service -f
+```
+
+**Check Bor Rest-server logs**
+
+```bash
+journalctl -u bor.service -f
+```
+
+## Ports and Firewall Setup
+
+Open ports 22, 26656 and 30303 to world (0.0.0.0/0) on sentry node firewall.
+
+You can use VPN to restrict access for port 22 as per your requirement and security guidelines.