docs: refactor zkstack docs

README.md

@@ -31,7 +31,7 @@ Unlock the full potential of ZKsync with our comprehensive resources:
 - **🛠️ Build:** Learn how to develop and deploy your smart contracts and
 applications on ZKsync Era. Our step-by-step guides and tutorials will help you get started quickly and efficiently.
 
-- **🔗 ZKsync Stack:** Dive into the ZKsync Stack to discover how to
+- **🔗 ZK Stack:** Dive into the ZK Stack to discover how to
 configure and build a ZKsync Chain tailored for your application. Explore the architecture, components, and best practices.
 
 - **🌐 ZKsync Node:** Set up and run your own ZKsync full node. Gain a deeper

content/00.zksync-network/30.unique-features/50.zksync-connect/00.index.md

@@ -4,7 +4,7 @@ description: Learn about how ZKsync Connect enables interoperable ZKsync chains.
 ---
 
 ZKsync Connect enables interoperability across ZKsync chains in the Elastic Network.
-Interop, or interoperability, is a way to communicate and transact between two ZKsync Stack chains.
+Interop, or interoperability, is a way to communicate and transact between two ZK Stack chains.
 It is made possible by smart contracts that verify transactions across chains using Merkle proofs.
 
 It allows you to:

content/00.zksync-network/40.tooling/20.hardhat/20.guides/20.migrating-to-zksync.md

