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

Nadim Kobeissi · web-flow · commit 8009bc2ddda5 · 2023-12-08T15:56:22.000+01:00
update - CDK intros done
diff --git a/docs/cdk/concepts/dac.md b/docs/cdk/concepts/dac.md
@@ -24,7 +24,7 @@ The CDK validium DAC is a secure consortium of nodes that ensures off-chain data
 
 ## DAC data flow
 
-![CDK validium DAC dataflow](../../img/cdk/zksupernets-dac.png)
+![CDK validium DAC dataflow](../../img/cdk/cdk-val-dac-02.png)
 
 The DAC works together with the sequencer to control the flow of data. The process can be broken down as follows:
 
diff --git a/docs/cdk/concepts/index.md b/docs/cdk/concepts/index.md
@@ -1 +1,3 @@
-Welcome to the Concepts section.
+This section covers some of the basic concepts needed to understand the CDK setting, which is a platform designed to allow developers to choose between validium and zk-rollup architectures.
+
+Concepts such as a rollup, a validium and data availability committee (DAC) are defined. Implications of off-chain data availability are briefly discussed.
diff --git a/docs/cdk/concepts/validium.md b/docs/cdk/concepts/validium.md
@@ -1,4 +1,4 @@
-Validiums are blockchain scaling solutions that do not store transaction data.
+Validiums are blockchain scaling solutions that do not store transaction data on-chain.
 
 !!! info "Recommended resource"
     See Ethereum.org's detailed [description of validiums](https://ethereum.org/en/developers/docs/scaling/validium/).
diff --git a/docs/cdk/how-to/index.md b/docs/cdk/how-to/index.md
@@ -1 +1,4 @@
-This introduction to the how to section is being written.
+This section describes how to manage policies pertaining to data access in the case of a Validium.
+
+Validia store data off-chain, and with this option comes the need to manage both the data and access to the data. This is facilitated through policies that stipulate which addresses can have access to data. Lists of addresses, such as the Allowlist and Denylist, are therefore kept to exclude or include certain addresses to having access.
+
diff --git a/docs/cdk/spec/index.md b/docs/cdk/spec/index.md
@@ -1 +1,7 @@
-This introduction to the specification section is being written.
+This section gives a comparison between a validium and a zk-rollup. 
+
+The main difference is the fact that a validium has a data availability layer whereas a zk-rollup does not. This difference alone is the reason for the substantially reduced gas fees for a validium compared to the zk-rollup.
+
+However, with this off-chain data availability, there is a trade-off between gas fees and security. Unlike in the zk-rollup, where forced batches are activated, the validium suffers from the possibility for the sequencer to go offline or the DAC to collude among themselves to withold state data.
+
+What remains common between the two architectures is the generation of proofs.
diff --git a/docs/img/cdk/cdk-val-dac-02.png b/docs/img/cdk/cdk-val-dac-02.png
diff --git a/docs/pos/architecture/index.md b/docs/pos/architecture/index.md
@@ -1,9 +1,19 @@
 # Architecture
 
+Due to the proof-of-stake consensus, Polygon PoS consists of a consensus layer called Heimdall and execution layer called Bor.
+
+Nodes on Polygon are therefore designed with a two-layer implementation represented by Bor (the block producer layer) and Heimdall (the validator layer).
+
+This section provides architectural details of Polygon PoS. 
+
+In particular, and on the execution client side, it delineates on snapshots and state syncing, network configurations, and frequently used commands when running PoS nodes.
+
+On the consesus client side, one finds descriptions on how Heimdall handles; authentication of account addresses, management of validators' keys, management of gas limits, enhancement of transaction verifications, balance transfers, staking and general chain management.   
+
+<!-- 
 <div class="flex-figure" markdown="1">
-<div class="flex-figure-left" markdown="1">
+<div class="flex-figure-left" markdown="1"> -->
 
-On Polygon, the node is designed with a two-layer implementation represented by Bor (the block producer layer) and Heimdall (the validator layer).
 
 </div>
 <div class="flex-figure-right">
