Merge pull request 0xPolygon#677 from 0xPolygon/pos-review-fixes

PoS review fixes

Author: hsutaiyu

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

@@ -2,22 +2,33 @@
 comments: true
 ---
 
-Ethereum developers are by default Polygon developers. Welcome. Simply switch to the [Polygon RPC](https://polygon-rpc.com/) and get started. All familiar tools used on Ethereum are supported on Polygon. Whether it is Foundry, Remix or Web3.js, Polygon offers the same UX as Ethereum.
+## Overview
+
+All your favorite Ethereum tools (Foundry, Remix, Web3.js) work seamlessly on Polygon, with the same familiar UX. Just switch to the [Polygon RPC](https://polygon-rpc.com/) and keep building.
 
 Connect your wallet and deploy any decentralized application to either PoS mainnet or Amoy testnet (Sepolia-anchored).
 
-## Overview
+Use the links below to find the right tooling and guides that suit your needs the best.
 
-Polygon is a Layer-2 (L2) network to Ethereum, employing a Proof-of-Stake (PoS) consensus mechanism, and thus composed of the following two layers:
+- [Faucets](../../tools/gas/matic-faucet.md) - Fetch test tokens
+- [Polygon gas station](../../tools/gas/polygon-gas-station.md) - Gas estimation API
+- [Polygon dApp Launchpad](../../tools/dApp-development/launchpad/intro.md) - dApp development CLI tool
+- [Popular third-party tooling](../../tools/dApp-development/third-party-tutorials.md)
+- [Matic.js library](../../tools/matic-js/installation.md)
 
-  - Heimdall layer, a consensus layer consisting of a set of proof-of-stake Heimdall nodes for monitoring staking contracts deployed on the Ethereum mainnet, and committing the Polygon PoS network checkpoints to the Ethereum mainnet. Heimdall is based on Tendermint.
-  - Bor layer, an execution layer which is made up of a set of block-producing Bor nodes shuffled by Heimdall nodes. Bor is based on Go Ethereum (Geth).
+If you have no prior experience in dApp development, the following resources will help you get started with some essential tools for building, testing, and deploying applications on Polygon PoS.
 
-In order to be a validator on the Polygon PoS network, you need to:
+- [Full Stack dApp: Tutorial Series](https://kauri.io/full-stack-dapp-tutorial-series/5b8e401ee727370001c942e3/c)
+- [Web3.js](https://www.dappuniversity.com/articles/web3-js-intro)
+- [Ethers.js](https://docs.ethers.io/v5/)
+- [thirdweb](https://portal.thirdweb.com)
+- [Remix](https://remix.ethereum.org/)
+- [Hardhat](https://hardhat.org/hardhat-runner/docs/getting-started)
+- [Foundry](https://github.com/foundry-rs/foundry/blob/master/README.md)
+- [Metamask](https://support.metamask.io/getting-started/)
+- [Venly (previously Arkane)](https://docs.venly.io/docs/getting-started-with-venly)
+- [Develop a dApp using Fauna, Polygon, and React](https://github.com/hello-ashleyintech/polygon-fauna-app)
 
-- Run a sentry node, which is a separate machine running a Heimdall node and a Bor node. A sentry node is open to all nodes on the Polygon PoS network.
-- Run a validator node, which is a separate machine running a Heimdall node and a Bor node. A validator node is only open to its sentry node and closed to the rest of the network.
-- Stake the MATIC tokens in the staking contracts deployed on the Ethereum mainnet.
 
 ## Network details
 
@@ -70,35 +81,14 @@ async function main() {
 main();
 ```
 
-!!! note "Take it easy!"
-
-    If this is overwhelming, that’s alright! You can jump right into the action and start hacking. Here are some notes before you start diving into resources, repositories, and docs:
-
-    1. **Beware the cost of being on the bleeding edge**: Like typical niche programming, dApps and blockchain development moves very quickly. While researching, you may find complex code repositories, 404s on a documentation site, or even no documentation. Use that opportunity to [open an issue on the Polygon Knowledge Layer's GitHub repository](https://github.com/0xPolygon/polygon-docs/issues).
-    2. **The learning curve may be daunting, but the barrier to entry is low**: The community is very open and welcoming! Projects welcome pull requests from outsiders and resolve any blockers actively. We’re working on creating a better world and contribution in any form is appreciated. We’ll be grateful to onboard you into this amazing Web3 ecosystem.
-
-## Building a new dApp on Polygon?
-
-Decentralized applications (dApps) act as the bridge between users and their data privacy on the blockchain. The increasing number of dApps validates their usefulness within the blockchain ecosystem, solving challenges like executing transactions between two participants without the need for central authority via smart contracts.
-
-Suppose you have no prior experience building dApps. In that case, the below-mentioned resources will give you a head start on the tools required to build, debug, and deploy dApps on the Polygon PoS network.
-
-- [Full Stack dApp: Tutorial Series](https://kauri.io/full-stack-dapp-tutorial-series/5b8e401ee727370001c942e3/c)
-- [Web3.js](https://www.dappuniversity.com/articles/web3-js-intro)
-- [Ethers.js](https://docs.ethers.io/v5/)
-- [thirdweb](https://portal.thirdweb.com)
-- [Remix](https://remix.ethereum.org/)
-- [Hardhat](https://hardhat.org/hardhat-runner/docs/getting-started)
-- [Foundry](https://github.com/foundry-rs/foundry/blob/master/README.md)
-- [Metamask](https://support.metamask.io/getting-started/)
-- [Venly (previously Arkane)](https://docs.venly.io/docs/getting-started-with-venly)
-- [Develop a dApp using Fauna, Polygon, and React](https://github.com/hello-ashleyintech/polygon-fauna-app)
-
-## Polygon DID
+!!! tip "Reach out to us!"
 
-You can refer to the elaborate startup guide for users who wish to implement the Polygon DID, which is a three-part package consisting of an identity-registrar, identity-resolver, and identity-registry-contract.
+    If you're encountering problems while hacking or have questions about something, please use the following methods to contact us:
 
-* [Polygon DID integration guide](../how-to/polygon-did.md)
+    1. If you come across a complex code repository, 404s on the docs site, or if you feel there's something missing - feel free to [open an issue on the Polygon Knowledge Layer's GitHub repository](https://github.com/0xPolygon/polygon-docs/issues). You can also open a PR if you're looking to [contribute](https://github.com/0xPolygon/polygon-docs?tab=readme-ov-file#contributing)!
+    2. Get in touch with us via Discord:
+        - [Community Discord](https://discord.com/invite/0xPolygonCommunity)
+        - [Research and Development Discord](https://discord.com/invite/0xpolygonrnd)
 
 ## Already have a dApp?
 

docs/pos/get-started/index.md

@@ -2,6 +2,10 @@
 comments: true
 ---
 
+!!! warning "Work in progress!"
+
+    This doc is currently undergoing revision, and the instructions provided may not be up to date. Stay tuned for updates!
+
 The mechanism to natively read Ethereum data from Polygon EVM chain is that of ‘State Sync’. In other words, this mechanism enables transfer of arbitrary data from Ethereum chain to Polygon chain. The procedure that makes it possible is: Validators on the Heimdall layer are listening for a particular event — `StateSynced` from a *sender* contract, as soon as the event is picked, the `data` that was passed in the event is written on the *receiver* contract. Read more [here](../../../architecture/bor/state-sync.md).
 
 The sender and receiver contracts are required to be mapped on Ethereum — [StateSender.sol](https://github.com/maticnetwork/contracts/blob/release-betaV2/contracts/root/stateSyncer/StateSender.sol) needs to be aware of each sender and receiver.

docs/pos/how-to/bridging/ethereum-polygon/ethereum-to-matic.md

@@ -2,6 +2,10 @@
 comments: true
 ---
 
+!!! warning "Work in progress!"
+
+    This doc is currently undergoing revision, and the instructions provided may not be up to date. Stay tuned for updates!
+
 The mechanism for transferring data from Polygon PoS to Ethereum differs from the process of transferring data from Ethereum to Polygon PoS. Validators create *checkpoint transactions* on the Ethereum chain to facilitate this transfer. These checkpoints serve as periodic summaries of the PoS chain’s state, ensuring data integrity and consistency when moving data back to Ethereum. The flow of this process is briefly described below.
 
 1. A transaction is created on Polygon PoS. It is crucial to emit an event and ensure that the event logs include the data intended for transfer to Ethereum. This process is essential for tracking and verifying the data transfer, as the event logs serve as a reliable record that can be referenced on the Ethereum network.

docs/pos/how-to/bridging/ethereum-polygon/matic-to-ethereum.md

@@ -4,7 +4,7 @@ The official bridge is available on both the PoS Amoy testnet as well as mainnet
 
 !!! tip "Polygon Portal"
 
-    To learn more about the features that Polygon Portal offers, and a series of step-by-step reference guides that help you with using the platform, check out [the doc available here](../../../../tools/wallets/portal.md).
+    To learn more about the features that Polygon Portal offers, and a series of step-by-step instructions that help you with using the platform, check out [the Portal guide](../../../../tools/wallets/portal.md).
 
 There is no change to the circulating supply of your token when it crosses the bridge. This is what goes on in the background when you bridge your tokens over to Polygon PoS from Ethereum:
 

…ow-to/bridging/ethereum-polygon/index.md …o/bridging/ethereum-polygon/portal-ui.mddocs/pos/how-to/bridging/ethereum-polygon/index.md renamed to docs/pos/how-to/bridging/ethereum-polygon/portal-ui.md docs/pos/how-to/bridging/ethereum-polygon/index.md renamed to docs/pos/how-to/bridging/ethereum-polygon/portal-ui.md

@@ -6,8 +6,7 @@ Token mapping is important in order to enable the transfer mechanism for the sai
 
 !!! info
 
-    - For more information on how bridging works in the background, see [the doc available here](../index.md).
-    - Thinking about bridging another popular token? Refer to the [reference guide on Polygon Portal](../../../../tools/wallets/portal.md).
+    Thinking about bridging a popular token? Refer to the [reference guide on Polygon Portal](../../../../tools/wallets/portal.md).
 
 ## Steps to submit a mapping request
 

docs/pos/how-to/bridging/ethereum-polygon/submit-mapping-request.md

@@ -2,6 +2,10 @@
 comments: true
 ---
 
+!!! warning "Work in progress!"
+
+    This doc is currently undergoing revision, and the instructions provided may not be up to date. Stay tuned for updates!
+
 Polygon validators continuously monitor a contract on Ethereum chain called `StateSender`. Each time a registered contract on Ethereum chain calls this contract, it emits an event. Using this event Polygon validators relay the data to another contract on Polygon chain. This *state sync* mechanism is used to send data from Ethereum to Polygon.
 
 Additionally, Polygon validators send the transaction hash, namely *checkpoint*, of each transaction on the PoS chain to Ethereum on a regular basis. You can use this to validate any transaction that took place on Polygon. Once a transaction has been verified to have occurred on the PoS chain, the corresponding action can then be executed on Ethereum.

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

@@ -1,10 +1,6 @@
-Welcome to the Polygon PoS node how-tos section!
-
-This section contains guides that describe the system requirements and configurations necessary to spin up different kinds of Polygon nodes, and then take you step by step through the process of setting them up on the PoS network. 
-
 Depending on the extent to which you're looking to participate in different network processes, and the kind of computational and network capabilities you can offer, you can choose to deploy any of the following nodes:
 
-!!! tip
+!!! tip "Different minimum and recommended system requirements"
 
     It's always a good idea to first read and understand the *minimum* and *recommended* system requirements for any node that you choose to deploy to the PoS network.