Merge pull request #997 from matter-labs/sb-port-docs-to-reorg

Port docs to kl/sync-layer-reorg

.github/SECURITY.md

@@ -5,7 +5,7 @@ We truly appreciate efforts to discover and disclose security issues responsibly
 ## Vulnerabilities
 
 If you'd like to report a security issue in the repositories of matter-labs organization, please proceed to our
-[Bug Bounty Program on Immunefi](https://era.zksync.io/docs/reference/troubleshooting/audit-bug-bounty.html#bug-bounty-program).
+[Bug Bounty Program on Immunefi](https://immunefi.com/bug-bounty/zksyncera/information/).
 
 ## Other Security Issues
 

.github/workflows/dead-links.yaml

@@ -0,0 +1,22 @@
+name: Check Dead Links in Markdown Files
+
+on: pull_request
+
+jobs:
+  check-dead-links:
+    name: Check Dead Links in Markdown Files
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install Rust and Lychee
+        run: |
+          curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
+          ~/.cargo/bin/cargo install lychee
+
+      - name: Find and check markdown files
+        run: |
+          GITHUB_TOKEN=${{ secrets.GITHUB_TOKEN }}
+          find . -type f -name "*.md" ! -path "*/node_modules/*" ! -path "*/openzeppelin*" ! -path "*/murky/*" -exec lychee --github-token $GITHUB_TOKEN {} +

CONTRIBUTING.md

@@ -13,7 +13,7 @@ There are many ways to contribute to the ZK Stack:
    issues.
 3. Resolve issues: either by showing an issue isn't a problem and the current state is ok as is or by fixing the problem
    and opening a PR.
-4. Report security issues, see [our security policy](./github/SECURITY.md).
+4. Report security issues, see [our security policy](./.github/SECURITY.md).
 5. [Join the team!](https://matterlabs.notion.site/Shape-the-future-of-Ethereum-at-Matter-Labs-dfb3b5a037044bb3a8006af2eb0575e0)
 
 ## Fixing issues
@@ -34,7 +34,7 @@ We aim to make it as easy as possible to contribute to the mission. This is stil
 and suggestions here too. Some resources to help:
 
 1. [In-repo docs aimed at developers](docs)
-2. [ZKsync Era docs!](https://era.zksync.io/docs/)
+2. [ZKsync Era docs!](https://docs.zksync.io/zk-stack)
 3. Company links can be found in the [repo's readme](README.md)
 
 ## Code of Conduct

README.md

@@ -8,7 +8,7 @@ or re-auditing a single line of code. ZKsync Era also uses an LLVM-based compile
 write smart contracts in C++, Rust and other popular languages.
 
 This repository contains both L1 and L2 ZKsync smart contracts. For their description see the
-[system overview](docs/Overview.md).
+[system overview](docs/overview.md).
 
 ## Disclaimer
 

SECURITY.md

@@ -5,7 +5,7 @@ We truly appreciate efforts to discover and disclose security issues responsibly
 ## Vulnerabilities
 
 If you'd like to report a security issue in the repositories of matter-labs organization, please proceed to our
-[Bug Bounty Program on Immunefi](https://era.zksync.io/docs/reference/troubleshooting/audit-bug-bounty.html#bug-bounty-program).
+[Bug Bounty Program on Immunefi](https://immunefi.com/bug-bounty/zksyncera/information/).
 
 ## Other Security Issues
 

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)
+
+## 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)
+- 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 leaves and chain id leaves 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/asset_router.md

@@ -0,0 +1,47 @@
+# 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