Port docs to kl/sync-layer-reorg

docs/README.md

@@ -0,0 +1,52 @@
+# ZK Stack contracts specs
+
+The order of the files here only roughly represents the order of reading. A lot of topics are intertwined, so it is recommended to read everything first to have a complete picture and then refer to specific documents for more details.
+
+- [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)
+- 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)
+- Bridging
+  - 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)
+- 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)
+- Upgrade history
+  - [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
+
+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)
+- 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).

docs/bridging/asset_router/Overview.md

@@ -0,0 +1,33 @@
+# 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.
+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  
+- 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
+
+Assets Handlers are registered in the Routers based on their assetId. The assetId is used to identify the asset when bridging, it is sent with the cross-chain transaction data and Router routes the data to the appropriate Handler. If the asset handler is not registered in the L2 Router, then the L1->L2 bridging transaction will fail on the L2 (expect for NTV assets, see below).
+
+`assetId = keccak256(chainId, asset deployment tracker = msg.sender, additionalData)`
+
+Asset registration is handled by the AssetDeploymentTracker. It is expected that this contract is deployed on the L1. Registration of the assetHandler on a ZKChain can be permissionless depending on the Asset (e.g. the AssetHandler can be deployed on the chain at a predefined address, this can message the L1 ADT, which can then register the asset in the Router). Registering the L1 Handler in the L1 Router can be done via a direct function call from the L1 Deployment Tracker. Registration in the L2 Router is done indirectly via the L1 Router.
+
+![Asset Registration](./img/custom_asset_handler_registration.png)
+
+The Native Token Vault is a special case of the Asset Handler, as we want it to support automatic bridging. This means it should be possible to bridge a L1 token to an L2 without deploying the Token contract beforehand and without registering it in the L2 Router. For NTV assets, L1->L2 transactions where the AssetHandler is not registered will not fail, but the message will be automatically be forwarded to the L2NTV. Here the contract checks that the asset is indeed deployed by the L1NTV, by checking that the assetId contains the correct ADT address (note, for NTV assets the ADT is the NTV and the used address is the L2NTV address). If the assetId is correct, the token contract is deployed.
+
+### Read more
+
+You can read more in the more in-depth about L1 and L2 asset routers and the default asset handler that is Native Token Vault [here](./asset_router.md).

docs/bridging/asset_router/asset_router.md

@@ -0,0 +1,48 @@
+# 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.
+
+In order to make this easier, all L2 chains have the asset router located on the same address on every chain. It is `0x10003` and it is pre-deployed contract. More on how it is deployed can be seen in the [Chain Genesis](../../chain_management/chain_genesis.md) section.
+
+The endgame is to have L1 asset router have the same functionality as the L2 one. This is not the case yet, but some progress has been made: L2AssetRouter can now bridge L2-native assets to L1, from which it could be bridged to other chains in the ecosystem.
+
+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.
+
+*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.
+
+Also, the L1NTV has the following specifics:
+
+- It operates the `chainBalance` mapping, ensuring that the chains do not go beyond their balances.
+- It allows recovering from failed L1→L2 transfers.
+- It needs to both be able to retrieve funds from the former L1SharedBridge (now this contract has L1Nullifier in its place), but also needs to support the old SDK that gives out allowance to the “l1 shared bridge” value returned from the API, i.e. in our case this is will the L1AssetRouter.
+
+### L2SharedBridgeLegacy
+
+L2AssetRouter has to be pre-deployed onto a specific address. The old L2SharedBridge will be upgraded to L2SharedBridgeLegacy contract. The main purpose of this contract is to ensure compatibility with the incoming deposits and re-route them to the shared bridge.
+
+This contract is never deployed for new chains.
+
+### Summary
+
+![image.png](./img/bridge_contracts.png)
+> New bridge contracts
+>