@@ -80,7 +80,7 @@ You can learn more about each plugin in the [Getting started section](/zksync-ne
 
 ## Compilation
 
-ZKsync Era (as well as other chains built with ZKsync Stack) is operated by the EraVM,
+ZKsync Era (as well as other chains built with ZK Stack) is operated by the EraVM,
 which executes a specific bytecode that differs from the EVM.
 This bytecode is generated by the `zksolc` (for Solidity contracts)
 and `zkvyper` (for Vyper contracts) compilers.
@@ -238,7 +238,7 @@ networks: {
 
 ## Deployment
 
-Smart contract deployment on ZKsync Era (and chains built with ZKsync Stack) differ from Ethereum
+Smart contract deployment on ZKsync Era (and chains built with ZK Stack) differ from Ethereum
 as they are handled by the `ContractDeployer` system contract
 (see [Ethereum differences](/zksync-protocol/differences/contract-deployment)).
 

content/00.zksync-network/65.zksync-os/00.index.md

@@ -62,7 +62,7 @@ The Developer Preview currently supports a **fully EVM-equivalent environment**,
 existing EVM tools (e.g. Foundry, Hardhat, solc) and deploy contracts without modification.
 Future versions may include **EraVM**, **WASM** and **native RISC-V** environments.
 
-Learn [more about ZKsync OS in the protocol documentation](../../zksync-protocol/zksyncos/overview).
+Learn [more about ZKsync OS in the protocol documentation](/zksync-protocol/zksyncos).
 
 ---
 
@@ -93,7 +93,7 @@ Key properties:
 Because both execution and proving compile from the same Rust source, Airbender proves the exact code path executed by ZKsync OS.
 This reduces audit complexity and guarantees consistency between runtime and proofs.
 
-Learn [more about Airbender in the protocol documentation](../../zksync-protocol/zksync-airbender/overview).
+Learn [more about Airbender in the protocol documentation](/zk-stack/components/zksync-airbender).
 
 ---
 

content/10.zk-stack/00.index.md

@@ -1,9 +1,9 @@
 ---
 title: Overview
-description: This section provides an overview of the ZKsync Stack as a key concept of the Elastic Network.
+description: This section provides an overview of the ZK Stack as a key tool to launch and operate ZKsync chains.
 ---
 
-ZKsync Stack is a developer friendly modular framework that makes it easy for you to customize & deploy your own interoperable ZK-powered blockchains.
+ZK Stack is a developer friendly modular framework that makes it easy for you to customize & deploy your own interoperable ZK-powered blockchains.
 All ZKsync chains in the ecosystem share users & liquidity.
 
 ::card-group
@@ -21,6 +21,6 @@ All ZKsync chains in the ecosystem share users & liquidity.
   icon: i-heroicons-rocket-launch-solid
   to: /zk-stack/running/quickstart
   ---
-  Run your own ZKsync chain using ZKsync Stack tooling.
+  Run your own ZKsync chain using ZK Stack tooling.
   ::
 ::

content/10.zk-stack/10.zk-chains.md

@@ -13,17 +13,21 @@ ZKsync chains are fully interoperable within the Elastic Network, facilitating s
 ZKsync chains operate with a shared bridge contract on Ethereum's L1 and include native bridges between individual rollups,
 enhancing the overall interoperability and efficiency of the network. Key features of ZKsync chains include:
 
+1. **Security and Trust**: All ZKsync chains must utilize the standardized ZK-engine to maintain consistent security and operational standards,
+  ensuring that trust and security are derived directly from Ethereum.
+1. **High Performance**: ZKsync chains are optimized for massive throughput and low latency,
+  enabling 10,000+ transactins per second and fast transaction finality without compromising security.
+1. **Low Costs**: ZKsync's state of the art infrastructure reduces transaction fees to $0.0001 per transaction,
+  a 99% reduction from Layer 1 solutions.
 1. **Trustless Validating Bridges**: Ensures that rollups within the ZKsync protocol are interconnected without requiring additional trust layers.
-2. **Asset Transfers**: Interoperability simplifies the transfer of assets, including burning and minting mechanisms, across the ecosystem.
-3. **Unified Governance**: Leveraging a shared governance framework on L1,
+1. **Asset Transfers**: Interoperability simplifies the transfer of assets, including burning and minting mechanisms, across the ecosystem.
+1. **Unified Governance**: Leveraging a shared governance framework on L1,
   the ecosystem can coordinate updates or respond collectively to vulnerabilities, much like a traditional blockchain network would handle a fork.
-4. **Security and Trust**: All ZKsync chains must utilize the standardized ZK-engine to maintain consistent security and operational standards,
-  ensuring that trust and security are derived directly from L1.
 
 ### Development and Deployment
 
 ZKsync chains can be developed and deployed by anyone, fostering a diverse and open ecosystem.
-However, for a ZKsync chain to remain trusted and fully interoperable within the Elastic Network, it must utilize the ZKsync Stack.
+However, for a ZKsync chain to remain trusted and fully interoperable within the Elastic Network, it must utilize the ZK Stack.
 This requirement ensures consistency in execution and security across different instances of ZKsync chains.
 
 ### Modular Implementation
@@ -37,7 +41,7 @@ while maintaining core standards necessary for network security and interoperabi
 
 ## How Interop Works
 
-Interop, or interoperability, is a way to communicate and transact between two ZKsync Stack chains.
+Interop, or interoperability, is a way to communicate and transact between two ZK Stack chains.
 It is made possible by smart contracts that verify transactions across chains using Merkle proofs.
 
 It allows you to:
@@ -79,7 +83,7 @@ Once planned upgrades for Gateway are complete, only a lightweight consensus mec
 
 ## Chain Customizations
 
-The ZKsync Stack offers several customization options for developers looking to tailor a ZKsync chain to specific needs
+The ZK Stack offers several customization options for developers looking to tailor a ZKsync chain to specific needs
 or create entirely new blockchain architectures.
 This modular approach allows for significant flexibility in configuring transaction sequencing, data availability policies, and privacy features.
 
@@ -100,14 +104,14 @@ This modular approach allows for significant flexibility in configuring transact
 
 ### Custom Base Tokens
 
-The ZKsync Stack supports using ERC20 tokens as the base token for chain fees instead of ETH.
+The ZK Stack supports using ERC20 tokens as the base token for chain fees instead of ETH.
 This enables ZKsync chains to use tokens like USDC or custom community tokens as the base currency for transactions.
 
 ### Data Availability (DA)
 
 Data Availability (DA) is a critical component in ensuring the security and functionality of ZKsync chain.
 It governs how transaction data is managed and made accessible, impacting everything from user privacy to transaction speed and cost.
-Below, we detail the various DA options available to developers using the ZKsync Stack, each tailored for specific security, privacy, and scalability needs.
+Below, we detail the various DA options available to developers using the ZK Stack, each tailored for specific security, privacy, and scalability needs.
 
 #### zk-Rollup
 
@@ -120,7 +124,7 @@ cheaper) on Ethereum's Layer 1 (L1). This approach benefits from:
 
 #### Validium
 
-A [validium](/zk-stack/running/validium)
+A [validium](/zk-stack/customizations/validium)
 offers a more flexible architecture ideal for enterprise applications that require both auditability and confidentiality.
 Its key characteristics are:
 

content/10.zk-stack/15.components/00.index.md

@@ -0,0 +1,15 @@
+---
+title: Overview
+description: Overview
+---
+
+This section provides a high-level overview of the components that make up a ZKsync Chain.
+
+The main components of each ZKsync chain are:
+
+- [ZKsync OS](/zk-stack/components/zksync-os): A new “operating system” for ZKsync Chains.
+- [ZKsync OS Server](/zk-stack/components/zksync-os): The new high-performance sequencer for ZKsync OS.
+- [ZKsync Airbender](/zk-stack/components/zksync-airbender): A horizontally scalable implementation of the ZK proof generator.
+- [Block Explorer](/zk-stack/components/block-explorer): An API and user interface for exploring transactions and verifying contracts.
+- [Portal](/zk-stack/components/portal): A user interface for bridging and sending assets, and viewing a wallet's transaction history.
+- [Fee Withdrawer](/zk-stack/components/fee-withdrawer): A tool to automate the transfer of collected fees from a ZKsync chain to a base layer address.

content/10.zk-stack/15.components/10.zksync-os.md

@@ -0,0 +1,10 @@
+---
+title: ZKsync OS
+description: Introduction to ZKsync OS.
+---
+
+:display-partial{path="/_partials/_zksyncos/_overview"}
+
+You can read more about how ZKsync OS works in the [protocol documentation](/zksync-protocol/zksyncos).
+
+The code for ZKsync OS can be found in the [ZKsync OS GitHub repository](https://github.com/matter-labs/zksync-os).

content/10.zk-stack/15.components/15.server.md

@@ -0,0 +1,43 @@
+---
+title: ZKsync OS Server
+description: Overview of the ZKsync OS sequencer.
+---
+
+The ZKsync OS Sever is a complex system composed of several services and modules that work together to monitor Ethereum Layer 1 (L1),
+maintain Layer 2 (L2) state, and manage the order of incoming transactions.
+
+The new sequencer can process **over 10,000 transactions per second** through a single-binary architecture that dramatically reduces operational overhead.
+The system scales horizontally through Elastic Nodes, delivering enterprise performance without enterprise complexity or costs.
+
+With the ZKsync OS Sequencer, transaction costs drop to **$0.0001 per transaction**, a 99% reduction from Layer 1 solutions.
+This enables microtransactions, high-frequency applications, and business models that weren't economically viable before.
+
+## Components
+
+The server implementation consists of three main subsystems:
+
+1. [Sequencer](https://github.com/matter-labs/zksync-os-server/tree/main/lib/sequencer):
+  Executes transactions and sends the results downstream to other components.
+1. [RPC API](https://github.com/matter-labs/zksync-os-server/tree/main/lib/rpc_api):
+  Implementation of the Web3 JSON-RPC API.
+1. [Batcher](https://github.com/matter-labs/zksync-os-server/tree/main/node/bin/src/batcher):
+  Turns a stream of blocks into a stream of batches (1 batch = 1 proof = 1 L1 commit),
+  exposes prover APIs, and submits batches and proofs to L1.
+
+For a more detailed overview, please refer to the [ZKsync OS Server GitHub repository](https://github.com/matter-labs/zksync-os-server).
+
+## Design Principles
+
+The three main design principles that were used for the server are:
+
+1. **Minimal, async persistence** to meet throughput and latency requirements.
+  Synchronous persistence is avoided at the critical path.
+  Additionally, the sequencer aims at storing only the data that is strictly needed, minimizing the potential for state inconsistency.
+1. **Easy to replay arbitrary blocks**.
+    The sequencer components are idempotent.
+    The batcher component skips all blocks until the first uncommitted batch.
+    Thus, downstream components only receive batches that they need need to act upon.
+1. **Strong separation between states**.
+  The actual state only includes data needed to execute the VM: key-value storage and a preimages map.
+  The receipts repositories includes data only needed in the API.
+  The data related to proofs and L1, which is not needed by the sequencer or JSON RPC, is only introduced downstream from batcher.

content/20.zksync-protocol/17.zksync-airbender/00.overview.md → content/10.zk-stack/15.components/20.zksync-airbender/00.index.md

@@ -3,19 +3,16 @@ title: Overview
 description: Introduction to ZKsync Airbender
 ---
 
-[ZKsync OS](/zksync-protocol/zksyncos/overview) and Airbender have been developed in parallel to
-support modular and scalable architecture for ZKsync Chains.
-
-- Airbender is a new ZK proof system.
-- ZKsync OS is a new “operating system” for ZKsync Chains, allowing chains to choose any Virtual Machine, such as EVM, EraVM, or WASM.
-
-## What is Airbender?
-
-Airbender is ZKsync's next-generation proof system, purpose-built to enable efficient ZK proofs of RISC-V bytecode execution.
+Airbender is ZKsync's next-generation RISC-V proof system, purpose-built to enable efficient ZK proofs of RISC-V bytecode execution.
 Built on the foundation of highly optimized STARK/FRI implementations, Airbender is designed to support ZKsync's
 long-term scaling strategy by being fast, cheap, and flexible to a wide range of use cases (without compromising security).
 
-### How It Fits with ZKsync OS
+Airbender runs on consumer GPUs and standard hardware, eliminating the dependency on large datacenters.
+
+## How It Fits with ZKsync OS
+
+[ZKsync OS](/zk-stack/components/zksync-os) and Airbender have been developed in parallel to
+support modular and scalable architecture for ZKsync Chains.
 
 ZKsync OS acts as a modular execution layer, allowing chains to run various virtual machines like EVM, EraVM, or WASM.
 Airbender serves as the proving system that validates the execution of these VMs, encoded in RISC-V bytecode.
@@ -49,8 +46,4 @@ satisfaction proof for the main circuit.
 
 - **Stage 6 - SNARK Wrapper:** Wrap the final FRI proof into a final FFLONK proof which gets posted and verified onchain.
 
-### Get Started
-
-- Get started with the RISC-V Prover tutorial: [RISC-V Prover tutorial](https://github.com/matter-labs/zksync-airbender/blob/main/docs/tutorial.md)
-- Get started with Docker: [Docker with anvil-zksync](https://github.com/matter-labs/zksync-airbender/tree/main/docker/anvil-bender)
-- Get started with running prover end-to-end: [Guide to run prover](https://github.com/matter-labs/zksync-airbender/blob/main/docs/end_to_end.md)
+The code for ZKsync Airbender can be found in the [ZKsync Airbender GitHub repository](https://github.com/matter-labs/zksync-airbender/tree/main).

content/20.zksync-protocol/17.zksync-airbender/01.deepdive.md → content/10.zk-stack/15.components/20.zksync-airbender/01.deepdive.md

@@ -83,3 +83,5 @@ correctness but requires careful program design.
 
 - **Memory Alignment**: The system disallows inefficient unaligned memory accesses to maintain proving
 efficiency, relying on compiler guarantees for proper memory layout.
+
+For more low-level details about ZKsync Airbender, you can refer to the [ZKsync Airbender GitHub repository](https://github.com/matter-labs/zksync-airbender/tree/main/docs).

content/10.zk-stack/30.components/30.block-explorer.md → content/10.zk-stack/15.components/30.block-explorer.md

@@ -18,3 +18,6 @@ This tool is especially useful for users and developers who need to monitor or i
 - **Block Explorer App:**
   This is the user interface that enables users and developers to navigate and examine transactions,
   blocks, batches, contracts, tokens, and other elements within the ZKsync chain.
+
+Instructions for how to set up a local block explorer
+can be found in the ["Using a Local ZK Chain"](/zk-stack/running/using-a-local-zk-chain#using-a-block-explorer) docs.

content/10.zk-stack/30.components/40.portal-wallet-bridge.md → content/10.zk-stack/15.components/40.portal.md

@@ -1,17 +1,22 @@
 ---
-title: "Portal: Wallet + Bridge"
+title: "Portal"
 description: Discover how the Portal dApp facilitates interaction with your ZKsync chain, including asset bridging, transaction tracking, and contract management.
 ---
 
-[The Portal](https://github.com/matter-labs/dapp-portal) is a decentralized application (dApp) designed to enhance interaction with your ZKsync chain.
+[The Portal](https://github.com/matter-labs/dapp-portal) is an application designed to enhance interaction with your ZKsync chain.
 It serves as a versatile tool for both you and your users, simplifying various operations within the blockchain environment.
 
+You can see a live instance of the portal for ZKsync Era at [`https://portal.zksync.io`](https://portal.zksync.io).
+
+Instructions for how to set up a local portal can be found in the ["Using a Local ZK Chain"](/zk-stack/running/using-a-local-zk-chain#using-the-portal)
+docs.
+
 ### Key Features
 
 - **Bridging Assets:** The Portal enables the movement of assets between the Layer 1 (L1) network and your ZKsync chain, facilitating smooth asset transfers.
 - **Internal Transactions:** Users can send assets within the ZKsync chain efficiently, utilizing the Portal's user-friendly interface.
 - **Transaction History:** The Portal provides access to view and verify historical transactions, enhancing transparency and user trust in the platform.
 - **Contract Management:** It supports users in managing smart contracts, including deployment and interaction functionalities.
 
-Enhancing the Portal's capabilities is possible by integrating it with the [Block Explorer Indexer/API](block-explorer),
+Enhancing the Portal's capabilities is possible by integrating it with the [Block Explorer Indexer/API](/zk-stack/components/block-explorer),
 which provides additional data and analytics support, further enriching the user experience.

content/10.zk-stack/15.components/_dir.yml

@@ -0,0 +1 @@
+title: Components