Boojum integration

.github/workflows/ci.yml

@@ -66,7 +66,7 @@ jobs:
             ethereum/cache
             ethereum/typechain
 
-  test:
+  test-hardhat:
     needs: [build, lint]
     runs-on: ubuntu-latest
 
@@ -103,3 +103,46 @@ jobs:
 
       - name: Run tests
         run: yarn test --no-compile
+
+  test-foundry:
+    needs: [build, lint]
+    runs-on: ubuntu-latest
+
+    defaults:
+      run:
+        working-directory: ethereum
+
+    steps:
+      - name: Checkout the repository
+        uses: actions/checkout@v3
+        with:
+          submodules: "recursive"
+
+      - name: "Install Foundry"
+        uses: "foundry-rs/foundry-toolchain@v1"
+
+      - name: Use Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: 16.15.1
+          cache: yarn
+          cache-dependency-path: ethereum/yarn.lock
+
+      - name: Install yarn
+        run: npm install -g yarn
+
+      - name: Install dependencies
+        run: yarn install
+
+      - name: Restore artifacts cache
+        uses: actions/cache/restore@v3
+        with:
+          fail-on-cache-miss: true
+          key: artifacts-${{ github.sha }}
+          path: |
+            ethereum/artifacts
+            ethereum/cache
+            ethereum/typechain
+
+      - name: Run tests
+        run: forge test

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "ethereum/lib/forge-std"]
+	path = ethereum/lib/forge-std
+	url = https://github.com/foundry-rs/forge-std

SystemConfig.json

