Merge pull request 0xPolygon#676 from 0xPolygon/cdk-add-erigondocs

CDK Erigon docs - edits

Author: EmpieichO

docs/cdk/concepts/blocks.md

@@ -1,56 +1,64 @@
 # Batches, blocks, and transactions
 
-The following definition are key to understanding how transactions are handled on L2s built with the CDK:
+The following definitions are key to understanding how transactions are handled on L2s built with the CDK:
 
 - Transaction: A 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.
+Transactions are included in blocks, and these blocks fill batches, which are then sequenced. See the figure below to best understand how these elements relate to each other. 
 
 ![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.
+A transaction is a cryptographically signed instruction from an account to update the state of the blockchain. 
 
-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.
+Let's take a look at a real transaction in the Polygon zkEVM (which is in a way a CDK rollup), and inspect how the transaction is recorded in the [explorer](https://zkevm.polygonscan.com/) as part of a block, then a batch, and ultimately in a sequence.
+
+Consider the Polygon zkEVM transaction with the transaction hash, [`0xdd ... 6ef8`](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).
+Each block must include the hash of the previous block, along with multiple transactions, to establish a link to the block before it. 
+
+Continuing with the above transaction, identified by the hash `0xdd ... 6ef8` and contained in block [`12952601`](https://zkevm.polygonscan.com/block/12952601), we observe that this block 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`:
+Also, as depicted in the figure below, block `12952601` is in turn contained in 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).
+Batches contain multiple transactions from multiple blocks.
 
-This means the batch `2041736` includes the two transactions from block `12952601` as well as eight transactions from other blocks.
+The two transactions from our example block `12952601` are included in batch [`2041736`](https://zkevm.polygonscan.com/batch/2041736), which contains [10 transactions](https://zkevm.polygonscan.com/txs?batch=2041736) in total.
 
-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.
+This means batch `2041736` includes the two transactions from block `12952601` as well as eight transactions from other blocks.
+
+As observed in the figure below, the presence of the `Sequence Tx Hash` field associated indicates that the 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:
+Further inspection of the transactions in the batch, as depicted in the figure below, reveals that:
 
-- Our original transaction example is included in this batch.
-- The batch contains many transactions from different blocks.
+- Our transaction example, with hash `0xdd ... 6ef8`, is included in this batch.
+- The batch contains several 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](../glossary/index.md#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.
+Since Polygon zkEVM is a [rollup](./layer2s.md) (that is, it uses Ethereum for [data availability](../glossary/index.md#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:
+We can inspect the `Sequence Tx Hash` transaction to ascertain if batch `2041736`, containing our original transaction example, was indeed part of the argument to the `sequenceBatches()` function. 
+
+In this case, batch `2041736` happens to be the last batch to be sequenced, as depicted in the figure below.
 
 ![Last batch sequenced](../../img/cdk/last-batch-sequenced.png)
 
 ## Further reading
 
-- [Blocks in the zkEVM Etrog upgrade](../../zkEVM/architecture/protocol/etrog-upgrade.md/?h=blocks#etrog-blocks).
+- [Blocks in the zkEVM Etrog upgrade](../../zkEVM/architecture/protocol/etrog-upgrade.md/?h=blocks#etrog-blocks).

docs/cdk/getting-started/cdk-erigon/deploy-cdk-erigon.md

@@ -1,5 +1,7 @@
 ## Prerequisites
 
+There are a few prerequisites for successfully deploying the CDK node.
+
 ### Hardware requirements
 
 * A Linux-based OS (e.g. Ubuntu 22.04 LTS).
@@ -57,7 +59,7 @@ CDK_ERIGON_SEQUENCER=1 ./build/bin/cdk-erigon <flags>
 
 The sequencer supports a special recovery mode which allows it to continue the chain using data from the L1. 
 
-To enable this add the following flag:
+To enable this, add the following flag:
 
 ```sh
 `zkevm.l1-sync-start-block: [first l1 block with sequencer data]`. 
@@ -66,9 +68,9 @@ To enable this add the following flag:
 !!! important
     Find the first block on the L1 from the sequencer contract that contains the `sequenceBatches` event. 
 
-When the node starts up it pulls the L1 data into the `cdk-erigon` database and uses this during execution rather than waiting for transactions from the transaction pool, effectively rebuilding the chain from the L1 data. 
+When the node starts up, it pulls the L1 data into the `cdk-erigon` database and uses it during execution, effectively rebuilding the chain from the L1 data rather than waiting for transactions from the transaction pool. 
 
-You can use this in tandem with unwinding the chain, or using the `zkevm.sync-limit` flag to limit the chain to a certain block height before starting the L1 recovery. This is useful if you have an RPC node available to speed up the process.
+You can use this in tandem with unwinding the chain or by using the `zkevm.sync-limit` flag to limit the chain to a specific block height before starting the L1 recovery. This is useful if you have an RPC node available to speed up the process.
 
 !!! warning
     If using the `zkevm.sync-limit` flag, you need to go to the boundary of a `batch+1` block; so if batch `41` ends at block `99` then set the flag to `100`.
@@ -103,15 +105,18 @@ In order to enable the `zkevm_ namespace`, add `zkevm` to the [`http.api`](#conf
 
 - `zkevm_getBroadcastURI` - removed by zkEVM.
 
-## Limitations/warnings
+## Warnings
+
+- The instantiation of Poseidon over the Goldilocks field is much faster on x86, but developers using MacOS M1/M2 chips may experience slower processing.
 
-- The golden poseidon hashing is much faster on x86, so developers using MacOS M1/M2 chips may experience slower processing.
-- Falling behind the network significantly causes an SMT rebuild which takes some time to complete on longer chains.
+- Developers should avoid falling significantly behind the network, especially for longer chains, as this triggers an SMT rebuild, which takes a considerable amount of time to complete.
 
 ## Configuration files
 
-- Config files are the easiest way to configure `cdk-erigon`. 
+- Config files are the easiest way to configure `cdk-erigon`.
+
 - There are examples files in the repository for each network; e.g. [`hermezconfig-mainnet.yaml.example`](https://github.com/0xPolygonHermez/cdk-erigon/blob/1d56fb0a5a64160fd8c05e11ffc8b668bd70b9e8/hermezconfig-mainnet.yaml.example#L4).
+
 - Depending on your RPC provider, you may wish to alter `zkevm.rpc-ratelimit` in the yaml file.
 
 ## Running CDK Erigon

docs/cdk/getting-started/cdk-erigon/index.md

@@ -1,24 +1,24 @@
-[Erigon](https://github.com/ledgerwatch/erigon), previously known as Turbo-Geth, is a high-performance Ethereum client designed to handle the growing demands of the Ethereum blockchain. It focuses on optimizing performance, disk space, and synchronization speed. 
+CDK Erigon is the implementation of Erigon adapted to be a specialized framework for creating and managing chains that run the Polygon zkEVM protocol. Its code repository can be found at [0xPolygonHermez/cdk-erigon](https://github.com/0xPolygonHermez/cdk-erigon).
+
+## Erigon
 
-Erigon has a modular architecture, which makes it highly efficient and customizable for various common blockchain tasks.
+[Erigon](https://github.com/ledgerwatch/erigon), previously known as Turbo-Geth, is a high-performance Ethereum client designed to handle the growing demands of the Ethereum blockchain. It focuses on optimizing performance, disk space, and synchronization speed. 
 
-## Key features
+Erigon is characterized by the following features: Modular architecture, optimized performance, reduced disk usage, and fast synchronization.
 
-### Modular architecture
-Erigon's modular design allows different components to be developed, optimized, and updated independently. This separation of concerns helps in improving the performance and reliability of each module.
+- Erigon has a modular architecture, which makes it highly efficient and customizable for various common blockchain tasks. This allows different components to be developed, optimized, and updated independently. Such a separation of concerns helps in improving the performance and reliability of each module.
 
-### Performance optimization
-Erigon employs advanced techniques for data handling, such as memory-mapped files and optimized data structures, to ensure high-speed processing of blockchain data.
+- Erigon employs advanced techniques for data handling, such as memory-mapped files and optimized data structures, to ensure high-speed processing of blockchain data.
 
-### Reduced disk usage
-By implementing a more efficient database schema, Erigon significantly reduces disk usage compared to other Ethereum clients.
+- By implementing a more efficient database schema, Erigon significantly reduces disk usage compared to other Ethereum clients.
 
-### Fast synchronization
-Erigon's fast sync method allows nodes to catch up with the blockchain more quickly by downloading only the most recent state of the blockchain, rather than the entire history.
+- Erigon's fast sync method allows nodes to catch up with the blockchain more quickly by downloading only the most recent state of the blockchain, rather than the entire history.
 
 ## Erigon as a sequencer
 
-Blockchain sequencers play a critical role in ordering transactions and creating new blocks. Erigon's sequencer processes incoming transactions, organizes them into blocks, and propagates these blocks across the network. 
+L2 chains require sequencer nodes that play the critical role of ordering transactions and creating new blocks. 
+
+Erigon can act as a sequencer to process incoming transactions, organize them into blocks, and propagate the blocks across the network. 
 
 ## RPC node
 
@@ -28,18 +28,16 @@ The following sequence diagram shows how a transaction is processed by the Erigo
 
 ![Erigon transactions](../../../img/cdk/erigon.png)
 
-## CDK erigon 
-
-The CDK implementation of Erigon, available at [0xPolygonHermez/cdk-erigon](https://github.com/0xPolygonHermez/cdk-erigon), is a specialized adaptation that provides a framework for creating and managing zkEVM networks with that run using the zkEVM protocol.
+## CDK Erigon vs. Erigon
 
-### Differences from the standard erigon
+Next is a quick look at how CDK Erigon is different from standard Erigon.
 
-- zkEVM consensus mechanisms: The CDK implementation integrates with zkEVM consensus protocols.
+- The first difference between CDK Erigon and standard Erigon is the integration of Polygon zkEVM consensus protocols.
 
-- Optimized for layer 2 solutions: This adaptation is optimized for layer 2 scaling solutions which focus on high throughput and reduced transaction costs.
+- CDK Erigon is an adaptation of standard Erigon, optimized specifically for L2 scaling solutions where high throughput and reduced transaction costs are of paramount importance.
 
-- Enhanced modular architecture: While Erigon is already modular, the CDK implementation extends this modularity, allowing developers to more easily customize and replace components, such as the consensus mechanism, transaction pool, and state management.
+- While standard Erigon is modular by design, the CDK implementation further extends this architecture, enabling developers to easily customize and replace components. For instance, developers can customize the consensus mechanism, transaction pool, and state management.
 
-- Integration with the Polygon ecosystem: CDK Erigon is designed to seamlessly integrate with the broader Polygon ecosystem, facilitating interoperability with Polygon products and services, scaling solutions and tools.
+- CDK Erigon is designed to seamlessly integrate with the broader Polygon ecosystem, facilitating interoperability with Polygon's products, services, scaling solutions, and tools.
 
-- Tailored RPC interface: The RPC interface in the CDK implementation is adapted to support the zkEVM protocol's functionalities and optimizations, enabling more efficient communication and interaction with the network.
+- The RPC interface in the CDK implementation is adapted to support the functionalities and optimizations of the zkEVM protocol, enabling more efficient communication and interaction with the network.

docs/cdk/version-matrix.md

@@ -30,7 +30,7 @@ The table below shows the version compatibility for CDK releases and related com
     <td>CDK Elderberry 2 Release </td>
     <td>9</td>
     <td><a href="https://github.com/0xPolygonHermez/zkevm-node/releases/tag/v0.6.4">v0.6.4 Elderberry 2</a></td>
-    <td><a href="https://hub.docker.com/layers/0xpolygon/cdk-validium-node/0.6.4-cdk.8/images/sha256-b9527c8c4b26ab203efd8781066b7606321e5ea3b875371a59469ba163ee15f1?context=explore">0.6.4+cdk.6</a> </td>
+    <td><a href="https://hub.docker.com/layers/0xpolygon/cdk-validium-node/0.6.4-cdk.8/images/sha256-b9527c8c4b26ab203efd8781066b7606321e5ea3b875371a59469ba163ee15f1?context=explore">0.6.4+cdk.8</a> </td>
     <td><a href="https://hub.docker.com/layers/0xpolygon/cdk-data-availability/0.0.7/images/sha256-17590789a831259d7a07d8a042ea87e381c5708dec3a7daef6f3f782f50b2c00?context=explore">v0.0.7</a></td>
     <td><a href="https://github.com/0xPolygonHermez/zkevm-prover/releases/tag/v6.0.0">v6.0.0</a></td>
     <td> <a href="https://github.com/0xPolygonHermez/zkevm-contracts/releases/tag/v6.0.0-rc.1-fork.9">v6.0.0</a></td>

docs/img/cdk/sequence-batch-block-transaction.png

@@ -25,7 +25,7 @@ Version-1 consists mainly of three (3) smart contracts:
 
 - The bridge contract ([PolygonZkEVMBridge.sol](https://github.com/0xPolygonHermez/zkevm-contracts/blob/feature/v2ForkID5/contracts/PolygonZkEVMBridge.sol)), which handles transfer of assets and messages between networks.
 - The global exit root manager contract ([PolygonZkEVMGlobalExitRoot.sol](https://github.com/0xPolygonHermez/zkevm-contracts/blob/feature/v2ForkID5/contracts/PolygonZkEVMGlobalExitRoot.sol)), which facilitates synchronization of state-info between the L2 and the L1.
-- The Polygon zkEVM consensus contract ([PolygonZkEVM.sol](https://github.com/0xPolygonHermez/zkevm-contracts/blob/feature/v2ForkID5/contracts/PolygonZkEVM.sol)), which handles the sequencing and verification of transactions in the form of batches.
+- The Polygon zkEVM consensus contract ([PolygonZkEVMEtrog.sol](https://github.com/0xPolygonHermez/zkevm-contracts/blob/1ad7089d04910c319a257ff4f3674ffd6fc6e64e/contracts/v2/consensus/zkEVM/PolygonZkEVMEtrog.sol)), which handles the sequencing and verification of transactions in the form of batches.
 
 ### Global exit trees review
 
@@ -39,13 +39,13 @@ The root of the global exit tree is the single source of state-truth communicate
 
 It is the global exit root manager contract's responsibility to update the global exit tree root and acts as a custodian for the global exit tree's history.
 
-A complete transfer of assets in version-1 involves invoking three smart contracts; `PolygonZkEVM.sol`, `PolygonZkEVMBridge.sol` and `PolygonZkEVMGlobalExitRoot.sol`.
+A complete transfer of assets in version-1 involves invoking three smart contracts; `PolygonZkEVMEtrog.sol`, `PolygonZkEVMBridge.sol` and `PolygonZkEVMGlobalExitRoot.sol`.
 
 The below figure depicts a _bridge_ of assets and a _claim_ of assets;
 
 ![Figure 1: An asset transfer and three Smart Contracts](../../../img/zkEVM/lxly-1-v1-asset-transfer.png)
 
-Observe, in the above figure, that the consensus contract (`PolygonZkEVM.sol`) is able to:
+Observe, in the above figure, that the consensus contract (`PolygonZkEVMEtrog.sol`) is able to:
 
 - Retrieve the global exit root from the mainnet, and make it available in L2
 - Update the exit tree root in the global exit tree root manager.
@@ -78,8 +78,8 @@ Once sequenced batches have been verified, the _global exit tree_ gets updated,
 
 The rollup manager is in charge of the following lists of availability:
 
-- Rollup consensus mechanisms: The list may consist of consensus contracts such as `PolygonZkEVM.sol` or `zkValidium.sol`.
-- Verifier contracts: For example, the `PolygonZkEVM.sol` uses the `Verifier.sol` contract for verification of batches.
+- Rollup consensus mechanisms: The list may consist of consensus contracts such as `PolygonZkEVMEtrog.sol` or `zkValidium.sol`.
+- Verifier contracts: For example, the `PolygonZkEVMEtrog.sol` uses the `Verifier.sol` contract for verification of batches.
 
 The governance contract oversees consensus mechanisms and verifiers that can be added to the respective lists.