tweeeeks

Author: kmurphypolygon

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

@@ -2,7 +2,30 @@
 comments: true
 ---
 
-## L1 main contracts
+## Consensus contracts
+
+The following contracts manage consensus mechanisms. They deal with sequencing and verifying transaction batches across the L1 and L2 realms.
+
+### `PolygonRollupBaseEtrog.sol`
+
+[PolygonRollupBaseEtrog.sol](https://github.com/0xPolygonHermez/zkevm-contracts/blob/main/contracts/v2/lib/PolygonRollupBaseEtrog.sol) is the base contract for rollups and validiums.
+
+### `PolygonZkEVMEtrog.sol`
+
+[PolygonZkEVMEtrog.sol](https://github.com/0xPolygonHermez/zkevm-contracts/blob/main/contracts/v2/consensus/zkEVM/PolygonZkEVMEtrog.sol) is the rollup contract that inherits from the base contract. 
+
+This contract calls the `onSequenceBatches(...)` function on the `PolygonRollupManager.sol` contract to trigger the verification mechanism after successful sequencing through the `sequenceBatches(...)` call.
+
+### `PolygonValidiumEtrog.sol`
+
+[PolygonValidiumEtrog.sol](https://github.com/0xPolygonHermez/zkevm-contracts/blob/main/contracts/v2/consensus/validium/PolygonValidiumEtrog.sol) is the validium contract that inherits from the base contract. 
+
+This contract calls the `onSequenceBatches(...)` function on the `PolygonRollupManager.sol` contract to trigger the verification mechanism after successful sequencing through the `sequenceBatchesValidium(...)` call.
+
+!!! info
+    - Custom chain contracts also exist at the consensus level and extend from common base contracts.
+
+## Rollup manager
 
 ### `PolygonRollupManager.sol`
 
@@ -18,6 +41,8 @@ It is responsible for the verification workflow by supplying updated exit root d
 - Getting exit root data by computing all local exit roots of all rollups.
 - Calculating batch rewards.
 
+## Bridge
+
 ### `PolygonZkEVMBridgeV2.sol`
 
 The [PolygonZkEVMBridgeV2.sol](https://github.com/0xPolygonHermez/zkevm-contracts/blob/main/contracts/v2/PolygonZkEVMBridgeV2.sol) is the main communication mechanism between the L1 and L2 realms. It manages bridging and claiming of assets and messages across environments.
@@ -32,6 +57,8 @@ The [PolygonZkEVMBridgeV2.sol](https://github.com/0xPolygonHermez/zkevm-contract
 - Providing access to the global exit root manager via the `IBasePolygonZkEVMGlobalExitRoot`.
 - Interacting with the `PolygonZkEVMGlobalExitRootL2.sol` contract which exists in the L2 space as part of the bridge functionality.
 
+## Exit roots
+
 ### `PolygonZkEVMGlobalExitRootV2.sol`
 
 The [PolygonZkEVMGlobalExitRootV2.sol](https://github.com/0xPolygonHermez/zkevm-contracts/blob/main/contracts/v2/PolygonZkEVMGlobalExitRootV2.sol) contract manages the L1 info tree that represents the current state of the system by updating global exit roots on state changes. It does this task across multiple networks and layers.
@@ -42,29 +69,7 @@ The [PolygonZkEVMGlobalExitRootV2.sol](https://github.com/0xPolygonHermez/zkevm-
 - Updating exit roots.
 - Retrieving latest exit roots and leaf values.
 
-## L1 consensus contracts
-
-The following contracts manage consensus mechanisms. They deal with sequencing and verifying transaction batches across the L1 and L2 realms.
-
-### `PolygonRollupBaseEtrog.sol`
-
-[PolygonRollupBaseEtrog.sol](https://github.com/0xPolygonHermez/zkevm-contracts/blob/main/contracts/v2/lib/PolygonRollupBaseEtrog.sol) is the base contract for rollups and validiums.
-
-### `PolygonZkEVMEtrog.sol`
-
-[PolygonZkEVMEtrog.sol](https://github.com/0xPolygonHermez/zkevm-contracts/blob/main/contracts/v2/consensus/zkEVM/PolygonZkEVMEtrog.sol) is the rollup contract that inherits from the base contract. 
-
-This contract calls the `onSequenceBatches(...)` function on the `PolygonRollupManager.sol` contract to trigger the verification mechanism after successful sequencing through the `sequenceBatches(...)` call.
-
-### `PolygonValidiumEtrog.sol`
-
-[PolygonValidiumEtrog.sol](https://github.com/0xPolygonHermez/zkevm-contracts/blob/main/contracts/v2/consensus/validium/PolygonValidiumEtrog.sol) is the validium contract that inherits from the base contract. 
-
-This contract calls the `onSequenceBatches(...)` function on the `PolygonRollupManager.sol` contract to trigger the verification mechanism after successful sequencing through the `sequenceBatchesValidium(...)` call.
 
-<!-- custom validium contracts
-### `PolygonRollupBaseEtrogNoGap.sol`
-### `PolygonValidiumStorageMigration.sol`-->
 
 !!! tip
     - For more information, and the Solidity code, check out the [API section](api/PolygonRollupManager.md).

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

@@ -37,8 +37,6 @@ The [PolygonRollupManager.sol](https://github.com/0xPolygonHermez/zkevm-contract
 ![Polygon Solidity smart contract rollup manager](../../../../img/cdk/high-level-architecture/rollup-manager.png){ width=80% }
 </center>
 
-
-
 ## Bridge 
 
 The unified bridge contract [PolygonZkEVMBridgeV2.sol](https://github.com/0xPolygonHermez/zkevm-contracts/blob/main/contracts/v2/PolygonZkEVMBridgeV2.sol) is responsible for bridging and claiming activity across L1 and L2 chains. 

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

@@ -4,10 +4,10 @@ comments: true
 
 Transactions flowing through the system reach the smart contract environment after one of two contract call use cases:
 
-- Sequence batches requests coming from the sequencer component.
-- Verifying batches requests coming from the aggregator component.
+- Sequence batches requests coming from the sequencer component in the node.
+- Verifying batches requests coming from the aggregator component in the node.
 
-This section looks at the sequencing workflow. The diagram below shows the sequencing workflow for rollup (non-validium) stacks. 
+This section looks at the sequencing workflow. The diagram below shows the sequencing workflow for rollup (non-validium) stacks which calls `sequenceBatches(...)` and `onSequenceBatches(...)`. 
 
 ![Polygon Solidity smart contract architecture](../../../../img/cdk/high-level-architecture/sequencing-flow.png)
 
@@ -57,6 +57,9 @@ Stepwise, the function does the following:
 
 ## `sequenceBatchesValidium(batches, l2Coinbase, dataAvailabilityMessage)`
 
+!!! info
+    - This function is not included in the sequence diagram above.
+
 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.