Review comments from docs team

Author: Jarrod Watts

docs/cdk/concepts/admin-upgradeability.md

@@ -0,0 +1,18 @@
+# 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 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:
+
+1. The [security council](https://docs.polygon.technology/zkEVM/architecture/protocol/security-council/) ([contract address](https://etherscan.io/address/0x37c58Dfa7BF0A165C5AAEdDf3e2EdB475ac6Dcb6)) that can be used to trigger the [emergency state](https://docs.polygon.technology/zkEVM/architecture/protocol/malfunction-resistance/emergency-state/) which can pause bridge functionality, prevent smart contract upgrades, or stop the [sequencer](./architecture.md#sequencer) from [sequencing batches](./transaction-lifecycle.md#sequenced).
+
+2. The [admin role](https://docs.polygon.technology/zkEVM/architecture/protocol/admin-role/) ([contract address](https://etherscan.io/address/0x242daE44F5d8fb54B198D03a94dA45B5a4413e21)) that can perform upgrades to patch bug fixes or add new features to the system by upgrading smart contracts with a 10-day waiting period (unless [emergency state](https://docs.polygon.technology/zkEVM/architecture/protocol/malfunction-resistance/emergency-state/) is active).
+
+## Further reading
+
+- [zkEVM protocol upgradability](https://docs.polygon.technology/zkEVM/architecture/protocol/upgradability/)
+- [zkEVM admin role and governance](https://docs.polygon.technology/zkEVM/architecture/protocol/admin-role/)
+- [zkEVM upgrade process](https://docs.polygon.technology/zkEVM/architecture/protocol/upgrade-process/)
+- [zkEVM security council](https://docs.polygon.technology/zkEVM/architecture/protocol/security-council/)
+- [zkEVM emergency state](https://docs.polygon.technology/zkEVM/architecture/protocol/malfunction-resistance/emergency-state/)
+- [L2Beat - Polygon zkEVM](https://l2beat.com/scaling/projects/polygonzkevm?selectedChart=activity)

docs/cdk/concepts/architecture.md

@@ -0,0 +1,44 @@
+# Architecture
+
+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 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
+
+Chains built with the CDK are EVM-compatible by default. Although the [type of ZK-EVM](https://docs.polygon.technology/cdk/architecture/type-1-prover/intro-t1-prover/#type-definitions) you choose to implement is customizable, CDK chains are designed to be compatible with existing Ethereum tools and libraries.
+
+This means both users and developers can use the same wallets (such as MetaMask) and libraries (such as Ethers.js) to interact with CDK-built chains as they do with Ethereum.
+
+The process for submitting transactions is the same as on Ethereum, using the same [JSON-RPC](https://ethereum.org/en/developers/docs/apis/json-rpc/) interface. Transactions are submitted directly to the L2 and go into a pending transaction pool.
+
+## Sequencer
+
+The sequencer is responsible for two vital tasks in the system:
+
+1. Executing transactions submitted by L2 users.
+2. Sending batches of transactions to the L1 smart contract.
+
+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 periodically creates batches of transactions and sends multiple batches of transactions to the L1 smart contract in a single transaction.
+
+## L1 smart contracts
+
+Multiple smart contracts, deployed on the L1 (Ethereum), 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 to prove the validity of the transactions.
+
+## Aggregator and prover
+
+The aggregator is responsible for periodically reading batches of L2 transactions 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 proof back to the L1 smart contract.
+
+## Further reading
+
+- [zkEVM architecture overview](https://docs.polygon.technology/zkEVM/architecture/high-level/overview/)

docs/cdk/concepts/blocks.md

@@ -0,0 +1,56 @@
+# Batches, blocks, and transactions
+
+The following concepts are key to understanding how transactions are handled on L2s built with the CDK:
+
+- 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.
+
+See the figure below to best understand how these concepts relate to each other. We follow a real transaction from the Polygon zkEVM to track how it first gets included in a block on the L2, then a batch, and finally, a sequence 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 leverage familiar tools and libraries, like MetaMask and Ethers.js, typically used for interacting with Ethereum, to send these transactions to CDK-built L2 chains.
+
+Transactions are included in blocks, and these blocks fill batches. Consider a Polygon zkEVM transaction as an example, [`0xdd`](https://zkevm.polygonscan.com/tx/0xdd3f79c24886310ddf868ad1d36aadc6a3b6495048f68aad765c658c42426ef8), which 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
+
+To link blocks together, blocks contain multiple transactions as well as the hash of the previous block in the chain. Following the transaction example from above, the `0xdd` transaction is included in block [`12952601`](https://zkevm.polygonscan.com/block/12952601), which contains [2 transactions in total](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 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).
+
+This means the batch `2041736` includes the two transactions from block `12952601` as well as eight transactions from other blocks.
+
+The presence of the `Sequence Tx Hash` field, associated with this batch, indicates that this batch has been sent to Ethereum along with other batches in a single transaction.
+
+![Batch of transactions](../../img/cdk/batch-overview.png)
+
+By inspecting the transactions in the batch, we can see:
+
+- Our original transaction example is included in this batch.
+- The batch contains many transactions from different blocks.
+
+![Transaction found inside batch](../../img/cdk/transaction-in-batch.png)
+
+If the L2 is a [rollup](./layer2s.md) (meaning it uses Ethereum for it’s [data availability](https://docs.polygon.technology/cdk/glossary/#data-availability)), it sends an array of batches to Ethereum, by providing the array as an argument to the `sequenceBatches` function of a smart contract on Ethereum.
+
+![Sequence Transaction](../../img/cdk/sequence-transaction.png)
+
+By inspecting the `Sequence Tx Hash` transaction, we can see that the `sequenceBatches` function is called with the array of batches as an argument. One of these batches is the batch we have been following, `2041736`, which contains our original transaction example:
+
+![Last Batch Sequenced](../../img/cdk/last-batch-sequenced.png)
+
+## Further reading
+
+- [Blocks in the zkEVM Etrog Upgrade](https://docs.polygon.technology/zkEVM/architecture/protocol/etrog-upgrade/?h=blocks#etrog-blocks)

docs/cdk/concepts/bridging.md

@@ -4,7 +4,7 @@
 
 CDK-built chains come with a built-in bridge service and customizable UI out of the box, with the option to have a standalone [LxLy bridge](#lxly-bridge) or alternatively opt-in to the AggLayer and use the [Unified Bridge](#unified-bridge) to enable cross-chain L2-to-L2 interoperability.
 
-## LxLy Bridge
+## LxLy bridge
 
 The LxLy bridge contracts carry out deposit and withdrawal of assets between L2 and L1.
 
@@ -16,7 +16,7 @@ This option is suited to chains that may want to customize how the bridge is man
 
 ![LxLy Bridge](../../img/cdk/lxly.png)
 
-## Unified Bridge
+## Unified bridge
 
 A single, shared instance of the LxLy bridge, called the [unified bridge](https://docs.polygon.technology/cdk/architecture/staking-the-bridge/) is available to use for all CDK chains that opt-in to the AggLayer. 
 
@@ -28,7 +28,7 @@ This option is suited to chains that want a standard bridging experience and do
 
 ![Unified Bridge](../../img/cdk/unified-bridge.png)
 
-## Further Reading
+## Further reading
 
 - [Aggregated Blockchains: A New Thesis](https://polygon.technology/blog/aggregated-blockchains-a-new-thesis)
 - [Unified Bridge Overview](https://docs.polygon.technology/zkEVM/architecture/protocol/unified-LxLy/lxly-bridge/)

docs/cdk/concepts/gas-fees.md

@@ -1,19 +1,11 @@
-# Gas Fees
+# Gas fees
 
-CDK-built chains have full control over how gas fees are set for users.
+CDK chains have full control over how gas fees are set for users, including what token to use for the native gas fees of the L2 chain, which is set to ETH by default.
 
-By default, gas fees on the L2 are paid in ETH and are determined by a combination of several factors, including the current gas price on Ethereum, the complexity of the submitted transaction, and the current demand on the L2 network itself.
-
-However, developers can use any [ERC-20 token](https://ethereum.org/en/developers/docs/standards/tokens/erc-20/) deployed on the L1 as their native gas token (see the [custom native gas token for a Polygon CDK chain tutorial](https://polygon.technology/blog/tutorial-launch-a-custom-native-gas-token-for-a-polygon-cdk-chain)).
 Gas fees can also be omitted entirely, allowing users to interact with the chain without needing to pay gas fees for transactions and have the fees covered by the chain operator.
 
-When building your chain, common options for gas fee configuration include:
-- Using ETH as the native gas token for easy onboarding from L1.
-- Using an existing ERC-20 token as the native gas token.
-- Sponsoring gas fees for all transactions.
-
-For more complex use cases, the CDK is also compatible with several [account abstraction providers](https://ecosystem.polygon.technology/spn/explore/?search=&competency=Wallet&chain=CDK) to provide more flexibility for users in regards to wallet support and gas fee payment.
+By default, gas fees on the L2 are determined by a combination of several factors, including the current gas price on Ethereum, the complexity of the submitted transaction, and the current demand on the L2 network itself.
 
-## Further Reading
+## Further reading
 
-- [zkEVM gas fees documentation](https://docs.polygon.technology/zkEVM/architecture/effective-gas/)
+- [zkEVM gas fees documentation](https://docs.polygon.technology/zkEVM/architecture/effective-gas/)

docs/cdk/concepts/layer2s.md

@@ -0,0 +1,24 @@
+# What is a layer 2 blockchain?
+
+Layer 2 (L2) blockchains are scaling solutions, typically built on top of Ethereum (L1) that are designed to increase transaction throughput without sacrificing decentralization or security.
+
+While L2s are their own chains, they are considered "extensions" of Ethereum. Users can submit transactions directly to L2 chains, which handle them more efficiently (in terms of cost and speed) than Ethereum.
+
+Under the hood, L2s create "batches" of transactions, and periodically submit many batches to Ethereum as a single transaction; potentially including information on thousands of transactions that occurred on the L2 in a single transaction on Ethereum.
+
+Typically, L2s deploy smart contracts to Ethereum that handle the verification of these batches, ensuring that the transactions are valid. Since this verification process occurs on Ethereum, it is often said that L2s inherit the security of Ethereum.
+
+![L2 Batching Overview](../../img/cdk/l2-overview-diagram.svg)
+
+## 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, or decentralization.
+
+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 not to send transaction data to Ethereum; instead relying on different data availability mechanisms.
+
+Since 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/)