Merge pull request #1432 from matter-labs/sb-sync-draft-v28-with-release-v27

Sync draft-v28 with release-v27

Author: StanislavBreadless

AllContractsHashes.json

@@ -985,19 +985,19 @@
   },
   {
     "contractName": "l1-contracts/GatewayCTMDeployer",
-    "zkBytecodeHash": "0x010003c110ebc4cf5572ae2c52982fb14feecbd72fd421a0b3c208a9c5baa51d",
+    "zkBytecodeHash": "0x010003c188a3d77697a3eb00d92b04ca871bfb40564a70949eb662b56546dc9b",
     "zkBytecodePath": "/l1-contracts/zkout/GatewayCTMDeployer.sol/GatewayCTMDeployer.json",
-    "evmBytecodeHash": "0x4228e6a4c6ceb51e8fc7de43555e94ad965e2d81b9a5304eaee00ad20e339033",
+    "evmBytecodeHash": "0xd22197a6f68f4088e6b82ff4b4bf558245a960a426658d83029de6d7ff17006d",
     "evmBytecodePath": "/l1-contracts/out/GatewayCTMDeployer.sol/GatewayCTMDeployer.json",
-    "evmDeployedBytecodeHash": "0x7a605035a883cbecefe739ff05ee9a4eb4e0c4766ac4ce061096e12281309490"
+    "evmDeployedBytecodeHash": "0xf26576e2640c73f8ba633df3b2cf56f8187d74920082bc99c86903c4ac4feb64"
   },
   {
     "contractName": "l1-contracts/GatewayTransactionFilterer",
-    "zkBytecodeHash": "0x010001392a1e41f32a832bc2da5fa2fb3bec2b9a0ed8641e450d6463846f964d",
+    "zkBytecodeHash": "0x0100013d861a00847ed28ea6f9b3590436b6e5a30fd54ce4003b9bd3b308e21d",
     "zkBytecodePath": "/l1-contracts/zkout/GatewayTransactionFilterer.sol/GatewayTransactionFilterer.json",
-    "evmBytecodeHash": "0x11183032e0669f5240613c9c738d21700f960e9bc81af49392da4b6090fab174",
+    "evmBytecodeHash": "0x23d1348c63ca21b735fe95c3687319512e56c6b2df1d41a1b8b378312ff9731e",
     "evmBytecodePath": "/l1-contracts/out/GatewayTransactionFilterer.sol/GatewayTransactionFilterer.json",
-    "evmDeployedBytecodeHash": "0xd758329f4455e69621e02d30c49c9d301f1a143ff687445175053bfe60dd7219"
+    "evmDeployedBytecodeHash": "0xa68a869e457533ea13e2bebca4acaafb46dc0d1f4eb638079134e776cb9948b9"
   },
   {
     "contractName": "l1-contracts/GatewayUpgrade",
@@ -1321,11 +1321,11 @@
   },
   {
     "contractName": "l1-contracts/ServerNotifier",
-    "zkBytecodeHash": "0x010000b991c3aadeb1b08b89a62875c20809bd6ba6485017e3345f34fdf90069",
+    "zkBytecodeHash": "0x010000abf9520e5e2db74ebdf0895d6f76c579d93de6ad238bc25523c7c4fce7",
     "zkBytecodePath": "/l1-contracts/zkout/ServerNotifier.sol/ServerNotifier.json",
-    "evmBytecodeHash": "0xbbf56a3820456bc835c2829697ddee0027bbc61b0081a3bd87a1842c481bfc1f",
+    "evmBytecodeHash": "0xf0998f4665cca015ddfd981f4d05b6b4b23d7d7107ed60d2b0d140285fe795aa",
     "evmBytecodePath": "/l1-contracts/out/ServerNotifier.sol/ServerNotifier.json",
-    "evmDeployedBytecodeHash": "0xc55c47324a3b9ac5f947f21b8e380f66025ececb2f45917713b2938c20e44b00"
+    "evmDeployedBytecodeHash": "0x50f16c3a61c78c0c1fc3aa379e4d6c5e0c3fa407d7213cee852956c8e72e1eba"
   },
   {
     "contractName": "l1-contracts/SignedMath",

audits/ZKsync EVM Equivalence Audit.pdf

@@ -33,13 +33,21 @@ The order of the files here only roughly represents the order of reading. A lot
 - Gateway
   - [General overview](./gateway/overview.md)
   - [Chain migration](./gateway/chain_migration.md)
-  - [L1->L3 messaging via gateway](./gateway/messaging_via_gateway.md)
-  - [L3->L1 messaging via gateway](./gateway/nested_l3_l1_messaging.md)
+  - [L1->L2 messaging via gateway](./gateway/messaging_via_gateway.md)
+  - [L2->L1 messaging via gateway](./gateway/l2_gw_l1_messaging.md)
   - [Gateway protocol versioning](./gateway/gateway_protocol_upgrades.md)
   - [DA handling on Gateway](./gateway/gateway_da.md)
+- EVM emulation
+  - [Technical overview](./evm_emulation/technical_overview.md)
+  - [Gas emulation](./evm_emulation/evm_gas_emulation.md)
+  - [Differences from EVM (Cancun)](./evm_emulation/differences_from_cancun_evm.md)
+  - [EVM predeploys list](./evm_emulation/evm_predeploys_list.md)
 - Upgrade history
-  - [Gateway upgrade diff](./upgrade_history/gateway_preparation_upgrade/gateway_diff_review.md)
-  - [Gateway upgrade process](<./upgrade_history/gateway_preparation_upgrade/upgrade_process_(no_gateway_chain).md>)
+  - Gateway
+    - [Gateway upgrade diff](./upgrade_history/gateway_preparation_upgrade/gateway_diff_review.md)
+    - [Gateway upgrade process](<./upgrade_history/gateway_preparation_upgrade/upgrade_process_(no_gateway_chain).md>)
+  - EVM emulator
+    - [Upgrade process and changes](./upgrade_history/v27_evm_emulation/v27-evm-emulation.md)
 
 ![Reading order](./img/reading_order.png)
 
@@ -57,8 +65,8 @@ The repository contains the following sections:
 
 This section is for auditors of the codebase. It includes some of the important invariants that the system relies on and which if broken could have bad consequences.
 
-- Assuming that the accepting CTM is correct & efficient, the L1→GW part of the L1→GW→L3 transaction never fails. It is assumed that the provided max amount for gas is always enough for any transaction that can realistically come from L1.
+- Assuming that the accepting CTM is correct & efficient, the L1→GW part of the L1→GW→L2 transaction never fails. It is assumed that the provided max amount for gas is always enough for any transaction that can realistically come from L1.
 - GW → L1 migration never fails. If it is possible to get into a state where the migration is not possible to finish, then the chain is basically lost. There are some exceptions where for now it is the expected behavior. (check out the “Migration invariants & protocol upgradability” section)
 - The general consistency of chains when migration between different settlement layers is done. Including the feasibility of emergency upgrades, etc. I.e. whether the whole system is thought-through.
-- Preimage attacks in the L3→L1 tree, we apply special prefixes to ensure that the tree structure is fixed, i.e. all logs are 88 bytes long (this is for backwards compatibility reasons). For batch leaves and chain id leaves we use special prefixes.
+- Preimage attacks in the L2→GW→L1 tree, we apply special prefixes to ensure that the tree structure is fixed, i.e. all logs are 88 bytes long (this is for backwards compatibility reasons). For batch leaves and chain id leaves we use special prefixes.
 - Data availability guarantees. Whether rollup users can always restore all their storage slots, etc. An example of a potential tricky issue can be found in “Security notes for Gateway-based rollups” [in this document](./gateway/gateway_da.md).

audits/ZKsync FFLONK Verifier Audit.pdf

@@ -0,0 +1,43 @@
+# General differences from Ethereum
+
+This feature allows EVM emulation on top of EraVM. This mode is not fully equivalent to native EVM and is limited by the EraVM design. This page describes the known differences between emulation and EVM (Cancun).
+
+## Gas behavior differences
+
+- EVM emulation is executed on top of EraVM and all transactions start in EraVM environment. So gas and gaslimit values signed in the transaction correspond to the native **EraVM** gas, not **EVM** gas. For that reason presigned/keyless transactions created for Ethereum may be not compatible with ZK Chains. For detailed info: [Gas emulation](./evm_gas_emulation.md).
+- Our “Intrinsic gas costs” are different from EVM.
+- We do not implement the gas refunds logic from **EVM**. Because users pay for EraVM gas and EVM gas is virtual, we use EraVM gas refunds logic instead of EVM one. It does not affect contracts behavior (refunds happen in the end of transaction).
+- We do not charge EVM gas for tx calldata.
+- Access lists are not supported (EIP-2930).
+
+## Limitations
+
+- `DELEGATECALL` between EVM and native EraVM contracts will be reverted.
+- Calls to empty addresses in kernel space (address < 2^16) will fail.
+- `GASLIMIT` opcode returns the same fixed constant as EraVM and should not be used.
+
+Unsupported opcodes:
+
+- `CALLCODE`
+- `SELFDESTRUCT`
+- `BLOBHASH`
+- `BLOBBASEFEE`
+
+## Precompiles
+
+EVM emulation supports the same precompiles that are supported by EraVM.
+
+## Technical differences
+
+_These changes are unlikely to have an impact on the developer experience._
+
+Differences:
+
+- `JUMPDEST` analysis is simplified. It is not checked that `JUMPDEST` is not a part of `PUSH` instruction.
+- No force of call stack depth limit. It is implicitly implemented by 63/64 gas rule.
+- Account storage is not destroyed during contract deployment.
+- If the deployer's nonce is overflowed during contract deployment, all passed gas will be consumed. EVM refunds all passed gas to the caller frame.
+- Nonces are limited by size of `u128`, not `u64`
+- During creation of EVM contract by EOA or EraVM contract, emulator does not charge additional `2` gas for every 32-byte chunk of `initcode` as specified in [EIP-3860](https://eips.ethereum.org/EIPS/eip-3860) (since perform `JUMPDEST` analysis is simplified). This cost **is** charged if contract is created by another EVM contract (to keep gas equivalence).
+- Code deposit cost is charged from constructor frame, not caller frame. It will be changed in the future.
+- Only those accounts that are accessed from an EVM environment become warm (including origin, sender, coinbase, precompiles). Anything that happens outside the EVM does not affect the warm/cold status of the accounts for EVM.

audits/ZKsync FFLONK and EVM Equivalence Diff Audit.pdf

@@ -0,0 +1,43 @@
+# EVM gas emulation overview
+
+The gas model can be one of the most tricky topics regarding EVM emulation since there are two interacting executions are supported at the same time. This document is intended to explain in more detail how the emulation of the EVM gas works.
+
+## EVM emulation execution flow
+
+From the point of view of EraVM, the EVM emulator is (almost) a regular EraVM contract. This contract is predefined and can be changed only during protocol upgrades. When an EVM contract is called, EraVM invokes the emulator code. The emulator loads the corresponding EVM bytecode and interprets it.
+
+Thus, the emulation is executed on top of EraVM, uses EraVM opcodes and, most importantly, **pays for EraVM operations in native gas (ergs)**.
+
+⚠️ To avoid confusion, native EraVM gas will be referred to as "ergs" further in the text.
+
+This means that **ergs** are used to pay for all operations on EraVM (and therefore on ZK Chains). Gas and gaslimit values signed in user's transactions are specified in **ergs**. All refunds are also made by the virtual machine in ergs.
+
+## EVM gas model emulation
+
+Full EVM gas equivalence is necessary to provide an EVM-compatible environment and meet the assumptions made in contracts. However, the cost of EraVM operations differs, and EVM emulation requires multiple EraVM operations for each EVM operation. As a result, we emulate the EVM gas model.
+
+As mentioned in the previous section, the EVM environment is virtual: it operates on top of EraVM and incurs costs for execution in EraVM ergs. The EVM emulator, however, has its own internal gas accounting system that corresponds to the EVM gas model. Each EVM opcode consumes a predefined amount of gas, according to the EVM specification. And if there is insufficient gas for an operation, the frame will be reverted.
+
+⚠️ EVM gas is used only for compatibility in the EVM emulation mode. Underlying virtual machine is not aware about EVM gas and uses native ergs.
+
+## Ergs to gas conversion rate for gas limit
+
+EVM gas units are not equivalent to EraVM ergs. And both the EVM and EraVM do not provide mechanisms for an EOA or contract to specify how to convert gas from one unit to another. For practical use in the emulator, a predefined constant is used to convert gas limit from one unit to another.
+
+⚠️ Current EraVM -> EVM gas limit conversion ratio is 5:1.
+
+This means that if a user made a call to an EVM contract with 100,000 ergs, the EVM emulator will start execution with 20,000 EVM gas. At the same time, underlying EraVM will have all 100,000 ergs available for use and will refund any unused ergs at the end of transaction.
+
+In the other direction, when calling an EraVM contract from EVM context, if 20,000 gas is provided, the emulator will <ins>try</ins> to pass 100,000 ergs (or less, if amount of ergs left is not enough).
+
+## Out-of-ergs situation
+
+Because EVM gas is virtual and it is not equivalent to EraVM ergs, situations are possible in which emulator has enough EVM gas to continue execution, but encounters `out-of-ergs` panic from EraVM. In this case we simply propagate special internal kind of panic and revert the **whole** EVM frames chain.
+
+⚠️ EVM emulation can only be executed completely, up to returning from the EVM context (incl. EVM reverts), or completely rolled back.
+
+This fact should be taken into account by smart contract developers:
+
+❗**It is <ins>highly</ins> discouraged to use try-catch patterns with unknown contracts in EVM environment**❗
+
+Technically, this problem is similar to classic gas-griefing issues in EVM contracts, if not handled appropriately.

docs/README.md

@@ -0,0 +1,18 @@
+# EVM predeploys
+
+Some important EVM contracts can be deployed to predefined addresses if EVM emulation is enabled on the chain. It can be done using [DeployEvmPredeploys.s.sol](../../l1-contracts/deploy-scripts/evm-predeploys/DeployEvmPredeploys.s.sol) script.
+
+List of contracts:
+
+- [Create2 proxy](https://github.com/Arachnid/deterministic-deployment-proxy)
+  `0x4e59b44847b379578588920cA78FbF26c0B4956C`
+- [Create2 deployer](https://github.com/pcaversaccio/create2deployer)
+  `0x13b0D85CcB8bf860b6b79AF3029fCA081AE9beF2`
+- [ERC2470 singleton factory](https://eips.ethereum.org/EIPS/eip-2470)
+  `0xce0042B868300000d44A59004Da54A005ffdcf9f`
+- [Safe Singleton Factory](https://github.com/safe-global/safe-singleton-factory/blob/main/source/deterministic-deployment-proxy.yul)
+  `0x914d7Fec6aaC8cd542e72Bca78B30650d45643d7`
+- [Multicall3](https://github.com/mds1/multicall/tree/main)
+  `0xcA11bde05977b3631167028862bE2a173976CA11`
+- [Create2 proxy](https://github.com/Zoltu/deterministic-deployment-proxy)
+  `0x7A0D94F55792C434d74a40883C6ed8545E406D12`