Merge pull request 0xPolygon#27 from 0xPolygon/nadim/pos3

Many fixes to PoS

Author: Nadim Kobeissi

docs/pos/api/index.md

@@ -1 +1 @@
-Auto-generated, apparently.
+Auto-generated, apparently.

docs/pos/architecture/bor/consensus.md

@@ -14,11 +14,11 @@ Once validators are active on Heimdall they get selected as producers through `b
 
 A logically defined set of blocks for which a set of validators is chosen from among all the available validators. Heimdall provides span details through span-details APIs.
 
-Each validator in span contains voting power. Based on their power, they get selected as block producers. Higher power, a higher probability of becoming block producers. Bor uses Tendermint's algorithm for the same. 
+Each validator in span contains voting power. Based on their power, they get selected as block producers. Higher power, a higher probability of becoming block producers. Bor uses Tendermint's algorithm for the same.
 
 ## Sprint
 
-A set of blocks within a span for which only a single block producer is chosen to produce blocks. The sprint size is a factor of span size. 
+A set of blocks within a span for which only a single block producer is chosen to produce blocks. The sprint size is a factor of span size.
 
 Apart from the current proposer, Bor also selects back-up producers.
 
@@ -91,12 +91,12 @@ header.Extra = header.Vanity + header.ProducerBytes /* optional */ + header.Seal
 
 Bor provides a mechanism where some specific events on the main Ethereum chain are relayed to Bor.
 
-1. Any contract on Ethereum may call [syncState](https://github.com/maticnetwork/contracts/blob/develop/contracts/root/stateSyncer/StateSender.sol#L33) in `StateSender.sol`. This call emits `StateSynced` event: https://github.com/maticnetwork/contracts/blob/develop/contracts/root/stateSyncer/StateSender.sol#L38
+1. Any contract on Ethereum may call [syncState](https://github.com/maticnetwork/contracts/blob/develop/contracts/root/stateSyncer/StateSender.sol#L33) in `StateSender.sol`. This call emits `StateSynced` event: <https://github.com/maticnetwork/contracts/blob/develop/contracts/root/stateSyncer/StateSender.sol#L38>
 
   ```js
   event StateSynced(uint256 indexed id, address indexed contractAddress, bytes data)
   ```
 
-2. Heimdall listens to these events and calls `function proposeState(uint256 stateId)` in `StateReceiver.sol`  - thus acting as a store for the pending state change ids. Note that the `proposeState` transaction will be processed even with a 0 gas fee as long as it is made by one of the validators in the current validator set: https://github.com/maticnetwork/genesis-contracts/blob/master/contracts/StateReceiver.sol#L24
+2. Heimdall listens to these events and calls `function proposeState(uint256 stateId)` in `StateReceiver.sol`  - thus acting as a store for the pending state change ids. Note that the `proposeState` transaction will be processed even with a 0 gas fee as long as it is made by one of the validators in the current validator set: <https://github.com/maticnetwork/genesis-contracts/blob/master/contracts/StateReceiver.sol#L24>
 
-3. At the start of every sprint, Bor pulls the details about the pending state changes using the states from Heimdall and commits them to the Bor state using a system call. See `commitState` here: https://github.com/maticnetwork/genesis-contracts/blob/f85d0409d2a99dff53617ad5429101d9937e3fc3/contracts/StateReceiver.sol#L41
+3. At the start of every sprint, Bor pulls the details about the pending state changes using the states from Heimdall and commits them to the Bor state using a system call. See `commitState` here: <https://github.com/maticnetwork/genesis-contracts/blob/f85d0409d2a99dff53617ad5429101d9937e3fc3/contracts/StateReceiver.sol#L41>

docs/pos/architecture/bor/index.md

@@ -2,7 +2,7 @@
 
 Bor is our Block producer layer, which, in sync with the Heimdall validator, selects the producers and verifiers for each span and sprint.
 
-The Bor node or the Block Producer implementation is basically the EVM-compatible blockchain operator. Currently, it is a Geth implementation with custom changes done to the consensus algorithm. 
+The Bor node or the Block Producer implementation is basically the EVM-compatible blockchain operator. Currently, it is a Geth implementation with custom changes done to the consensus algorithm.
 
 Polygon PoS uses dual-consensus architecture on the Polygon Network to optimise for speed and decentralisation.
 
@@ -26,5 +26,5 @@ The ratio of Stake/Staking power specifies the probability to be selected as a m
 
 1. Validators are given slots proportionally according to their stake.
 2. Using historical Ethereum block data as seed, we shuffle this array.
-3. Now depending on Producer count*(maintained by validator's governance)*, validators are taken from the top. 
+3. Now depending on Producer count*(maintained by validator's governance)*, validators are taken from the top.
 4. Using this validator set and Tendermint's proposer selection algorithm, we choose a producer for every sprint on Bor.

docs/pos/architecture/bor/snapshots.md

@@ -1,10 +1,8 @@
-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. **Note: We no longer support bor archive snapshots due to unsustainable data growth.** 
+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. **Note: We no longer support bor archive snapshots due to unsustainable data growth.**
 
-:::tip
+!!! tip
 
-For the latest snapshot, please visit [<ins>Polygon Chains Snapshots</ins>](https://snapshot.polygon.technology/).
-
-:::
+    For the latest snapshot, please visit [<ins>Polygon Chains Snapshots</ins>](https://snapshot.polygon.technology/).
 
 ## Client Snapshots
 
@@ -29,7 +27,7 @@ curl -L https://snapshot-download.polygon.technology/snapdown.sh | bash -s -- --
 - Consider using a Screen session to prevent accidental interruptions during the chaindata download and extraction process.
 - The raw bash script code is collapsed below for transparency:
 
-<details> 
+<details>
 <summary>View script here ↓</summary>
 
 ```bash
