another reorg

docs/README.md

@@ -1,8 +1,35 @@
 # ZK Stack contracts specs
 
-1. [Introduction](./introduction.md)
-1. [Bridgehub](./bridgehub/README.md)
-1. [ZKChain](./zk_chain/README.md)
-1. [L1 Contracts](./l1_smart_contracts.md)
+- [Glossary](./glossary.md)
+- [Overview](./overview.md)
+- [Bridging](./bridging/overview.md)
+    - [Bridgehub](./bridgehub/overview.md)
+        - [Chain registry](./bridgehub/chain_registry.md)
+        - [L1 ecosystem contracts](./bridgehub/bridgehub.md)
+    - [Asset Router](./asset_router/overview.md)
+- [Chain Management](./chain_management/overview.md)
+    - [Chain type manager](./chain_management/chain_type_manager.md)
+    - [Admin roles](./chain_management/admin_roles.md)
+    - [Chain genesis](./chain_management/chain_genesis.md)
+    - [Upgrade process](./chain_management/upgrade_process.md)
+- [Settlement contracts](./settlement_contracts/overview.md)
+    - [L1 smart contracts](./settlement_contracts/l1_smart_contracts.md)
+    - [Data availability](./settlement_contracts/data_availability.md)
+        - [Custom DA](./settlement_contracts/data_availability/custom_da.md)
+        - [Rollup DA](./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)
+    - [Priority Queue](./settlement_contracts/priority_queue.md)
+- [L2 System Contracts](./l2_system_contracts.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)
+    - [L2 processing of L1->L2 transactions](./l2_system_contracts/l2_processing_of_l1->l2_txs.md)
+    - [System contracts bootloader description](./l2_system_contracts/system_contracts_bootloader_description.md)
+    - [ZKsync fee model](./l2_system_contracts/zksync_fee_model.md)
+- [Gateway](./gateway/overview.md)
+    - [Chain migration](./gateway/chain_migration.md)
+    - [Gateway protocol upgrades](./gateway/gateway_protocol_upgrades.md)
+- [Upgrade History](./upgrade_history.md)
+    - [Gateway upgrade](./upgrade_history/gateway_upgrade.md)
 
 ![Reading order](./img/reading_order.png)

docs/bridging/asset_router/Overview.md

@@ -0,0 +1,46 @@
+#### Bridges
+
+Bridges are completely separate contracts from the Diamond. They are a wrapper for L1 <-> L2 communication on contracts
+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.
+
+Unlike the native Ether bridging, all other assets can be bridged by the custom implementation relying on the trustless
+L1 <-> L2 communication.
+
+##### L1ERC20Bridge
+
+The legacy implementation of the ERC20 token bridge. Works only with regular ERC20 tokens, i.e. not with
+fee-on-transfer tokens or other custom logic for handling user balances. Only works for Era.
+
+- `deposit` - lock funds inside the contract and send a request to mint bridged assets on L2.
+- `claimFailedDeposit` - unlock funds if the deposit was initiated but then failed on L2.
+- `finalizeWithdrawal` - unlock funds for the valid withdrawal request from L2.
+
+##### L1AssetRouter
+
+The "standard" implementation of the ERC20 and WETH token bridge. Works only with regular ERC20 tokens, i.e. not with
+fee-on-transfer tokens or other custom logic for handling user balances.
+
+- `deposit` - lock funds inside the contract and send a request to mint bridged assets on L2.
+- `claimFailedDeposit` - unlock funds if the deposit was initiated but then failed on L2.
+- `finalizeWithdrawal` - unlock funds for the valid withdrawal request from L2.
+
+The bridge also handles WETH token deposits between the two domains. It is designed to streamline and
+enhance the user experience for bridging WETH tokens by minimizing the number of transactions required and reducing
+liquidity fragmentation thus improving efficiency and user experience.
+
+This contract accepts WETH deposits on L1, unwraps them to ETH, and sends the ETH to the L2 WETH bridge contract, where
+it is wrapped back into WETH and delivered to the L2 recipient.
+
+Thus, the deposit is made in one transaction, and the user receives L2 WETH that can be unwrapped to ETH.
+
+##### L2SharedBridge
+
+The L2 counterpart of the L1 Shared bridge.
+
+- `withdraw` - initiate a withdrawal by burning funds on the contract and sending a corresponding message to L1.
+- `finalizeDeposit` - finalize the deposit and mint funds on L2.
+
+For WETH withdrawals, the contract receives ETH from the L2 WETH bridge contract, wraps it into WETH, and sends the WETH to
+the L1 recipient.
+

docs/bridging/custom_asset_bridging/contracts_review_cab.md → docs/bridging/asset_router/asset_router.md

@@ -32,47 +32,3 @@ The Native Token Vault is a special case of the Asset Handler, as we want it to
 
 ![Automatic Bridge](./automatic-bridging.png)
 
-## Known Issues
-
-### storage layout
-
-L2SharedBridge will be a system contract, L2NativeTokenVault will replace it (the storage layout is still not yet backwards compatible)
-
-### bridgehubDeposit API change
-
-> /// @notice Allows bridgehub to acquire mintValue for L1->L2 transactions.
-
-    /// @dev If the corresponding L2 transaction fails, refunds are issued to a refund recipient on L2.
-    function bridgehubDepositBaseToken(
-        uint256 _chainId,
-        bytes32 _assetId,
-
-Note, that the new SB is not compatible with both:
-
-- old Mailbox on Era
-- old Bridgehub
-- And vice versa.
-
-We need to either:
-
-- ensure that all 3 get upgraded at the same time. Upgrading BH and SB at the same time is feasible IMHO. But upgrading DP (Mailbox) in the same transaction may not be.
-- have a concrete plan for such case. E.g. explicitly tell that the legacy deposits will stop working. In this case we need to check (at the very least visually) that the worst thing that can happen is just deposits not working and not some funds lost
-- Add the corresponding legacy functions
-
-### Not allowing legacy withdrawals
-
-> require(!\_isEraLegacyEthWithdrawal(\_chainId, \_l2BatchNumber), "ShB: legacy eth withdrawal");
-
-No method to finalize an old withdrawal.
-We will manually finalize all legacy withdrawals before the upgrade, i.e. withdrawals that happened before the previous Bridgehub upgrade.
-
-### Custom Errors not implemented
-
-> require(expectedDepositAmount == \_depositAmount, "3T"); // The token has non-standard transfer logic
-
-Custom errors will be introduced for all contracts.
-
-## Migration plan
-
-- Bulkheads will need to be migrated (methods added)
-- Tokens will have to be transferred (methods added)