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

update POS docs, all intros done

docs/pos/architecture/index.md

@@ -1,11 +1,11 @@
 # Architecture
 
+This section provides architectural details of Polygon PoS from a node perspective. 
+
 Due to the proof-of-stake consensus, Polygon PoS consists of a consensus layer called Heimdall and execution layer called Bor.
 
 Nodes on Polygon are therefore designed with a two-layer implementation represented by Bor (the block producer layer) and Heimdall (the validator layer).
 
-This section provides architectural details of Polygon PoS. 
-
 In particular, and on the execution client side, it delineates on snapshots and state syncing, network configurations, and frequently used commands when running PoS nodes.
 
 On the consesus client side, one finds descriptions on how Heimdall handles; authentication of account addresses, management of validators' keys, management of gas limits, enhancement of transaction verifications, balance transfers, staking and general chain management.   

docs/pos/get-started/building-on-polygon.md

@@ -22,15 +22,15 @@ In order to be a validator on the Polygon Network, you need to:
 
 ## Wallets
 
-To interact with the Polygon Network, you need to have an Ethereum-based wallet because Polygon runs on Ethereum Virtual Machine (EVM). You can choose to set up a [Metamask](https://github.com/0xPolygon/wiki/blob/master/docs/tools/wallets/metamask/overview.md) or [Arkane](https://github.com/0xPolygon/wiki/blob/master/docs/develop/wallets/arkane/intro_arkane.md) Wallet. More on wallet-related information and why you need one can be found in our [wallet documentation](https://docs.polygon.technology/docs/develop/wallets/getting-started).
+To interact with the Polygon Network, you need to have an Ethereum-based wallet because Polygon runs on Ethereum Virtual Machine (EVM). You can choose to set up a [Metamask](https://github.com/0xPolygon/wiki/blob/master/docs/tools/wallets/metamask/overview.md) or Arkane Wallet.
 
 ## Smart contracts
 
-Polygon supports many services you can use to test, compile, debug, and deploy decentralized applications onto the Polygon Network. These include deployment using [thirdweb](https://github.com/0xPolygon/wiki/blob/master/docs/develop/thirdweb.md), [Alchemy](https://github.com/0xPolygon/wiki/blob/master/docs/develop/alchemy.md), [Chainstack](https://github.com/0xPolygon/wiki/blob/master/docs/develop/chainstack.md), [QuickNode](https://github.com/0xPolygon/wiki/blob/master/docs/develop/quicknode.md), [Remix](https://github.com/0xPolygon/wiki/blob/master/docs/develop/remix.md), [Truffle](https://github.com/0xPolygon/wiki/blob/master/docs/develop/truffle.md), [Hardhat](https://github.com/0xPolygon/wiki/blob/master/docs/develop/hardhat.md), and [Replit](https://github.com/0xPolygon/wiki/blob/master/docs/develop/replit.md).
+Polygon supports many services you can use to test, compile, debug, and deploy decentralized applications onto the Polygon Network. These include deployment using thirdweb, Alchemy, Chainstack, QuickNode, Remix, Truffle, Hardhat, and Replit.
 
 ## Connecting to Polygon
 
-You can add Polygon to MetaMask or directly use Arkane, which allows you to connect to Polygon using [RPC](https://docs.polygon.technology/docs/tools/wallets/metamask/config-polygon-on-metamask/).
+You can add Polygon to MetaMask or directly use Arkane, which allows you to connect to Polygon using RPC.
 
 In order to connect with the Polygon network to read blockchain information, we recommend using the Alchemy SDK.
 
@@ -71,11 +71,11 @@ Suppose you have no prior experience building decentralized applications (dApps)
 - [Web3.js](https://www.dappuniversity.com/articles/web3-js-intro)
 - [Ethers.js](https://docs.ethers.io/v5/)
 - [thirdweb](https://portal.thirdweb.com)
-- [Remix](https://docs.polygon.technology/docs/develop/remix/)
-- [Truffle](https://docs.polygon.technology/docs/develop/truffle)
-- [Metamask](https://docs.polygon.technology/docs/tools/wallets/metamask/overview)
-- [Arkane](https://docs.polygon.technology/docs/develop/wallets/arkane/intro)
-- [Develop a dApp using Fauna, Polygon and React](https://docs.polygon.technology/docs/develop/dapp-fauna-polygon-react)
+- Remix
+- Truffle
+- Metamask
+- Arkane
+- Develop a dApp using Fauna, Polygon and React
 
 ## Already have a dApp?
 

docs/pos/how-to/bridging/index.md

@@ -0,0 +1,14 @@
+This subsection contains guides on how to deploy bridge smart contracts to enable transfer of assets between the Polygon PoS and Ethereum, as well as setting up a communication channel between an L2 chain and an L1 network.
+
+The subsection gives details on how to enable reading state data in the Polygon chain as though it is read in the Ethereum network. This is enabled through a process that involves deployment of a `Sender contract` and a `Receiver contract`, mapping the Sender with the Receiver, and finally sending and receiving data.
+
+Sending data from Polygon to Ethereum is different from the converse, which is discussed above. The `MATIC to Ethereum` subsection outlines how to setup such a bridge, and provides a tutorial on how to achieve the transfer.
+
+The L1-L2 communication sub-subsection discusses how to achieve `State transfer` and `State syncing`.
+
+
+
+
+
+
+

docs/pos/how-to/bridging/l1-l2-communication/index.md

@@ -0,0 +1,5 @@
+This sub-subsection provides technical details on how to achieve `State transfer` and `State syncing`.
+
+The `State transfer` sub-subsection provides details of all requirements, contracts and functions that will be called to execute a State transfer.
+
+The subsequent `Bridging with FxPortal` sub-subsection contains a tutorial implementing State syncing using FxPortal, which is a powerful yet simple implementation of Polygon's State syncing mechanism relying on a centralized mapping of a party's tokens on one chain to their contract on the other.

docs/pos/how-to/operating/access-node.md

@@ -4,7 +4,7 @@ The majority of developers use a node provider, or a third-party external servic
 
 !!! tip Recommended
 
-    New developers on the Polygon network can use Alchemy as their node provider because of it's reliability, scale, and [Enhanced APIs](https://docs.alchemy.com/reference/enhanced-apis-overview).
+    New developers on the Polygon network can use Alchemy as their node provider because of its reliability, scalability, and [Enhanced APIs](https://docs.alchemy.com/reference/enhanced-apis-overview).
 
 ## Send your first blockchain request
 

docs/pos/how-to/operating/full-node/docker.md

@@ -83,34 +83,35 @@ With Docker running and storage prepared, it's time to set up Heimdall:
 
 1. Test Heimdall with Docker:
 
-   ```bash
-   docker run -it 0xpolygon/heimdall:1.0.3 heimdallcli version
-   ```
+      ```bash
+         docker run -it 0xpolygon/heimdall:1.0.3 heimdallcli version
+      ```
 
-2. Initialize Heimdall's home directory:
+   2. Initialize Heimdall's home directory:
 
-   ```bash
-   docker run -v /mnt/data/heimdall:/heimdall-home:rw --entrypoint /usr/bin/heimdalld -it 0xpolygon/heimdall:1.0.3 init --home=/heimdall-home
-   ```
+      ```bash
+         docker run -v /mnt/data/heimdall:/heimdall-home:rw --entrypoint /usr/bin/heimdalld -it 0xpolygon/heimdall:1.0.3 init --home=/heimdall-home
+      ```
 
-3. Edit `config.toml` in `/mnt/data/heimdall/config`:
+   3. Edit `config.toml` in `/mnt/data/heimdall/config`:
 
-   - Set `moniker` to a unique node name.
-   - Change `laddr` to `tcp://0.0.0.0:26657`.
-   - Update `seeds` with the latest list (found in the section on seed nodes and bootnodes).
+      - Set `moniker` to a unique node name.
+      - Change `laddr` to `tcp://0.0.0.0:26657`.
+      - Update `seeds` with the latest list (found in the section on seed nodes and bootnodes).
 
-4. Edit `heimdall-config.toml`:
+   4. Edit `heimdall-config.toml`:
 
-   - Set `eth_rpc_url` to your Ethereum Mainnet RPC URL.
-   - Change `bor_rpc_url` to `<http://bor:8545>
+      - Set `eth_rpc_url` to your Ethereum Mainnet RPC URL.
+      - Change `bor_rpc_url` to `<http://bor:8545>`.
 
-`.
+   5. Update the `genesis.json` for Mainnet:
 
-5. Update the `genesis.json` for Mainnet:
 
-   ```bash
-   sudo curl -o /mnt/data/heimdall/config/genesis.json https://raw.githubusercontent.com/maticnetwork/heimdall/master/builder/files/genesis-mainnet-v1.json
-   ```
+      ```bash
+         sudo curl -o /mnt/data/heimdall/config/genesis.json https://raw.githubusercontent.com/maticnetwork/heimdall/master/builder/files/genesis-mainnet-v1.json
+      ```
+
+      
 
    Verify the hash with `sha256sum genesis.json`.
 

docs/pos/how-to/smart-contracts/alchemy.md

@@ -6,8 +6,6 @@
 
     Polygon technical documentation serves as an industry public good and is made available under the [MIT License](https://opensource.org/license/mit/). In addition, please view the official [Polygon Labs Terms of Use](https://polygon.technology/terms-of-use).
 
-This tutorial is for developers who are either new to Ethereum blockchain development or want to understand the fundamentals of deploying and interacting with smart contracts. It will walk you through creating and deploying a smart contract on the Polygon Mumbai test network using a cryptocurrency wallet ([Metamask](https://metamask.io)), [Solidity](https://docs.soliditylang.org/en/v0.8.0/), [Hardhat](https://hardhat.org), and [Alchemy](https://alchemy.com/?a=polygon-docs).
-
 ## What you will learn
 
 To create a smart contract in this tutorial, you will learn how to use Alchemy's platform to:

docs/pos/how-to/smart-contracts/index.md

@@ -1 +1,5 @@
-Welcome to the Polygon PoS how-to section! There's a bunch of how-tos here to help you get started with common technical tasks. We hope you find them useful.
+This subsection provides guides on how to work with smart contracts, following tutorials supplied by various third parties.
+
+The tutorials contained in here are suitable for developers who are either new to blockchain development on Ethereum, or want to understand the fundamentals of deploying and interacting with smart contracts.
+
+The tutorials are walk-throughs to creating and deploying smart contracts on the Polygon Mumbai test network using a Web3 wallet like [Metamask](https://metamask.io), [Solidity](https://docs.soliditylang.org/en/v0.8.0/), [Hardhat](https://hardhat.org), and [Alchemy](https://alchemy.com/?a=polygon-docs).

mkdocs.yml

@@ -258,8 +258,8 @@ nav:
             - Topup: pos/architecture/heimdall/topup.md
             - Chain management: pos/architecture/heimdall/chain-management.md
             - Governance: pos/architecture/heimdall/governance.md
-      - Specification:
-          - Specification: pos/spec/index.md
+      # - Specification:
+      #     - Specification: pos/spec/index.md
       - Concepts:
           - Concepts: pos/concepts/index.md
           - Tokens:
@@ -271,8 +271,8 @@ nav:
             - EIP-1559: pos/concepts/transactions/eip-1559.md
             - EIP-4337: pos/concepts/transactions/eip-4337.md
             - Meta-transactions: pos/concepts/transactions/meta-transactions.md
-      - API:
-          - pos/api/index.md
+      # - API:
+      #     - pos/api/index.md
   - Miden:
       - Miden: miden/index.md # marketing landing page
       - Get started: miden/get-started/index.md