@@ -179,7 +177,7 @@ curl -L https://snapshot-download.polygon.technology/snapdown.sh | bash -s -- --
 aria2c -c -m 0 -x6 -s6 -i $client-$network-parts.txt --max-concurrent-downloads=1
 ```
 
-Once the extraction is complete, ensure that you update the datadir configuration of your client to point to the path where the extracted data is located. This ensures that the systemd services can correctly register the snapshot data when the client starts. 
+Once the extraction is complete, ensure that you update the datadir configuration of your client to point to the path where the extracted data is located. This ensures that the systemd services can correctly register the snapshot data when the client starts.
 If you wish to preserve the default client configuration settings, you can use symbolic links (symlinks).
 
 For example, let's say you have mounted your block device at `~/snapshots` and have downloaded and extracted the chaindata
@@ -212,7 +210,7 @@ sudo service bor start
 | approx. compressed total | 250 GB (bor) + 35 GB (heimdall) | 285 GB |
 | approx. data growth daily | 10 GB (bor) + .5 GB (heimdall) | 10.5 GB |
 | approx. total extracted size | 350 GB (bor) + 50 GB (heimdall) | 400 GB |
-| suggested disk size (2.5x buffer) | 400 GB * 2.5 (natural chain growth) | 1 TB | 
+| suggested disk size (2.5x buffer) | 400 GB * 2.5 (natural chain growth) | 1 TB |
 
 **Polygon Mainnet**
 
@@ -230,7 +228,7 @@ sudo service bor start
 | approx. compressed total | 210 GB (erigon) + 35 GB (heimdall) | 245 GB |
 | approx. data growth daily | 4.5 GB (erigon) + .5 GB (heimdall) | 5 GB |
 | approx. total extracted size | 875 GB (erigon) + 50 GB (heimdall) | 925 GB |
-| suggested disk size (2.5x buffer) | 925 GB * 2.5 (natural chain growth) | 2.5 TB | 
+| suggested disk size (2.5x buffer) | 925 GB * 2.5 (natural chain growth) | 2.5 TB |
 
 **NOTE**
 PoS Network is deprecating Archive Node snapshots we request users to move to the Erigon Client and make use of Erigon Snapshots.

docs/pos/architecture/bor/state-sync.md

@@ -1,10 +1,9 @@
-`State Sync` is the native mechanism to read Ethereum data from Matic EVM chain. 
+`State Sync` is the native mechanism to read Ethereum data from Matic EVM chain.
 
-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. 
+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.
 
 The receiver contract inherits [IStateReceiver](https://github.com/maticnetwork/genesis-contracts/blob/master/contracts/IStateReceiver.sol), and custom logic sits inside [onStateReceive](https://github.com/maticnetwork/genesis-contracts/blob/05556cfd91a6879a8190a6828428f50e4912ee1a/contracts/IStateReceiver.sol#L5) function.
 
-
 This is the flow required from dapps / users to work with state-sync:
 
 1. Call the smart contract function present here: [https://github.com/maticnetwork/contracts/blob/19163ddecf91db17333859ae72dd73c91bee6191/contracts/root/stateSyncer/StateSender.sol#L33](https://github.com/maticnetwork/contracts/blob/19163ddecf91db17333859ae72dd73c91bee6191/contracts/root/stateSyncer/StateSender.sol#L33)
@@ -14,30 +13,29 @@ This is the flow required from dapps / users to work with state-sync:
 5. After every sprint on `bor`, the Bor node fetches the pending state-sync events from Heimdall via an API call.
 6. The receiver contract inherits `IStateReceiver` interface, and custom logic of decoding the data bytes and performing any action sits inside `onStateReceive` function: [https://github.com/maticnetwork/genesis-contracts/blob/master/contracts/IStateReceiver.sol](https://github.com/maticnetwork/genesis-contracts/blob/master/contracts/IStateReceiver.sol)
 
-
-# How does State Sync work?
+## How does State Sync work?
 
 State management sends the state from the Ethereum chain to the Bor chain. It is called **state-sync**.
 
-State transfer from Ethereum to Bor happens through system call. Suppose, a user deposits USDC to the deposit manager on Ethereum. Validators listen to those events, validate, and store them in Heimdall state. Bor gets the latest state-sync records and updates the Bor state (mints equal amount of USDC on Bor) using a system call. 
+State transfer from Ethereum to Bor happens through system call. Suppose, a user deposits USDC to the deposit manager on Ethereum. Validators listen to those events, validate, and store them in Heimdall state. Bor gets the latest state-sync records and updates the Bor state (mints equal amount of USDC on Bor) using a system call.
 
 ## State sender
 
 Source: [https://github.com/maticnetwork/contracts/blob/develop/contracts/root/stateSyncer/StateSender.sol](https://github.com/maticnetwork/contracts/blob/develop/contracts/root/stateSyncer/StateSender.sol)
 
-To sync state, the contract calls following method **state sender contract** on Ethereum chain. 
+To sync state, the contract calls following method **state sender contract** on Ethereum chain.
 
 ```jsx
 contract StateSender {
-	/**
-	 * Emits `stateSynced` events to start sync process on Ethereum chain
-	 * @param receiver    Target contract on Bor chain
-	 * @param data        Data to send
-	 */
-	function syncState (
-		address receiver, 
-		bytes calldata data
-	) external;
+ /**
+  * Emits `stateSynced` events to start sync process on Ethereum chain
+  * @param receiver    Target contract on Bor chain
+  * @param data        Data to send
+  */
+ function syncState (
+  address receiver, 
+  bytes calldata data
+ ) external;
 }
 ```
 
@@ -51,9 +49,9 @@ contract StateSender {
  * @param data                Data to send to Bor chain for Target contract address
  */
 event StateSynced (
-	uint256 indexed id, 
-	address indexed contractAddress, 
-	bytes data
+ uint256 indexed id, 
+ address indexed contractAddress, 
+ bytes data
 );
 ```
 
