some more changes

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_managment/overview.md)
+    - [Chain type manager](./chain_managment/chain_type_manager.md)
+    - [Admin roles](./chain_managment/admin_roles.md)
+    - [Chain genesis](./chain_managment/chain_genesis.md)
+    - [Upgrade process](./chain_managment/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/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)

docs/bridging/bridgehub/l1_ecosystem_contracts.md → docs/bridging/bridgehub/bridgehub.md

@@ -242,18 +242,8 @@ Note, however, that it is not the way to withdraw base token. To withdraw base t
 
 After the batch with the withdrawal request has been executed, the user can finalize the withdrawal on L1 by calling `L1AssetRouter.finalizeWithdrawal`, where the user provides the proof of the corresponding withdrawal message.
 
-# Additional limitations for the current release
+# Additional limitations for the current version
 
-In the current release creating new chains will not be permissionless. That is needed to ensure that no malicious input can be provided there. 
+In the current version creating new chains will not be permissionless. That is needed to ensure that no malicious input can be provided there. 
 
 Also, since in the current release, there will be little benefits from shared liquidity, i.e. the there will be no direct ST<>ST transfers supported, as a measure of additional security we’ll also keep track of balances for each individual ST and will not allow it to withdraw more than it has deposited into the system.
-
-# Other contracts
-
-## Governance
-
-The documentation about decentralized governance can be read here (FIXME: provide link).
-
-## ValidatorTimelock
-
-All the chains registered on the current CTM share the same timelock for batch execution. It is a security feature, you can read more about it [here](./L1%20smart%20contracts.md#validatortimelock). 

docs/bridging/bridgehub/chain_registry.md

@@ -0,0 +1,2 @@
+# Chain registry
+https://github.com/ethereum/ERCs/pull/669/files

docs/chain_managment/chain_type_manager.md

@@ -0,0 +1,68 @@
+## Chain Type Manager (CTM)
+
+> If someone is already familiar with the [previous version](https://github.com/code-423n4/2024-03-zksync) of zkSync architecture, this contract was previously known as "State Transition Manager (CTM)".
+
+Currently bridging between different zk rollups requires the funds to pass through L1. This is slow & expensive.
+
+The vision of seamless internet of value requires transfers of value to be *both* seamless and trustless. This means that for instance different STs need to share the same L1 liquidity, i.e. a transfer of funds should never touch L1 in the process. However, it requires some sort of trust between two chains. If a malicious (or broken) rollup becomes a part of the shared liquidity pool it can steal all the funds. 
+
+However, can two instances of the same zk rollup trust each other? The answer is yes, because no new additions of rollups introduce new trust assumptions. Assuming there are no bugs in circuits, the system will work as intended.
+
+How can two rollups know that they are two different instances of the same system? We can create a factory of such contracts (and so we would know that each new rollup created by this instance is correct one). But just creating correct contracts is not enough. Ethereum changes, new bugs may be found in the original system & so an instance that does not keep itself up-to-date with the upgrades may exploit some bug from the past and jeopardize the entire system. Just deploying is not enough. We need to constantly make sure that all STs are up to date and maintain whatever other invariants are needed for these STs to trust each other.  
+
+Let’s define as *Chain Type Manager* (CTM) **as a contract that is responsible for the following:
+
+- It serves as a factory to deploy STs (new ZK chains)
+- It is responsible for ensuring that all the STs deployed by it are up-to-date.
+
+Note, that this means that STs have a “weaker” governance. I.e. governance can only do very limited number of things, such as setting the validator. ST admin can not set its own upgrades and it can only “execute” the upgrade that has already been prepared by the CTM.
+
+In the long term vision STs deployment will be permissionless, however CTM will always remain the main point of trust and will have to be explicitly whitelisted by the decentralized governance of the entire ecosystem before its ST can get the access to the shared liquidity.
+
+## Configurability in the first release
+
+For now, only one CTM will be supported — the one that deploys instances of zkSync Era, possibly using other DA layers. To read more about different DA layers, check out this document (FIXME link).
+
+The exact process of deploying & registering a ST will be described in [sections below](#creating-new-chains-with-bridgehub). Overall, each ST in the first release will have the following parameters:
+
+| ST parameter | Updatability | Comment |
+| --- | --- | --- |
+| chainId | Permanent | Permanent identifier of the ST. Due to wallet support reasons, for now chainId has to be small (48 bits). This is one of the reasons why for now we’ll deploy STs manually, to prevent STs from having the same chainId as some another popular chain.  In the future it will be trustlessly assigned as a random 32-byte value.|
+| baseTokenAssetId | Permanent | Each ST can have their own custom base token (i.e. token used for paying the fees). It is set once during creation and can never be changed. Note, that we refer to and "asset id" here instead of an L1 address. To read more about what is assetId and how it works check out the document for custom asset bridging (FIXME: link) |
+| chainTypeManager | Permanent | The CTM that deployed the ST. In principle, it could be possible to migrate between CTMs (assuming both CTMs support that). However, in practice it may be very hard and as of now such functionality is not supported. |
+| admin | By admin of ST | The admin of the ST. It has some limited powers to govern the chain. To read more about which powers are available to a chain admin and which precautions should be taken, check out this document (FIXME: link to document about admin precauotions) |
+| validatorTimelock | CTM | For now, we want all the chains to use the same 21h timelock period before their batches are finalized. Only CTM can update the address that can submit state transitions to the rollup (that is, the validatorTimelock).  |
+| validatorTimelock.validator | By admin of ST | The admin of ST can choose who can submit new batches to the ValidatorTimelock.  |
+|  priorityTx FeeParams | By admin of ST | The admin of a ZK chain can amend the priority transaction fee params. |
+|  transactionFilterer | By admin of ST | A chain may put an additional filter to the incoming L1->L2 transactions. This may be needed by a permissioned chain (e.g. a Validium bank-lile corporate chain). |
+|  DA validation / permanent rollup status | By admin of ST | A chain can decide which DA layer to use. You check out more about safe DA management here (FIXME: link to admin doc) |
+| executing upgrades | By admin of ST | While exclusively CTM governance can set the content of the upgrade, STs will typically be able to choose suitable time for them to actually execute it. In the first release, STs will have to follow our upgrades. |
+| settlement layer | By admin of ST | The admin of the chain can enact migrations to other settlement layers. |
+
+> Note, that if we take a look at the access control for the corresponding functions inside the [AdminFacet](../../l1-contracts/contracts/state-transition/chain-deps/facets/Admin.sol), the may see that a lot of methods from above that are marked as "By admin of ST" could be in theory amended by the ChainTypeManager. However, this sort of action requires approval from decentralized governance. Also, in case of an urgent high risk situation, the decentralized governance might force upgrade the contract via CTM.
+
+## Upgradability in the current release
+
+In the first release, each chain will be an instance of zkSync Era and so the upgrade process of each individual ST will be similar to that of zkSync Era.
+
+1. Firstly, the governance of the CTM will publish the server (including sequencer, prover, etc) that support the new version . This is done offchain. Enough time should be given to various zkStack devs to update their version.
+2. The governance of the CTM will publish the upgrade onchain by atomatically executing the following three transactions:
+
+- `setChainCreationParams` ⇒ to ensure that new chains will be created with the version 
+- `setValidatorTimelock` (if needed) ⇒ to ensure that the new chains will use the new validator timelock right-away
+- `setNewVersionUpgrade` ⇒ to save the upgrade information that each ST will need to follow to conduct the upgrade on their side.
+
+3. After that, each ChainAdmin can upgrade to the new version in suitable time for them. 
+
+> Note, that while the governance does try to give the maximal possible time for chains to upgrade, the governance will typically put restrictions (aka deadlines) on the time by which the chain has to be upgraded. If the deadline is passed, the chain can not commit new batches until the upgrade is executed.
+
+### Emergency upgrade
+
+In case of an emergency, the [security council](https://blog.zknation.io/introducing-zk-nation/) has the ability to freeze the ecosystem and conduct an emergency upgrade (FIXME: link to governance doc).
+
+In case we are aware that some of the committed batches on an ST are dangerous to be executed, the CTM can call `revertBatches` on that ST. For faster reaction, the admin of the ChainTypeManager has the ability to do so without waiting for govenrnace approval that may take a lot of time. This action does not lead to funds being lost, so it is considered suitable for the partially trusted role of the admin of the ChainTypeManager.
+
+### Issues & caveats
+
+- If an ZK chain skips an upgrade (i.e. it has version X, it did not upgrade to `X + 1` and now the latest protocol version is `X + 2` there is no built-in way to upgrade). This team will require manual intervention from us to upgrade.
+- The approach of calling `revertBatches` for malicious STs is not scalable (O(N) of the number of chains). The situation is very rare, so it is fine in the short term, but not in the long run.