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

Update PoS - fixed link + MS styling
0xPolygon · Dec 19, 2023 · 4c44fcb · 4c44fcb
2 parents ec42a9b + 0338f5c
commit 4c44fcb
Show file tree

Hide file tree

Showing 46 changed files with 683 additions and 64 deletions.
diff --git a/docs/img/pos/choose-eth-mainnet.png b/docs/img/pos/choose-eth-mainnet.png
diff --git a/docs/img/pos/claim-rewards.mp4 b/docs/img/pos/claim-rewards.mp4
diff --git a/docs/img/pos/claim-stake1.png b/docs/img/pos/claim-stake1.png
diff --git a/docs/img/pos/claim-stake2.png b/docs/img/pos/claim-stake2.png
diff --git a/docs/img/pos/claim-stake3.png b/docs/img/pos/claim-stake3.png
diff --git a/docs/img/pos/claiming-stake.mov b/docs/img/pos/claiming-stake.mov
diff --git a/docs/img/pos/click-my-account.png b/docs/img/pos/click-my-account.png
diff --git a/docs/img/pos/delegate.png b/docs/img/pos/delegate.png
diff --git a/docs/img/pos/delegate2.png b/docs/img/pos/delegate2.png
diff --git a/docs/img/pos/delegate3.png b/docs/img/pos/delegate3.png
diff --git a/docs/img/pos/delegateB.png b/docs/img/pos/delegateB.png
diff --git a/docs/img/pos/home.png b/docs/img/pos/home.png
diff --git a/docs/img/pos/move.png b/docs/img/pos/move.png
diff --git a/docs/img/pos/move2.png b/docs/img/pos/move2.png
diff --git a/docs/img/pos/moving.mp4 b/docs/img/pos/moving.mp4
diff --git a/docs/img/pos/my-account.png b/docs/img/pos/my-account.png
diff --git a/docs/img/pos/myAccount.png b/docs/img/pos/myAccount.png
diff --git a/docs/img/pos/restake-rewards.png b/docs/img/pos/restake-rewards.png
diff --git a/docs/img/pos/restake-rewards1.png b/docs/img/pos/restake-rewards1.png
diff --git a/docs/img/pos/restake-rewards2.png b/docs/img/pos/restake-rewards2.png
diff --git a/docs/img/pos/restake.mp4 b/docs/img/pos/restake.mp4
diff --git a/docs/img/pos/staking-lp.png b/docs/img/pos/staking-lp.png
diff --git a/docs/img/pos/staking-more.mov b/docs/img/pos/staking-more.mov
diff --git a/docs/img/pos/staking.mp4 b/docs/img/pos/staking.mp4
diff --git a/docs/img/pos/supported-wallet.png b/docs/img/pos/supported-wallet.png
diff --git a/docs/img/pos/unbond-from-validator.png b/docs/img/pos/unbond-from-validator.png
diff --git a/docs/img/pos/unbond.mp4 b/docs/img/pos/unbond.mp4
diff --git a/docs/img/pos/unbond.png b/docs/img/pos/unbond.png
diff --git a/docs/img/pos/withdraw-reward.png b/docs/img/pos/withdraw-reward.png
diff --git a/docs/img/pos/withdraw1.png b/docs/img/pos/withdraw1.png
diff --git a/docs/img/pos/withdraw2.png b/docs/img/pos/withdraw2.png
diff --git a/docs/img/zkEVM/staking-lp.png b/docs/img/zkEVM/staking-lp.png
diff --git a/docs/img/zkEVM/staking-more.mov b/docs/img/zkEVM/staking-more.mov
diff --git a/docs/pos/architecture/bor/state-sync.md b/docs/pos/architecture/bor/state-sync.md
@@ -1,4 +1,4 @@
-`State Sync` is the native mechanism to read Ethereum data from Matic EVM chain.
+`State Sync` is the native mechanism for a user in the Polygon PoS chain to read the latest Ethereum data.
 
 Validators on the Heimdall layer pickup the [StateSynced](https://github.com/maticnetwork/contracts/blob/a4c26d59ca6e842af2b8d2265be1da15189e29a4/contracts/root/stateSyncer/StateSender.sol#L24) event and pass it on to the Bor layer.
 
@@ -76,7 +76,8 @@ Only `0x0000000000000000000000000000000000001001` — `StateReceiver.sol`, must
 
 ## System call
 
-Only system address, `2^160-2`, allows making a system call. Bor calls it internally with the system address as `msg.sender`. It changes the contract state and updates the state root for a particular block. Inspired from [https://github.com/ethereum/EIPs/blob/master/EIPS/eip-210.md](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-210.md) and [https://wiki.parity.io/Validator-Set#contracts](https://wiki.parity.io/Validator-Set#contracts)
+Only system address, `2^160-2`, allows making a system call. Bor calls it internally with the system address as `msg.sender`. It changes the contract state and updates the state root for a particular block. Inspired by [https://github.com/ethereum/EIPs/blob/master/EIPS/eip-210.md](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-210.md). 
+<!-- and [https://wiki.parity.io/Validator-Set#contracts](https://wiki.parity.io/Validator-Set#contracts) -->
 
 System call is helpful to change state to contract without making any transaction.
 

diff --git a/docs/pos/get-started/building-on-polygon.md b/docs/pos/get-started/building-on-polygon.md
@@ -1,12 +1,11 @@
 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 Truffle, Remix or Web3js, Polygon offers the same UX as Ethereum.
 
-Connect your wallet and deploy any decentralized application to either Polygon Mainnet or Polygon Mumbai Testnet. 
+Connect your wallet and deploy any decentralized application to either Polygon Mainnet or Polygon Mumbai Testnet.
 
-Polygon Mumbai Testnet connects to Ethereum Goërli Testnet, which acts as its ParentChain, a testnet layer 1 (L1). 
+Polygon Mumbai Testnet connects to Ethereum Goërli Testnet, which acts as its ParentChain, a testnet layer 1 (L1).
 
 Find all the network-related details in the [network documentation](https://github.com/0xPolygon/wiki/blob/master/docs/pos/reference/rpc-endpoints.md).
 
-
 ## Overview
 
 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:

diff --git a/docs/pos/how-to/index.md b/docs/pos/how-to/index.md
@@ -1,5 +1,5 @@
- Welcome to the Polygon PoS how-to section! There is a number of how-to guides here to help you get started with common technical tasks. We hope you find them useful.
+ Welcome to the Polygon PoS how-to section. There is a number of how-to guides here to help you get started with common technical tasks. We hope you find them useful.
 
 The section covers a number of tutorials on how to operate different types of Polygon PoS nodes, how to bridge assets from PoS to Ethereum and conversely, or send messages between L1 and L2 networks, and how to work with smart contracts.
 
-Included in the section is an elaborate startup guide for users who wish to implement the Polygon DID, which is a three-part package consisting of an indentity-registrar, an identity-resolver and an identity-registry-contract.
+Included in the section is an elaborate startup guide for users who wish to implement the Polygon DID, which is a three-part package consisting of an indentity-registrar, identity-resolver, and identity-registry-contract.
diff --git a/docs/pos/how-to/snapshots.md b/docs/pos/how-to/snapshots.md
@@ -5,9 +5,11 @@ For the latest snapshot, please visit [Polygon Chains Snapshots](https://snapsho
 !!! warning "Bor snapshots no longer supported"
     We no longer support bor archive snapshots due to unsustainable data growth.
 
-## Client Snapshots
+## Client snapshots
+
+To begin, ensure that your node environment meets the **prerequisites** outlined [here](
+  ../operate-node/operate/full-node-binaries.md). Before starting any services, execute the shell script provided below. This script will download and extract the snapshot data, which allows for faster bootstrapping. In our example, we will be using an Ubuntu Linux m5d.4xlarge machine with an 8TB block device attached.
 
-To begin, ensure that your node environment meets the **prerequisites** outlined [here](https://wiki.polygon.technology/docs/operate/full-node-binaries/). Before starting any services, execute the shell script provided below. This script will download and extract the snapshot data, which allows for faster bootstrapping. In our example, we will be using an Ubuntu Linux m5d.4xlarge machine with an 8TB block device attached.
 To transfer the correct chaindata to your disk, follow these steps:
 
 - All one has to do is specify the network ("mainnet" or "mumbai") and client type ("heimdall" or "bor" or "erigon") of your desired snapshot and run the following command:

diff --git a/docs/pos/operate-node/delegate/delegate.md b/docs/pos/operate-node/delegate/delegate.md
@@ -0,0 +1,127 @@
+
+# How to delegate
+
+This is a step-by-step guide to help you become a delegator on the Polygon Network.
+
+The only prerequisite is to have your MATIC tokens and ETH on the Ethereum mainnet address.
+
+## Access the dashboard
+
+  1. In your wallet (e.g. MetaMask), choose the Ethereum mainnet.
+
+    ![Figure: Choose ERTHh mainnet ](../../../img/pos/choose-eth-mainnet.png)
+
+  2. Log in to [Polygon Staking](https://staking.polygon.technology/).
+
+  3. Once you log in, you will see overall statistics along with the list of validators.
+
+    ![img](../../../img/pos/home.png)
+
+
+
+
+!!!note
+    If you are a validator, use a different non-validating address to log in as delegator.
+
+
+## Delegate to a validator
+
+  1. Click **Become a Delegator** or scroll down to a specific validator and click **Delegate**.
+
+    ![img](../../../img/pos/home.png)
+
+  2. Provide the amount of MATIC to delegate.
+
+    ![img](../../../img/pos/delegateB.png)
+
+
+  3. Approve the delegation transaction and click **Delegate**.
+
+    ![img](../../../img/pos/delegate2.png)
+
+
+After the delegation transaction completes, you will see the **Delegation Completed** message.
+
+  ![img](../../../img/pos/delegate3.png)
+
+
+## View your delegations
+
+To view your delegations, click [My Account](https://staking.polygon.technology/account).
+
+![img](../../../img/pos/myAccount.png)
+
+## Withdraw rewards
+
+  1. Click [My Account](https://staking.polygon.technology/account).
+
+    ![img](../../../img/pos/click-my-account.png)
+
+
+  2. Under your delegated validator, click **Withdraw Reward**.
+
+    ![img](../../../img/pos/withdraw-reward.png)
+
+
+This will withdraw the MATIC token rewards to your Ethereum address.
+
+## Restake rewards
+
+  1. Click [My Account](https://staking.polygon.technology/account).
+
+    ![img](../../../img/pos/click-my-account.png)
+
+
+  2. Under your delegated validator, click **Restake Reward**.
+
+    ![img](../../../img/pos/restake-rewards.png)
+
+
+
+This will restake the MATIC token rewards to the validator and increase your delegation stake.
+
+## Unbond from a validator
+
+  1. Click [My Account](https://staking.polygon.technology/account).
+
+    ![img](../../../img/pos/click-my-account.png)
+
+
+  2. Under your delegated validator, click **Unbond**.
+
+    ![img](../../../img/pos/unbond-from-validator.png)
+
+
+  This will withdraw your rewards from the validator and your entire stake from the validator.
+
+  Your withdrawn rewards will show up immediately on your Ethereum account.
+
+  Your withdrawn stake funds will be locked for 80 checkpoints.
+
+    ![img](../../../img/pos/unbond.png)
+
+
+!!!note
+
+    The fund locking for the unbonding period is in place to ensure there is no malicious behaviour on the network.
+
+
+## Move stake from one node to another node
+
+Moving stake from one node to another node is a single transaction. There are no delays or unbonding periods during this event.
+
+  1. Log in to the [My Account](https://staking.polygon.technology/account) on the Staking dashboard.
+
+  2. Click **Move Stake** under your delegated validator.
+
+  3. Select an external validator and click **Stake here**.
+
+    ![img](../../../img/pos/move.png)
+
+
+  4. Provide the stake amount and click **Move Stake**.
+
+    ![img](../../../img/pos/move2.png)
+
+
+This will move the stake. The dashboard will update after 12 block confirmations.
diff --git a/docs/pos/operate-node/delegate/delegator-faq.md b/docs/pos/operate-node/delegate/delegator-faq.md
@@ -0,0 +1,171 @@
+
+### What is the staking dashboard URL?
+
+The staking dashboard URL is https://staking.polygon.technology/.
+
+### What is the minimum stake amount?
+
+There is no minimum stake amount to delegate. However, you can always start with 1 MATIC token.
+
+### How many rewards will I get if I delegate?
+
+Please use the [Polygon earnings calculator](https://staking.polygon.technology/rewards-calculator) to determine your estimates.
+
+### Why does my transaction take so long?
+
+All staking transactions of Polygon happen on Ethereum for security reasons.
+
+The time taken to complete a transaction depends on the gas fees that you have allowed and also the network congestion of Ethereum mainnet at that point in time. You can always use the “Speed Up” option to increase the gas fees so that your transaction can be completed soon.
+
+### Which wallets are currently supported?
+
+We have recently upgraded the wallet support to WalletConnect v2.0. Now you can choose from a plethora of wallets, including Metamask, Coinbase, and others, on both desktop and mobile devices to log in.
+
+  <center>
+  ![Figure: Supported wallet](../../../img/pos/supported-wallet.png)
+  </center>
+
+### Are hardware wallets supported?
+
+Yes, hardware wallets are supported. You can use the "Connect Hardware Wallet" option on MetaMask and connect your Hardware wallet and then continue the delegation process.
+
+### Why can’t I stake directly from Binance?
+
+Staking through Binance is not yet supported. There will be an announcement if and when Binance starts supporting it.
+
+### I have completed my delegation, where can I check details?
+
+Once you have completed your delegation, wait for 12 block confirmations on Ethereum (approx. 3-5 minutes), then on the Dashboard, you can click on **My Account**.
+
+![Figure: My account](../../../img/pos/my-account.png)
+
+
+### Where can I check my rewards?
+
+On the Dashboard, you can click on the **My Account** option on the left-hand side.
+
+![Figure: My account](../../../img/pos/my-account.png)
+
+
+### Do I need ETH to pay for gas fees?
+
+Yes. You should provision for ~0.05-0.1 ETH to be safe.
+
+### Do I need to deposit MATIC tokens to the Polygon mainnet network for staking?
+
+No. All your funds need to be on the main Ethereum network.
+
+### When I try to do the transaction my **Confirm** button is disabled.
+
+Please check if you have enough ETH for the gas fees.
+
+### When does reward get distributed?
+
+The rewards are distributed whenever a checkpoint is submitted.
+
+Currently, 71795 MATIC tokens are distributed proportionately on each successful checkpoint submission to each delegator based on their stake relative to the overall staking pool of all validators and delegators. Also, the percentage for the reward distributed to each delegator will vary with each checkpoint depending on the relative stake of the delegator, validator and the overall stake.
+
+(Note that there is a 10% proposer bonus that accrues to the validator who submits the checkpoint, but over time, the effect of the extra bonus is nullified over multiple checkpoints by different validators.)
+
+The checkpoint submission is done by one of the validators approximately every 30 minutes. This time is approximate and may vary based on validator consensus on the Polygon Heimdall layer. This may also vary based on Ethereum Network. Higher congestion in the network may result in delayed checkpoints.
+
+You can track checkpoints on the staking contract [here](https://etherscan.io/address/0x86e4dc95c7fbdbf52e33d563bbdb00823894c287)
+
+### Why does reward keep getting decreased every checkpoint?
+
+Actual rewards earned will depend on the actual total locked supply in the network at each checkpoint. This is expected to vary significantly as more MATIC tokens get locked in the staking contracts.
+
+Rewards will be higher, to begin with, and will keep decreasing as the locked supply % goes up. This change in locked supply is captured at every checkpoint, and rewards are calculated based on this.
+
+### How can I claim my rewards?
+
+You can claim your rewards instantly by clicking on the **Withdraw Reward** button. This will transfer the rewards accumulated to your delegated account on Metamask.
+
+![Figure: Withdraw-reward](../../../img/pos/withdraw-reward.png)
+
+
+### What is the unbonding period?
+
+The unbonding period on Polygon is 80 checkpoints. This period applies to the originally delegated amount and re-delegated amounts - it does not apply to any rewards that were not re-delegated.
+
+### Will I keep receiving rewards after I unbond?
+
+No. Once you unbond, you will stop receiving rewards.
+
+### How many transactions does the delegation require?
+
+Delegation requires 2 transactions, one after the other. One to **Approve** the request and another to **Deposit**.
+
+![Figure: Delegate ](../../../img/pos/delegate.png) 
+
+### What does redelegate rewards mean?
+
+Redelegating your rewards simply means that you want to increase your stake by restaking the rewards you have accumulated.
+
+### Can I stake to any validator?
+Yes, you can delegate to any validator except the ones which are offline.
+
+### Which browser is compatible with the Polygon earnings calculator?
+
+Chrome, Firefox, and Brave
+
+### My MetaMask is stuck at confirming after login, what do I do? Or nothing happens when I try to login?
+
+Check for the following:
+
+- If you’re using Brave, please turn off the option for **Use Crypto Wallets** in the settings panel.
+- Check if you are logged into Metamask
+- Check if you are logged into MetaMask with Trezor/Ledger. You need to additionally turn on permission to call contracts on your Ledger device, if not enabled already.
+- Check your system timestamp. If the system time is not correct, you will need to correct it.
+
+### How do I send funds from Binance or other exchanges to Polygon wallet?
+
+The Polygon Wallet Suite is a web application. 
+
+First, you must withdraw your funds from Binance or any other exchange to your Ethereum address on Metamask. If you don't know how to use Metamask, google it a bit. There are plenty of videos and blogs to get started with it.
+
+### When can I become a validator and how many tokens do I for that?
+
+A user can earn a validator spot only by if the below conditions come into play:
+1. When a validator decides to unstake from the network, or
+2. Wait for the auction mechanism and replace the inactive validator.
+
+The minimum stake depends on the auction process where one user outbids another.
+
+### If I have earned rewards while delegating, and if I add additional funds to the same validator node, what happens?
+
+If you have not re-delegated your rewards before delegating additional funds to the same validator node, your rewards will be withdrawn automatically.
+
+In case you dont want that to happen, re-delegate your rewards before delegating additional funds.
+
+### I have delegated my tokens via MetaMask on the dashboard. Do I need to keep my system or device on?
+
+No. Once your delegation transactions are confirmed, and you can see your tokens reflected in the **Total Stake** and **New Reward** sections, then you are done. There is no need to keep your system or device on.
+
+### I have unbonded, how long will it take to unbond?
+
+The unbonding period is currently set to 80 checkpoints. Every checkpoint takes approximately 30 minutes. However, some checkpoints could be delayed upto ~1 hour due to congestion on Ethereum.
+
+### I have unbonded, and I now see the **Claim Stake** button, but it is disabled.
+
+The Claim Stake button will only be enabled when your unbonding period is complete. The unbonding period is currently set at 80 checkpoints.
+
+### When will the **Claim Stake** button be enabled?
+
+Under the **Claim Stake** button you should see a note on how many checkpoints are pending before the **Claim Stake** button is enabled. Every checkpoint takes approximately 30 minutes. However, some checkpoints could be delayed upto ~1 hour due to congestion on Ethereum.
+
+![Figure: Unbound ](../../../img/pos/unbond.png)
+
+
+
+### Have the foundations nodes been turned off?
+
+Yes, the foundation nodes had been turned off.
+
+### Will there be any foundation nodes in the future?
+
+No, there won't be any Foundation nodes in the future.
+
+### How many transactions do I need to pay for gas when I do a "move stake"?
+
+The move stake is a single transaction only. All transactions are on the Ethereum blockchain so you will spend some ETH to make the transaction.
diff --git a/docs/pos/operate-node/validator/responsibilities.md b/docs/pos/operate-node/validator/responsibilities.md
@@ -9,7 +9,7 @@ A blockchain validator is someone who is responsible for validating transactions
 
 !!!info
 
-    Currently, there is a limit of 100 active validators at a time. For a detailed description on what a validator is, see [<ins>Validator</ins>](../../index.md).
+    Currently, there is a limit of 100 active validators at a time. For a detailed description on what a validator is, see [<ins>Validator</ins>](./getting-started.md).
 
     Also, after the [<ins>PIP4 governance proposal</ins>](https://forum.polygon.technology/t/pip-4-validator-performance-management/9956) is implemented on the contract-level, the minimum staking amount will increase to 10,000 MATIC.