PoS: review update

Author: hsutaiyu

docs/pos/architecture/bor/commands.md

@@ -35,84 +35,84 @@ bor attach .bor/data/bor.ipc <command>
 | `heimdalld unsafe-reset-all` | Resets the database in case of issues. |
 | `curl localhost:26657/status` | Provides comprehensive information about Heimdall. |
 
-## Node Management Commands
+## Node management commands
 
 | Description                           | Command                                        |
 | ------------------------------------- | ---------------------------------------------- |
-| **Locate Heimdall genesis file**      | `$CONFIGPATH/heimdall/config/genesis.json`     |
-| **Locate heimdall-config.toml**       | `/etc/heimdall/config/heimdall-config.toml`    |
-| **Locate config.toml**                | `/etc/heimdall/config/config.toml`             |
-| **Locate heimdall-seeds.txt**         | `$CONFIGPATH/heimdall/heimdall-seeds.txt`      |
-| **Start Heimdall**                    | `$ sudo service heimdalld start`               |
-| **Start Heimdall rest-server**        | `$ sudo service heimdalld-rest-server start`   |
-| **Start Heimdall bridge-server**      | `$ sudo service heimdalld-bridge start`        |
-| **Locate Bor genesis file**           | `$CONFIGPATH/bor/genesis.json`                 |
-| **Start Bor**                         | `sudo service bor start`                       |
-| **Retrieve Heimdall logs**            | `/var/log/matic-logs/`                         |
-| **Check Heimdall logs**               | `tail -f heimdalld.log`                        |
-| **Check Heimdall rest-server logs**   | `tail -f heimdalld-rest-server.log`            |
-| **Check Heimdall bridge logs**        | `tail -f heimdalld-bridge.log`                 |
-| **Check Bor logs**                    | `tail -f bor.log`                              |
-
-## Useful Configuration Commands
-
-### Sync Status of Heimdall
+| Locate Heimdall genesis file      | `$CONFIGPATH/heimdall/config/genesis.json`     |
+| Locate heimdall-config.toml       | `/etc/heimdall/config/heimdall-config.toml`    |
+| Locate config.toml                | `/etc/heimdall/config/config.toml`             |
+| Locate heimdall-seeds.txt         | `$CONFIGPATH/heimdall/heimdall-seeds.txt`      |
+| Start Heimdall                    | `$ sudo service heimdalld start`               |
+| Start Heimdall rest-server        | `$ sudo service heimdalld-rest-server start`   |
+| Start Heimdall bridge-server      | `$ sudo service heimdalld-bridge start`        |
+| Locate Bor genesis file           | `$CONFIGPATH/bor/genesis.json`                 |
+| Start Bor                         | `sudo service bor start`                       |
+| Retrieve Heimdall logs            | `/var/log/matic-logs/`                         |
+| Check Heimdall logs               | `tail -f heimdalld.log`                        |
+| Check Heimdall rest-server logs   | `tail -f heimdalld-rest-server.log`            |
+| Check Heimdall bridge logs        | `tail -f heimdalld-bridge.log`                 |
+| Check Bor logs                    | `tail -f bor.log`                              |
+
+## Useful configuration commands
+
+### Sync Heimdall status
 
 To check if Heimdall is synced, run:
 
 ```bash
 curl http://localhost:26657/status
 ```
 
-### Latest Block Height on Heimdall
+### Latest block height on Heimdall
 
 To check the latest block height on Heimdall, run:
 
 ```bash
 curl localhost:26657/status
 ```
 
-### Latest Block Height on Bor
+### Latest block height on Bor
 
 To check the latest block height on Bor, use:
 
 ```bash
 curl http://<your ip>:8545 -X POST -H "Content-Type: application/json" -d '{"jsonrpc":"2.0", "id":1, "method":"bor_getSigners", "params":["0x98b3ea"]}'
 ```
 
-### Cleanup: Deleting Remnants of Heimdall and Bor
+### Cleanup: Deleting remnants of Heimdall and Bor
 
-##### For Linux package:
+##### For Linux package
 
 ```bash
 sudo dpkg -i matic-bor
 sudo rm -rf /etc/bor
 ```
 
-##### For Binaries:
+##### For binaries
 
 ```bash
 sudo rm -rf /etc/bor
 sudo rm /etc/heimdall
 ```
 
