Merge branch 'zkevm/contracts' of https://github.com/0xPolygon/polygon-docs into zkevm/contracts

Author: kmurphypolygon

docs/zkEVM/architecture/high-level/smart-contracts/api/CDKValidiumTimelock.md

@@ -1,7 +1,7 @@
-
 Contract module which acts as a timelocked controller.
-This gives time for users of the controlled contract to exit before a potentially dangerous maintenance operation is applied.
-If emergency mode of the cdkValidium contract system is active, this timelock have no delay.
+It provides time, for users of the controlled contract, to exit before any risky maintenance operation is applied.
+
+However, if the emergency mode of the cdkValidium contract system is active, any timelock is bypassed without delay.
 
 ## Functions
 ### constructor
@@ -16,7 +16,6 @@ If emergency mode of the cdkValidium contract system is active, this timelock ha
 ```
 Constructor of timelock
 
-
 ##### Parameters:
 | Name | Type | Description                                                          |
 | :--- | :--- | :------------------------------------------------------------------- |
@@ -26,7 +25,6 @@ Constructor of timelock
 |`admin` | address | optional account to be granted admin role; disable with zero address
 |`_cdkValidium` | contract CDKValidium | cdkValidium address
 
-
 ### getMinDelay
 ```solidity
   function getMinDelay(
@@ -35,7 +33,5 @@ Constructor of timelock
 
 Returns the minimum delay for an operation to become valid.
 
-This value can be changed by executing an operation that calls `updateDelay`.
-If CDKValidium is on emergency state the minDelay will be 0 instead.
-
-
+The minimum delay value can be changed by executing any operation that calls `updateDelay`.
+If CDKValidium is on emergency state the `minDelay` will be 0 instead.

docs/zkEVM/architecture/high-level/smart-contracts/api/PolygonZkEVMGlobalExitRootV2.md

@@ -20,7 +20,7 @@ Contract responsible for managing the exit roots across multiple networks.
 
 ### `updateExitRoot`
 
-Update the exit root of one of the networks and the global exit root.
+Updates the exit root of any of the networks and the global exit root.
 
 ```solidity
   function updateExitRoot(
@@ -36,7 +36,7 @@ Update the exit root of one of the networks and the global exit root.
 
 ### `getLastGlobalExitRoot`
 
-Return last global exit root.
+Returns last global exit root.
 
 ```solidity
   function getLastGlobalExitRoot(
@@ -54,7 +54,7 @@ Computes and returns the Merkle root of the `L1InfoTree`.
 
 ### `getLeafValue`
 
-Given the leaf data returns the leaf hash.
+Given leaf data, it returns the leaf hash.
 
 ```solidity
   function getLeafValue(
@@ -76,7 +76,7 @@ Given the leaf data returns the leaf hash.
 
 ### `UpdateL1InfoTree`
 
-Emitted when the global exit root is updated
+Emitted when the global exit root is updated.
 
 ```solidity
   event UpdateL1InfoTree(

docs/zkEVM/architecture/high-level/smart-contracts/api/consensus/dataComittee/CDKDataCommittee.md

@@ -9,7 +9,7 @@
 
 ### `setupCommittee`
 
-Allows the admin to setup the members of the committee. 
+Allows the admin to setup members of the committee. 
 
 ```solidity
   function setupCommittee(
@@ -21,8 +21,8 @@ Allows the admin to setup the members of the committee.
 
 !!! note
     - The system requires N/M signatures where N => `_requiredAmountOfSignatures` and M => `urls.length`.
-    - There must be the same amount of urls than addresses encoded in the `addrsBytes`.
-    - A member is represented by the url and the address contained in `urls[i]` and `addrsBytes[i*_ADDR_SIZE : i*_ADDR_SIZE + _ADDR_SIZE]`.
+    - The number of urls must be the same as the addresses encoded in the `addrsBytes`.
+    - A member is represented by a url and the address contained in `urls[i]` and `addrsBytes[i*_ADDR_SIZE : i*_ADDR_SIZE + _ADDR_SIZE]`.
 
 
 ##### Parameters

docs/zkEVM/architecture/high-level/smart-contracts/api/consensus/dataComittee/PolygonDataComittee.md

@@ -43,15 +43,15 @@ Allows a sequencer to send multiple batches.
 
 | Name | Type | Description                                                          |
 | :--- | :--- | :------------------------------------------------------------------- |
-|`batches` | struct PolygonDataComittee.ValidiumBatchData[] | Struct array which holds the necessary data to append new batches to the sequence
+|`batches` | struct PolygonDataComittee.ValidiumBatchData[] | Struct array which holds the necessary data to append new batches to a sequence
 |`l2Coinbase` | address | Address that will receive the fees from L2
-|`dataAvailabilityMessage` | bytes | Byte array containing the signatures and all the addresses of the committee in ascending order
+|`dataAvailabilityMessage` | bytes | Byte array containing signatures and all addresses of the committee members in the ascending order
 [signature 0, ..., signature requiredAmountOfSignatures -1, address 0, ... address N]
 note that each ECDSA signatures are used, therefore each one must be 65 bytes
 
 ### `switchSequenceWithDataAvailability`
 
-Allows the admin to turn on the force batches.
+Allows the admin to activate force batches.
 
 This action is not reversible.
 
@@ -69,4 +69,4 @@ This action is not reversible.
   )
 ```
 
-Emitted when switching the ability to sequence with data availability.
+Emitted when switching the sequencing functionality from a rollup to a validium, where the data availability committee is in operation.

docs/zkEVM/architecture/high-level/smart-contracts/api/consensus/validium/PolygonDataCommittee.md

@@ -2,7 +2,7 @@
 
 ### `constructor`
 
-Disable initializers on the implementation following best practices.
+Disables initializers on the implementation, following best practices.
 
 ```solidity
   function constructor(
@@ -21,9 +21,9 @@ Disable initializers on the implementation following best practices.
 Allows the admin to setup the members of the committee. 
 
 !!! note
-    - The system will require `N/M` signatures where `N` => `_requiredAmountOfSignatures` and `M` => `urls.length`.
-    - There must be the same amount of urls than addresses encoded in the `addrsBytes`.
-    - A member is represented by the url and the address contained in urls[i] and `addrsBytes. [i*_ADDR_SIZE : i*_ADDR_SIZE + _ADDR_SIZE]`.
+    - The system requires `N/M` signatures where `N` => `_requiredAmountOfSignatures` and `M` => `urls.length`.
+    - The number of urls must be the same as addresses encoded in the `addrsBytes`.
+    - A member is represented by a url and the address contained in urls[i] and `addrsBytes. [i*_ADDR_SIZE : i*_ADDR_SIZE + _ADDR_SIZE]`.
 
 ```solidity
   function setupCommittee(
@@ -43,7 +43,7 @@ Allows the admin to setup the members of the committee.
 
 ### `verifyMessage`
 
-Verifies that the given signedHash has been signed by requiredAmountOfSignatures committee members.
+Verifies that the given signedHash has been signed by the requiredAmountOfSignatures committee members.
 
 ```solidity
   function verifyMessage(
@@ -56,14 +56,14 @@ Verifies that the given signedHash has been signed by requiredAmountOfSignatures
 
 | Name | Type | Description                                                          |
 | :--- | :--- | :------------------------------------------------------------------- |
-|`signedHash` | bytes32 | Hash that must have been signed by requiredAmountOfSignatures of committee members
-|`signaturesAndAddrs` | bytes | Byte array containing the signatures and all the addresses of the committee in ascending order
+|`signedHash` | bytes32 | Hash that must have been signed by the requiredAmountOfSignatures of committee members
+|`signaturesAndAddrs` | bytes | Byte array containing signatures and all addresses of the committee members in ascending order
 [signature 0, ..., signature requiredAmountOfSignatures -1, address 0, ... address N]
-note that each ECDSA signatures are used, therefore each one must be 65 bytes
+note that all signatures are ECDSA, therefore each must be 65 bytes long
 
 ### `getAmountOfMembers`
 
-Return the amount of committee members.
+Returns the number of committee members.
 
 ```solidity
   function getAmountOfMembers(

docs/zkEVM/architecture/high-level/smart-contracts/api/consensus/validium/PolygonValidiumEtrog.md

@@ -38,16 +38,13 @@ Allows a sequencer to send multiple batches.
 
 | Name | Type | Description                                                          |
 | :--- | :--- | :------------------------------------------------------------------- |
-|`batches` | struct PolygonValidiumEtrog.ValidiumBatchData[] | Struct array which holds the necessary data to append new batches to the sequence
-|`maxSequenceTimestamp` | uint64 | Max timestamp of the sequence. This timestamp must be inside a safety range (actual + 36 seconds).
-This timestamp should be equal or higher of the last block inside the sequence, otherwise this batch will be invalidated by circuit.
-|`initSequencedBatch` | uint64 | This parameter must match the current last batch sequenced.
-This will be a protection for the sequencer to avoid sending undesired data
-|`l2Coinbase` | address | Address that will receive the fees from L2
-|`dataAvailabilityMessage` | bytes | Byte array containing the signatures and all the addresses of the committee in ascending order
-[signature 0, ..., signature requiredAmountOfSignatures -1, address 0, ... address N]
-note that each ECDSA signatures are used, therefore each one must be 65 bytes
-note Pol is not a reentrant token
+|`batches` | struct PolygonValidiumEtrog.ValidiumBatchData[] | Struct array which holds data necessary for appending new batches to the sequence
+|`maxSequenceTimestamp` | uint64 | Max timestamp of the sequence. </br> This timestamp must be within a safety range (actual + 36 seconds). </br> This timestamp should be equal or greater than that of the last block inside the sequence, otherwise this batch is invalidated by the circuit. |
+|`initSequencedBatch` | uint64 | This parameter must match the current last batch sequenced. </br> This is a protection mechanism against the sequencer sending undesired data. |
+|`l2Coinbase` | address | Address that will receive the fees from L2 |
+|`dataAvailabilityMessage` | bytes | Byte array containing signatures and all addresses of the committee members in ascending order </br> [signature 0, ..., signature requiredAmountOfSignatures -1, address 0, ... address N]. </br> Note that all signatures are ECDSA, therefore each must be 65 bytes long. |
+
+Note that POL is not a reentrant token.
 
 ### `sequenceBatches`
 
@@ -66,17 +63,14 @@ Allows a sequencer to send multiple batches.
 
 | Name | Type | Description                                                          |
 | :--- | :--- | :------------------------------------------------------------------- |
-|`batches` | struct PolygonRollupBaseEtrog.BatchData[] | Struct array which holds the necessary data to append new batches to the sequence
-|`maxSequenceTimestamp` | uint64 | Max timestamp of the sequence. This timestamp must be inside a safety range (actual + 36 seconds).
-This timestamp should be equal or higher of the last block inside the sequence, otherwise this batch will be invalidated by circuit.
-|`initSequencedBatch` | uint64 | This parameter must match the current last batch sequenced.
-This will be a protection for the sequencer to avoid sending undesired data
-|`l2Coinbase` | address | Address that will receive the fees from L2
-note Pol is not a reentrant token
+|`batches` | struct PolygonRollupBaseEtrog.BatchData[] | Struct array which holds data necessary for appending new batches to the sequence. |
+|`maxSequenceTimestamp` | uint64 | Max timestamp of the sequence. This timestamp must be within a safety range (actual + 36 seconds). It should be equal or greater than the last block inside the sequence, otherwise this batch is invalidated by circuit. |
+|`initSequencedBatch` | uint64 | This parameter must match the current last batch sequenced. This is a protection mechanism against the sequencer sending undesired data. |
+|`l2Coinbase` | address | Address that will receive the fees from L2. Note that POL is not a reentrant token. |
 
 ### `setDataAvailabilityProtocol`
 
-Allow the admin to set a new data availability protocol.
+Allows the admin to set a new data availability protocol.
 
 ```solidity
   function setDataAvailabilityProtocol(
@@ -88,11 +82,11 @@ Allow the admin to set a new data availability protocol.
 
 | Name | Type | Description                                                          |
 | :--- | :--- | :------------------------------------------------------------------- |
-|`newDataAvailabilityProtocol` | contract IDataAvailabilityProtocol | Address of the new data availability protocol
+|`newDataAvailabilityProtocol` | contract IDataAvailabilityProtocol | Address of the new data availability protocol. |
 
 ### `switchSequenceWithDataAvailability`
 
-Allow the admin to switch the sequence with data availability.
+Allows the admin to switch the sequencing functionality from a rollup to a validium, where the data availability committee is in operation.
 
 ```solidity
   function switchSequenceWithDataAvailability(
@@ -104,7 +98,7 @@ Allow the admin to switch the sequence with data availability.
 
 | Name | Type | Description                                                          |
 | :--- | :--- | :------------------------------------------------------------------- |
-|`newIsSequenceWithDataAvailabilityAllowed` | bool | Boolean to switch
+|`newIsSequenceWithDataAvailabilityAllowed` | bool | A Boolean to switch sequencing mode. |
 
 ## Events
 
@@ -119,7 +113,7 @@ Emitted when the admin updates the data availability protocol.
 
 ### `SwitchSequenceWithDataAvailability`
 
-Emitted when switch the ability to sequence with data availability.
+Emitted when switching the sequencing functionality to a validium, a network with a data availability committee.
 
 ```solidity
   event SwitchSequenceWithDataAvailability(