diff --git a/docs/pos/concepts/index.md b/docs/pos/concepts/index.md
@@ -1 +1,6 @@
-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 section covers basic concepts necessary in understanding a few more aspects about Polygon PoS. Specifically the network's native token MATIC and its proposed replacement POL, two Ethereum improvement proposals (EIP-1559 and EIP-4337) pertaining to gas estimations, transaction costs, as well as account abstraction.
+
+The section contains an elaborate discussion on the proposed transition from MATIC to POL as the Polygon PoS's native token. The POL subsection defines the POL token and continues to present, in a question-and-answer (Q&A) format, all the information that users need to know about the proposed transition. A subsequent subsection defines what the MATIC token is, gives an example script to send MATIC tokens from one account to another, the three different ways to acquire MATIC tokens and finally how to obtain test MATIC tokens.
+
+In the Transactions subsection is a brief discussion on the types of transactions, how legacy transaction format works, and ways in which different types of transactions can be sent.
+
diff --git a/docs/pos/concepts/tokens/index.md b/docs/pos/concepts/tokens/index.md
@@ -1 +1,5 @@
-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.
+The Tokens subsection focuses on the proposed Polygon PoS's native token POL and the soon to be replaced native token MATIC.
+
+The POL subsection defines the POL token and continues to present, in a question-and-answer (Q&A) format, all the information that users need to know about the proposed transition.
+
+The subsequent MATIC subsection defines what the MATIC token is, gives an example script to send MATIC tokens from one account to another, the three different ways to acquire MATIC tokens and finally how to obtain test MATIC tokens.
diff --git a/docs/pos/concepts/transactions/index.md b/docs/pos/concepts/transactions/index.md
@@ -1 +1,8 @@
-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.
+
+
+The Transactions subsection provides information about the EIP-1559 as it applies to how gas estimations and costing of transations work on Polygon PoS. Further on, are discussions on new and old types of transaction formats and how they are processed in Polygon PoS.
+
+Regarding account abstraction, the subsection contains a simplified overview of the different components of ERC-4337 and how these components work together. These are altogether; `UserOperation`, `Bundler`, `EntryPoint`, and `Contract Account`. Optional ERC-4337 components are `Paymasters` and `Aggregators`.
+
+There is a extra subsection discussion several aspects of the so-called Meta-transactions. These are transactions that allow anyone to interact with the blockchain without requiring users to have tokens in order to pay for the network’s services. 
+
diff --git a/docs/pos/get-started/building-on-polygon.md b/docs/pos/get-started/building-on-polygon.md
@@ -1,19 +1,23 @@
-If you are an Ethereum developer, you are already a Polygon developer. Simply switch to the [Polygon RPC](https://polygon-rpc.com/) and get started. All the tools you are familiar with on the Ethereum blockchain are supported on Polygon by default, such as Truffle, Remix, and Web3js.
+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. 
+
+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).
 
-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).
 
 ## Overview
 
-Polygon consists of the three following layers:
+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:
 
-- 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.
+  - 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 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).
 
-To be a validator on the Polygon Network, you must run:
+In order to be a validator on the Polygon Network, you need to:
 
-- 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.
+- 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 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.
 
 ## Wallets
diff --git a/docs/pos/get-started/index.md b/docs/pos/get-started/index.md
@@ -1 +1,3 @@
-To be written.
+This section of the documentation provides guidelines to building on the Polygon PoS network. It gives a brief architectural overview of the PoS network, and showcases how various developer toolings commonly used on Ethereum work seamlessly on Polygon PoS.
+
+It outlines how developers can build on Polygon PoS by connecting commonly used wallets such as Metamask and Arkane, deploying Ethereum smart contracts using Remix or developing a decentralized apps (dApps) using Fauna.
diff --git a/docs/pos/how-to/index.md b/docs/pos/how-to/index.md
@@ -1 +1,5 @@
-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.
+ 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.
diff --git a/docs/pos/how-to/operating/index.md b/docs/pos/how-to/operating/index.md
@@ -1 +1,3 @@
-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 subsection contains details on the requirements users need in order to setup the different types of Polygon PoS nodes, and guides on how to setup each type of a Polygon PoS node.
+
+Polygon PoS users can participate in the network in various ways. Depending on the extend to which each user wishes to participate and their individual computational capacity, they can connect to the network as; Full nodes, Validator nodes, Access nodes, Archive nodes or Erigon nodes. Details on each of these nodes, and their requirements, are elaborated on in the ensuing sub-subsections.
diff --git a/docs/zkEVM/concepts/index.md b/docs/zkEVM/concepts/index.md
@@ -1,7 +1,7 @@
 This section covers some of the basic concepts crucial to understanding the design approach of Polygon zkEVM. Since Polygon zkEVM emulates the EVM, a few EVM basics are herein detailed.
 
-One of the differences between Polygon zkEVM and Ethereum is in the way their states are recorded. Ethereum uses Patricia Merkle tries while Polygon zkEVM uses Sparse Merkle trees (SMTs). The Concepts section therefore discusses how SMTs are constructed and the Create, Read, Update and Delete operations executed on the SMTs.
+One of the differences between Polygon zkEVM and Ethereum is in the way their states are recorded. Ethereum uses Patricia Merkle tries while Polygon zkEVM uses Sparse Merkle trees (SMTs). The Concepts section therefore discusses how SMTs are constructed and the operations executable on the SMTs. These are Create, Read, Update and Delete, or simply CRUD.
 
-The design approach is delineated in terms of an example: the multiplicative Fibonacci state machine. Further details of the Polygon zkEVM design are given in the form of a 'Generic state machine', which involves a program written in zkASM called the ROM.
+The design approach is delineated in terms of an example: the multiplicative Fibonacci state machine. Further details of the Polygon zkEVM's state machine design are given in the form of a 'Generic state machine', which involves a program written in zkASM called the ROM.
 
 This section also includes a brief discussion on what CIRCOM is, and how it is used in the zkProver.
diff --git a/docs/zkEVM/get-started/index.md b/docs/zkEVM/get-started/index.md
@@ -1,4 +1,4 @@
-This documentation contains guides on how to connect wallets to the Polygon zkEVM network, deploy new or existing Ethereum smart contracts, and bridge assets between Polygon zkEVM and Ethereum.
+This section of the documentation contains guides on how to connect wallets to the Polygon zkEVM network, deploy new or existing Ethereum smart contracts, and bridge assets between Polygon zkEVM and Ethereum.
 
 Developers can herein find guides to setting up an RPC zkNode, spinning up a production zkNode, or even implementing their own fully-fledged zkEVM.
 