@@ -92,4 +90,4 @@ Bor produces a new tx / receipt just for the client which includes all the logs
 keccak256("matic-bor-receipt-" + block number + block hash)
 ```
 
-This doesn't change any consensus logic, only client changes. `eth_getBlockByNumber`, `eth_getTransactionReceipt`,  and `eth_getLogs` include state-sync logs with derived. Note that the bloom filter on the block doesn't include inclusion for state-sync logs. It also doesn't include derived tx in `transactionRoot` or `receiptRoot`.
+This doesn't change any consensus logic, only client changes. `eth_getBlockByNumber`, `eth_getTransactionReceipt`,  and `eth_getLogs` include state-sync logs with derived. Note that the bloom filter on the block doesn't include inclusion for state-sync logs. It also doesn't include derived tx in `transactionRoot` or `receiptRoot`.

docs/pos/architecture/heimdall/checkpoint.md

@@ -8,25 +8,25 @@ Checkpoint structure on Heimdall state looks like following:
 
 ```go
 type CheckpointBlockHeader struct {
-	// Proposer is selected based on stake
-	Proposer        types.HeimdallAddress `json:"proposer"`
+ // Proposer is selected based on stake
+ Proposer        types.HeimdallAddress `json:"proposer"`
 
-	// StartBlock: The block number on Bor from which this checkpoint starts
-	StartBlock      uint64                `json:"startBlock"`
+ // StartBlock: The block number on Bor from which this checkpoint starts
+ StartBlock      uint64                `json:"startBlock"`
 
-	// EndBlock: The block number on Bor from which this checkpoint ends
-	EndBlock        uint64                `json:"endBlock"`
+ // EndBlock: The block number on Bor from which this checkpoint ends
+ EndBlock        uint64                `json:"endBlock"`
 
-	// RootHash is the Merkle root of all the leaves containing the block
-	// headers starting from start to the end block
-	RootHash        types.HeimdallHash    `json:"rootHash"`
+ // RootHash is the Merkle root of all the leaves containing the block
+ // headers starting from start to the end block
+ RootHash        types.HeimdallHash    `json:"rootHash"`
 
-	// Account root hash for each validator
+ // Account root hash for each validator
   // Hash of data that needs to be passed from Heimdall to Ethereum chain like withdraw topup etc.
-	AccountRootHash types.HeimdallHash    `json:"accountRootHash"`
+ AccountRootHash types.HeimdallHash    `json:"accountRootHash"`
 
   // Timestamp when checkpoint was created on Heimdall
-	TimeStamp       uint64          `json:"timestamp"`
+ TimeStamp       uint64          `json:"timestamp"`
 }
 ```
 
@@ -61,10 +61,10 @@ Source: [https://github.com/maticnetwork/heimdall/blob/develop/checkpoint/types/
 ```go
 // Golang representation of block data used in checkpoint
 blockData := crypto.Keccak256(appendBytes32(
-	blockHeader.Number.Bytes(),
-	new(big.Int).SetUint64(blockHeader.Time).Bytes(),
-	blockHeader.TxHash.Bytes(),
-	blockHeader.ReceiptHash.Bytes(),
+ blockHeader.Number.Bytes(),
+ new(big.Int).SetUint64(blockHeader.Time).Bytes(),
+ blockHeader.TxHash.Bytes(),
+ blockHeader.ReceiptHash.Bytes(),
 ))
 
 // array of block hashes of Bor blocks
