Merge pull request 0xPolygon#654 from 0xPolygon/empieichO-docs-review

zkEVM docs update as per team review

Author: EmpieichO

docs/cdk/agglayer/unified-bridge.md

@@ -8,7 +8,7 @@ The unified bridge is a single bridge contract on Ethereum, providing a safe, co
 
 ## Bridging mechanism
 
-The bridging mechanism enables token transfers and message-passing between Ethereum (L1) and CDK chains via smart contracts. Detailed in the [zkEVM bridging documentation](../../zkEVM/architecture/high-level/smart-contracts/bridging.md), core components include the bridge and exit root Solidity smart contracts.
+The bridging mechanism enables token transfers and message-passing between Ethereum (L1) and CDK chains via smart contracts. Detailed in the [zkEVM bridging documentation](../../zkEVM/architecture/high-level/unified-LxLy/bridging.md), core components include the bridge and exit root Solidity smart contracts.
 
 ## Data structures 
 

docs/cdk/concepts/bridging.md

@@ -8,7 +8,7 @@ CDK-built chains come with a built-in bridge service and customizable UI out of
 
 The LxLy bridge contracts carry out deposit and withdrawal of assets between L2 and L1.
 
-Chains looking to run their own bridge infrastructure can choose to deploy a new instance of the [LxLy bridge](../../zkEVM/architecture/protocol/unified-LxLy/lxly-bridge.md) that allows users to move assets (both native and [ERC20](https://ethereum.org/en/developers/docs/standards/tokens/erc-20/) tokens) from L1 to the L2 and vice versa.
+Chains looking to run their own bridge infrastructure can choose to deploy a new instance of the [LxLy bridge](../../zkEVM/architecture/high-level/unified-LxLy/lxly-bridge.md) that allows users to move assets (both native and [ERC20](https://ethereum.org/en/developers/docs/standards/tokens/erc-20/) tokens) from L1 to the L2 and vice versa.
 
 Deploying an individual instance of the LxLy means interoperability with other L2 chains via the [AggLayer](../agglayer/overview.md) is not possible. To enable cross-chain interoperability (i.e. L2-to-L2 cross-chain transactions), chains can opt-in to the AggLayer and use the [unified bridge](../agglayer/unified-bridge.md).
 
@@ -31,5 +31,5 @@ This option is suited to chains that want a standard bridging experience and do
 ## Further reading
 
 - [Aggregated blockchains: A new thesis](https://polygon.technology/blog/aggregated-blockchains-a-new-thesis).
-- [LxLy bridge](../../zkEVM/architecture/protocol/unified-LxLy/lxly-bridge.md).
+- [LxLy bridge](../../zkEVM/architecture/high-level/unified-LxLy/lxly-bridge.md).
 - [Unified bridge Ooverview](../agglayer/unified-bridge.md).

docs/zkEVM/architecture/high-level/smart-contracts/exit-roots.md

@@ -1,4 +1,4 @@
-An exit tree is a binary, append-only, sparse Merkle tree (SMT) whose leaf nodes store bridging data. The exit trees have a depth of 32.
+An exit tree is a binary, append-only, sparse Merkle tree (SMT) with a maximum depth of 32, where leaf nodes store bridging data.
 
 The Merkle root of an exit tree is known as the exit tree root, and it is the fingerprint of all the information recorded in the exit tree's leaf nodes. 
 
@@ -71,7 +71,7 @@ uint8 private constant _LEAF_TYPE_ASSET = 0;
 uint8 private constant _LEAF_TYPE_MESSAGE = 1;
 ```
 
-Data in a leaf contains a Keccak256 hash of the metadata (ABI encoded metadata if any) and the following parameters (matched by publicly available transaction data as seen in the [bridge L1 to L2](bridging.md#l1-to-l2) documentation):
+Data in a leaf contains a Keccak256 hash of the metadata (ABI encoded metadata if any) and the following parameters (matched by publicly available transaction data as seen in the [bridge L1 to L2](../unified-LxLy/bridging.md#l1-to-l2) documentation):
 
 ```solidity
 _addLeaf(

docs/zkEVM/architecture/high-level/smart-contracts/sequencing.md

@@ -13,9 +13,13 @@ The diagram below shows the sequencing workflow for rollup (non-validium) stacks
 
 ![Polygon Solidity smart contract architecture](../../../../img/cdk/high-level-architecture/sequencing-flow.png)
 
-## `sequenceBatches(batches, maxSequenceTs, initSequenceBatch, l2Coinbase)`
+## `sequenceBatches()`
 
-This function is called on the `PolygonZkEVMEtrog.sol` contract.
+The `sequenceBatches()` function is called on the `PolygonZkEVMEtrog.sol` contract:
+
+```
+sequenceBatches(batches, maxSequenceTs, initSequenceBatch, l2Coinbase)
+```
 
 The rollup sequencer component calls the [`sequenceBatches`](https://github.com/0xPolygonHermez/zkevm-contracts/blob/1ad7089d04910c319a257ff4f3674ffd6fc6e64e/contracts/v2/lib/PolygonRollupBaseEtrog.sol#L425) function on the [`PolygonZkEVMEtrog.sol`](https://github.com/0xPolygonHermez/zkevm-contracts/blob/1ad7089d04910c319a257ff4f3674ffd6fc6e64e/contracts/v2/consensus/zkEVM/PolygonZkEVMEtrog.sol) contract which inherits the function from [PolygonRollupBaseEtrog.sol](https://github.com/0xPolygonHermez/zkevm-contracts/blob/1ad7089d04910c319a257ff4f3674ffd6fc6e64e/contracts/v2/lib/PolygonRollupBaseEtrog.sol).
 
@@ -45,9 +49,13 @@ Stepwise, the function does the following:
 1. Calls the `PolygonRollupManager.onSequenceBatches(...)` function which waits for an `OnSequenceBatches(...)` event callback.
 1. Emits `SequenceBatches(...)` event.
 
-## `onSequenceBatches(newSequencedBatches, newAccInputHash)`
+## `onSequenceBatches()`
 
-This function is called on the `PolygonRollupManager.sol` contract.
+The `onSequenceBatches()` function is called on the `PolygonRollupManager.sol` contract:
+
+```
+onSequenceBatches(newSequencedBatches, newAccInputHash)
+```
 
 It takes the sequenced batches and the accumulated hash from the calling contract, adds the batches to the correct stack, and updates the batch count.
 
@@ -59,13 +67,18 @@ Stepwise, the function does the following:
 1. Attempts to consolidate pending state for the rollup by updating `lastVerifiedBatch`, `batchNumToStateRoot[]`, and `lastLocalExitRoot` state variables, and also by updating `globalExitRootManager.updateExitRoot(L2sLocalExitRoot)`, after which it emits a `ConsolidatePendingState(...)` event.
 1. Emits an `OnSequenceBatches(...)` event back to the original `sequenceBatches(...)` call.
 
-## `sequenceBatchesValidium(batches, l2Coinbase, dataAvailabilityMessage)`
+## `sequenceBatchesValidium()`
+
+The `sequenceBatchesValidium()` function is called on the `PolygonValidiumEtrog.sol` contract:
+
+```
+sequenceBatchesValidium(batches, l2Coinbase, dataAvailabilityMessage)
+```
 
 !!! info
     - This function is not included in the sequence diagram above.
     - The differences, however, are minimal.
 
-This function is called on the `PolygonValidiumEtrog.sol` contract.
 
 The sequencing logic is nearly the same as for the rollup `sequenceBatches(...)` function except the function takes a `ValidiumBatchData[]` array instead of `BatchData[]`. This means that, instead of passing the actual transaction data, the struct passes the hashes of the transactions.
 

docs/zkEVM/architecture/high-level/smart-contracts/verification.md

@@ -13,9 +13,14 @@ The sequence diagram below shows the verification workflow for rollup stacks and
 
 ![Polygon Solidity consensus verification flow](../../../../img/cdk/high-level-architecture/verification-flow.png)
 
-## `verifyBatchesTrustedAggregator(rollupID, pendingStateNum, initNumBatch, finalNewBatch, newLocalExitRoot, newStateRoot, beneficiary, proof)`
+## `verifyBatchesTrustedAggregator()`
 
-This function is called on the `PolygonRollupManager` contract.
+The `verifyBatchesTrustedAggregator()` function is called on the `PolygonRollupManager` contract:
+
+```
+verifyBatchesTrustedAggregator(rollupID, pendingStateNum, initNumBatch,
+ finalNewBatch, newLocalExitRoot, newStateRoot, beneficiary, proof)
+```
 
 The zkEVM node aggregator, or the AggLayer, calls the [`verifyBatchesTrustedAggregator`](https://github.com/0xPolygonHermez/zkevm-contracts/blob/b2a62e6af5738366e7494e8312184b1d6fdf287c/contracts/v2/PolygonRollupManager.sol#L921) function on the [`PolygonRollupManager.sol`](https://github.com/0xPolygonHermez/zkevm-contracts/blob/feature/etrog/contracts/v2/PolygonRollupManager.sol) contract.
 

…e/high-level/smart-contracts/bridging.md …ture/high-level/unified-LxLy/bridging.mddocs/zkEVM/architecture/high-level/smart-contracts/bridging.md renamed to docs/zkEVM/architecture/high-level/unified-LxLy/bridging.md docs/zkEVM/architecture/high-level/smart-contracts/bridging.md renamed to docs/zkEVM/architecture/high-level/unified-LxLy/bridging.md

@@ -93,7 +93,7 @@ The data below is transaction data (represented by a leaf node in an exit tree)
 
 1. When a batch of transactions is processed, the bridge contract appends the L2 exit tree with a new leaf containing the batch information. This updates the L2 exit tree root.
 
-2. The bridge contracts communicates the L2 exit tree root to the L2 global exit root manager. The L2 global exit root manager, however, does not update the global exit tree at this stage.
+2. The bridge contract transmits the L2 exit tree root to the L2 global exit root manager. The L2 global exit root manager, however, does not update the global exit tree at this stage.
 
 3. For proving and verification, the zk-proof-generating circuit obtains the L2 exit tree root from the L2 global exit root manager.
 

…ure/protocol/unified-LxLy/lxly-bridge.md …e/high-level/unified-LxLy/lxly-bridge.mddocs/zkEVM/architecture/protocol/unified-LxLy/lxly-bridge.md renamed to docs/zkEVM/architecture/high-level/unified-LxLy/lxly-bridge.md docs/zkEVM/architecture/protocol/unified-LxLy/lxly-bridge.md renamed to docs/zkEVM/architecture/high-level/unified-LxLy/lxly-bridge.md

@@ -1,4 +1,4 @@
-The LxLy bridge is an interoperability solution aimed at enabling cross-chain communication among Polygon chains. It facilitates interaction between two L2 chains or between an L2 chain and Ethereum as the L1.
+The LxLy bridge is an interoperability solution aimed at enabling cross-chain communication among networks. It facilitates interaction between two L2 chains or between an L2 chain and Ethereum as the L1.
 
 The LxLy bridge SC (or [PolygonZkEVMBridgeV2](https://github.com/0xPolygonHermez/zkevm-contracts/blob/feature/v2ForkID5/contracts/v2/PolygonZkEVMBridgeV2.sol)) is an improved and a more robust version of the [zkEVM bridge](https://github.com/0xPolygonHermez/zkevm-contracts/blob/feature/v2ForkID5/contracts/PolygonZkEVMBridge.sol) deployed in the Polygon zkEVM mainnet_beta version_.
 
@@ -86,14 +86,20 @@ The governance contract oversees consensus mechanisms and verifiers that can be
 The [rollup manager contract](https://github.com/0xPolygonHermez/zkevm-contracts/blob/feature/v2ForkID5/contracts/v2/PolygonRollupManager.sol) has the relevant function for adding a new rollup:
 
 ```bash
- function addNewRollupType(
-        address consensusImplementation,
-        IVerifierRollup verifier,
-        uint64 forkID,
-        bytes32 genesis,
-        uint8 rollupCompatibilityID,
-        string memory description
-    ) ...
+function createNewRollup(
+    uint32 rollupTypeID,
+    uint64 chainID,
+    address admin,
+    address sequencer,
+    address gasTokenAddress,
+    uint32 gasTokenNetwork,
+    string memory sequencerURL,
+    string memory networkName
+) external onlyRole(_CREATE_ROLLUP_ROLE) {
+    // Check that rollup type exists
+    if (rollupTypeID == 0 || rollupTypeID > rollupTypeCount) {
+        revert RollupTypeDoesNotExist();
+    }
 ```
 
 - To create and connect a rollup to the LxLy bridge,

…ol/unified-LxLy/ulxly-exit-trees-node.md …el/unified-LxLy/ulxly-exit-trees-node.mddocs/zkEVM/architecture/protocol/unified-LxLy/ulxly-exit-trees-node.md renamed to docs/zkEVM/architecture/high-level/unified-LxLy/ulxly-exit-trees-node.md docs/zkEVM/architecture/protocol/unified-LxLy/ulxly-exit-trees-node.md renamed to docs/zkEVM/architecture/high-level/unified-LxLy/ulxly-exit-trees-node.md

@@ -62,7 +62,7 @@ Recall also that in the bridge contract, the mapping $\texttt{tokenInfoToWrapped
 
 The problem is that if we change the $\texttt{creationBytecode}$ of the ERC-20 token contract, this will change all the addresses of the contract instances and breaks the data of the mapping.
 
-The $\texttt{creationBytecode}$ will change with high probability if we compile the factory (in our case the bridge) with another version of the Solidity compiler. In this case, we had to options:
+The $\texttt{creationBytecode}$ will change with high probability if we compile the factory (in our case the bridge) with another version of the Solidity compiler. In this case, we had two options:
 
 (a) Freeze the Solidity compiler version for the development of the whole bridge contract.