matter-labs · kelemeno · Oct 26, 2024 · Oct 26, 2024 · Oct 26, 2024 · Oct 26, 2024
diff --git a/docs/README.md b/docs/README.md
@@ -1,8 +1,8 @@
-# Documentation index
+# 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)
 
-
-## Structure of the repo
-
-1. 
-1. [System contracts/bootloader description](./other/System%20contracts%20bootloader%20description.md).
+![Reading order](./img/reading_order.png)
diff --git a/docs/bridging/bridgehub/README.MD b/docs/bridging/bridgehub/README.MD
diff --git a/...idgehub/img/L1_L2_tx_processing_on_L2.png → ...idgehub/img/L1_L2_tx_processing_on_L2.png b/...idgehub/img/L1_L2_tx_processing_on_L2.png → ...idgehub/img/L1_L2_tx_processing_on_L2.png
diff --git a/docs/bridgehub/img/gateway-architecture.png → ...ng/bridgehub/img/gateway-architecture.png b/docs/bridgehub/img/gateway-architecture.png → ...ng/bridgehub/img/gateway-architecture.png
diff --git a/docs/bridgehub/img/newChain.png → docs/bridging/bridgehub/img/newChain.png b/docs/bridgehub/img/newChain.png → docs/bridging/bridgehub/img/newChain.png
diff --git a/...dgehub/img/requestL2TransactionDirect.png → ...dgehub/img/requestL2TransactionDirect.png b/...dgehub/img/requestL2TransactionDirect.png → ...dgehub/img/requestL2TransactionDirect.png
diff --git a/...ransactionTwoBridges_depositEthToUSDC.png → ...ransactionTwoBridges_depositEthToUSDC.png b/...ransactionTwoBridges_depositEthToUSDC.png → ...ransactionTwoBridges_depositEthToUSDC.png
diff --git a/.../requestL2TransactionTwoBridges_token.png → .../requestL2TransactionTwoBridges_token.png b/.../requestL2TransactionTwoBridges_token.png → .../requestL2TransactionTwoBridges_token.png
diff --git a/docs/bridgehub/l1_ecosystem_contracts.md → ...dging/bridgehub/l1_ecosystem_contracts.md b/docs/bridgehub/l1_ecosystem_contracts.md → ...dging/bridgehub/l1_ecosystem_contracts.md
@@ -14,13 +14,13 @@
 We want to create a system where:
 
 - ZK chains should be launched permissionlessly within the ecosystem.
-- Hyperbridges should enable unified liquidity for assets across the ecosystem.
+- 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.
 
 
 ### Images:
 
-![Contracts](./L1%20smart%20contracts/gateway-architecture.png)
+![Contracts](./img/gateway-architecture.png)
 
 > This document will not cover how ZK Gateway works, you can check it out in a separate doc (TODO: link).
 
@@ -91,7 +91,7 @@
 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