@@ -105,21 +105,21 @@ Golang code for the account hash can be found here: [https://github.com/maticnet
 ```go
 // DividendAccount contains Fee, Slashed amount
 type DividendAccount struct {
-	ID            DividendAccountID `json:"ID"`
-	FeeAmount     string            `json:"feeAmount"`     // string representation of big.Int
-	SlashedAmount string            `json:"slashedAmount"` // string representation of big.Int
+ ID            DividendAccountID `json:"ID"`
+ FeeAmount     string            `json:"feeAmount"`     // string representation of big.Int
+ SlashedAmount string            `json:"slashedAmount"` // string representation of big.Int
 }
 
 // calculate hash for particular account
 func (da DividendAccount) CalculateHash() ([]byte, error) {
-	fee, _ := big.NewInt(0).SetString(da.FeeAmount, 10)
-	slashAmount, _ := big.NewInt(0).SetString(da.SlashedAmount, 10)
-	divAccountHash := crypto.Keccak256(appendBytes32(
-		new(big.Int).SetUint64(uint64(da.ID)).Bytes(),
-		fee.Bytes(),
-		slashAmount.Bytes(),
-	))
-
-	return divAccountHash, nil
+ fee, _ := big.NewInt(0).SetString(da.FeeAmount, 10)
+ slashAmount, _ := big.NewInt(0).SetString(da.SlashedAmount, 10)
+ divAccountHash := crypto.Keccak256(appendBytes32(
+  new(big.Int).SetUint64(uint64(da.ID)).Bytes(),
+  fee.Bytes(),
+  slashAmount.Bytes(),
+ ))
+
+ return divAccountHash, nil
 }
 ```