-### Terminate Bor Process
+### Terminate Bor process
 
-##### For Linux:
+##### For Linux package
 
 ```bash
 ps -aux | grep bor
 sudo kill -9 <PID>
 ```
 
-##### For Binaries:
+##### For binaries
 
 ```bash
 cd CS-2003/bor
 bash stop.sh
 ```
 
-### Retrieve Latest Peer Details
+### Retrieve latest peer details
 
 To retrieve the latest peer details, run:
 
@@ -124,16 +124,16 @@ admin.peers.forEach(function(value){
 exit
 ```
 
-### Stop Heimdall and Bor Services
+### Stop Heimdall and Bor services
 
-##### For Linux packages:
+##### For Linux packages
 
 ```bash
 sudo service heimdalld stop
 sudo service bor stop
 ```
 
-##### For Binaries:
+##### For binaries
 
 ```bash
 pkill heimdalld
@@ -142,16 +142,16 @@ cd CS-2001/bor
 bash stop.sh
 ```
 
-### Remove Heimdall and Bor Directories
+### Remove Heimdall and Bor directories
 
-##### For Linux packages:
+##### For Linux packages
 
 ```bash
 sudo rm -rf /etc/heimdall/*
 sudo rm -rf /etc/bor/*
 ```
 
-##### For Binaries:
+##### For binaries
 
 ```bash
 sudo rm -rf /var/lib/heimdalld/

docs/pos/architecture/bor/index.md

@@ -1,55 +1,55 @@
-Bor is an integral component of the Polygon network that operates based on principles derived from the Clique consensus protocol, detailed in [EIP-225](https://eips.ethereum.org/EIPS/eip-225). This consensus model is characterized by predefined block producers who collectively participate in a voting process to appoint new producers, taking turns in block generation.
+Bor is an integral component of the Polygon network that operates based on principles derived from the *Clique consensus protocol*, detailed in [EIP-225](https://eips.ethereum.org/EIPS/eip-225). This consensus model is characterized by predefined block producers who collectively participate in a voting process to appoint new producers, taking turns in block generation.
 
-## Proposers and Producers Selection
+## Proposers and producers selection
 
-Block Producers for the Bor layer are a committee selected from the validator pool on the basis of their stake, which happens at regular intervals and is shuffled periodically. These intervals are decided by the Validator's governance with regard to dynasty and network.
+Block producers for the Bor layer are a committee selected from the validator pool on the basis of their stake, which happens at regular intervals and is shuffled periodically. These intervals are decided by the validator's governance with regard to dynasty and network.
 
-The ratio of Stake/Staking power specifies the probability to be selected as a member of the block producer committee.
+The ratio of stake/staking power specifies the probability to be selected as a member of the block producer committee.
 
-#### Selection Process
+#### Selection process
 
 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.
 4. Using this validator set and Tendermint's proposer selection algorithm, we choose a producer for every sprint on Bor.
 
-## Detailed Mechanics of Bor Consensus
+## Detailed mechanics of Bor consensus
 
-### Validators in Polygon's Proof-of-Stake System
+### Validators in Polygon's Proof-of-Stake system
 
 In Polygon's Proof-of-Stake (PoS) framework, participants can stake MATIC tokens on a designated Ethereum smart contract, known as the "staking contract," to become validators. Active validators on Heimdall are eligible for selection as block producers through the Bor module.
 
-### Span: Defining Validator Sets and Voting Power
+### Span: Defining validator sets and voting power
 
 A span is a defined set of blocks, during which a specific subset of validators is selected from the broader validator pool. Heimdall provides intricate details of each span through its span-details APIs. Within a span, each validator is assigned a certain voting power. The probability of a validator being chosen as a block producer is directly proportional to their voting power. The selection algorithm for block producers is borrowed from Tendermint's consensus protocol.
 
-### Sprint: Single Block Producer Selection within a Span
+### Sprint: Single block producer selection within a span
 
 Within a span, a sprint is a smaller subset of blocks. For each sprint, only one block producer is selected to generate blocks. The size of a sprint is a fraction of the overall span size. Bor also designates backup producers, ready to step in if the primary producer is unable to fulfill its role.
 
-### Block Authorization by Producers
+### Block authorization by producers
 
 Block producers in Bor are also referred to as signers. To authorize a block, a producer signs the block's hash, encompassing all components of the block header except the signature itself. This signature is generated using the `secp256k1` elliptic curve algorithm and is appended to the `extraData` field of the block header.
 
 Each block is assigned a difficulty level. Blocks signed in-turn (by the designated producer) are given a higher difficulty (`DIFF_INTURN`) compared to out-of-turn signatures (`DIFF_NOTURN`).
 
-#### Handling Out-of-Turn Signing
+#### Handling out-of-turn signing
 
 Bor selects multiple backup producers to address situations where the designated producer fails to generate a block. This failure could be due to various reasons, including technical issues, intentional withholding, or other disruptions. The backup mechanism is activated based on a sequential order of validators and a predefined delay known as the "wiggle" time.
 
-#### Wiggle Time: Delay before Backup Production
+#### Wiggle time: Delay before backup production
 
 Wiggle time is the predefined delay a backup producer waits before starting to generate a block. This delay is calculated based on the last block's production time and a variable parameter known as `Period`. The wiggle time is dynamically adjusted based on the position of the backup producer in the validator sequence relative to the designated producer's position.
 
-#### Resolving Forks with Difficulty Metrics
+#### Resolving forks with difficulty metrics
 
 The potential for forks arises when backup producers generate blocks due to delays in block propagation. Bor addresses this by selecting the fork with the highest cumulative difficulty, reflecting the sequence of in-turn block production. The difficulty of a block is determined based on the validator's turn to produce the block, with in-turn production assigned the highest difficulty.
 
-### View Change and Span Commitment
+### View change and span commitment
 
 At the end of each span, Bor undergoes a view change, fetching new producers for the subsequent span. This involves an HTTP call to the Heimdall node to retrieve new span data and a `commitSpan` call to the `BorValidatorSet` genesis contract. Block headers in Bor are also structured to include producer bytes, aiding in the fast-syncing process.
 
-### State Synchronization with the Ethereum Chain
+### State synchronization with the Ethereum chain
 
 Bor features a mechanism to relay specific events from the Ethereum chain to Bor. This involves:
 

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

@@ -1,4 +1,4 @@
-`State Sync` is the native mechanism for a user in the Polygon PoS chain to read the latest Ethereum data.
+`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.
 
@@ -8,7 +8,7 @@ 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)
 2. Which emits an event called `StateSynced(uint256 indexed id, address indexed contractAddress, bytes data);`
-3. All the validators on the Heimdall chain receive this event and one of them, whoever wishes to get the tx fees for state sync sends this transaction to Heimdall.
+3. All the validators on the Heimdall chain receive this event and one of them, whoever wishes to get the transaction fees for state sync sends this transaction to Heimdall.
 4. Once `state-sync` transaction on Heimdall has been included in a block, it is added to pending state-sync list.
 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)
@@ -55,7 +55,7 @@ event StateSynced (
 );
 ```
 
-Once the `StateSynced` event is emitted on the `stateSender` contract on Ethereum, Heimdall listens to those events and adds to the Heimdall state after 2/3+ validators agree on the.
+Once the `StateSynced` event is emitted on the `stateSender` contract on Ethereum, Heimdall listens to those events and adds to the Heimdall state after $2/3+$ validators agree on the.
 
 After every sprint (currently 16 blocks on Bor), Bor fetches a new state-sync record and updates the state using a `system` call. Here is the code for the same: [https://github.com/maticnetwork/bor/blob/6f0f08daecaebbff44cf18bee558fc3796d41832/consensus/bor/genesis_contracts_client.go#L51](https://github.com/maticnetwork/bor/blob/6f0f08daecaebbff44cf18bee558fc3796d41832/consensus/bor/genesis_contracts_client.go#L51)
 
@@ -85,10 +85,10 @@ System call is helpful to change state to contract without making any transactio
 
 Events emitted by system calls are handled in a different way than normal logs. Here is the code: [https://github.com/maticnetwork/bor/pull/90](https://github.com/maticnetwork/bor/pull/90).
 
-Bor produces a new tx / receipt just for the client which includes all the logs for state-sync. Tx hash is derived from block number and block hash (last block at that sprint):
+Bor produces a new transaction/receipt just for the client which includes all the logs for state-sync. Transaction hash is derived from block number and block hash (last block at that sprint):
 
 ```jsx
 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 transaction in `transactionRoot` or `receiptRoot`.

docs/pos/architecture/heimdall/authentication.md

@@ -91,7 +91,7 @@ Use the following command to print account related data into Heimdall:
 heimdalld show-account
 ```
 
-Expected Result:
+Expected result:
 
 ```json
 {
@@ -102,13 +102,13 @@ Expected Result:
 
 ### Account and coin details
 
-To display account details, coins, sequence and account number;
+To display account details, coins, sequence and account number:
 
 ```bash
 heimdallcli query auth account 0x68243159a498cf20d945cf3E4250918278BA538E --trust-node
 ```
 
-Expected Result:
+Expected result:
 
 ```json
 address: 0x68243159a498cf20d945cf3e4250918278ba538e
@@ -129,7 +129,7 @@ Use the following command to print all params:
 heimdallcli query auth params
 ```
 
-Expected Result:
+Expected result:
 
 ```go
 max_memo_characters: 256

docs/pos/architecture/heimdall/balance-transfers.md

@@ -1,4 +1,4 @@
-Heimdall's `bank` module handles balance transfers between accounts. This module corresponds to the `bank` module from cosmos-sdk.
+Heimdall's `bank` module handles balance transfers between accounts. This module corresponds to the `bank` module from the Cosmos SDK.
 
 ## Messages
 

docs/pos/architecture/heimdall/chain-management.md

@@ -47,7 +47,7 @@ Use the following command to print all params:
 heimdallcli query chainmanager params --trust-node
 ```
 
-### Expected result
+Expected result:
 
 ```yaml
 tx_confirmation_time: 12s

docs/pos/architecture/heimdall/checkpoints.md

@@ -189,7 +189,7 @@ Expected Result:
 checkpoint_buffer_time: 16m40s
 ```
 
-### Send Checkpoint
+### Send checkpoint
 
 Following command sends checkpoint transaction on Heimdall:
 

docs/pos/architecture/heimdall/governance.md

@@ -1,4 +1,4 @@
-Heimdall's governance operates identically to the Cosmos-sdk `x/gov` module, as detailed in [Cosmos-sdk documentation](https://docs.cosmos.network/main/build/modules/gov).
+Heimdall's governance operates identically to the Cosmos SDK `x/gov` module, as detailed in [Cosmos SDK documentation](https://docs.cosmos.network/main/build/modules/gov).
 
 ## Overview
 

docs/pos/architecture/heimdall/heimdall-and-bor.md

@@ -157,7 +157,7 @@ Expected output:
 }
 ```
 
-### Query span by id
+### Query span by ID
 
 ```bash
 heimdallcli query bor span --span-id <span-id> --chain-id <heimdall-chain-id>
@@ -167,7 +167,7 @@ It prints the result in same format as above.
 
 ### Parameters
 
-To print all params;
+Use the following command to print all params:
 
 ```go
 heimdalldcli query bor params

docs/pos/architecture/heimdall/index.md

@@ -5,9 +5,9 @@ Heimdall is the heart of the Polygon PoS network. It performs the following func
 - Manages validators
 - Handles block producer selection
 - Facilitates spans
-- Orchestrates the state-sync mechanism between Ethereum and Matic
+- Orchestrates the state sync mechanism between Ethereum and Polygon PoS
 - Addresses other essential aspects of the system
 
-It uses the *Cosmos-SDK* and a forked version of Tendermint, called *Peppermint*. Here is the Peppermint source: [https://github.com/maticnetwork/tendermint/tree/peppermint](https://github.com/maticnetwork/tendermint/tree/peppermint)
+It uses the *Cosmos SDK* and a forked version of Tendermint, called *Peppermint*. Here is the Peppermint source: [https://github.com/maticnetwork/tendermint/tree/peppermint](https://github.com/maticnetwork/tendermint/tree/peppermint)
 
-Heimdall removes certain modules from Cosmos-SDK but primarily utilizes a customized version of it, following a similar pattern.
+Heimdall removes certain modules from Cosmos SDK but primarily utilizes a customized version of it, following a similar pattern.