refactor(l2): contracts (#2551)

**Motivation**

- Some variable names are misleading and can confuse the reader.
- There was no getter method for withdrawal logs merkle roots in
`CommonBridge`.

**Description**

- Renamed deposit logs related variables in `OnChainProposer` and
`CommonBridge` and their interfaces with clearer names.
- Improved some documentation on the above.
- Renamed some misleading naming in variables such as `commitment` in
`OnChainProposer` and its interface.

Author: ilitteri

cmd/ethrex_l2/src/utils/config/default_values.rs

@@ -17,13 +17,13 @@ pub const DEFAULT_ADDRESS: H160 = H160([
     0x3d, 0x1e, 0x15, 0xa1, 0xa5, 0x55, 0x78, 0xf7, 0xc9, 0x20, 0x88, 0x4a, 0x99, 0x43, 0xb3, 0xb3,
     0x5d, 0x0d, 0x88, 0x5b,
 ]);
-// 0xc19743cc824301ef62bd5a962efc1bfbbab004d6
+// 0xaf6b492a2e60f9a366f3da02b78b6305b130edc7
 pub const DEFAULT_CONTRACTS_COMMON_BRIDGE_ADDRESS: H160 = H160([
-    0xc1, 0x97, 0x43, 0xcc, 0x82, 0x43, 0x01, 0xef, 0x62, 0xbd, 0x5a, 0x96, 0x2e, 0xfc, 0x1b, 0xfb,
-    0xba, 0xb0, 0x04, 0xd6,
+    0xaf, 0x6b, 0x49, 0x2a, 0x2e, 0x60, 0xf9, 0xa3, 0x66, 0xf3, 0xda, 0x02, 0xb7, 0x8b, 0x63, 0x05,
+    0xb1, 0x30, 0xed, 0xc7,
 ]);
-// 0x52178cfc3db571f60016d43adf47d61c2009fa72
+// 0xea6d04861106c1fb69176d49eeb8de6dd14a9cfe
 pub const DEFAULT_CONTRACTS_ON_CHAIN_PROPOSER_ADDRESS: H160 = H160([
-    0x52, 0x17, 0x8c, 0xfc, 0x3d, 0xb5, 0x71, 0xf6, 0x00, 0x16, 0xd4, 0x3a, 0xdf, 0x47, 0xd6, 0x1c,
-    0x20, 0x09, 0xfa, 0x72,
+    0xea, 0x6d, 0x04, 0x86, 0x11, 0x06, 0xc1, 0xfb, 0x69, 0x17, 0x6d, 0x49, 0xee, 0xb8, 0xde, 0x6d,
+    0xd1, 0x4a, 0x9c, 0xfe,
 ]);

crates/l2/configs/sequencer_config_example.toml

@@ -34,7 +34,7 @@ coinbase_address = "0x0007a881CD95B1484fca47615B64803dad620C8d"
 l1_address = "0x3d1e15a1a55578f7c920884a9943b3b35d0d885b"
 # Private key corresponding to the above address.
 l1_private_key = "0x385c546456b6a603a1cfcaa9ec9494ba4832da08dd6bcf4de9a71e4a01b74924"
-on_chain_proposer_address = "0x52178cfc3db571f60016d43adf47d61c2009fa72"
+on_chain_proposer_address = "0xea6d04861106c1fb69176d49eeb8de6dd14a9cfe"
 # How often does the sequencer commit new blocks to the L1.
 commit_time_ms = 5000
 # 1 Gwei

crates/l2/contracts/src/l1/CommonBridge.sol

@@ -22,9 +22,10 @@ contract CommonBridge is ICommonBridge, Ownable, ReentrancyGuard {
     /// @dev The value is the merkle root of the logs.
     /// @dev If there exist a merkle root for a given block number it means
     /// that the logs were published on L1, and that that block was committed.
-    mapping(uint256 => bytes32) public blockWithdrawalsLogs;
+    mapping(uint256 => bytes32) public blockWithdrawalLogsMerkleRoots;
 
-    bytes32[] public depositLogs;
+    /// @notice Array of hashed pending deposit logs.
+    bytes32[] public pendingDepositLogs;
 
     address public ON_CHAIN_PROPOSER;
 
@@ -67,8 +68,8 @@ contract CommonBridge is ICommonBridge, Ownable, ReentrancyGuard {
     }
 
     /// @inheritdoc ICommonBridge
-    function getDepositLogs() public view returns (bytes32[] memory) {
-        return depositLogs;
+    function getPendingDepositLogs() public view returns (bytes32[] memory) {
+        return pendingDepositLogs;
     }
 
     function _deposit(DepositValues memory depositValues) private {
@@ -86,7 +87,7 @@ contract CommonBridge is ICommonBridge, Ownable, ReentrancyGuard {
             )
         );
 
-        depositLogs.push(
+        pendingDepositLogs.push(
             keccak256(
                 bytes.concat(
                     bytes20(depositValues.to),
@@ -128,18 +129,18 @@ contract CommonBridge is ICommonBridge, Ownable, ReentrancyGuard {
     }
 
     /// @inheritdoc ICommonBridge
-    function getDepositLogsVersionedHash(
+    function getPendingDepositLogsVersionedHash(
         uint16 number
     ) public view returns (bytes32) {
         require(number > 0, "CommonBridge: number is zero (get)");
         require(
-            uint256(number) <= depositLogs.length,
+            uint256(number) <= pendingDepositLogs.length,
             "CommonBridge: number is greater than the length of depositLogs (get)"
         );
 
         bytes memory logs;
         for (uint i = 0; i < number; i++) {
-            logs = bytes.concat(logs, depositLogs[i]);
+            logs = bytes.concat(logs, pendingDepositLogs[i]);
         }
 
         return
@@ -148,31 +149,41 @@ contract CommonBridge is ICommonBridge, Ownable, ReentrancyGuard {
     }
 
     /// @inheritdoc ICommonBridge
-    function removeDepositLogs(uint16 number) public onlyOnChainProposer {
+    function removePendingDepositLogs(
+        uint16 number
+    ) public onlyOnChainProposer {
         require(
-            number <= depositLogs.length,
+            number <= pendingDepositLogs.length,
             "CommonBridge: number is greater than the length of depositLogs (remove)"
         );
 
-        for (uint i = 0; i < depositLogs.length - number; i++) {
-            depositLogs[i] = depositLogs[i + number];
+        for (uint i = 0; i < pendingDepositLogs.length - number; i++) {
+            pendingDepositLogs[i] = pendingDepositLogs[i + number];
         }
 
         for (uint _i = 0; _i < number; _i++) {
-            depositLogs.pop();
+            pendingDepositLogs.pop();
         }
     }
 
+    /// @inheritdoc ICommonBridge
+    function getWithdrawalLogsMerkleRoot(
+        uint256 blockNumber
+    ) public view returns (bytes32) {
+        return blockWithdrawalLogsMerkleRoots[blockNumber];
+    }
+
     /// @inheritdoc ICommonBridge
     function publishWithdrawals(
         uint256 withdrawalLogsBlockNumber,
         bytes32 withdrawalsLogsMerkleRoot
     ) public onlyOnChainProposer {
         require(
-            blockWithdrawalsLogs[withdrawalLogsBlockNumber] == bytes32(0),
+            blockWithdrawalLogsMerkleRoots[withdrawalLogsBlockNumber] ==
+                bytes32(0),
             "CommonBridge: withdrawal logs already published"
         );
-        blockWithdrawalsLogs[
+        blockWithdrawalLogsMerkleRoots[
             withdrawalLogsBlockNumber
         ] = withdrawalsLogsMerkleRoot;
         emit WithdrawalsPublished(
@@ -190,7 +201,7 @@ contract CommonBridge is ICommonBridge, Ownable, ReentrancyGuard {
         bytes32[] calldata withdrawalProof
     ) public nonReentrant {
         require(
-            blockWithdrawalsLogs[withdrawalBlockNumber] != bytes32(0),
+            blockWithdrawalLogsMerkleRoots[withdrawalBlockNumber] != bytes32(0),
             "CommonBridge: the block that emitted the withdrawal logs was not committed"
         );
         require(
@@ -244,6 +255,8 @@ contract CommonBridge is ICommonBridge, Ownable, ReentrancyGuard {
             }
             withdrawalLogIndex /= 2;
         }
-        return withdrawalLeaf == blockWithdrawalsLogs[withdrawalBlockNumber];
+        return
+            withdrawalLeaf ==
+            blockWithdrawalLogsMerkleRoots[withdrawalBlockNumber];
     }
 }

crates/l2/contracts/src/l1/OnChainProposer.sol

@@ -13,9 +13,16 @@ import {IPicoVerifier} from "./interfaces/IPicoVerifier.sol";
 /// @title OnChainProposer contract.
 /// @author LambdaClass
 contract OnChainProposer is IOnChainProposer, ReentrancyGuard {
+    /// @notice Committed blocks data.
+    /// @dev This struct holds the information about the committed blocks.
+    /// @dev processedDepositLogsRollingHash is the Merkle root of the logs of the
+    /// deposits that were processed in the block being committed. The amount of
+    /// logs that is encoded in this root are to be removed from the
+    /// pendingDepositLogs queue of the CommonBridge contract.
     struct BlockCommitmentInfo {
-        bytes32 commitmentHash;
-        bytes32 depositLogs;
+        bytes32 newStateRoot;
+        bytes32 stateDiffKZGVersionedHash;
+        bytes32 processedDepositLogsRollingHash;
     }
 
     /// @notice The commitments of the committed blocks.
@@ -137,25 +144,29 @@ contract OnChainProposer is IOnChainProposer, ReentrancyGuard {
     /// @inheritdoc IOnChainProposer
     function commit(
         uint256 blockNumber,
-        bytes32 commitment,
+        bytes32 newStateRoot,
+        bytes32 stateDiffKZGVersionedHash,
         bytes32 withdrawalsLogsMerkleRoot,
-        bytes32 depositLogs
+        bytes32 processedDepositLogsRollingHash
     ) external override onlySequencer {
         require(
             blockNumber == lastCommittedBlock + 1,
             "OnChainProposer: blockNumber is not the immediate successor of lastCommittedBlock"
         );
         require(
-            blockCommitments[blockNumber].commitmentHash == bytes32(0),
+            blockCommitments[blockNumber].newStateRoot == bytes32(0),
             "OnChainProposer: block already committed"
         );
+
         // Check if commitment is equivalent to blob's KZG commitment.
 
-        if (depositLogs != bytes32(0)) {
-            bytes32 savedDepositLogs = ICommonBridge(BRIDGE)
-                .getDepositLogsVersionedHash(uint16(bytes2(depositLogs)));
+        if (processedDepositLogsRollingHash != bytes32(0)) {
+            bytes32 claimedProcessedDepositLogs = ICommonBridge(BRIDGE)
+                .getPendingDepositLogsVersionedHash(
+                    uint16(bytes2(processedDepositLogsRollingHash))
+                );
             require(
-                savedDepositLogs == depositLogs,
+                claimedProcessedDepositLogs == processedDepositLogsRollingHash,
                 "OnChainProposer: invalid deposit logs"
             );
         }
@@ -166,11 +177,12 @@ contract OnChainProposer is IOnChainProposer, ReentrancyGuard {
             );
         }
         blockCommitments[blockNumber] = BlockCommitmentInfo(
-            commitment,
-            depositLogs
+            newStateRoot,
+            stateDiffKZGVersionedHash,
+            processedDepositLogsRollingHash
         );
         lastCommittedBlock = blockNumber;
-        emit BlockCommitted(commitment);
+        emit BlockCommitted(newStateRoot);
     }
 
     /// @inheritdoc IOnChainProposer
@@ -202,7 +214,8 @@ contract OnChainProposer is IOnChainProposer, ReentrancyGuard {
         );
 
         require(
-            blockCommitments[blockNumber].commitmentHash != bytes32(0),
+            blockCommitments[blockNumber].stateDiffKZGVersionedHash !=
+                bytes32(0),
             "OnChainProposer: block not committed"
         );
 
@@ -236,10 +249,12 @@ contract OnChainProposer is IOnChainProposer, ReentrancyGuard {
         lastVerifiedBlock = blockNumber;
         // The first 2 bytes are the number of deposits.
         uint16 deposits_amount = uint16(
-            bytes2(blockCommitments[blockNumber].depositLogs)
+            bytes2(
+                blockCommitments[blockNumber].processedDepositLogsRollingHash
+            )
         );
         if (deposits_amount > 0) {
-            ICommonBridge(BRIDGE).removeDepositLogs(deposits_amount);
+            ICommonBridge(BRIDGE).removePendingDepositLogs(deposits_amount);
         }
 
         // Remove previous block commitment as it is no longer needed.

crates/l2/contracts/src/l1/interfaces/ICommonBridge.sol

@@ -58,10 +58,10 @@ interface ICommonBridge {
         bytes data;
     }
 
-    /// @notice Method to retrieve all the deposit logs hashes.
-    /// @dev This method is used by the L2 L1_Watcher to get the remaining
-    /// deposit logs to be processed.
-    function getDepositLogs() external view returns (bytes32[] memory);
+    /// @notice Method to retrieve all the pending deposit logs hashes.
+    /// @dev This method is used by the L2 L1_Watcher to get the pending deposit
+    /// logs to be processed.
+    function getPendingDepositLogs() external view returns (bytes32[] memory);
 
     /// @notice Initializes the contract.
     /// @dev This method is called only once after the contract is deployed.
@@ -76,19 +76,30 @@ interface ICommonBridge {
     /// @param depositValues the values needed to create the deposit.
     function deposit(DepositValues calldata depositValues) external payable;
 
-    /// @notice Method to retrieve the versioned hash of the first `number` deposit logs.
-    /// @param number of deposit logs to retrieve the versioned hash.
-    function getDepositLogsVersionedHash(
+    /// @notice Method to retrieve the versioned hash of the first `number`
+    /// pending deposit logs.
+    /// @param number of pending deposit logs to retrieve the versioned hash.
+    function getPendingDepositLogsVersionedHash(
         uint16 number
     ) external view returns (bytes32);
 
-    /// @notice Remove deposit from depositLogs queue.
-    /// @dev This method is used by the L2 OnChainOperator to remove the deposit
-    /// logs from the queue after the deposit is verified.
-    /// @param number of deposit logs to remove.
+    /// @notice Remove pending deposit from the pendingDepositLogs queue.
+    /// @dev This method is used by the L2 OnChainOperator to remove the pending
+    /// deposit logs from the queue after the deposit is verified.
+    /// @param number of pending deposit logs to remove.
     /// As deposits are processed in order, we don't need to specify
-    /// the deposit logs to remove, only the number of them.
-    function removeDepositLogs(uint16 number) external;
+    /// the pending deposit logs to remove, only the number of them.
+    function removePendingDepositLogs(uint16 number) external;
+
+    /// @notice Method to retrieve the merkle root of the withdrawal logs of a
+    /// given block.
+    /// @dev This method is used by the L2 OnChainOperator at the verify stage.
+    /// @param blockNumber the block number in L2 where the withdrawal logs were
+    /// emitted.
+    /// @return the merkle root of the withdrawal logs of the given block.
+    function getWithdrawalLogsMerkleRoot(
+        uint256 blockNumber
+    ) external view returns (bytes32);
 
     /// @notice Publishes the L2 withdrawals on L1.
     /// @dev This method is used by the L2 OnChainOperator to publish the L2

crates/l2/contracts/src/l1/interfaces/IOnChainProposer.sol

@@ -16,7 +16,8 @@ interface IOnChainProposer {
 
     /// @notice A block has been committed.
     /// @dev Event emitted when a block is committed.
-    event BlockCommitted(bytes32 indexed currentBlockCommitment);
+    /// @param newStateRoot The new state root of the block that was committed.
+    event BlockCommitted(bytes32 indexed newStateRoot);
 
     /// @notice A block has been verified.
     /// @dev Event emitted when a block is verified.
@@ -40,15 +41,18 @@ interface IOnChainProposer {
     /// @dev Committing to an L2 block means to store the block's commitment
     /// and to publish withdrawals if any.
     /// @param blockNumber the number of the block to be committed.
-    /// @param commitment of the block to be committed.
+    /// @param newStateRoot the new state root of the block to be committed.
+    /// @param stateDiffKZGVersionedHash of the block to be committed.
     /// @param withdrawalsLogsMerkleRoot the merkle root of the withdrawal logs
     /// of the block to be committed.
-    /// @param depositLogs the deposit logs of the block to be committed.
+    /// @param processedDepositLogsRollingHash the rolling hash of the processed
+    /// deposits logs of the block to be committed.
     function commit(
         uint256 blockNumber,
-        bytes32 commitment,
+        bytes32 newStateRoot,
+        bytes32 stateDiffKZGVersionedHash,
         bytes32 withdrawalsLogsMerkleRoot,
-        bytes32 depositLogs
+        bytes32 processedDepositLogsRollingHash
     ) external;
 
     /// @notice Method used to verify an L2 block proof.