Merge branch 'sb-port-docs-to-reorg' of ssh://github.com/matter-labs/…

…era-contracts into sb-port-docs-to-reorg

da-contracts/contracts/IL1DAValidator.sol

@@ -17,7 +17,7 @@ struct L1DAValidatorOutput {
 interface IL1DAValidator {
     /// @notice The function that checks the data availability for the given batch input.
     /// @param _chainId The chain id of the chain that is being committed.
-    /// @param _chainId The batch number for which the data availability is being checked.
+    /// @param _batchNumber The batch number for which the data availability is being checked.
     /// @param _l2DAValidatorOutputHash The hash of that was returned by the l2DAValidator.
     /// @param _operatorDAInput The DA input by the operator provided on L1.
     /// @param _maxBlobsSupported The maximal number of blobs supported by the chain.

docs/Overview.md

@@ -1,4 +1,5 @@
 # Overview
+
 [back to readme](./README.md)
 
 Ethereum's future is rollup-centric. This means breaking with the current paradigm of isolated EVM chains to infrastructure that is focused on an ecosystem of interconnected zkEVMs/zkVMs, (which we name ZK chain). This ecosystem will be grounded on Ethereum, requiring the appropriate L1 smart contracts. Here we outline our ZK Stack approach for these contracts, their interfaces, the needed changes to the existing architecture, as well as future features to be implemented.
@@ -15,7 +16,6 @@ We want to create a system where:
 - Interop is seamless and enables unified liquidity for assets across the ecosystem.
 - Multi-chain smart contracts need to be easy to develop, which means easy access to traditional bridges, and other supporting architecture.
 
-
 ZKsync Era is a permissionless general-purpose ZK rollup. Similar to many L1 blockchains and sidechains it enables
 deployment and interaction with Turing-complete smart contracts.
 

docs/README.md

@@ -5,48 +5,48 @@ The order of the files here only roughly represents the order of reading. A lot
 - [Glossary](./glossary.md)
 - [Overview](./overview.md)
 - Contracts of an individual chain
-    - [ZK Chain basics](./settlement_contracts/zkchain_basics.md)
-    - Data availability
-        - [Custom DA support](./settlement_contracts/data_availability/custom_da.md)
-        - [Rollup DA support](./settlement_contracts/data_availability/rollup_da.md)
-        - [Standard pubdata format](./settlement_contracts/data_availability/standard_pubdata_format.md)
-        - [State diff compression v1 spec](./settlement_contracts/data_availability/state_diff_compression_v1_spec.md)
-    - L1->L2 transaction handling
-        -  [Processing of L1->L2 transactions](./settlement_contracts/priority_queue/processing_of_l1->l2_txs.md)
-        - [Priority queue](./settlement_contracts/priority_queue/priority-queue.md)
+  - [ZK Chain basics](./settlement_contracts/zkchain_basics.md)
+  - Data availability
+    - [Custom DA support](./settlement_contracts/data_availability/custom_da.md)
+    - [Rollup DA support](./settlement_contracts/data_availability/rollup_da.md)
+    - [Standard pubdata format](./settlement_contracts/data_availability/standard_pubdata_format.md)
+    - [State diff compression v1 spec](./settlement_contracts/data_availability/state_diff_compression_v1_spec.md)
+  - L1->L2 transaction handling
+    - [Processing of L1->L2 transactions](./settlement_contracts/priority_queue/processing_of_l1->l2_txs.md)
+    - [Priority queue](./settlement_contracts/priority_queue/priority-queue.md)
 - Chain Management
-    - [Chain type manager](./chain_management/chain_type_manager.md)
-    - [Admin role](./chain_management/admin_role.md)
-    - [Chain genesis](./chain_management/chain_genesis.md)
-    - [Standard Upgrade process](./chain_management/upgrade_process.md)
+  - [Chain type manager](./chain_management/chain_type_manager.md)
+  - [Admin role](./chain_management/admin_role.md)
+  - [Chain genesis](./chain_management/chain_genesis.md)
+  - [Standard Upgrade process](./chain_management/upgrade_process.md)
 - Bridging
-    - Bridgehub
-        - [Overview of the bridgehub functionality](./bridging/bridgehub/overview.md)
-    - [Asset Router](./bridging/asset_router/Overview.md)
+  - Bridgehub
+    - [Overview of the bridgehub functionality](./bridging/bridgehub/overview.md)
+  - [Asset Router](./bridging/asset_router/Overview.md)
 - L2 System Contracts
-    - [System contracts bootloader description](./l2_system_contracts/system_contracts_bootloader_description.md)
-    - [Batches and blocks on ZKsync](./l2_system_contracts/batches_and_blocks_on_zksync.md)
-    - [Elliptic curve precompiles](./l2_system_contracts/elliptic_curve_precompiles.md)
-    - [ZKsync fee model](./l2_system_contracts/zksync_fee_model.md)
+  - [System contracts bootloader description](./l2_system_contracts/system_contracts_bootloader_description.md)
+  - [Batches and blocks on ZKsync](./l2_system_contracts/batches_and_blocks_on_zksync.md)
+  - [Elliptic curve precompiles](./l2_system_contracts/elliptic_curve_precompiles.md)
+  - [ZKsync fee model](./l2_system_contracts/zksync_fee_model.md)
 - 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)
-    - [Gateway protocol versioning](./gateway/gateway_protocol_upgrades.md)
-    - [DA handling on Gateway](./gateway/gateway_da.md)
+  - [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)
+  - [Gateway protocol versioning](./gateway/gateway_protocol_upgrades.md)
+  - [DA handling on Gateway](./gateway/gateway_da.md)
 - Upgrade history
-    - [Gateway upgrade diff](./upgrade_history/gateway_upgrade/gateway_diff_review.md)
-    - [Gateway upgrade process](./upgrade_history/gateway_upgrade/upgrade_process.md)
+  - [Gateway upgrade diff](./upgrade_history/gateway_upgrade/gateway_diff_review.md)
+  - [Gateway upgrade process](./upgrade_history/gateway_upgrade/upgrade_process.md)
 
 ![Reading order](./img/reading_order.png)
 
-# Invariants/tricky places to look out for
+## For auditors: Invariants/tricky places to look out for
 
 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.
-- 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)
+- 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 leafs and chain id leafs 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).
+- 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).

