architecture and transaction lifecycle

Author: jarrodwatts

docs/cdk/concepts/architecture.md

@@ -0,0 +1,38 @@
+# 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.
+
+![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 also periodically creates batches of transactions together 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.
+
+## 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.

docs/cdk/concepts/blocks.md

@@ -39,10 +39,10 @@ By inspecting the transactions in the batch, we can see:
 
 ![Transaction found inside batch](../../img/cdk/transaction-in-batch.png)
 
-If the L2 is a [rollup](./layer2s.md), 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.
+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.
+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)

docs/cdk/concepts/transaction-finality.md

@@ -0,0 +1,11 @@
+# Transaction Finality
+
+Through the [transaction lifecycle](./transaction-lifecycle.md), transactions progress through three states of finality:
+
+1. **Trusted**: The transaction has been **submitted** and **executed** on the L2. The user receives the result of the transaction and can continue to interact with the L2 chain.
+
+2. **Virtual**: The transaction has been **batched** and **sequenced**, meaning the batch containing the transaction has been sent to Ethereum. However, the ZK-proof to verify the validity of the transaction has not yet been posted and verified on Ethereum.
+
+3. **Consolidated**: A ZK-proof has been generated, posted, and verified on Ethereum. The transaction is now considered final at the L1 level. This means the user is free to withdraw their funds from the L2 chain back to Ethereum.
+
+![Transaction Finality](../../img/cdk/transaction-finality.png)

docs/cdk/concepts/transaction-lifecycle.md

@@ -0,0 +1,45 @@
+# 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:
+
+1. **Submitted**: The transaction is submitted to the L2.
+2. **Executed**: The transaction is executed on the L2 by the sequencer.
+3. **Batched**: The transaction is included in a batch of transactions.
+4. **Sequenced**: The batch containing the transaction is sent to Ethereum.
+5. **Aggregated**: A ZK-proof is generated, posted, and verified on Ethereum to prove the transaction is valid.
+
+## 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.
+
+![User submitting transactions to L2](../../img/cdk/user-to-pending-pool.png)
+
+## Executed
+
+The [sequencer](./architecture.md#sequencer) reads transactions from the pending transaction pool and executes them on the L2. Once executed, transactions are added to [blocks](./blocks.md#block), then the blocks fill [batches](./blocks.md#batch), and the sequencer’s local L2 state is updated.
+
+Once the state is updated, it is also broadcast to all other zkEVM nodes which provide the transaction information back to the user or application that submitted the transaction.
+
+At this point, the transaction appears complete to users, as they are provided with the result of whether the transaction was executed or reverted. Users can continue to interact with the chain with the updated state.
+
+![Transaction executed on L2](../../img/cdk/execution.png)
+
+## Batched
+
+As a background process, the [sequencer](./architecture.md#sequencer) is constantly creating [batches](./blocks.md#batch) of transactions. These batches contain multiple transactions from multiple [blocks](./blocks.md#block) on the L2.
+
+One field in the batch data structure is `transactions`, which contains a [`bytes`](https://docs.soliditylang.org/en/latest/types.html#bytes-and-string-as-arrays) representation of the transactions in the batch. This is generated by serializing each transaction in the batch using [RLP serialization](https://ethereum.org/en/developers/docs/data-structures-and-encoding/rlp/) and then concatenating them together.
+
+![Batch of transactions](../../img/cdk/batch-generation.png)
+
+## Sequenced
+
+Depending on the data availability design choices of the L2, if the L2 is a [rollup](./rollup-vs-validium.md#rollups), the sequencer sends arrays of batches to the [L1 smart contract](./architecture.md#l1-smart-contracts), where they are stored inside the state of the smart contract.
+
+![Sequence Batches](../../img/cdk/sequence-batches.png)
+
+## Aggregated
+
+The final step of the transaction lifecycle is to generate a ZK-proof that proves the batch of transactions is valid. Batches of transactions are read by the [aggregator](./architecture.md#aggregator) which utilizes a [prover](./architecture.md#prover) to generate a ZK-proof that is posted back to Ethereum.
+
+![Aggregator posting ZK-proof](../../img/cdk/aggregate-batches.png)