docs: update developer reference docs (#126)

# Description

Update developer reference docs from
https://github.com/code-423n4/2024-03-zksync/tree/main/docs

---------

Co-authored-by: Razzor <[email protected]>
Co-authored-by: Nicolas Villanueva <[email protected]>

Author: 3 people

.gitignore

@@ -99,4 +99,6 @@ yarn.lock
 .nitro
 .cache
 dist
-.firebase
+.firebase
+
+.vscode/

.lintstagedrc.yml

@@ -3,6 +3,6 @@
   - eslint
 '*.md':
   - markdownlint-cli2
-  - cspell lint --file
+  - cspell lint --no-must-find-files --files
 '*.{json,yml}':
   - prettier --list-different

content/00.build/65.developer-reference/00.index.md

@@ -12,7 +12,7 @@ overview to help you effectively build on ZKsync Era.
   ---
   title: Introduction to Rollups
   icon: i-heroicons-scale-16-solid
-  to: /build/developer-reference/intro-rollups
+  to: /build/developer-reference/protocol
   ---
   Explore the fundamentals of rollups for enhanced scalability and lower gas costs.
   ::

content/00.build/65.developer-reference/10.intro-rollups.md

@@ -0,0 +1,83 @@
+---
+title: ZKsync Era Protocol
+description: Learn about ZKsync Era and the differences from Ethereum
+---
+
+ZKsync Era is a Layer 2 scaling solution designed to enhance Ethereum's scalability without compromises.
+This document provides an overview of ZKsync Era's rollup mechanism, explaining the main idea and how it contributes to a more scalable,
+secure, and user-friendly blockchain ecosystem.
+
+## What is a Rollup?
+
+A rollup is a blockchain scalability solution that processes and stores transaction data off-chain
+while ensuring the data's integrity and availability on the main chain.
+By doing so, rollups significantly increase transaction throughput without compromising security.
+There are primarily two types of rollups: Optimistic Rollups and Zero-Knowledge (zk) Rollups.
+ZKsync Era utilizes the latter, leveraging cryptographic proofs for security and efficiency.
+
+## How and why it works?
+
+Ethereum's decentralized network has limited transaction throughput because its capacity doesn't scale with the number of validators.
+In essence, each validator performs the same job of validating each processed transaction, creating a bottleneck.
+In contrast, in Web2 scalability improves with the addition of more servers,
+as the network's capacity to handle requests increases linearly with each new server.
+
+The concept of a rollup addresses the blockchain scalability issue by moving computation off-chain
+and only sending the result of these computations back to Ethereum.
+ZK rollups, in particular, submit a validity proof alongside the execution result,
+making the validation of a zk proof significantly cheaper than re-executing each transaction.
+
+### The Data Availability (DA) Problem
+
+A crucial aspect of ensuring the integrity and security of rollups is addressing the Data Availability (DA) problem.
+If the state of the rollup is unknown to observers of Ethereum,
+then in scenarios where the validators (centralized or decentralized) stop processing,
+it becomes impossible to make state transitions without relying on a trusted validator.
+However, if the data is always available to observers, it's feasible to restore the state and continue processing the network
+even if the trusted validator ceases its operation.
+This link provides further details on the Data Availability problem: [Ethereum Data Availability](https://ethereum.org/en/developers/docs/data-availability/).
+
+### ZK proof
+
+Zero-Knowledge Proofs (ZKPs) offer a method to execute verifiable programs, wherein it's cheap to verify a zk proof on-chain.
+In the context of ZKsync, ZKPs allow for the confirmation of the correctness of transaction execution without re-executing them.
+
+ZK circuits are out of the contest's scope.
+However, there is an ongoing [live bug bounty program on Immunefi](https://immunefi.com/bounty/zksyncera/)
+open to anyone interested in identifying vulnerabilities within this domain.
+
+## ZKsync Era components
+
+ZKsync Era protocol consists of the following critical components:
+
+- **Node Implementation**: This component is responsible for receiving transactions from users and processing them.
+  It maintains the off-chain state and handles the aggregation of transactions into batches as well as sends sealed batches onchain.
+- **ZK Circuits**: These circuits are intricate mathematical constructs that represent verifiable computation logic.
+  They are responsible for determining what can be verified as a valid proof.
+  Specifically for ZKsync, these circuits define the computation rules for EraVM execution, thats also defines how transactions are executed.
+- **Prover**: The prover constructs the cryptographic proofs that attest to the correctness of the transactions processed off-chain.
+  These proofs can be verified later on Ethereum, ensuring that only valid transactions are accepted.
+- **Smart Contracts**: These contracts are the on-chain component of the zkRollup.
+  They are responsible for verifying the proofs submitted by the prover and updating the Ethereum blockchain's state accordingly.
+  Additionally, they facilitate interactions between Ethereum and ZKsync, such as deposits, withdrawals, and cross-layer messaging.
+
+![ZKsync components.png](/images/developer-reference/zksync-components.png)
+
+While this contest primarily focuses on the smart contracts side of ZKsync Era,
+understanding the interaction between different components can be beneficial.
+For additional context or insights, consider exploring these resources:
+
+- **Node Implementation**: https://github.com/matter-labs/zksync-era
+- **ZK Circuits**: https://github.com/matter-labs/era-zkevm_circuits
+
+## The ZK Chain
+
+The ZK Chain is the continuation of Ethereum's rollup centric roadmap.
+Ethereum provides security via DA and verification of proofs, but the question of execution is left to the rollups.
+In order to have the best UX, it is necessary to solve interoperability and the free flow of assets between chains.
+We do this via the Shared Bridge Contract on L1 which stores Ether and ERC20 tokens for all ZK Chains (implementing custom bridges is still possible).
+This upgrade will allow hyperbridging between ZK Chains in the next major upgrade.
+The chains will be able to trust each other due to the fact that they are managed by the same STM contract, using the same VM and proof system.
+In the future more upgrades will follow, as this is still a topic under heavy research.
+
+- For more details watch this video on [How the ZK Stack will power the Internet of Value](https://www.youtube.com/watch?v=BxpKa-S2m34).

content/00.build/65.developer-reference/10.protocol.md

@@ -0,0 +1,50 @@
+---
+title: Migrating ZKsync Era into the ZK Chain
+description: Guide on how to migrate a single chain ZKsync Era into the ZK Chain
+---
+
+This document describes the process of migrating the currently deployed single chain ZKsync Era into the ZK Chain,
+including the process of moving funds from Diamond Proxy and L1 ERC20 Bridge into the brand new Shared bridge while ensuring security guarantees.
+
+**Note: The migration to the new system of ZK Chains has already happened.**
+
+## Migration process
+
+We will migrate the old system of Era's `Diamond Proxy`, `L1ERC20Bridge`
+to a system that is capable of hosting multiple interoperable ZK Chains with the
+`L1SharedBridge`, `Bridgehub`, `StateTransitionManager` and other contracts.
+
+This upgrade process has the following steps:
+
+### I. Upgrade the system
+
+1. Deploy the new contracts
+
+    We first deploy the new contracts.
+    These include the `Bridgehub`, `StateTransitionManager`, `L1SharedBridge`, the new facets and the `ValidatorTimelock`.
+    At this point, if we wanted to we could register new ZK Chains.
+
+2. Integrate Era into new contracts, and upgrade L2 system contracts
+
+    We upgrade Era (we do this via a standard diamond cut upgrade, set the L2 system contract upgrade tx hash,
+    and a call to the new DiamondInit function to initialize the `DiamondProxy` with the new protocol version and variables).
+    We integrate Era into the the contracts via `registerAlreadyDeployedStateTransition` on STM and `createNewChain` on Bridgehub.
+    We transfer all Ether to the `L1SharedBridge`. We do this via the the `transferFundsFromLegacy` function on the `L1SharedBridge`.
+
+    At this point deposits to the `L1SharedBridge` and to the legacy functions on `Mailbox` facet of the `DiamondProxy` should work.
+    The legacy `L1ERC20Bridge` will also work, as it will communicate with the backwards compatible `Mailbox`.
+
+### II. Upgrade L1ERC20Bridge contract
+
+1. Upgrade L2 bridge
+
+    The new `L2ERC20Bridge` will upgraded to become the `L2SharedBridge`,
+    and it will be backwards compatible with all messages from the old `L1ERC20Bridge`,
+    so we upgrade that first as L1->L2 messages are much faster, and in the meantime we can upgrade the `L1ERC20Bridge`.
+    The new `L2SharedBridge` can receive deposits from both the old `L1ERC20Bridge` and the new `L1SharedBridge`.
+
+2. Upgrade L1ERC20Bridge
+
+    We upgrade the `L1ERC20Bridge`, and move all ERC20 tokens to the `L1SharedBridge`.
+
+Note migrating Era and its `L1ERC20Bridge` are possible to do for other separately deployed ZK Chains as well, in case we need to do it multiple times.