Merge pull request 0xPolygon#550 from 0xPolygon/revert-549-revert-504-jw/cdk-docs

Revert "Revert "CDK: Overview, getting started, concepts""

Author: EmpieichO

docs/cdk/concepts/admin-upgradeability.md

@@ -0,0 +1,17 @@
+# 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 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
+
+Chains built with the CDK are EVM-compatible by default. While the [type of zkEVM](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) that they use to interact with Ethereum to interact with chains built with the CDK.
+
+The process to submit transactions is the same as 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 users on the L2.
+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
+
+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 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 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
+
+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 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 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 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).
+
+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)
+
+By inspecting the transactions in the batch, we can see:
+
+- Our original example transaction is included in this batch.
+- The batch contains many transactions from many 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 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 example transaction:
+
+![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

@@ -0,0 +1,19 @@
+# Bridging
+
+[Bridges](https://ethereum.org/en/developers/docs/bridges/) are a fundamental component of L2s. A core feature of chains built with the CDK is **interoperability**, which allows developers to access funds from Ethereum as well as other L2s when building dApps on your chain.
+
+## L1 <-> L2 Bridge
+
+CDK chains come with a built-in bridge service and customizable UI that enables users to move assets (both native and ERC20 tokens) between L1 and L2 or between different L2s.
+
+A key benefit to building ZK-powered L2s with the CDK is that there are no challenge periods unlike [optimistic rollups](./zk-vs-optimistic.md#optimistic-rollups), meaning users can move funds from the L2 to the L1 immediately after the [aggregation](./transaction-lifecycle.md#aggregated) process is complete (i.e. a ZK proof is posted & verified).
+
+## Unified Bridge
+
+By default, chains launched using the CDK are opt-in to the AggLayer, enabling cross-chain transactions via the unified bridge. The unified bridge enables cross-chain L2 to L2 transactions to other chains that have opted-in to the [AggLayer](https://polygon.technology/blog/aggregated-blockchains-a-new-thesis).
+
+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.
+
+## Further Reading
+
+- [Unified Bridge Overview](https://docs.polygon.technology/zkEVM/architecture/protocol/unified-LxLy/lxly-bridge/)

docs/cdk/concepts/gas-fees.md

@@ -0,0 +1,11 @@
+# Gas Fees
+
+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.
+
+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.
+
+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
+
+- [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 to not send transaction data to Ethereum at all; instead relying on different data availability mechanisms.
+
+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/)