docs/bridging/asset_router/Overview.md

@@ -1,18 +1,19 @@
 # Overview of Custom Asset Bridging with the Asset Router
+
 [back to readme](../../README.md)
 
 Bridges are completely separate contracts from the ZKChains and system contracts. They are a wrapper for L1 <-> L2 communication on both L1 and L2. Upon locking assets on one layer, a request is sent to mint these bridged assets on the other layer.
 Upon burning assets on one layer, a request is sent to unlock them on the other.
 
 Custom asset bridging is a new bridging model that allows to:
 
-1. Minimize the effort needed by custom tokens to be able to become part of the elastic chain ecosystem. Before, each custom token would have to build its own bridge, but now just custom asset deployment trackers / asset handler is needed. This is achieved by building a modular bridge which separates the logic of L1<>L2 messaging from the holding of the asset. 
+1. Minimize the effort needed by custom tokens to be able to become part of the elastic chain ecosystem. Before, each custom token would have to build its own bridge, but now just custom asset deployment trackers / asset handler is needed. This is achieved by building a modular bridge which separates the logic of L1<>L2 messaging from the holding of the asset.
 2. Unify the interfaces between L1 and L2 bridge contracts, paving the way for easy cross chain bridging. It will especially become valuable once interop is enabled.
 
 #### New concepts
 
 - assetId => identifier to track bridged assets across chains. This is used to link messages to specific asset handlers in the AssetRouters.
-- AssetHandler => contract that manages liquidity (burns/mints, locks/unlocks, etc.) for specific token (or a set of them) on a chain. Every asset  
+- AssetHandler => contract that manages liquidity (burns/mints, locks/unlocks, etc.) for specific token (or a set of them) on a chain. Every asset
 - AssetDeploymentTracker => contract that manages the deployment of asset handlers across chains. This is the contract that registers these asset handlers in the AssetRouters.
 
 ### Normal flow

docs/bridging/asset_router/asset_router.md

@@ -1,4 +1,5 @@
 # AssetRouters (L1/L2) and NativeTokenVault
+
 [back to readme](../../README.md)
 
 The main job of the asset router is to be the central point of coordination for bridging. All crosschain token bridging is done between asset routers only and once the message reaches asset router, it then routes it to the corresponding asset handler.
@@ -10,23 +11,22 @@ The endgame is to have L1 asset router have the same functionality as the L2 one
 The specifics of the L2AssetRouter is the need to interact with the previously deployed L2SharedBridgeLegacy if it was already present. It has less “rights” than the L1AssetRouter: at the moment it is assumed that all asset deployment trackers are from L1, the only way to register an asset handler on L2 is to make an L1→L2 transaction.
 
 > Note, that today registering new asset deployment trackers will be permissioned, but the plan is to make it permissionless in the future
-> 
 
 The specifics of the L1AssetRouter come from the need to be backwards compatible with the old L1SharedBridge. Yes, it will not share the same storage, but it will inherit the need to be backwards compatible with the current SDK. Also, L1AssetRouter needs to facilitate L1-only operations, such as recovering from failed deposits.
 
 Also, L1AssetRouter is the only base token bridge contract that can participate in initiation of cross chain transactions via the bridgehub. This will change in the future with the support of interop.
 
 ### L1Nullifier
 
-While the endgoal is to unify L1 and L2 asset routers, in reality, it may not be that easy: while L2 asset routers get called by L1→L2 transactions, L1 ones don't and require manual finalization of transactions, which involves proof verification, etc. To move this logic outside of the L1AssetRouter, it was moved into a separate L1Nullifier contract. 
+While the endgoal is to unify L1 and L2 asset routers, in reality, it may not be that easy: while L2 asset routers get called by L1→L2 transactions, L1 ones don't and require manual finalization of transactions, which involves proof verification, etc. To move this logic outside of the L1AssetRouter, it was moved into a separate L1Nullifier contract.
 
-*This is the contract the previous L1SharedBridge will be upgraded to, so it should have the backwards compatible storage.*
+_This is the contract the previous L1SharedBridge will be upgraded to, so it should have the backwards compatible storage._
 
 ### NativeTokenVault (L1/L2)
 
 NativeTokenVault is an asset handler that is available on all chains and is also predeployed. It is provides the functionality of the most basic bridging: locking funds on one chain and minting the bridged equivalent on the other one. On L2 chains NTV is predeployed at the `0x10004` address.
 
-The L1 and L2 versions of the NTV are almost identical in functionality, the main differences come from the differences of the deployment functionality in L1 and L2 envs, where the former uses standard CREATE2 and the latter uses low level calls to `CONTRACT_DEPLOYER`system contract. 
+The L1 and L2 versions of the NTV are almost identical in functionality, the main differences come from the differences of the deployment functionality in L1 and L2 envs, where the former uses standard CREATE2 and the latter uses low level calls to `CONTRACT_DEPLOYER`system contract.
 
 Also, the L1NTV has the following specifics:
 
@@ -43,5 +43,5 @@ This contract is never deployed for new chains.
 ### Summary
 
 ![image.png](./img/bridge_contracts.png)
+
 > New bridge contracts
->