@@ -178,13 +178,13 @@

 For the purpose of this document, it is enough to treat the Asset Router as a blackbox that is responsible for processing escrowing funds on the source chain and minting them on the destination chain.

 > For those that are aware of the [previous zkSync architecture](https://github.com/code-423n4/2024-03-zksync/blob/main/docs/Smart%20contract%20Section/L1%20ecosystem%20contracts.md), its role is similar to L1SharedBridge that we had before. Note, however, that it is a different contract with much enhanced functionality. Also, note that the L1SharedBridge will NOT be upgraded to the L1AssetRouter. For more detials about migration, please check out the migration doc (FIXME: migration doc).

 ### Handling base tokens

 On L2, *a base token* (not to be consfused with a *native token*, i.e. an ERC20 token with a main contract on the chain) is the one that is used for `msg.value` and it is managed at `L2BaseToken` system contract. We need its logic to be strictly defined in `L2BaseToken`, since the base asset is expected to behave the exactly the same as ether on EVM. For now this token contract does not support base minting and burning of the asset, nor further customization.

 In other words, in the current release base assets can only be transfered through `msg.value`. They can also only be minted when they are backed 1-1 on L1.

 ### **L1→L2 communication**

@@ -300,7 +300,7 @@
 1. After some time, the corresponding L1→L2 is created.
 2. The L2AssetRouter will receive the message and re-route it to the asset handler of the bridged token. To read more about how it works, check out the custom asset bridging documentation (FIXME: link). 

 ***Diagram of a depositing ETH onto a chain with USDC as the baseToken. Note that some contract calls (like `USDC.transerFrom` are omitted for the sake of consiceness):***

 ![requestL2TransactionTwoBridges (SharedBridge) (1).png](./L1%20smart%20contracts/requestL2TransactionTwoBridges_depositEthToUSDC.png)


diff --git a/...om_asset_bridging/contracts_review_cab.md → ...om_asset_bridging/contracts_review_cab.md b/...om_asset_bridging/contracts_review_cab.md → ...om_asset_bridging/contracts_review_cab.md
diff --git a/...asset_bridging/img/asset-registration.png → ...asset_bridging/img/asset-registration.png b/...asset_bridging/img/asset-registration.png → ...asset_bridging/img/asset-registration.png
diff --git a/...asset_bridging/img/automatic-bridging.png → ...asset_bridging/img/automatic-bridging.png b/...asset_bridging/img/automatic-bridging.png → ...asset_bridging/img/automatic-bridging.png
diff --git a/docs/chain_managment/chain_genesis.md b/docs/chain_managment/chain_genesis.md
diff --git a/docs/chain_managment/upgrade_process.md b/docs/chain_managment/upgrade_process.md
diff --git a/...teway_protocol_versioning_and_upgrades.md → docs/gateway/gateway_protocol_upgrades.md b/...teway_protocol_versioning_and_upgrades.md → docs/gateway/gateway_protocol_upgrades.md
diff --git a/docs/img/reading_order.png b/docs/img/reading_order.png
diff --git a/docs/data_availability/Rollup DA.md → ..._contracts/data_availability/Rollup DA.md b/docs/data_availability/Rollup DA.md → ..._contracts/data_availability/Rollup DA.md
diff --git a/...a_availability/Standard pubdata format.md → ...a_availability/Standard pubdata format.md b/...a_availability/Standard pubdata format.md → ...a_availability/Standard pubdata format.md
diff --git a/docs/data_availability/custom-da.md → ..._contracts/data_availability/custom-da.md b/docs/data_availability/custom-da.md → ..._contracts/data_availability/custom-da.md
diff --git a/docs/data_availability/custom_da_support.md → ...ts/data_availability/custom_da_support.md b/docs/data_availability/custom_da_support.md → ...ts/data_availability/custom_da_support.md
diff --git a/...a_availability/img/Custom-da-external.png → ...a_availability/img/Custom-da-external.png b/...a_availability/img/Custom-da-external.png → ...a_availability/img/Custom-da-external.png
diff --git a/docs/data_availability/img/Rollup_DA.png → ...racts/data_availability/img/Rollup_DA.png b/docs/data_availability/img/Rollup_DA.png → ...racts/data_availability/img/Rollup_DA.png
diff --git a/docs/data_availability/img/custom_da.png → ...racts/data_availability/img/custom_da.png b/docs/data_availability/img/custom_da.png → ...racts/data_availability/img/custom_da.png
diff --git a/...ability/state_diff_compression_v1_spec.md → ...ability/state_diff_compression_v1_spec.md b/...ability/state_diff_compression_v1_spec.md → ...ability/state_diff_compression_v1_spec.md
diff --git a/docs/ctm_and_diamond/img/Diamond-scheme.png → ...ttlement_contracts/img/Diamond-scheme.png b/docs/ctm_and_diamond/img/Diamond-scheme.png → ...ttlement_contracts/img/Diamond-scheme.png
diff --git a/docs/ctm_and_diamond/l1_smart_contracts.md → ...ettlement_contracts/l1_smart_contracts.md b/docs/ctm_and_diamond/l1_smart_contracts.md → ...ettlement_contracts/l1_smart_contracts.md
diff --git a/docs/priority_queue/img/PQ1.png → ...ment_contracts/priority_queue/img/PQ1.png b/docs/priority_queue/img/PQ1.png → ...ment_contracts/priority_queue/img/PQ1.png
diff --git a/docs/priority_queue/img/PQ2.png → ...ment_contracts/priority_queue/img/PQ2.png b/docs/priority_queue/img/PQ2.png → ...ment_contracts/priority_queue/img/PQ2.png
diff --git a/docs/priority_queue/img/PQ3.png → ...ment_contracts/priority_queue/img/PQ3.png b/docs/priority_queue/img/PQ3.png → ...ment_contracts/priority_queue/img/PQ3.png
diff --git a/docs/priority_queue/priority-merkle-tree.md → ...ts/priority_queue/priority-merkle-tree.md b/docs/priority_queue/priority-merkle-tree.md → ...ts/priority_queue/priority-merkle-tree.md
diff --git a/...upgrade/contract_and_sdk_compatibility.md → ...upgrade/contract_and_sdk_compatibility.md b/...upgrade/contract_and_sdk_compatibility.md → ...upgrade/contract_and_sdk_compatibility.md
diff --git a/docs/upgrades/gateway_upgrade/upgrade_process.md b/docs/upgrades/gateway_upgrade/upgrade_process.md