PoS: edits

Author: nadimkobeissi

docs/pos/api/index.md

@@ -1 +1 @@
-Auto-generated, apparently.
+This section is meant to be auto-generated soon.

docs/pos/architecture/heimdall/validation.md

@@ -1,24 +1,26 @@
-Heimdall's "Ante handler" is responsible for checking and validating all transactions. After verification, it checks the balance of the sender for enough fees and deduct fees in case of successful transaction inclusion.
+Heimdall's "Ante Handler" plays a crucial role in the integrity and efficiency of transaction processing. It is primarily responsible for the preliminary verification and validation of all transactions, ensuring that they meet the necessary criteria before being included in a block. This includes checking the sender's balance to ensure there are sufficient funds to cover transaction fees and subsequently deducting these fees for successful transactions.
 
-## Gas limit
+## Advanced Gas Management in Heimdall
 
-Each block and transaction have a limit for gas usage. A block can contain multiple transactions, but gas used by all transactions in a block must be less than block gas limit to avoid larger blocks.
+### Block and Transaction Gas Limits
+
+Heimdall employs a gas limit system to regulate the computational and storage resources consumed by transactions and blocks. This system is designed to prevent excessive block sizes and ensure network stability.
+
+#### Block Gas Limit
+
+Each block in Heimdall has a maximum gas limit, constraining the total gas used by all transactions within the block. The sum of the gas used by each transaction in a block must not exceed this limit:
 
 ```go
 block.GasLimit >= sum(tx1.GasUsed + tx2.GasUsed + ..... + txN.GasUsed)
 ```
 
