Proof reading

Author: Jarrod Watts

docs/cdk/concepts/admin-upgradeability.md

@@ -1,6 +1,6 @@
 # Admin Upgradeability
 
-As L2s work through the [stages of training wheels](https://medium.com/l2beat/introducing-stages-a-framework-to-evaluate-rollups-maturity-d290bb22befe) to become fully decentralized, chains built with the CDK that opt in to the [AggLayer](https://docs.polygon.technology/cdk/glossary/#agglayer-v1-al1) implement shared security mechanisms with other AggLayer chains including the [Polygon zkEVM](https://docs.polygon.technology/zkEVM/architecture/protocol/upgradability/) to ensure the safety of users.
+As L2s work through the [stages of training wheels](https://medium.com/l2beat/introducing-stages-a-framework-to-evaluate-rollups-maturity-d290bb22befe) to become fully decentralized, chains that opt in to the [AggLayer](https://docs.polygon.technology/cdk/glossary/#agglayer-v1-al1) implement shared security mechanisms with other AggLayer chains including the [Polygon zkEVM](https://docs.polygon.technology/zkEVM/architecture/protocol/upgradability/) to ensure the safety of users.
 
 Chains opted into the AggLayer share the following upgradeability controls:
 

docs/cdk/concepts/architecture.md

@@ -2,6 +2,8 @@
 
 While each chain built with the CDK is unique, they all share a common high-level architecture. Before diving into the specifics of how [transactions](./transaction-lifecycle.md) are processed, it’s helpful to first understand the role of each component in the system.
 
+Below is an overview of the high-level architecture of a chain built with the CDK, showing how transactions sent by users are processed and finalized on the L1:
+
 ![CDK Architecture](../../img/cdk/architecture-overview.png)
 
 ## Users
@@ -21,21 +23,21 @@ The sequencer is responsible for two vital tasks in the system:
 
 The sequencer reads transactions from the pending transaction pool and executes them on the L2, effectively updating the state of the L2 and providing this information back to the user. Once this process is complete _(typically in a matter of seconds)_, users are free to continue interacting with the L2 as if the transaction was finalized.
 
-In the background, the sequencer also periodically creates batches of transactions together and sends multiple batches of transactions to the L1 smart contract in a single transaction.
+In the background, the sequencer periodically creates batches of transactions and sends multiple batches of transactions to the L1 smart contract in a single transaction.
 
 ## L1 Smart Contracts
 
 Deployed on the L1 (Ethereum), multiple smart contracts work together to finalize transactions received from the L2 on the L1. Typically there is a main “rollup” smart contract that is responsible for:
 
 1. Receiving and storing batches of transactions from the L2 (depending on the design of the L2, it may not use Ethereum for [data availability](https://docs.polygon.technology/cdk/glossary/#data-availability)).
 
-2. Receiving and verifying ZK-proofs from the aggregator.
+2. Receiving and verifying ZK-proofs from the aggregator to prove the validity of the transactions.
 
 ## Aggregator & Prover
 
 The aggregator is responsible for periodically reading batches of transactions from the L2 that have not been verified yet, and generating ZK-proofs for them to prove their validity.
 
-To do this, the aggregator sends the batches of transactions to a **prover**. The prover generates ZK proofs and sends them back to the aggregator, which then posts the proofs back to the L1 smart contract.
+To do this, the aggregator sends the batches of transactions to a **prover**. The prover generates ZK proofs and sends them back to the aggregator, which then posts the proof back to the L1 smart contract.
 
 ## Further Reading
 

docs/cdk/concepts/blocks.md

@@ -1,34 +1,38 @@
 # Batches, Blocks, and Transactions
 
-To understand how transactions are handled on L2s built with the CDK, there are four key concepts to understand:
+To understand how transactions are handled on L2s built with the CDK, there are three key concepts to understand:
 
 - **Transaction**: Signed instruction to perform an action on the blockchain.
 - **Block**: A group of transactions and a hash of the previous block in the chain.
 - **Batch**: A group of many transactions from multiple blocks.
 
-To best understand how these concepts relate to each other, on this page, we will follow a real transaction from the Polygon zkEVM to see how it first gets included in a block on the L2, then in a batch, and finally, a sequence that is sent to Ethereum.
+To best understand how these concepts relate to each other, on this page, we will follow a real transaction from the Polygon zkEVM to track how it first gets included in a block on the L2, then in a batch, and finally, a sequence that is sent to Ethereum.
 
 ![Batches, blocks, transactions](../../img/cdk/sequence-batch-block-transaction.png)
 
 ## Transaction
 
 A transaction is a cryptographically signed instruction from an account to update the state of the blockchain. Users can send transactions to L2 chains built with the CDK using the same tools and libraries they use to interact with Ethereum such as MetaMask.
 
-Transactions are included in both blocks and batches. An example Polygon zkEVM transaction [`0xdd`](https://zkevm.polygonscan.com/tx/0xdd3f79c24886310ddf868ad1d36aadc6a3b6495048f68aad765c658c42426ef8) performs a `Simple Swap` function call, and part of block [`12952601`](https://zkevm.polygonscan.com/block/12952601) on the L2.
+Transactions are included in both blocks and batches. An example Polygon zkEVM transaction, [`0xdd`](https://zkevm.polygonscan.com/tx/0xdd3f79c24886310ddf868ad1d36aadc6a3b6495048f68aad765c658c42426ef8), performs a `Simple Swap` function call, and is included in block number [`12952601`](https://zkevm.polygonscan.com/block/12952601) on the L2.
 
 ![Transaction with Block Number](../../img/cdk/transaction-block.png)
 
 ## Block
 
-Blocks contain multiple transactions and the hash of the previous block in the chain to link blocks together. Following our example transaction from above, the `0xdd` transaction is included in block [`12952601`](https://zkevm.polygonscan.com/block/12952601), which contains [2 total transactions](https://zkevm.polygonscan.com/txs?block=12952601).
+Blocks contain multiple transactions as well as the hash of the previous block in the chain to link blocks together. Following our example transaction from above, the `0xdd` transaction is included in block [`12952601`](https://zkevm.polygonscan.com/block/12952601), which contains [2 total transactions](https://zkevm.polygonscan.com/txs?block=12952601).
+
+We can see this `0xdd` transaction is included in both a block and a batch, specifically, it is included in the block `12952601` and the batch `2041736`:
 
 ![Block and Batch](../../img/cdk/block-batch.png)
 
 ## Batch
 
 Batches contain multiple transactions from multiple blocks. The two total transactions from our example block `12952601` are included in batch [`2041736`](https://zkevm.polygonscan.com/batch/2041736), which contains [10 total transactions](https://zkevm.polygonscan.com/txs?batch=2041736).
 
-As there is also a `Sequence Tx Hash` field associated with this batch, we can infer that this batch is part of a sequence of batches that have already been sent to Ethereum.
+This means the batch `2041736` includes the two transactions from block `12952601` as well as eight transactions from other blocks.
+
+As there is a `Sequence Tx Hash` field associated with this batch, this means that this batch has been sent to Ethereum along with other batches in a single transaction.
 
 ![Batch of transactions](../../img/cdk/batch-overview.png)
 

docs/cdk/concepts/bridging.md

@@ -14,8 +14,6 @@ By default, chains launched using the CDK are opt-in to the AggLayer, enabling c
 
 This allows developers to build unique cross-chain experiences by integrating a `bridgeAndCall` function into their smart contracts, enabling users to call smart contract functions on other L2 chains without requiring users to bridge or hold tokens on the target chain.
 
-Learn more on the [zkEVM unified bridge documentation](https://docs.polygon.technology/zkEVM/architecture/protocol/unified-LxLy/ulxly-rollupmanager/).
-
 ## Further Reading
 
 - [Unified Bridge Overview](https://docs.polygon.technology/zkEVM/architecture/protocol/unified-LxLy/lxly-bridge/)

docs/cdk/concepts/layer2s.md

@@ -12,13 +12,13 @@ Typically, L2s deploy smart contracts to Ethereum that handle the verification o
 
 ## Types of Layer 2s
 
-L2s come in different shapes and sizes in terms of their relationship with Ethereum; each design decision comes with trade-offs in terms of security, scalability, decentralization, etc.
+L2s come in different shapes and sizes in terms of their relationship with Ethereum; each design decision comes with trade-offs in terms of security, scalability, or decentralization.
 
-For example, some L2s such as the Polygon zkEVM send all transaction data to Ethereum, whereas other L2s only send information about the state differences, or choose to not send transaction data to Ethereum at all; instead relying on different data availability mechanisms.
+For example, some L2s, such as the [Polygon zkEVM](https://docs.polygon.technology/zkEVM/) send all transaction data to Ethereum, whereas other L2s only send information about the state differences, or choose to not send transaction data to Ethereum at all; instead relying on different data availability mechanisms.
 
-As storing information on Ethereum is expensive, building an L2 chain requires a balance between security, decentralization and scalability. The CDK provides developers with the tools to make these trade-offs and build a chain that meets their specific needs depending on their use case.
+As storing information on Ethereum is expensive, (see [gas and fees](https://ethereum.org/en/developers/docs/gas/)), building an L2 chain means making tradeoffs between security, decentralization and scalability. The CDK provides developers with the tools to make these trade-offs and build a chain that meets their specific needs depending on their use case.
 
 ## Further Reading
 
-- [Ethereum documentation: layer 2s](https://ethereum.org/en/layer-2/)
-- [Ethereum documentation: scaling](https://ethereum.org/en/developers/docs/scaling/)
+- [Ethereum documentation: Layer 2s](https://ethereum.org/en/layer-2/)
+- [Ethereum documentation: Scaling](https://ethereum.org/en/developers/docs/scaling/)

docs/cdk/concepts/rollup-vs-validium.md

@@ -14,13 +14,15 @@ The CDK provides full flexibility to developers to choose what to do with transa
 
 ## Validiums
 
-Validiums **do not** store transaction data on Ethereum. Instead, they post ZK proofs called validity proofs to Ethereum that verify the state of the L2 chain.
+Validiums **do not** store transaction data on Ethereum. Instead, they only post ZK proofs called validity proofs to Ethereum that verify the state of the L2 chain.
 
-As the L2 does not pay the high gas fees associated with storing data on Ethereum, this approach is more cost-effective than rollups, meaning gas fees are also lower for users. However, validiums are typically considered less secure than rollups, as they rely on alternative data availability solutions such as a [Data Availability Committee (DAC)](https://docs.polygon.technology/cdk/glossary/#data-availability-committee-dac).
+As the L2 does not pay the high gas fees associated with storing data on Ethereum, this approach is more cost-effective than rollups, meaning gas fees are also lower for users. 
+
+However, validiums are typically considered less secure than rollups, as they store transaction data off of Ethereum using solutions such as a [Data Availability Committee (DAC)](https://docs.polygon.technology/cdk/glossary/#data-availability-committee-dac) or [alternative data availability solutions](#alternative-da-solutions).
 
 ### Alternative DA Solutions
 
-The CDK also supports the integration of alternative DA solutions, with support for networks such as [Avail DA](https://blog.availproject.org/avail-ecosystem-series-polygon-zkevm-validium/), [Celestia](https://polygon.technology/blog/celestias-high-throughput-out-of-the-box-data-availability-layer-to-integrate-with-polygon-cdk), [Near DA](https://pages.near.org/blog/near-da-integrates-with-polygon-cdk-for-developers-building-ethereum-zk-rollups/) and more.
+The CDK supports the integration of alternative DA solutions, including solutions such as [Avail DA](https://blog.availproject.org/avail-ecosystem-series-polygon-zkevm-validium/), [Celestia](https://polygon.technology/blog/celestias-high-throughput-out-of-the-box-data-availability-layer-to-integrate-with-polygon-cdk), [Near DA](https://pages.near.org/blog/near-da-integrates-with-polygon-cdk-for-developers-building-ethereum-zk-rollups/) and more.
 
 ## What's Best for You?
 
@@ -32,6 +34,10 @@ The method you use to store transaction data should be determined by your specif
 
 ![zkEVM Rollup vs Validium](../../img/cdk/zkevm-rollup-validium.png)
 
+## Default Configuration
+
+By default, chains built with the CDK are set up as a validium. For most use cases, this is the more suitable option as it offers lower gas fees and higher throughput, while still maintaining strong security guarantees provided by the use of validity proofs.
+
 ## Technical Comparison
 
 Below is a breakdown of the technical differences between a zkEVM rollup and validium:
@@ -51,9 +57,6 @@ Below is a breakdown of the technical differences between a zkEVM rollup and val
 
 <sub><sup>\*</sup>JSON RPC, Pool DB, Sequencer, Etherman, Synchronizer, State DB, Aggregator, Prover</sub>
 
-## Default Configuration
-
-By default, chains built with the CDK are set up as a validium. For most use cases, this is the more suitable option as it offers lower gas fees and higher throughput, while still maintaining strong security guarantees provided by the use of validity proofs.
 
 ## Further Reading
 

docs/cdk/concepts/transaction-finality.md

@@ -1,6 +1,6 @@
 # Transaction Finality
 
-Through the [transaction lifecycle](./transaction-lifecycle.md), transactions progress through three states of finality:
+Throughout the [transaction lifecycle](./transaction-lifecycle.md), transactions progress through three states of finality:
 
 1. **Trusted**: The transaction has been [submitted](./transaction-lifecycle.md#submitted) and [executed](./transaction-lifecycle.md#executed) on the L2. The user receives the result of the transaction and can continue to interact with the L2 chain.
 

docs/cdk/concepts/transaction-lifecycle.md

@@ -1,6 +1,7 @@
 # Transaction Lifecycle
 
-Chains built using the CDK go through a series of steps to eventually reach [finality](./transaction-finality.md) on Ethereum. Transactions submitted by users to an L2 built with the CDK go through the following lifecycle:
+Transactions on chains built using the CDK go through a series of steps to eventually reach [finality](./transaction-finality.md) on Ethereum.
+Specifically, they go through the following steps:
 
 1. **Submitted**: The transaction is submitted to the L2.
 2. **Executed**: The transaction is executed on the L2 by the sequencer.
@@ -10,7 +11,7 @@ Chains built using the CDK go through a series of steps to eventually reach [fin
 
 ## Submitted
 
-Just like Ethereum, users submit transactions to a “pool” of pending transactions on the L2. The transaction is submitted using the same interface as Ethereum, via [JSON-RPC](https://ethereum.org/en/developers/docs/apis/json-rpc/) which is implemented by tools such as MetaMask and developer libraries.
+Just like Ethereum, users submit transactions to a “pool” of pending transactions on the L2. The transaction is submitted using the same interface as Ethereum, via [JSON-RPC](https://ethereum.org/en/developers/docs/apis/json-rpc/) which is implemented by wallets such as MetaMask and developer libraries such as Ethers.js.
 
 ![User submitting transactions to L2](../../img/cdk/user-to-pending-pool.png)
 

docs/cdk/concepts/zk-vs-optimistic.md

@@ -18,13 +18,13 @@ If the fault proof is accepted, meaning there were fraudulent transactions poste
 
 The key advantage to optimistic rollups is that they are cost-effective. Because fraud proofs are only rarely submitted in the event of a dispute, the gas fees associated with optimistic rollups are lower than ZK rollups which are regularly posting proofs to Ethereum to prove the validity of transactions.
 
-There are several disadvantages to this approach, primarily that users cannot withdraw their funds until the challenge period has passed, and the security of the rollup is dependent on the honesty of the actors; i.e. at least one honest actor must be actively monitoring the rollup and submitting fault proofs to maintain the integrity of the chain, or the rollup could be compromised.
+However, there are several disadvantages to this optimistic approach; users cannot withdraw their funds until the challenge period has passed, and the security of the rollup is dependent on the honesty of the actors; i.e. at least one honest actor must be actively monitoring the rollup and submitting fault proofs to maintain the integrity of the chain, or the rollup could be compromised.
 
 ## Zero-Knowledge Rollups
 
 ZK rollups act on a "guilty until proven innocent" basis, meaning transactions are only considered valid once an associated validity proof (ZK proof) is posted and verified on Ethereum to prove the validity of transactions.
 
-By using cryptographic mechanisms for security, ZK rollups are generally considered more secure than optimistic rollups, as there is no situation where fraudulent transactions can be finalized, unlike optimistic rollups which rely on a challenge period to correct any fraudulent transactions.
+By using cryptographic mechanisms for security, ZK rollups are generally considered more secure than optimistic rollups; as there is no situation where fraudulent transactions can be finalized, unlike optimistic rollups which rely on a challenge period to correct any fraudulent transactions.
 
 As validity proofs are posted regularly to Ethereum to prove the validity of transactions (for example, see the [Polygon zkEVM trusted aggregator](https://etherscan.io/address/0x6329Fe417621925C81c16F9F9a18c203C21Af7ab)), the gas fees are typically slightly higher than optimistic rollups, as the L2 must pay Ethereum’s high gas fees to store data on the L1.