@@ -1,13 +1,13 @@
 {
   "L2_TX_MAX_GAS_LIMIT": 80000000,
-  "MAX_PUBDATA_PER_BLOCK": 110000,
+  "MAX_PUBDATA_PER_BATCH": 110000,
   "PRIORITY_TX_MAX_PUBDATA": 99000,
   "FAIR_L2_GAS_PRICE": 500000000,
   "L1_GAS_PER_PUBDATA_BYTE": 17,
-  "BLOCK_OVERHEAD_L2_GAS": 1200000,
-  "BLOCK_OVERHEAD_L1_GAS": 1000000,
-  "MAX_TRANSACTIONS_IN_BLOCK": 1024,
-  "BOOTLOADER_TX_ENCODING_SPACE": 485225,
+  "BATCH_OVERHEAD_L2_GAS": 1200000,
+  "BATCH_OVERHEAD_L1_GAS": 1000000,
+  "MAX_TRANSACTIONS_IN_BATCH": 1024,
+  "BOOTLOADER_TX_ENCODING_SPACE": 273132,
   "L1_TX_INTRINSIC_L2_GAS": 167157,
   "L1_TX_INTRINSIC_PUBDATA": 88,
   "L1_TX_MIN_L2_GAS_BASE": 173484,

docs/Overview.md

@@ -19,7 +19,8 @@ See the [documentation](https://era.zksync.io/docs/dev/fundamentals/rollups.html
 - **Governor** - a privileged address that controls the upgradability of the network and sets other privileged
   addresses.
 - **Security council** - an address of the Gnosis multisig with the trusted owners that can decrease upgrade timelock.
-- **Validator/Operator** - a privileged address that can commit/verify/execute L2 blocks.
+- **Validator/Operator** - a privileged address that can commit/verify/execute L2 batches.
+- **L2 batch (or just batch)** - An aggregation of multiple L2 blocks. Note, that while the API operates on L2 blocks, the prove system operates on batches, which represent a single proved VM execution, which typically contains multiple L2 blocks.
 - **Facet** - implementation contract. The word comes from the EIP-2535.
 - **Gas** - a unit that measures the amount of computational effort required to execute specific operations on the
   zkSync Era network.
@@ -43,9 +44,9 @@ even an upgrade system is a separate facet that can be replaced.
 
 One of the differences from the reference implementation is access freezability. Each of the facets has an associated
 parameter that indicates if it is possible to freeze access to the facet. Privileged actors can freeze the **diamond**
-(not a specific facet!) and all facets with the marker `isFreezable` should be inaccessible until the governor unfreezes
-the diamond. Note that it is a very dangerous thing since the diamond proxy can freeze the upgrade system and then the
-diamond will be frozen forever.
+(not a specific facet!) and all facets with the marker `isFreezable` should be inaccessible until the governor or its owner
+unfreezes the diamond. Note that it is a very dangerous thing since the diamond proxy can freeze the upgrade system and then
+the diamond will be frozen forever.
 
 #### DiamondInit
 
@@ -55,41 +56,33 @@ diamond constructor and is not saved in the diamond as a facet.
 Implementation detail - function returns a magic value just like it is designed in
 [EIP-1271](https://eips.ethereum.org/EIPS/eip-1271), but the magic value is 32 bytes in size.
 
-#### DiamondCutFacet
-
-These smart contracts manage the freezing/unfreezing and upgrades of the diamond proxy. That being said, the contract
-must never be frozen.
-
-Currently, freezing and unfreezing are implemented as access control functions. It is fully controlled by the governor
-but can be changed later. The governor can call `freezeDiamond` to freeze the diamond and `unfreezeDiamond` to restore
-it.
-
-Another purpose of `DiamondCutFacet` is to upgrade the facets. The upgrading is split into 2-3 phases:
-
-- `proposeTransparentUpgrade`/`proposeShadowUpgrade` - propose an upgrade with visible/hidden parameters.
-- `cancelUpgradeProposal` - cancel the upgrade proposal.
-- `securityCouncilUpgradeApprove` - approve the upgrade by the security council.
-- `executeUpgrade` - finalize the upgrade.
-
-The upgrade itself characterizes by three variables:
-
-- `facetCuts` - a set of changes to the facets (adding new facets, removing facets, and replacing them).
-- pair `(address _initAddress, bytes _calldata)` for initializing the upgrade by making a delegate call to
-  `_initAddress` with `_calldata` inputs.
-
 #### GettersFacet
 
 Separate facet, whose only function is providing `view` and `pure` methods. It also implements
 [diamond loupe](https://eips.ethereum.org/EIPS/eip-2535#diamond-loupe) which makes managing facets easier.
+This contract must never be frozen.
 
-#### GovernanceFacet
+#### AdminFacet
 
 Controls changing the privileged addresses such as governor and validators or one of the system parameters (L2
-bootloader bytecode hash, verifier address, verifier parameters, etc).
+bootloader bytecode hash, verifier address, verifier parameters, etc), and it also manages the freezing/unfreezing and execution of
+upgrades in the diamond proxy.
+
+#### Governance
+
+This contract manages operations (calls with preconditions) for governance tasks. The contract allows for operations to be scheduled,
+executed, and canceled with appropriate permissions and delays. It is used for managing and coordinating upgrades and changes in all
+zkSync Era governed contracts.
+
+Each upgrade consists of two steps:
+
+- Upgrade Proposal - The governor can schedule upgrades in two different manners:
+    - Fully transparent data. All implementation contracts and migration contracts are known to the community. The governor must wait
+for the timelock to execute the upgrade.
+    - Shadow upgrade. The governor only shows the commitment for the upgrade. The upgrade can be executed only with security council
+approval without timelock.
+- Upgrade execution - perform the upgrade that was proposed.
 
-At the current stage, the governor has permission to instantly change the key system parameters with `GovernanceFacet`.
-Later such functionality will be removed and changing system parameters will be possible only via Diamond upgrade (see
-_DiamondCutFacet_).
 
 #### MailboxFacet
 
@@ -143,11 +136,11 @@ burn the funds on L2, allowing the user to reclaim them through the `finalizeEth
 L2 -> L1 communication, in contrast to L1 -> L2 communication, is based only on transferring the information, and not on
 the transaction execution on L1.
 
-From the L2 side, there is a special zkEVM opcode that saves `l2ToL1Log` in the L2 block. A validator will send all
-`l2ToL1Logs` when sending an L2 block to the L1 (see `ExecutorFacet`). Later on, users will be able to both read their
+From the L2 side, there is a special zkEVM opcode that saves `l2ToL1Log` in the L2 batch. A validator will send all
+`l2ToL1Logs` when sending an L2 batch to the L1 (see `ExecutorFacet`). Later on, users will be able to both read their
 `l2ToL1logs` on L1 and _prove_ that they sent it.
 
-From the L1 side, for each L2 block, a Merkle root with such logs in leaves is calculated. Thus, a user can provide
+From the L1 side, for each L2 batch, a Merkle root with such logs in leaves is calculated. Thus, a user can provide
 Merkle proof for each `l2ToL1Logs`.
 
 _NOTE_: For each executed L1 -> L2 transaction, the system program necessarily sends an L2 -> L1 log. To verify the
@@ -164,24 +157,43 @@ this trick:
 
 #### ExecutorFacet
 
-A contract that accepts L2 blocks, enforces data availability and checks the validity of zk-proofs.
+A contract that accepts L2 batches, enforces data availability and checks the validity of zk-proofs.
 
 The state transition is divided into three stages:
 
-- `commitBlocks` - check L2 block timestamp, process the L2 logs, save data for a block, and prepare data for zk-proof.
-- `proveBlocks` - validate zk-proof.
-- `executeBlocks` - finalize the state, marking L1 -> L2 communication processing, and saving Merkle tree with L2 logs.
+- `commitBatches` - check L2 batch timestamp, process the L2 logs, save data for a batch, and prepare data for zk-proof.
+- `proveBatches` - validate zk-proof.
+- `executeBatches` - finalize the state, marking L1 -> L2 communication processing, and saving Merkle tree with L2 logs.
 
-When a block is committed, we process L2 -> L1 logs. Here are the invariants that are expected there:
+Each L2 -> L1 system log will have a key that is part of the following:
+```solidity
+enum SystemLogKey {
+    L2_TO_L1_LOGS_TREE_ROOT_KEY,
+    TOTAL_L2_TO_L1_PUBDATA_KEY,
+    STATE_DIFF_HASH_KEY,
+    PACKED_BATCH_AND_L2_BLOCK_TIMESTAMP_KEY,
+    PREV_BATCH_HASH_KEY,
+    CHAINED_PRIORITY_TXN_HASH_KEY,
+    NUMBER_OF_LAYER_1_TXS_KEY,
+    EXPECTED_SYSTEM_CONTRACT_UPGRADE_TX_HASH_KEY
+}
+```
 
-- The only L2 -> L1 log from the `L2_SYSTEM_CONTEXT_ADDRESS`, with the `key == l2BlockTimestamp` and
-  `value == l2BlockHash`.
-- Several (or none) logs from the `L2_KNOWN_CODE_STORAGE_ADDRESS` with the `key == bytecodeHash`, where bytecode is
-  marked as a known factory dependency.
-- Several (or none) logs from the `L2_BOOTLOADER_ADDRESS` with the `key == canonicalTxHash` where `canonicalTxHash` is a
-  hash of processed L1 -> L2 transaction.
-- Several (of none) logs from the `L2_TO_L1_MESSENGER` with the `value == hashedMessage` where `hashedMessage` is a hash
-  of an arbitrary-length message that is sent from L2
+When a batch is committed, we process L2 -> L1 system logs. Here are the invariants that are expected there:
+
+- In a given batch there will be either 7 or 8 system logs. The 8th log is only required for a protocol upgrade.
+- There will be a single log for each key that is containted within `SystemLogKey`
+- Three logs from the `L2_TO_L1_MESSENGER` with keys:
+ - `L2_TO_L1_LOGS_TREE_ROOT_KEY`
+ - `TOTAL_L2_TO_L1_PUBDATA_KEY`
+ - `STATE_DIFF_HASH_KEY`
+- Two logs from `L2_SYSTEM_CONTEXT_SYSTEM_CONTRACT_ADDR` with keys:
+  - `PACKED_BATCH_AND_L2_BLOCK_TIMESTAMP_KEY`
+  - `PREV_BATCH_HASH_KEY`
+- Two or three logs from `L2_BOOTLOADER_ADDRESS` with keys:
+  - `CHAINED_PRIORITY_TXN_HASH_KEY`
+  - `NUMBER_OF_LAYER_1_TXS_KEY`
+  - `EXPECTED_SYSTEM_CONTRACT_UPGRADE_TX_HASH_KEY` 
 - None logs from other addresses (may be changed in the future).
 
 #### Bridges
@@ -230,13 +242,23 @@ the L1 recipient.
 #### ValidatorTimelock
 
 An intermediate smart contract between the validator EOA account and the zkSync smart contract. Its primary purpose is
-to provide a trustless means of delaying block execution without modifying the main zkSync contract. zkSync actively
+to provide a trustless means of delaying batch execution without modifying the main zkSync contract. zkSync actively
 monitors the chain activity and reacts to any suspicious activity by freezing the chain. This allows time for
 investigation and mitigation before resuming normal operations.
 
 It is a temporary solution to prevent any significant impact of the validator hot key leakage, while the network is in
 the Alpha stage.
 
+This contract consists of four main functions `commitBatches`, `proveBatches`, `executeBatches`, and `revertBatches`, that
+can be called only by the validator.
+
+When the validator calls `commitBatches`, the same calldata will be propogated to the zkSync contract (`DiamondProxy` through
+`call` where it invokes the `ExecutorFacet` through `delegatecall`), and also a timestamp is assigned to these batches to track
+the time these batches are commited by the validator to enforce a delay between committing and execution of batches. Then, the
+validator can prove the already commited batches regardless of the mentioned timestamp, and again the same calldata (related
+to the `proveBatches` function) will be propogated to the zkSync contract. After, the `delay` is elapsed, the validator
+is allowed to call `executeBatches` to propogate the same calldata to zkSync contract.
+
 #### Allowlist
 
 The auxiliary contract controls the permission access list. It is used in bridges and diamond proxies to control which

ethereum/.gitignore

@@ -4,3 +4,5 @@
 /typechain
 node_modules
 ./contracts/DS_Store
+/artifacts-forge
+/cache-forge

ethereum/contracts/bridge/L1ERC20Bridge.sol

@@ -21,6 +21,7 @@ import "../common/ReentrancyGuard.sol";
 import "../vendor/AddressAliasHelper.sol";
 
 /// @author Matter Labs
+/// @custom:security-contact [email protected]
 /// @notice Smart contract that allows depositing ERC20 tokens from Ethereum to zkSync Era
 /// @dev It is standard implementation of ERC20 Bridge that can be used as a reference
 /// for any other custom token bridges.
@@ -33,7 +34,7 @@ contract L1ERC20Bridge is IL1Bridge, IL1BridgeLegacy, AllowListed, ReentrancyGua
     /// @dev zkSync smart contract that is used to operate with L2 via asynchronous L2 <-> L1 communication
     IZkSync internal immutable zkSync;
 
-    /// @dev A mapping L2 block number => message number => flag
+    /// @dev A mapping L2 batch number => message number => flag
     /// @dev Used to indicate that zkSync L2 -> L1 message was already processed
     mapping(uint256 => mapping(uint256 => bool)) public isWithdrawalFinalized;
 
@@ -247,24 +248,24 @@ contract L1ERC20Bridge is IL1Bridge, IL1BridgeLegacy, AllowListed, ReentrancyGua
     /// @param _depositSender The address of the deposit initiator
     /// @param _l1Token The address of the deposited L1 ERC20 token
     /// @param _l2TxHash The L2 transaction hash of the failed deposit finalization
-    /// @param _l2BlockNumber The L2 block number where the deposit finalization was processed
+    /// @param _l2BatchNumber The L2 batch number where the deposit finalization was processed
     /// @param _l2MessageIndex The position in the L2 logs Merkle tree of the l2Log that was sent with the message
-    /// @param _l2TxNumberInBlock The L2 transaction number in a block, in which the log was sent
+    /// @param _l2TxNumberInBatch The L2 transaction number in a batch, in which the log was sent
     /// @param _merkleProof The Merkle proof of the processing L1 -> L2 transaction with deposit finalization
     function claimFailedDeposit(
         address _depositSender,
         address _l1Token,
         bytes32 _l2TxHash,
-        uint256 _l2BlockNumber,
+        uint256 _l2BatchNumber,
         uint256 _l2MessageIndex,
-        uint16 _l2TxNumberInBlock,
+        uint16 _l2TxNumberInBatch,
         bytes32[] calldata _merkleProof
     ) external nonReentrant senderCanCallFunction(allowList) {
         bool proofValid = zkSync.proveL1ToL2TransactionStatus(
             _l2TxHash,
-            _l2BlockNumber,
+            _l2BatchNumber,
             _l2MessageIndex,
-            _l2TxNumberInBlock,
+            _l2TxNumberInBatch,
             _merkleProof,
             TxStatus.Failure
         );
@@ -284,34 +285,34 @@ contract L1ERC20Bridge is IL1Bridge, IL1BridgeLegacy, AllowListed, ReentrancyGua
     }
 
     /// @notice Finalize the withdrawal and release funds
-    /// @param _l2BlockNumber The L2 block number where the withdrawal was processed
+    /// @param _l2BatchNumber The L2 batch number where the withdrawal was processed
     /// @param _l2MessageIndex The position in the L2 logs Merkle tree of the l2Log that was sent with the message
-    /// @param _l2TxNumberInBlock The L2 transaction number in a block, in which the log was sent
+    /// @param _l2TxNumberInBatch The L2 transaction number in the batch, in which the log was sent
     /// @param _message The L2 withdraw data, stored in an L2 -> L1 message
     /// @param _merkleProof The Merkle proof of the inclusion L2 -> L1 message about withdrawal initialization
     function finalizeWithdrawal(
-        uint256 _l2BlockNumber,
+        uint256 _l2BatchNumber,
         uint256 _l2MessageIndex,
-        uint16 _l2TxNumberInBlock,
+        uint16 _l2TxNumberInBatch,
         bytes calldata _message,
         bytes32[] calldata _merkleProof
     ) external nonReentrant senderCanCallFunction(allowList) {
-        require(!isWithdrawalFinalized[_l2BlockNumber][_l2MessageIndex], "pw");
+        require(!isWithdrawalFinalized[_l2BatchNumber][_l2MessageIndex], "pw");
 
         L2Message memory l2ToL1Message = L2Message({
-            txNumberInBlock: _l2TxNumberInBlock,
+            txNumberInBatch: _l2TxNumberInBatch,
             sender: l2Bridge,
             data: _message
         });
 
         (address l1Receiver, address l1Token, uint256 amount) = _parseL2WithdrawalMessage(l2ToL1Message.data);
         // Preventing the stack too deep error
         {
-            bool success = zkSync.proveL2MessageInclusion(_l2BlockNumber, _l2MessageIndex, l2ToL1Message, _merkleProof);
+            bool success = zkSync.proveL2MessageInclusion(_l2BatchNumber, _l2MessageIndex, l2ToL1Message, _merkleProof);
             require(success, "nq");
         }
 
-        isWithdrawalFinalized[_l2BlockNumber][_l2MessageIndex] = true;
+        isWithdrawalFinalized[_l2BatchNumber][_l2MessageIndex] = true;
         // Withdraw funds
         IERC20(l1Token).safeTransfer(l1Receiver, amount);