-Note that each state manipulation on transaction costs gas, including signature verification for the transaction.
-
-### Block gas limit
-
-Max block gas limit and bytes per block is passed while setting up app's consensus params: [https://github.com/maticnetwork/heimdall/blob/develop/app/app.go#L464-L471](https://github.com/maticnetwork/heimdall/blob/develop/app/app.go#L464-L471)
+The maximum block gas limit and block size are specified as part of the consensus parameters during the application setup, as seen in the Heimdall source code at [app.go#L464-L471](https://github.com/maticnetwork/heimdall/blob/develop/app/app.go#L464-L471):
 
 ```go
 maxGasPerBlock   int64 = 10000000 // 10 Million
 maxBytesPerBlock int64 = 22020096 // 21 MB
 
-// pass consensus params
+// Setting consensus parameters
 ConsensusParams: &abci.ConsensusParams{
  Block: &abci.BlockParams{
   MaxBytes: maxBytesPerBlock,
@@ -28,26 +30,30 @@ ConsensusParams: &abci.ConsensusParams{
 },
 ```
 
-### Transaction Gas limit
+#### Transaction Gas Limit
 
-The transaction gas limit is defined in params in `auth` module. It can be changed through the Heimdall `gov` module.
+For individual transactions, the gas limit is determined by parameters in the `auth` module and can be modified through Heimdall's governance (`gov`) module.
 
-### Checkpoint transaction gas limit
+#### Special Handling of Checkpoint Transactions
 
-Since block contains multiple transactions and verifies this particular transaction on the Ethereum chain, Merkle proof is required. To avoid extra Merkle proof verification for checkpoint transaction, Heimdall only allows one transaction in the block if the transaction type is `MsgCheckpoint`
+Checkpoint transactions, which require Merkle proof verification on the Ethereum chain, are treated distinctly. To streamline processing and avoid the overhead of additional Merkle proof verification, Heimdall restricts blocks containing a `MsgCheckpoint` transaction to just that one transaction:
 
 ```go
-// fee wanted for checkpoint transaction
+// Gas requirement for checkpoint transaction
 gasWantedPerCheckpoinTx sdk.Gas = 10000000 // 10 Million
 
-// checkpoint gas limit
+// Special gas limit handling for checkpoint transactions
 if stdTx.Msg.Type() == "checkpoint" && stdTx.Msg.Route() == "checkpoint" {
  gasForTx = gasWantedPerCheckpoinTx
 }
 ```
 
-## Transaction verification and replay protection
+## Enhanced Transaction Verification and Replay Protection
+
+The Ante Handler in Heimdall is instrumental in ensuring the legitimacy and uniqueness of transactions. It performs a thorough verification of incoming transactions, including signature validation, as delineated in the source code at [ante.go#L230-L266](https://github.com/maticnetwork/heimdall/blob/develop/auth/ante.go#L230-L266).
+
+### Sequence Number for Replay Protection
 
-Ante Handler handles and verifies signature in incoming transaction: [https://github.com/maticnetwork/heimdall/blob/develop/auth/ante.go#L230-L266](https://github.com/maticnetwork/heimdall/blob/develop/auth/ante.go#L230-L266)
+A critical aspect of transaction security in Heimdall is the use of a `sequenceNumber` in each transaction. This feature is a safeguard against replay attacks, where a transaction might be fraudulently or mistakenly repeated. To prevent such scenarios, the Ante Handler increments the sequence number for the sender's account after each successful transaction. This incrementation ensures that each transaction is unique and that previous transactions cannot be replayed.
 
-Each transaction must include `sequenceNumber` to avoid replay attacks. After each successful transaction inclusion, Ante handler increases the sequence number for the TX sender account to avoid duplication (replay) of the previous transactions.
+In summary, Heimdall's Ante Handler, along with its sophisticated gas management and transaction verification systems, provides a robust framework for secure and efficient transaction processing. The careful balance of block and transaction gas limits, coupled with advanced replay protection mechanisms, ensures the smooth operation of the Heimdall chain within the Polygon network.

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

@@ -2,15 +2,30 @@ If you are an Ethereum developer, you are already a Polygon developer. Simply sw
 
 You can deploy decentralized applications to either Polygon Mumbai Testnet or the Mainnet. The Polygon Mumbai Testnet connects with the Ethereum Goërli Testnet, which acts as its ParentChain. You can find all the network-related details in the [network documentation](https://github.com/0xPolygon/wiki/blob/master/docs/operate/network.md).
 
-### Wallets
+## Overview
+
+Polygon consists of the three following layers:
+
+- Ethereum layer — a set of contracts on the Ethereum mainnet.
+- Heimdall layer — a set of proof-of-stake Heimdall nodes running in parallel to the Ethereum mainnet, monitoring the set of staking contracts deployed on the Ethereum mainnet, and committing the Polygon Network checkpoints to the Ethereum mainnet. Heimdall is based on Tendermint.
+- Bor layer — a set of block-producing Bor nodes shuffled by Heimdall nodes. Bor is based on Go Ethereum.
+
+To be a validator on the Polygon Network, you must run:
+
+- Sentry node — a separate machine running a Heimdall node and a Bor node. A sentry node is open to all nodes on the Polygon Network.
+- Validator node — 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.
+
+
+## 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).
 
-### Smart Contracts
+## 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).
 
-### Connecting to Polygon
+## 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/).
 
@@ -36,6 +51,13 @@ 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 reach out to us via any social media channel.
+    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.
@@ -59,43 +81,3 @@ If you already have a decentralized application (dApp) and are looking for a pla
 1. **Easily migrate from Ethereum Virtual Machine (EVM) based chain**: Polygon prides itself in being the ultimate Layer-2 scaling solution for Ethereum. You don't have to worry about the underlying architecture while moving or deploying your dApps to the Polygon Network as long as it is EVM-compatible.
 2. **Use Polygon as a faster transaction layer**: Deploying your dApp to the Polygon Mainnet allows you to leverage Polygon as a faster transaction layer for your dApp. Additionally, you can get your tokens mapped by us. You can join our [technical discussions group](http://bit.ly/matic-technical-group) on Telegram to learn more.
 
-## Side Note
-
-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 reach out to us via any social media channel.
-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.
-
-## Overview
-
-Polygon consists of the three following layers:
-
-- Ethereum layer — a set of contracts on the Ethereum mainnet.
-- Heimdall layer — a set of proof-of-stake Heimdall nodes running in parallel to the Ethereum mainnet, monitoring the set of staking contracts deployed on the Ethereum mainnet, and committing the Polygon Network checkpoints to the Ethereum mainnet. Heimdall is based on Tendermint.
-- Bor layer — a set of block-producing Bor nodes shuffled by Heimdall nodes. Bor is based on Go Ethereum.
-
-To be a validator on the Polygon Network, you must run:
-
-- Sentry node — a separate machine running a Heimdall node and a Bor node. A sentry node is open to all nodes on the Polygon Network.
-- Validator node — 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.
-
-## Components
-
-### Heimdall
-
-Heimdall does the following:
-
-- Monitors the staking contracts on the Ethereum mainnet.
-- Verifies all state transitions on the Bor chain.
-- Commits the Bor chain state checkpoints to the Ethereum mainnet.
-
-Heimdall is based on Tendermint.
-
-### Bor
-
-Bor does the following:
-
-- Produces blocks on the Polygon Network.
-
-Bor is the Block producer node and layer for the Polygon Network. It is based on Go Ethereum. Blocks produced on Bor are validated by Heimdall nodes.

docs/pos/how-to/index.md

@@ -1 +1 @@
-This introductory page is currently being written. In the meantime, please review documentation existing under this section, which, in all likelihood, is also in a relatively early editorial state.
+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.

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

@@ -1 +1 @@
-This introductory page is currently being written. In the meantime, please review documentation existing under this section, which, in all likelihood, is also in a relatively early editorial state.
+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.

docs/pos/spec/index.md

@@ -1 +1 @@
-This introductory page is currently being written. In the meantime, please review documentation existing under this section, which, in all likelihood, is also in a relatively early editorial state.
+This introductory page is currently being written.