diff --git a/README.md b/README.md index b7ebdf81..852977cf 100644 --- a/README.md +++ b/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 diff --git a/content/00.zksync-network/30.unique-features/50.zksync-connect/00.index.md b/content/00.zksync-network/30.unique-features/50.zksync-connect/00.index.md index 66167eba..e24b7eca 100644 --- a/content/00.zksync-network/30.unique-features/50.zksync-connect/00.index.md +++ b/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: diff --git a/content/00.zksync-network/40.tooling/20.hardhat/20.guides/20.migrating-to-zksync.md b/content/00.zksync-network/40.tooling/20.hardhat/20.guides/20.migrating-to-zksync.md index 9e497ccf..eecbe149 100644 --- a/content/00.zksync-network/40.tooling/20.hardhat/20.guides/20.migrating-to-zksync.md +++ b/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)). diff --git a/content/00.zksync-network/65.zksync-os/00.index.md b/content/00.zksync-network/65.zksync-os/00.index.md index 2fc1b09a..637d52f1 100644 --- a/content/00.zksync-network/65.zksync-os/00.index.md +++ b/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). --- diff --git a/content/10.zk-stack/00.index.md b/content/10.zk-stack/00.index.md index 7f19b970..66507280 100644 --- a/content/10.zk-stack/00.index.md +++ b/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. :: :: diff --git a/content/10.zk-stack/10.zk-chains.md b/content/10.zk-stack/10.zk-chains.md index 1bac594b..e318d2e3 100644 --- a/content/10.zk-stack/10.zk-chains.md +++ b/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: diff --git a/content/10.zk-stack/15.components/00.index.md b/content/10.zk-stack/15.components/00.index.md new file mode 100644 index 00000000..8047fc5d --- /dev/null +++ b/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. diff --git a/content/10.zk-stack/15.components/10.zksync-os.md b/content/10.zk-stack/15.components/10.zksync-os.md new file mode 100644 index 00000000..a6fbfe24 --- /dev/null +++ b/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). diff --git a/content/10.zk-stack/15.components/15.server.md b/content/10.zk-stack/15.components/15.server.md new file mode 100644 index 00000000..b465efc7 --- /dev/null +++ b/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. diff --git a/content/20.zksync-protocol/17.zksync-airbender/00.overview.md b/content/10.zk-stack/15.components/20.zksync-airbender/00.index.md similarity index 68% rename from content/20.zksync-protocol/17.zksync-airbender/00.overview.md rename to content/10.zk-stack/15.components/20.zksync-airbender/00.index.md index 5083d68a..335c697d 100644 --- a/content/20.zksync-protocol/17.zksync-airbender/00.overview.md +++ b/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). diff --git a/content/20.zksync-protocol/17.zksync-airbender/01.deepdive.md b/content/10.zk-stack/15.components/20.zksync-airbender/01.deepdive.md similarity index 96% rename from content/20.zksync-protocol/17.zksync-airbender/01.deepdive.md rename to content/10.zk-stack/15.components/20.zksync-airbender/01.deepdive.md index 171011f8..19468251 100644 --- a/content/20.zksync-protocol/17.zksync-airbender/01.deepdive.md +++ b/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). diff --git a/content/20.zksync-protocol/17.zksync-airbender/_dir.yml b/content/10.zk-stack/15.components/20.zksync-airbender/_dir.yml similarity index 100% rename from content/20.zksync-protocol/17.zksync-airbender/_dir.yml rename to content/10.zk-stack/15.components/20.zksync-airbender/_dir.yml diff --git a/content/10.zk-stack/30.components/30.block-explorer.md b/content/10.zk-stack/15.components/30.block-explorer.md similarity index 86% rename from content/10.zk-stack/30.components/30.block-explorer.md rename to content/10.zk-stack/15.components/30.block-explorer.md index 56ba7155..e7b9f664 100644 --- a/content/10.zk-stack/30.components/30.block-explorer.md +++ b/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. diff --git a/content/10.zk-stack/30.components/40.portal-wallet-bridge.md b/content/10.zk-stack/15.components/40.portal.md similarity index 67% rename from content/10.zk-stack/30.components/40.portal-wallet-bridge.md rename to content/10.zk-stack/15.components/40.portal.md index 554154eb..6f136b86 100644 --- a/content/10.zk-stack/30.components/40.portal-wallet-bridge.md +++ b/content/10.zk-stack/15.components/40.portal.md @@ -1,11 +1,16 @@ --- -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. @@ -13,5 +18,5 @@ It serves as a versatile tool for both you and your users, simplifying various o - **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. diff --git a/content/10.zk-stack/30.components/50.fee-withdrawer.md b/content/10.zk-stack/15.components/50.fee-withdrawer.md similarity index 100% rename from content/10.zk-stack/30.components/50.fee-withdrawer.md rename to content/10.zk-stack/15.components/50.fee-withdrawer.md diff --git a/content/10.zk-stack/15.components/_dir.yml b/content/10.zk-stack/15.components/_dir.yml new file mode 100644 index 00000000..9937383b --- /dev/null +++ b/content/10.zk-stack/15.components/_dir.yml @@ -0,0 +1 @@ +title: Components diff --git a/content/10.zk-stack/20.running/10.quickstart.md b/content/10.zk-stack/20.running/10.quickstart.md index a32a2ff1..9a7ff416 100644 --- a/content/10.zk-stack/20.running/10.quickstart.md +++ b/content/10.zk-stack/20.running/10.quickstart.md @@ -1,8 +1,12 @@ --- -title: Getting started with ZKsync Stack -description: Quickstart - Getting Started with ZKsync Stack +title: Launch a ZKsync chain +description: Launch a ZKsync chain locally using the zkstack CLI --- +::callout{icon="i-heroicons-exclamation-triangle" color="amber"} +`zkstack` is not yet updated to use ZKsync OS. Following this guide will create a legacy EraVM chain. +:: + ## Development dependencies Ensure you have followed [these instructions](https://github.com/matter-labs/zksync-era/blob/main/docs/src/guides/setup-dev.md) @@ -10,16 +14,16 @@ to set up dependencies on your machine (don't worry about the Environment sectio ## Deploying locally -::callout{icon="i-heroicons-exclamation-triangle" color="amber"} +::callout{icon="i-heroicons-light-bulb"} This guide is for setting up an Elastic Network ecosystem and for spinning up your own ZKsync chains -using ZKsync Stack. If you just want play around with a pre-built ZKsync chain, you can use `zksync-cli dev` to run docker containers. +using ZK Stack. If you just want play around with a pre-built ZKsync chain, you can use `zksync-cli dev` to run docker containers. Learn more on [zksync-cli](/zksync-network/tooling/zksync-cli). :: -### Install ZKsync Stack CLI +### Install ZK Stack CLI -ZKsync Stack CLI facilitates the creation and management of an Elastic Network ecosystem and ZKsync chains using ZKsync Stack. All commands are interactive, -but you can also pass all necessary arguments via the command line. See here for [full instructions for ZKsync Stack CLI](https://github.com/matter-labs/zksync-era/tree/main/zkstack_cli). +ZK Stack CLI facilitates the creation and management of an Elastic Network ecosystem and ZKsync chains using ZK Stack. All commands are interactive, +but you can also pass all necessary arguments via the command line. See here for [full instructions for ZK Stack CLI](https://github.com/matter-labs/zksync-era/tree/main/zkstack_cli). 1. Install zkstack from git: @@ -27,7 +31,7 @@ but you can also pass all necessary arguments via the command line. See here for cargo install --git https://github.com/matter-labs/zksync-era/ --locked zkstack --force ``` -Note: Foundry is utilized for deploying smart contracts with ZKsync Stack CLI. For commands related to deployment, you can pass flags for Foundry integration. +Note: Foundry is utilized for deploying smart contracts with ZK Stack CLI. For commands related to deployment, you can pass flags for Foundry integration. If you have previously installed `zksync-foundry` and have issues with this quickstart, try installing the standard latest version of foundry. ::callout{icon="i-heroicons-light-bulb"} @@ -39,7 +43,7 @@ You can find a full reference for the `zkstack` CLI in the [`zksync-era` repo](h An Elastic Chain ecosystem includes the components that connects all ZKsync chains, like the BridgeHub, ZKsync Router, and state transition managers. -1. To create a ZKsync Stack project, you must first create the Elastic Network ecosystem. +1. To create a ZK Stack project, you must first create the Elastic Network ecosystem. ```bash zkstack ecosystem create @@ -90,7 +94,7 @@ that connects all ZKsync chains, like the BridgeHub, ZKsync Router, and state tr ### Add more ZKsync chains (optional) -Upon ecosystem setup, the first ZKsync chain is automatically generated. However, ZKsync Stack supports many ZKsync +Upon ecosystem setup, the first ZKsync chain is automatically generated. However, ZK Stack supports many ZKsync chains running on the same Elastic Chain ecosystem. You can create additional chains and switch between them. 1. To create additional chains: diff --git a/content/10.zk-stack/20.running/20.using-a-local-zk-chain.md b/content/10.zk-stack/20.running/20.using-a-local-zk-chain.md index 8af4c357..375693e0 100644 --- a/content/10.zk-stack/20.running/20.using-a-local-zk-chain.md +++ b/content/10.zk-stack/20.running/20.using-a-local-zk-chain.md @@ -1,6 +1,6 @@ --- -title: Using a local ZKsync Chain -description: +title: Interact with your chain +description: Learn how to deposit funds into your ZKsync chain, launch the portal and explorer --- ## Funding accounts @@ -34,7 +34,7 @@ and start interacting with your ZKsync chain using the L2 funded account. ## Using your chain RPC -Your server contains both HTTPS as well as WebSocket (WS) RPC services that are fully web3 compatible (and contain some extra ZKsync Stack functionalities). +Your server contains both HTTPS as well as WebSocket (WS) RPC services that are fully web3 compatible (and contain some extra ZK Stack functionalities). Learn more on the [API reference page](../../20.zksync-protocol/10.api/00.index.md). ## Using zksync-cli @@ -104,3 +104,27 @@ your ecosystem directory. You can edit this file to configure the app if needed. You can now navigate to the explorer web-app. By default, explorer frontend starts on `http://localhost:3010`, you can configure the port in `apps.yaml` file. + +### Contract Verification + +The contract verifier is used to check contract source code against deployed bytecode. +This is going to be used in the explorer to display the source code and ABIs of contracts. + +To setup a local contract verification API for your block explorer, +follow the steps below: + +1. Initialize the contract verifier. + You can choose here what versions of the compiler you want to support. + This will download the needed binaries for verifying contracts on the block explorer. + + ```bash + zkstack contract-verifier init + ``` + +1. Run the verifier. + + ```bash + zkstack contract-verifier run + ``` + +The verifier will be running on the default port of `3070`. diff --git a/content/10.zk-stack/20.running/25.gateway-settlement-layer.md b/content/10.zk-stack/20.running/25.gateway-settlement-layer.md index 46a36512..167f2e7c 100644 --- a/content/10.zk-stack/20.running/25.gateway-settlement-layer.md +++ b/content/10.zk-stack/20.running/25.gateway-settlement-layer.md @@ -1,6 +1,6 @@ --- -title: ZKsync Gateway settlement layer -description: +title: ZKsync Gateway +description: Migrate your ZKsync chain to settle on ZKsync Gateway --- ZKsync Gateway is an **optional settlement layer** for ZKsync chains, including both rollups and validiums. It is purpose-built to @@ -196,7 +196,7 @@ In order to migrate a chain, operators will need the following information: - **Chain identifiers:** - `L2_CHAIN_ID`: id of the L2 network to migrate. - `GATEWAY_CHAIN_ID`: more info in [ZKsync Gateway overview](../../zksync-protocol/gateway/overview). -- **ZKsync Gateway configuration:** the ZKsync Stack config file for the ZKsync Gateway, which contains relevant information of how the chain operates. +- **ZKsync Gateway configuration:** the ZK Stack config file for the ZKsync Gateway, which contains relevant information of how the chain operates. This file can be found [in the zksync-era repository](https://github.com/matter-labs/zksync-era/tree/main/etc/env/ecosystems/gateway). Save in `etc/ecosystem/gateway/.yaml`. diff --git a/content/10.zk-stack/20.running/40.proving.md b/content/10.zk-stack/20.running/40.proving.md index 7dbf9af1..862b6384 100644 --- a/content/10.zk-stack/20.running/40.proving.md +++ b/content/10.zk-stack/20.running/40.proving.md @@ -1,8 +1,12 @@ --- -title: Proving -description: +title: Prover setup +description: Enable ZK proofs on your ZKsync chain --- +::callout{icon="i-heroicons-exclamation-triangle" color="amber"} +`zkstack` is not yet updated to use ZKsync Airbender. +:: + ## Enabling Boojum prover With the default configuration, your ZKsync chain is not running a prover, and has a DummyExecutor contract, @@ -10,7 +14,7 @@ which mainly “accepts” that a batch is executed without proof. This enables When enabling the Boojum prover, there are two options for running it: in GPU, or in CPU. -::callout{icon="i-heroicons-exclamation-triangle" color="amber"} +::callout{icon="i-heroicons-light-bulb"} **Running a prover is not required** for deploying a testnet. The requirements below are only necessary if you want to enable the prover. :: @@ -23,21 +27,6 @@ Ensure you have installed: - [cmake](https://apt.kitware.com/) - [nvcc (CUDA toolkit)](https://developer.nvidia.com/cuda-downloads) -Refer to the [prover docs](https://matter-labs.github.io/zksync-era/prover/latest/) for more -information. - -### Running the prover - -To initialize the prover, first use the init command: - -`zkstack prover init` - -It will guide you through the necessary configuration. - -Then to run the prover: - -`zkstack prover run` - ### Requirements for GPU prover The docker compose file assumes you will be running all components in the same machine. The current minimum requirements for a low TPS scenario are: @@ -55,3 +44,18 @@ The current minimum requirements for a low TPS scenario are: - 32 Core CPU - 128 GB of RAM - 700 GB of Disk Space (SSD preferred) + +### Running the prover + +To initialize the prover, first use the init command: + +`zkstack prover init` + +It will guide you through the necessary configuration. + +Then to run the prover: + +`zkstack prover run` + +Refer to the [prover docs](https://matter-labs.github.io/zksync-era/prover/latest/) for more +information. diff --git a/content/10.zk-stack/20.running/55.ownership-model.md b/content/10.zk-stack/20.running/55.ownership-model.md index 5edfde7d..e480413a 100644 --- a/content/10.zk-stack/20.running/55.ownership-model.md +++ b/content/10.zk-stack/20.running/55.ownership-model.md @@ -1,6 +1,6 @@ --- title: Ownership Model -description: An overview of the most important contracts and roles in the ZKsync Stack ecosystem. +description: An overview of the most important contracts and roles in the ZK Stack ecosystem. --- This section covers L1 and L2 contracts, their relationships, and the roles that manage them. diff --git a/content/10.zk-stack/20.running/60.production.md b/content/10.zk-stack/20.running/60.production.md deleted file mode 100644 index 3b05d224..00000000 --- a/content/10.zk-stack/20.running/60.production.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: In production ---- - -## Deploying to a non-local environment - -The process to deploy to a non local environment is pretty similar to the local one. -The wizard allows you to set up URLs to external services (database, RPCs, etc). - -## Database - -The wizard allows you to provide a custom database url connector. -Make sure you provide it and that it accepts external connections if your server is not running in the same private network. - -## Server (Sequencer) & Prover - -After configuring your ZKsync chain, you can generate docker images for your server and prover. -To do that run `zk stack docker-setup`. - -This command will guide you to properly name and tag your image. -After building it, a docker compose file will be available so you can run the images on whichever cloud environment you desire. diff --git a/content/10.zk-stack/20.running/70.raas.md b/content/10.zk-stack/20.running/70.raas.md index 92e1dffe..28500bb9 100644 --- a/content/10.zk-stack/20.running/70.raas.md +++ b/content/10.zk-stack/20.running/70.raas.md @@ -5,22 +5,33 @@ description: ## Deploying and running using a Rollup as a Service provider -Looking to deploy a ZKsync Stack chain but worried about complexities? -RaaS providers are here to simplify the process! -Providers offer scalable and secure nodes, and may provide quick and user-friendly interfaces, -allowing you to deploy your ZKsync Stack chain with ease and efficiency. -Experience the seamless integration of advanced blockchain technology without the hassle. -Get started today and revolutionize your product with the power of RaaS and ZKsync Stack! +Launching a ZKsync-based chain involves a number of infrastructure and operational considerations — from sequencer management and data availability +to monitoring, scaling, and security. +To streamline this process, you can work with **Rollup-as-a-Service (RaaS)** providers. -Use RaaS in to improve scalability, reduce costs, access specialized services, speed up development, enhance interoperability, -and maintain flexibility in an ever-evolving technological landscape. +RaaS partners offer the infrastructure and tooling needed to **deploy, operate, and customize** your ZK Stack chain. +These providers handle much of the heavy lifting around setup and maintenance, allowing your team to focus on your protocol, product, and community. -The list of RaaS providers you can use to deploy and customise your ZKsync chain: +We collaborate with multiple RaaS partners to ensure that projects can choose the setup that best fits their **technical, business, and +operational needs**. Whether you’re optimizing for scalability, flexibility, compliance, or time-to-market, you can select from a range +of providers with varying architectures, hosting options, and service models. -- [Caldera](https://www.caldera.xyz/) -- [Zeeve](https://www.zeeve.io/appchains/zksync-hyperchains-zkrollups/) -- [Ankr](https://www.ankr.com/rollup-as-a-service-raas/) +## Benefits of Using a RaaS Provider + +- **Simplified deployment** and lifecycle management of your ZKsync chain. +- **Reliable infrastructure** and performance monitoring tools. +- **Reduced operational overhead** and faster development cycles. +- **Integration of specialized services** such as custom settings or data availability layers. +- **Flexibility and scalability** as your chain evolves . + +## Available RaaS Providers + +Below is a list of RaaS providers that support **ZKsync chain deployment and customization:** + +- [Matter Labs](https://matter-labs.io) +- [Alchemy](https://www.alchemy.com/rollups) - [AltLayer](https://altlayer.io/raas) -- [Magic](https://magic.link/docs/blockchains/other-chains/evm/zksync) -- [Luganodes](https://www.luganodes.com/product/zkraas/) +- [Ankr](https://www.ankr.com/rollup-as-a-service-raas/) +- [Caldera](https://www.caldera.xyz/) - [QuickNode](https://www.quicknode.com/rollup) +- [Zeeve](https://www.zeeve.io/appchains/zksync-hyperchains-zkrollups/) diff --git a/content/10.zk-stack/20.running/_dir.yml b/content/10.zk-stack/20.running/_dir.yml index 7fe270b0..d19d191f 100644 --- a/content/10.zk-stack/20.running/_dir.yml +++ b/content/10.zk-stack/20.running/_dir.yml @@ -1 +1 @@ -title: Running a ZKsync Chain +title: Run a ZKsync Chain diff --git a/content/10.zk-stack/30.components/00.index.md b/content/10.zk-stack/30.components/00.index.md deleted file mode 100644 index 6c88c8bb..00000000 --- a/content/10.zk-stack/30.components/00.index.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: Overview -description: Overview ---- - -This section provides a high-level overview of the components that make up a ZKsync Chain. -It aims to cover the _dynamic_ parts, such as binaries or front-end applications. As such, it does not focus on components like smart contracts -and virtual machine overview. To get more details on those, see the [Protocol documentation](/zksync-protocol). - -The main components of each ZKsync chain are: - -- [Server](/zk-stack/components/server): The modular sequencer node implementation. -- [Prover](/zk-stack/components/prover): A horizontally scalable implementation of ZK proof generator. -- [Block Explorer](/zk-stack/components/block-explorer) -- [Portal/Wallet/Bridge](/zk-stack/components/portal-wallet-bridge) -- [Fee Withdrawer](/zk-stack/components/fee-withdrawer) diff --git a/content/10.zk-stack/30.components/10.server.md b/content/10.zk-stack/30.components/10.server.md deleted file mode 100644 index 8bd10119..00000000 --- a/content/10.zk-stack/30.components/10.server.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: Server -description: Overview of the sequencer node implementation. ---- - -The ZKsync Sequencer 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 code for the server can be found in the [ZKsync Era GitHub repository](%%zk_git_repo_zksync-era%%). - -More technical documentation for the server can be found in the [ZKsync Core book](https://matter-labs.github.io/zksync-era/core/latest/). - -## Components - -The server implementation consists of multiple modules, which can run either as a monolithic application or as a set of microservices. - -Main server components are: - -- [State keeper](https://github.com/matter-labs/zksync-era/tree/core-v25.2.0/core/node/state_keeper): The sequencer. -- [API](https://github.com/matter-labs/zksync-era/tree/core-v25.2.0/core/node/api_server): Implementation of the Web3 JSON-RPC API. -- [Metadata calculator](https://github.com/matter-labs/zksync-era/tree/core-v25.2.0/core/node/metadata_calculator): Implementation of the ZKsync - Merkle tree with extensions required for ZKP generation. -- [ETH sender](https://github.com/matter-labs/zksync-era/tree/core-v25.2.0/core/node/eth_sender): Component responsible for submitting - commit/prove/execute operations to L1. -- [ETH watcher](https://github.com/matter-labs/zksync-era/tree/core-v25.2.0/core/node/eth_watch): Component responsible for listening for - updated on the L1 contract. -- [Proof data handler](https://github.com/matter-labs/zksync-era/tree/core-v25.2.0/core/node/proof_data_handler): API for interacting with the - prover subsystem. - -For a more detailed overview, please refer to the ZKsync Era GitHub repository. diff --git a/content/10.zk-stack/30.components/20.prover.md b/content/10.zk-stack/30.components/20.prover.md deleted file mode 100644 index 2c84c5db..00000000 --- a/content/10.zk-stack/30.components/20.prover.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: Prover -description: Overview of the prover implementation. ---- - -The ZKsync Prover is a subsystem responsible for generating ZK proofs. -The subsystem consists of several parts responsible for different steps of the proof generation. - -Detailed information about ZKsync Prover can be found in the [ZKsync Prover book](https://matter-labs.github.io/zksync-era/prover/latest/). diff --git a/content/10.zk-stack/30.components/_dir.yml b/content/10.zk-stack/30.components/_dir.yml deleted file mode 100644 index 36945bb5..00000000 --- a/content/10.zk-stack/30.components/_dir.yml +++ /dev/null @@ -1 +0,0 @@ -title: ZKsync Chain components diff --git a/content/10.zk-stack/20.running/30.custom-base-tokens.md b/content/10.zk-stack/30.customizations/10.custom-base-tokens.md similarity index 90% rename from content/10.zk-stack/20.running/30.custom-base-tokens.md rename to content/10.zk-stack/30.customizations/10.custom-base-tokens.md index 006f7afd..d83cc044 100644 --- a/content/10.zk-stack/20.running/30.custom-base-tokens.md +++ b/content/10.zk-stack/30.customizations/10.custom-base-tokens.md @@ -5,11 +5,9 @@ description: Learn how to use custom base tokens for a ZKsync chain. You can customize your ZKsync chain by changing the base token used for gas from ETH to an ERC20 token. -With the initial release of ZKsync stack, custom ERC20 base tokens must be added to an allowlist for use as a base token for a chain. -The allowed addresses for all ERC20 tokens that can be used as a base token for a ZKsync chain are stored in the `BridgeHub` contract on the L1. - -In the future it will be possible to add a new token in a permissionless process. -For now, you have the ability to add any tokens to the allowlist in your local ecosystem. +::callout{icon="i-heroicons-exclamation-triangle" color="amber"} +Choosing a base token is a non-revertible action and token can not be changed. +:: ## Custom Base Token Setup diff --git a/content/10.zk-stack/20.running/35.validium.md b/content/10.zk-stack/30.customizations/20.validium.md similarity index 85% rename from content/10.zk-stack/20.running/35.validium.md rename to content/10.zk-stack/30.customizations/20.validium.md index 4c923441..f68cc8bb 100644 --- a/content/10.zk-stack/20.running/35.validium.md +++ b/content/10.zk-stack/30.customizations/20.validium.md @@ -1,50 +1,40 @@ --- -title: Validium in ZKsync Stack -description: Dive deeper into ZKsync Stack Validiums. +title: Validium in ZK Stack +description: Dive deeper into ZK Stack Validiums. --- -This section provides an in-depth exploration of validiums in ZKsync Stack. For more general overview of validiums, -see [here](/zksync-protocol/rollup/data-availability). +## What is a DA Layer? -## Understanding Validiums +A Data Availability layer (or DA Layer) is a blockchain network optimized for storing data in a cost-effective way. -There are 3 different types of validiums based on the level of data availability they provide: +A DA layer *does not* prove the correctness of a L2 chain. -- **Stage 0** - the simplest type of validium that only stores its pubdata in the database of the node(s) running the - chain. -- **Stage 1** - a validium that only sends its pubdata to the DA layer, but doesn’t verify its inclusion onchain. -- **Stage 2** - a validium that sends its pubdata to the DA layer, and also verifies its inclusion on the L1, - either by using verification bridges or ZK proofs directly. +Often DA layers are used in tandem with Ethereum for consensus. A DA layer can prove on Ethereum that some specific data in their network exists. +By extension, this means that it can prove that data exists in a L2 blockchain that uses that DA layer. -There are multiple DA layers that ZKsync Stack will be integrated with, however the first on the list are: -[Avail](https://www.availproject.org/), [Celestia](https://celestia.org/), and [EigenDA](https://www.eigenda.xyz/). +The ZKsync protocol for the Elastic Network then uses the DA layer's contracts on Ethereum to verify the inclusion proofs it receives from the chain. -::drop-panel - - ::panel{label="What is a DA Layer?"} - - A DA layer is a blockchain network optimized for storing data in a cost-effective way. - A DA layer *does not* prove the correctness of a L2 chain. +## What data does it store? - Often DA layers are used in tandem with Ethereum for consensus. - A DA layer can prove on Ethereum that some specific data in their network exists. - By extension, this means that it can prove that data exists in a L2 blockchain that uses that DA layer. - - The ZKsync protocol for the Elastic Network then uses the DA layer's contracts on Ethereum to verify the inclusion proofs it receives from the chain. - - :: +The DA layer receives and stores pubdata of [L1 batches](/zksync-protocol/rollup/blocks#the-role-of-l1-batches) from a ZKsync chain. +Pubdata consists of the state diffs, L2 to L1 logs, L2 to L1 messages, and published bytecodes. - ::panel{label="What data does it store?"} +After the data is sent to the DA layer, the corresponding entry in the node's `data_availability` table is created. - The DA layer receives and stores pubdata of [L1 batches](/zksync-protocol/rollup/blocks#the-role-of-l1-batches) from a ZKsync chain. +## Types of Validium - Pubdata consists of the state diffs, L2 to L1 logs, L2 to L1 messages, and published bytecodes. +There are 3 different types of validiums based on the level of data availability they provide: - After the data is sent to the DA layer, the corresponding entry in the node's `data_availability` table is created. +- **Stage 0** - the simplest type of validium that only stores its pubdata in the database of the node(s) running the + chain. +- **Stage 1** - a validium that only sends its pubdata to the DA layer, but doesn’t verify its inclusion onchain. +- **Stage 2** - a validium that sends its pubdata to the DA layer, and also verifies its inclusion on the L1, + either by using verification bridges or ZK proofs directly. - :: +There are multiple DA layers that ZK Stack will be integrated with, however the first on the list are: +[Avail](https://www.availproject.org/), [Celestia](https://celestia.org/), and [EigenDA](https://www.eigenda.xyz/). -::panel{label="How is DA validated?"} +## How is DA validated? The DA inclusion verification process consists of two steps, with a corresponding smart contract responsible for each of them: @@ -85,10 +75,6 @@ If we go a step further and do the ZK proof that has the following characteristi It would be possible only verify the proof without the need for additional checks against the bridges. This solution is especially relevant with DA layers that use the commitments that are inefficient to produce on EVM. -:: - -:: - ## Working with Validiums ### Server-related details @@ -98,13 +84,13 @@ handled by two components: DA dispatcher and DA client: - DA client’s role is to abstract the access to the DA layer and generalize it to 3 functions: `dispatch_blob`, `ensure_finality` and `get_inclusion_data`. Clients are a part of the `zksync-era` repository, see the - code [here](https://github.com/matter-labs/zksync-era/tree/main/core/node/da_clients/src). + [code](https://github.com/matter-labs/zksync-era/tree/main/core/node/da_clients/src). - DA dispatcher is responsible for periodically fetching the pubdata from the database, and calling the DA client to dispatch a blob, check that it was finalized or get an inclusion proofs for it. It also handles retries in case the client function call failed with a retryable error. The DA-related information is stored in the `data_availability` table in the database. -A Validium’s new batches can’t be committed if their inclusion data in this table is NULL. +A Validium’s new batches can’t be committed if their inclusion data in this table is `NULL`. **Configuration** @@ -148,12 +134,12 @@ All the configs can also be set using environment variables instead of `.yaml` f ::drop-panel - ::panel{label="How do I set up the new Validium chain locally?"} + ::panel{label="How do I set up a new Validium chain locally?"} 1. Install `zkstack` following [this](https://github.com/matter-labs/zksync-era/tree/main/zkstack_cli) guide 2. `zkstack dev clean all` - to make sure you have an empty setup 3. `zkstack containers` - this creates the necessary docker containers - 4. `zkstack ecosystem init` - init a default ecosystem (go with default options everywhere) + 4. `zkstack ecosystem init --dev` - init a default ecosystem with the default options 5. `zkstack chain create` - create a new chain, stick to the default options, but select Validium when prompted, use this chain as default (the last question there) 6. `zkstack chain init` - init the new chain diff --git a/content/10.zk-stack/20.running/50.configurations.md b/content/10.zk-stack/30.customizations/30.configurations.md similarity index 96% rename from content/10.zk-stack/20.running/50.configurations.md rename to content/10.zk-stack/30.customizations/30.configurations.md index 7ec32da8..720fd1e8 100644 --- a/content/10.zk-stack/20.running/50.configurations.md +++ b/content/10.zk-stack/30.customizations/30.configurations.md @@ -7,6 +7,18 @@ Running the `zkstack ecosystem create` CLI will generate an ecosystem folder that contains the configurations and more for your ecosystem and its chains. Understanding the configuration files for your chain and ecosystem is important for understanding how to interact with and customize your chain and environment. +## Ecosystem configurations + +The main configuration file for the ecosystem can be found at `elastic_chain_ecosystem/ZkStack.yaml`. +This file contains general configuration values for the ecosystem. + +More configuration files for the ecosystem can be found in `/configs`: + +1. `contracts.yaml`: configurations for all the L1 & L2 contracts. +1. `erc20.yaml`: Information about the test ERC20 tokens. +1. `initial_deployments.yaml`: configuration values for the initial ecosystem deployment. +1. `wallets.yaml`: all wallets that you are using for the ecosystem. + ## Chain configurations The main configuration file for a chain called can be found in `/chains//ZkStack.yaml`. @@ -24,15 +36,3 @@ Inside `/chains//configs`, you can fi ::callout{icon="i-heroicons-exclamation-triangle" color="amber"} Never commit your private keys or sensitive secrets to a public repository. :: - -## Ecosystem configurations - -The main configuration file for the ecosystem can be found at `elastic_chain_ecosystem/ZkStack.yaml`. -This file contains general configuration values for the ecosystem. - -More configuration files for the ecosystem can be found in `/configs`: - -1. `contracts.yaml`: configurations for all the L1 & L2 contracts. -1. `erc20.yaml`: Information about the test ERC20 tokens. -1. `initial_deployments.yaml`: configuration values for the initial ecosystem deployment. -1. `wallets.yaml`: all wallets that you are using for this chain. diff --git a/content/10.zk-stack/40.extending/20.transaction-filtering.md b/content/10.zk-stack/30.customizations/40.transaction-filtering.md similarity index 92% rename from content/10.zk-stack/40.extending/20.transaction-filtering.md rename to content/10.zk-stack/30.customizations/40.transaction-filtering.md index 9f5c9789..8bb5d659 100644 --- a/content/10.zk-stack/40.extending/20.transaction-filtering.md +++ b/content/10.zk-stack/30.customizations/40.transaction-filtering.md @@ -6,6 +6,7 @@ description: Learn how to filter transactions on the ZKsync chain, including L1 The ZKsync Chain operators can filter both the transactions initiated from L1 and the ones submitted via API directly to L2. ## L1->L2 Transactions + To filter L1→L2 transactions coming through the Diamond proxy, operators shall: 1. Implement & deploy the `TransactionFilterer` contract which implement the @@ -21,6 +22,11 @@ To disable L1→L2 filtering, the same function that registers the filtered to t ## L2 Transactions +::callout{icon="i-heroicons-exclamation-triangle" color="amber"} +Instructions for L2 transaction filtering is not yet updated for ZKsync OS. +These instructions reflect how to achieve L2 transaction filtering for EraVM. +:: + To filter the transactions sent via the API, operators shall include filtering logic before txs get to the mempool. To do this, an alternative [`TxSinkLayer`](https://github.com/matter-labs/zksync-era/blob/7ace594fb3140212bd94ffd6bffcac99805cf4b1/core/node/node_framework/src/implementations/layers/web3_api/tx_sink/master_pool_sink.rs) diff --git a/content/10.zk-stack/30.customizations/_dir.yml b/content/10.zk-stack/30.customizations/_dir.yml new file mode 100644 index 00000000..afccc004 --- /dev/null +++ b/content/10.zk-stack/30.customizations/_dir.yml @@ -0,0 +1 @@ +title: Customizations diff --git a/content/10.zk-stack/35.prividium/00.index.md b/content/10.zk-stack/35.prividium/00.index.md index 1e5ad7f9..0734ef7a 100644 --- a/content/10.zk-stack/35.prividium/00.index.md +++ b/content/10.zk-stack/35.prividium/00.index.md @@ -46,11 +46,11 @@ These interactions will be visible on the receiving chain. All other transaction and state data remains inside the private chain database, accessible only to the operator. -To learn more about data availability in the ZKsync Stack, visit the [Validium page](/zk-stack/running/validium). +To learn more about data availability in the ZK Stack, visit the [Validium page](/zk-stack/customizations/validium). ### How It Works -ZKsync Prividium enforces privacy and access control at the API layer, using infrastructure built into the ZKsync Stack. +ZKsync Prividium enforces privacy and access control at the API layer, using infrastructure built into the ZK Stack. - Access control is configured in a YAML file that defines which users or groups can call specific contracts and methods. - Users and applications connect through a Private RPC proxy, which enforces access policies on every request. diff --git a/content/10.zk-stack/35.prividium/05.architecture.md b/content/10.zk-stack/35.prividium/05.architecture.md index 5820eb20..912d87c8 100644 --- a/content/10.zk-stack/35.prividium/05.architecture.md +++ b/content/10.zk-stack/35.prividium/05.architecture.md @@ -27,7 +27,7 @@ making ZKsync Prividium well-suited for institutional use cases such as trading, Adding privacy to a ZKsync chain is possible by making changes to the RPC API and block explorer. -The ZKsync Stack CLI provides a production-ready implementation +The ZK Stack CLI provides a production-ready implementation of these changes for you, but they can be customized as needed. - [Access Controls](/zk-stack/prividium/proxy#configuring-access): Fine-grained, role-based permissions ensure that only authorized personnel can @@ -36,7 +36,7 @@ view or interact with your private chain. your internal access policies to every request, maintaining full control over data access and interactions - [Private Block Explorer](/zk-stack/prividium/explorer) with privacy protections enabled. This self-hosted interface gives authorized users visibility into transactions, blocks, and state without exposing sensitive data to the public -- [Validium Chain](/zk-stack/running/validium): A dedicated ZKsync Chain deployed within your infrastructure. +- [Validium Chain](/zk-stack/customizations/validium): A dedicated ZKsync Chain deployed within your infrastructure. It includes a built-in sequencer and prover to handle transaction processing and proof generation privately. -- [ZKsync Gateway](/zk-stack/zk-chains#gateway): Receives ZK proofs from your permissioned chain and publishes commitments to Ethereum. +- [ZKsync Gateway](/zksync-protocol/gateway/overview): Receives ZK proofs from your permissioned chain and publishes commitments to Ethereum. This anchors integrity, ensures finality, and enables future interoperability. diff --git a/content/10.zk-stack/35.prividium/10.run-prividium-chain.md b/content/10.zk-stack/35.prividium/10.run-prividium-chain.md index 187433d5..45002c66 100644 --- a/content/10.zk-stack/35.prividium/10.run-prividium-chain.md +++ b/content/10.zk-stack/35.prividium/10.run-prividium-chain.md @@ -1,9 +1,9 @@ --- title: Run ZKsync Prividium Chain -description: Get started running a local ZKsync Prividium chain with ZKsync Stack. +description: Get started running a local ZKsync Prividium chain with ZK Stack. --- -This guide shows you how to use the ZKsync Stack CLI to run local a ZKsync Prividium chain. +This guide shows you how to use the ZK Stack CLI to run local a ZKsync Prividium chain. By following this guide you will: - Set up a local **Elastic Network ecosystem** @@ -12,7 +12,7 @@ By following this guide you will: - **Test interacting** with your contract - Run a local **block explorer** -## Installing ZKsync Stack CLI +## Installing ZK Stack CLI :display-partial{path="/zk-stack/prividium/_partials/quickstart/_installs"} diff --git a/content/10.zk-stack/35.prividium/20.proxy.md b/content/10.zk-stack/35.prividium/20.proxy.md index 0d9de058..90fe5d2c 100644 --- a/content/10.zk-stack/35.prividium/20.proxy.md +++ b/content/10.zk-stack/35.prividium/20.proxy.md @@ -3,7 +3,7 @@ title: Proxy RPC API description: Learn about the Prividium Proxy RPC API. --- -The proxy RPC API is the main component that enables privacy in the ZKsync Stack. +The proxy RPC API is the main component that enables privacy in the ZK Stack. In a standard rollup, there is a standard RPC API that provides full access to transaction data for users. @@ -126,6 +126,6 @@ to be executed from Ethereum, and it can be used to bypass the privacy configuration of a ZKsync Prividium chain. Currently **L1-L2 transactions are not automatically disabled** in ZKsync Prividium chains. -ZKsync Prividium chain operators can be protected against malicious use of these forced transactions by implementing [transaction filtering](/zk-stack/extending/transaction-filtering). +ZKsync Prividium chain operators can be protected against malicious use of these forced transactions by implementing [transaction filtering](/zk-stack/customizations/transaction-filtering). Note that for users, this means that the chain has the ability to censor transactions. It is the responsibility of the chain operator to decide how to implement this filtering. diff --git a/content/10.zk-stack/35.prividium/_partials/quickstart/_installs.md b/content/10.zk-stack/35.prividium/_partials/quickstart/_installs.md index d94f193d..1ae02bdd 100644 --- a/content/10.zk-stack/35.prividium/_partials/quickstart/_installs.md +++ b/content/10.zk-stack/35.prividium/_partials/quickstart/_installs.md @@ -17,5 +17,5 @@ zkstackup ``` ::callout{icon="i-heroicons-light-bulb"} -You can find a full reference for the ZKsync Stack CLI in the [`zksync-era` repo](https://github.com/matter-labs/zksync-era/tree/main/zkstack_cli). +You can find a full reference for the ZK Stack CLI in the [`zksync-era` repo](https://github.com/matter-labs/zksync-era/tree/main/zkstack_cli). :: diff --git a/content/10.zk-stack/40.extending/00.index.md b/content/10.zk-stack/40.extending/00.index.md deleted file mode 100644 index 6171110b..00000000 --- a/content/10.zk-stack/40.extending/00.index.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: Overview -description: Overview ---- - -ZKsync Stack framework provides many abilities to customize your chain, such as ability to switch between Rollup and Validium, choose a different base -token, and others described in the [Running](/zk-stack/running) sections. - -However, the extensibility doesn't end here. It's possible to customize your chain even more, although it would require more effort. diff --git a/content/10.zk-stack/40.extending/10.node-framework.md b/content/10.zk-stack/40.extending/10.node-framework.md deleted file mode 100644 index 6f7083aa..00000000 --- a/content/10.zk-stack/40.extending/10.node-framework.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: Node Framework -description: Learn how to implement custom components for ZKsync server. ---- - -[ZKsync server](/zk-stack/components/server) is built using custom [dependency injection](https://en.wikipedia.org/wiki/Dependency_injection) framework. -It means that the node can be composed from a set of modules that implement certain interfaces. - -Many of customization options, such as different Data Availability networks or custom base tokens, are supported natively. -However, by utilizing the node framework, it's possible to support custom features, such as different cloud providers, e.g. AWS or Azure or -alternative L1s. - -::callout{icon="i-heroicons-information-circle-16-solid" color="amber"} -While node framework is already functional and can be used today, the support for modified binaries is lacking in many adjacent areas, such as -CI workflows, Docker images, and Infrastructure as a Code. Additionally, the core codebase is not currently published on crates.io. If you want -to run a customized version of the server, the best course of action for now would be to fork zksync-era repository and modify all the relevant -parts (e.g. dockerfiles and automation to push docker images). In the future, reusable infrastructure to support custom server implementations -will be provided. -:: - -To learn mode about the node framework, check out: - -- [Framework showcase](https://github.com/matter-labs/zksync-era/blob/main/core/lib/node_framework/examples/showcase.rs) -- [The framework library](https://github.com/matter-labs/zksync-era/blob/main/core/lib/node_framework/src/lib.rs) -- [Already implemented resources and layers](https://github.com/matter-labs/zksync-era/tree/main/core/node/node_framework/src/implementations) -- [Main node builder](https://github.com/matter-labs/zksync-era/blob/main/core/bin/zksync_server/src/node_builder.rs) -- [External node builder](https://github.com/matter-labs/zksync-era/blob/main/core/bin/external_node/src/node_builder.rs) diff --git a/content/10.zk-stack/40.extending/_dir.yml b/content/10.zk-stack/40.extending/_dir.yml deleted file mode 100644 index 1d4c1d57..00000000 --- a/content/10.zk-stack/40.extending/_dir.yml +++ /dev/null @@ -1 +0,0 @@ -title: Extending ZKsync Chains diff --git a/content/10.zk-stack/_dir.yml b/content/10.zk-stack/_dir.yml index 376923d7..7ac56ee0 100644 --- a/content/10.zk-stack/_dir.yml +++ b/content/10.zk-stack/_dir.yml @@ -1 +1 @@ -title: ZKsync Stack +title: ZK Stack diff --git a/content/20.zksync-protocol/00.index.md b/content/20.zksync-protocol/00.index.md index 51015149..443910e1 100644 --- a/content/20.zksync-protocol/00.index.md +++ b/content/20.zksync-protocol/00.index.md @@ -28,20 +28,12 @@ on ZKsync. --- title: ZKsync OS icon: i-heroicons-cube-transparent - to: /zksync-protocol/zksyncos/overview + to: /zksync-protocol/zksyncos --- Learn about the ZKsync OS, the execution layer. :: ::card --- - title: ZKsync Airbender - icon: i-heroicons-sparkles - to: /zksync-protocol/zksync-airbender/overview - --- - Deep dive into ZKsync Airbender, the new ZK proof system. - :: - ::card - --- title: Contracts icon: i-heroicons-document-magnifying-glass-16-solid to: /zksync-protocol/contracts @@ -80,11 +72,3 @@ on ZKsync. --- Learn about the key distinctions between Ethereum Layer 1 and ZKsync. :: - ::card - --- - title: Native Account Abstraction - icon: i-heroicons-user-circle-16-solid - to: /zksync-protocol/account-abstraction - --- - Utilize account abstraction to streamline user experiences and contract interactions. - :: diff --git a/content/20.zksync-protocol/00.rollup/00.index.md b/content/20.zksync-protocol/00.rollup/00.index.md index dca84aec..a0923987 100644 --- a/content/20.zksync-protocol/00.rollup/00.index.md +++ b/content/20.zksync-protocol/00.rollup/00.index.md @@ -3,7 +3,7 @@ title: ZKsync protocol overview description: Learn about ZK Rollups --- -ZKsync is a protocol designed to enable the creation of a network of interoperable zero-knowledge (ZK) L2 rollups and validiums built with [ZKsync Stack](../../10.zk-stack/00.index.md). +ZKsync is a protocol designed to enable the creation of a network of interoperable zero-knowledge (ZK) L2 rollups and validiums built with [ZK Stack](../../10.zk-stack/00.index.md). This document offers an overview of the protocol’s architecture, focusing on how its modular design supports the development of multiple interconnected chains. Together, these chains enhance Ethereum’s scalability, security, and usability without compromising on decentralization. @@ -74,4 +74,4 @@ still possible). With Shared Bridge, the chains are 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. -- For more details watch this video on [How the ZKsync Stack will power the Internet of Value](https://www.youtube.com/watch?v=BxpKa-S2m34). +- 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). diff --git a/content/20.zksync-protocol/00.rollup/10.transaction-lifecycle.md b/content/20.zksync-protocol/00.rollup/10.transaction-lifecycle.md index cc4e387d..8bb776a4 100644 --- a/content/20.zksync-protocol/00.rollup/10.transaction-lifecycle.md +++ b/content/20.zksync-protocol/00.rollup/10.transaction-lifecycle.md @@ -3,7 +3,7 @@ title: Transaction lifecycle description: An in-depth guide on the transaction lifecycle on ZKsync Chains, explaining the roles of the sequencer and prover, and detailing the transaction statuses and types. --- -The ZKsync Stack facilitates the launch of rollups, which require certain operators like the sequencer and the prover. +The ZK Stack facilitates the launch of rollups, which require certain operators like the sequencer and the prover. These operators are responsible for creating blocks and proofs, and submitting them to the L1 contract. Transactions are cryptographically signed instructions from accounts that aim to update the state of the Ethereum network. diff --git a/content/20.zksync-protocol/00.rollup/50.fee-model/10.how-l2-gas-price-works.md b/content/20.zksync-protocol/00.rollup/50.fee-model/10.how-l2-gas-price-works.md index 40546510..2ad02264 100644 --- a/content/20.zksync-protocol/00.rollup/50.fee-model/10.how-l2-gas-price-works.md +++ b/content/20.zksync-protocol/00.rollup/50.fee-model/10.how-l2-gas-price-works.md @@ -122,7 +122,7 @@ the operator can simply censor bad transactions or increase the `FAIR_L2_GAS_PRI To reiterate, the formulas above are used for L1→L2 transactions on L1 to protect the operator from malicious transactions. However, for L2 transactions, it is solely the responsibility of the ZKsync Chain operator to provide the correct values. -It is designed this way for more fine-grained control over the system for the ZKsync Stack operators +It is designed this way for more fine-grained control over the system for the ZK Stack operators (including Validiums, maybe Era on top of another L1, etc). This fee model also provides a very high degree of flexibility to the operator & so if we find out that we earn too much with a certain part, diff --git a/content/20.zksync-protocol/05.gateway/00.overview.md b/content/20.zksync-protocol/05.gateway/00.overview.md index 8cde3a64..d9219aa9 100644 --- a/content/20.zksync-protocol/05.gateway/00.overview.md +++ b/content/20.zksync-protocol/05.gateway/00.overview.md @@ -31,7 +31,7 @@ Switching between direct Ethereum interaction and Gateway is supported at the pr but a chain must first be deployed with Ethereum as its initial point of settlement. ::callout{icon="i-heroicons-exclamation-triangle" color="amber"} -Learn more about [migrating an existing chain to Gateway in the ZKsync Stack documentation](../../zk-stack/running/gateway-settlement-layer). +Learn more about [migrating an existing chain to Gateway in the ZK Stack documentation](../../zk-stack/running/gateway-settlement-layer). :: ## Gateway Network Details diff --git a/content/20.zksync-protocol/05.gateway/10.features.md b/content/20.zksync-protocol/05.gateway/10.features.md index 45c13918..71cb1be0 100644 --- a/content/20.zksync-protocol/05.gateway/10.features.md +++ b/content/20.zksync-protocol/05.gateway/10.features.md @@ -7,7 +7,7 @@ ZKsync Gateway serves as a shared proof aggregation layer for ZK chains, focusin This section describes its key technical features. ::callout{icon="i-heroicons-exclamation-triangle" color="amber"} -Learn more about [migrating an existing chain to Gateway in the ZKsync Stack documentation](../../zk-stack/running/gateway-settlement-layer). +Learn more about [migrating an existing chain to Gateway in the ZK Stack documentation](../../zk-stack/running/gateway-settlement-layer). :: ## Ethereum as the Root Layer diff --git a/content/20.zksync-protocol/05.gateway/20.da-considerations.md b/content/20.zksync-protocol/05.gateway/20.da-considerations.md index 865bd087..89680bbc 100644 --- a/content/20.zksync-protocol/05.gateway/20.da-considerations.md +++ b/content/20.zksync-protocol/05.gateway/20.da-considerations.md @@ -20,7 +20,7 @@ previously deployed on Ethereum. DA Validator contracts are available on ZKsync Gateway for different data availability solutions, and the chain’s DA configuration must be updated to use the new deployment. -See the list of deployed DA validators [here](/zk-stack/running/validium#zksync-gateway). +See the list of deployed DA validators [here](/zk-stack/customizations/validium). ### Chains with Custom Data Availability diff --git a/content/20.zksync-protocol/05.gateway/50.gateway-faq.md b/content/20.zksync-protocol/05.gateway/50.gateway-faq.md index 08378ec1..999683cd 100644 --- a/content/20.zksync-protocol/05.gateway/50.gateway-faq.md +++ b/content/20.zksync-protocol/05.gateway/50.gateway-faq.md @@ -60,4 +60,4 @@ so the data availability strategy must be enforceable within that context. ### Where can I find more information about migrating a chain to ZKsync Gateway? -Detailed instructions are available in the [ZKsync Stack migration guide](../../zk-stack/running/gateway-settlement-layer). +Detailed instructions are available in the [ZK Stack migration guide](../../zk-stack/running/gateway-settlement-layer). diff --git a/content/20.zksync-protocol/15.zksyncos/00.index.md b/content/20.zksync-protocol/15.zksyncos/00.index.md new file mode 100644 index 00000000..37b3f254 --- /dev/null +++ b/content/20.zksync-protocol/15.zksyncos/00.index.md @@ -0,0 +1,51 @@ +--- +title: Overview +description: Introduction to ZKsync OS +--- + +:display-partial{path="/_partials/_zksyncos/_overview"} + +### Running Environments + +As mentioned before, we have two targets for ZKsync OS. However, this is not just a compilation target, but also how some system primitives +are handled. + +The two running environments are: + +1. **Forward Running Mode:** To be used in the sequencer. In such mode we expect code to be run on the usual platform with OS, +so default memory allocator can be used (as it’s part of the OS). For non-determinism source, we can just pass Oracle's Rust implementation as a +bootloader input. Some code can be skipped in this mode as well (e.g. merkle proof verification for the storage reads). +2. **Proving Running Mode:** To be used during proof generation. The code runs on a pure RISC-V platform without an OS, +so memory management must be handled manually. +Additionally, special care is needed to pass external data into the RISC-V machine due to the absence of standard non-determinism sources. +All behavior must be fully deterministic and provable. + +--- + +## System Resources + +In ZKsync OS, the concept of "resources" is required to limit and charge for both computation (primarily proving) and data usage. +This is more complex than it may initially appear: ZKsync OS is designed to be EVM gas-equivalent, +meaning that EVM code execution should follow the same gas schedule as on Ethereum. + +However, the EVM gas schedule does not accurately reflect the cost of ZK proof generation. +To address this mismatch, ZKsync OS introduces [double accounting](/zksync-protocol/zksyncos/double-accounting): tracking both +Execution Environment (EE) gas-equivalent to EVM gas, and a "native" computational resource that models the cost of proving. + +## L1 Integration + +ZKsync OS is designed for use in ZK rollups and validiums, where state transition correctness must be verified on the settlement +layer (referred to here as L1 for simplicity). + +Specifically, a state commitment is stored on L1. For each block or batch, a proof is generated to verify that a valid state transition has occurred +from a known L1 state commitment to a new one based on some set of inputs. This means the state pre and post transition must be included in +the public inputs (or preimage) of the ZK proof. + +In addition, the public input will include other components required for: + +- Messaging +- Data availability (DA) validation +- Input validation + +ZKsync OS also includes a messaging mechanism that enables trustless communication between L1 and L2, fully compatible with +[EraVM](/zksync-protocol/rollup/l1_l2_communication). This includes L1 to L2 transactions and L2 to L1 messages. diff --git a/content/20.zksync-protocol/15.zksyncos/00.overview.md b/content/20.zksync-protocol/15.zksyncos/00.overview.md deleted file mode 100644 index abf3287c..00000000 --- a/content/20.zksync-protocol/15.zksyncos/00.overview.md +++ /dev/null @@ -1,96 +0,0 @@ ---- -title: Overview -description: Introduction to ZKsync OS ---- - -ZKsync is rebuilding the core of the protocol around two complementary -pillars: [**ZKsync Airbender**](/zksync-protocol/zksync-airbender/overview), -a next-generation proof system, -and **ZKsync OS**, a modular execution layer capable of hosting multiple virtual machines. - -In this section, we will deep dive into ZKsync OS. - -::callout{icon="i-heroicons-exclamation-triangle" color="amber"} -ZKsync OS is under active development and **not** yet used in production chains. -:: - -## ZKsync OS: The Execution Layer - -ZKsync OS is a system-level implementation for ZKsync's state transition function. -Under ZKsync's new architecture, execution is decoupled from proving. -ZKsync OS acts as the operation layer in this new architecture. -It takes block data and an initial state as input and computes the -new state after the application of the block. - -ZKsync OS is implemented as a Rust program that will be compiled to two targets. This first one, x86, is used for running in the sequencer. -The second, RISC-V, is fed as an input to the ZKsync Airbender prover to produce the validity proof of the state transition. - -## Components of ZKsync OS - -ZKsync OS is designed to support multiple VMs. This is needed to seamlessly migrate old Era chains while adding full native EVM equivalence. -In addition, this will allow us to support alt-VMs. - -The main components of ZKsync OS are: - -- [**Bootloader**](/zksync-protocol/zksyncos/bootloader): The entry point program. It initializes the system and then -runs transactions using two components: the system and the execution environment interpreters. -- [**Execution Environments**](/zksync-protocol/zksyncos/execution-environment): Regular interpreters that take bytecode, -calldata, resources (similar to gas) and some other call context values -as its input. Interpreters are instantiated with some local state to execute a frame. When an interpreter sees a call to another contract, -return/revert from current frame, or contract creation it triggers special functionality to process it, as a potentially different -interpreter should be run. -- [**System**](/zksync-protocol/zksyncos/system): Common for all environments and the bootloader. Provides an abstract interface for -low-level handling of IO (storage, events, -L1 messages, oracles) and memory management. The system communicates with the external oracle (non-determinism source), which is needed to read block data -, and also for some IO operations, e.g. to perform the initial read for a storage slot. - -::centered-container -![zksyncOS.png](/images/zksyncos-airbender/zksyncOS.png) -:: - -This modular design enables us to isolate a minimal interface required to implement an Execution Environment. In addition, the system abstraction -makes the storage model customizable and allows for different instances of the entire system. - -### Running Environments - -As mentioned before, we have two targets for ZKsync OS. However, this is not just a compilation target, but also how some system primitives -are handled. - -The two running environments are: - -1. **Forward Running Mode:** To be used in the sequencer. In such mode we expect code to be run on the usual platform with OS, -so default memory allocator can be used (as it’s part of the OS). For non-determinism source, we can just pass Oracle's Rust implementation as a -bootloader input. Some code can be skipped in this mode as well (e.g. merkle proof verification for the storage reads). -2. **Proving Running Mode:** To be used during proof generation. The code runs on a pure RISC-V platform without an OS, -so memory management must be handled manually. -Additionally, special care is needed to pass external data into the RISC-V machine due to the absence of standard non-determinism sources. -All behavior must be fully deterministic and provable. - ---- - -## System Resources -In ZKsync OS, the concept of "resources" is required to limit and charge for both computation (primarily proving) and data usage. -This is more complex than it may initially appear: ZKsync OS is designed to be EVM gas-equivalent, -meaning that EVM code execution should follow the same gas schedule as on Ethereum. - -However, the EVM gas schedule does not accurately reflect the cost of ZK proof generation. -To address this mismatch, ZKsync OS introduces [double accounting](/zksync-protocol/zksyncos/double-accounting): tracking both -Execution Environment (EE) gas-equivalent to EVM gas, and a "native" computational resource that models the cost of proving. - -## L1 Integration - -ZKsync OS is designed for use in ZK rollups and validiums, where state transition correctness must be verified on the settlement -layer (referred to here as L1 for simplicity). - -Specifically, a state commitment is stored on L1. For each block or batch, a proof is generated to verify that a valid state transition has occurred -from a known L1 state commitment to a new one based on some set of inputs. This means the state pre and post transition must be included in -the public inputs (or preimage) of the ZK proof. - -In addition, the public input will include other components required for: - -- Messaging -- Data availability (DA) validation -- Input validation - -ZKsync OS also includes a messaging mechanism that enables trustless communication between L1 and L2, fully compatible with -[EraVM](/zksync-protocol/rollup/l1_l2_communication). This includes L1 to L2 transactions and L2 to L1 messages. diff --git a/content/20.zksync-protocol/15.zksyncos/01.double-accounting.md b/content/20.zksync-protocol/15.zksyncos/01.double-accounting.md index 55b24985..719c9136 100644 --- a/content/20.zksync-protocol/15.zksyncos/01.double-accounting.md +++ b/content/20.zksync-protocol/15.zksyncos/01.double-accounting.md @@ -3,7 +3,7 @@ title: Double Resource Accounting description: Introduction to Double Resource Accounting --- -ZKsync OS implements a double resource accounting model, where both a Execution Environment resource (EVM gas, for instance) and native resource are tracked. +ZKsync OS implements a double resource accounting model, where both a Execution Environment resource (EVM gas, for instance) and native resources are tracked. The interface to interact with resources can be found in [resources.rs](https://github.com/matter-labs/zksync-os/blob/main/zk_ee/src/system/resources.rs). diff --git a/content/20.zksync-protocol/15.zksyncos/04.system.md b/content/20.zksync-protocol/15.zksyncos/04.system.md index dd652fe8..7e99e447 100644 --- a/content/20.zksync-protocol/15.zksyncos/04.system.md +++ b/content/20.zksync-protocol/15.zksyncos/04.system.md @@ -9,7 +9,7 @@ It provides access to memory, IO, and oracles. Oracles are the interface throu The System struct is generic over memory, IO, oracles and allocators and provides little else besides access to those and block metadata. The *Concrete system implementations* are two instances of those components to result in full system implementations, one for the sequencer and the other for the prover (as mentioned in the -[Overview](/zksync-protocol/zksyncos/overview#running-environments)). +[Overview](/zksync-protocol/zksyncos#running-environments)). ### System Struct diff --git a/content/20.zksync-protocol/15.zksyncos/05.tx-processing.md b/content/20.zksync-protocol/15.zksyncos/05.tx-processing.md index e6050762..f3415825 100644 --- a/content/20.zksync-protocol/15.zksyncos/05.tx-processing.md +++ b/content/20.zksync-protocol/15.zksyncos/05.tx-processing.md @@ -14,6 +14,7 @@ transactions. We'll describe the latter first and the **L1 -> L2 transactions** 6. **Refunding**: Unused resources are refunded. ## Resources + Transaction processing starts with the parsing of the transaction. After parsing the transaction, the bootloader computes how many resources the transaction can spend. This resource calculation involves taking the diff --git a/content/20.zksync-protocol/20.contracts/10.l1-contracts/00.index.md b/content/20.zksync-protocol/20.contracts/10.l1-contracts/00.index.md index dc76cf65..42502cd2 100644 --- a/content/20.zksync-protocol/20.contracts/10.l1-contracts/00.index.md +++ b/content/20.zksync-protocol/20.contracts/10.l1-contracts/00.index.md @@ -3,12 +3,12 @@ title: L1 contracts description: --- -This section explores the core Layer 1 smart contracts used by ZKsync Chains, including both rollups and validiums built using the ZKsync Stack. +This section explores the core Layer 1 smart contracts used by ZKsync Chains, including both rollups and validiums built using the ZK Stack. These contracts facilitate communication, proof verification, and asset bridging between Ethereum (Layer 1) and individual ZKsync Chains (Layer 2s) that make up the broader ZKsync ecosystem. While this page focuses primarily on the shared smart contract architecture used by ZKsync Era and other ZKsync Chains, it does *not* cover the full -architecture of ZKsync Stack chains, such as inter-chain messaging or shared liquidity across multiple rollups. +architecture of ZK Stack chains, such as inter-chain messaging or shared liquidity across multiple rollups. For protocol-level details around cross-chain coordination and ecosystem-level contracts, see [Ecosystem Contracts](/zksync-protocol/contracts/l1-contracts/l1-ecosystem-contracts). @@ -41,7 +41,7 @@ The diamond proxy pattern is very flexible and extendable. For now, it allows splitting implementation contracts by their logical meaning, removes the limit of bytecode size per contract and implements security features such as freezing. In the future, it can also be viewed as [EIP-6900](https://eips.ethereum.org/EIPS/eip-6900) -for [ZKsync Stack](https://blog.matter-labs.io/introducing-the-zk-stack-c24240c2532a), +for [ZK Stack](https://blog.matter-labs.io/introducing-the-zk-stack-c24240c2532a), where each ZKsync Chain can implement a sub-set of allowed implementation contracts. ### GettersFacet diff --git a/content/20.zksync-protocol/20.contracts/10.l1-contracts/10.l1-ecosystem-contracts.md b/content/20.zksync-protocol/20.contracts/10.l1-contracts/10.l1-ecosystem-contracts.md index 9f8d95f5..a817becc 100644 --- a/content/20.zksync-protocol/20.contracts/10.l1-contracts/10.l1-ecosystem-contracts.md +++ b/content/20.zksync-protocol/20.contracts/10.l1-contracts/10.l1-ecosystem-contracts.md @@ -5,9 +5,9 @@ description: Ethereum's future is rollup-centric. This means moving beyond isolated EVM chains toward an infrastructure centered around an ecosystem of interconnected **ZKsync Chains**. -These chains are independently deployed rollups or validiums built using the ZKsync Stack, and together they form a coordinated network secured by Ethereum. +These chains are independently deployed rollups or validiums built using the ZK Stack, and together they form a coordinated network secured by Ethereum. -To support this ecosystem, Ethereum requires shared Layer 1 smart contracts. This page outlines the ZKsync Stack’s approach to these contracts: +To support this ecosystem, Ethereum requires shared Layer 1 smart contracts. This page outlines the ZK Stack’s approach to these contracts: their interfaces, architectural changes, and future features to enable cross-chain functionality, shared liquidity, and interoperability. If you're new to ZKsync Chains, see our [Introduction to ZKsync Chains](https://blog.matter-labs.io/introduction-to-hyperchains-fdb33414ead7). @@ -43,7 +43,7 @@ we’ll call each rollup a ZKsync Chain (note, that these can also be Validiums) Since protocol upgrade v24 (May 2024), all ZKsync Chain contracts, including ZKsync Era diamond proxy, no longer directly manages any funds. Instead, this responsibility transitions to the shared bridge. -This document describes technical details of ZKsync Stack contracts that make it possible for multiple chains to share liquidity, +This document describes technical details of ZK Stack contracts that make it possible for multiple chains to share liquidity, and provide cost-effective communication among them. Before delving into the details of ecosystem contracts, please familiarize yourself with the concept of [ZKsync Chains](/zksync-protocol/rollup) and read @@ -119,13 +119,13 @@ and so the upgrade process of each individual ZKsync Chain will be similar to th 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 ZKsync Stack devs to update their version. + This is done offchain. Enough time should be given to various ZK Stack devs to update their version. 2. The governance of the CTM will schedule the upgrade. This operation also notifies the operators of ZKsync Chains on when they should start processing new batches. The server is written in such a way that automatically at the scheduled timestamp of the upgrade the new version will be used in batches. If the timestamp is set in the past, the new version will be used immediately. -3. After the timestamp has passed it is expected that ZKsync Stack instances will all start processing the new version on the server side. +3. After the timestamp has passed it is expected that ZK Stack instances will all start processing the new version on the server side. After that the governance atomically calls the following three functions: diff --git a/content/20.zksync-protocol/20.contracts/10.l1-contracts/20.shared-bridges.md b/content/20.zksync-protocol/20.contracts/10.l1-contracts/20.shared-bridges.md index fb851030..9010f2c5 100644 --- a/content/20.zksync-protocol/20.contracts/10.l1-contracts/20.shared-bridges.md +++ b/content/20.zksync-protocol/20.contracts/10.l1-contracts/20.shared-bridges.md @@ -7,7 +7,7 @@ Ethereum's evolving infrastructure is shifting towards a rollup-centric future, focusing on an interconnected ecosystem of zero-knowledge Ethereum Virtual Machines (zkEVMs), collectively known as ZKsync chains. This transformation relies on robust Layer 1 (L1) smart contracts to maintain coherence and security across the ecosystem. -## ZKsync Stack approach +## ZK Stack approach Our approach to developing this ecosystem involves specific architectures and interfaces of L1 smart contracts. These contracts are designed to support the changing needs of the Ethereum landscape and facilitate the integration of new features as the technology advances. diff --git a/content/10.zk-stack/50.zk-chain-addresses.md b/content/20.zksync-protocol/20.contracts/10.l1-contracts/30.zk-chain-addresses.md similarity index 98% rename from content/10.zk-stack/50.zk-chain-addresses.md rename to content/20.zksync-protocol/20.contracts/10.l1-contracts/30.zk-chain-addresses.md index 0771391d..0b43d7e5 100644 --- a/content/10.zk-stack/50.zk-chain-addresses.md +++ b/content/20.zksync-protocol/20.contracts/10.l1-contracts/30.zk-chain-addresses.md @@ -7,7 +7,7 @@ To enable seamless interoperability of the ZKsync Chain ecosystem, the Bridgehub, SharedBridges and Chain Type Managers (CTMs) are deployed on L1 and L2 to manage communication between ZKsync Chain contracts. -Learn more about [Shared Bridges](/zksync-protocol/contracts/l1-contracts/shared-bridges) in the ZKsync Stack section. +Learn more about [Shared Bridges](/zksync-protocol/contracts/l1-contracts/shared-bridges) in the ZK Stack section. To understand the concept of ZKsync Chains, learn more on [ZKsync Chains](/zk-stack/zk-chains). ## Getting the Chain Type Manager for a ZKsync Chain diff --git a/content/20.zksync-protocol/80.account-abstraction/20.design.md b/content/20.zksync-protocol/80.account-abstraction/20.design.md index 522efc67..9fad2246 100644 --- a/content/20.zksync-protocol/80.account-abstraction/20.design.md +++ b/content/20.zksync-protocol/80.account-abstraction/20.design.md @@ -176,7 +176,7 @@ EIP-4337 defines three types of gas limits to manage the costs associated with d #### Unified Gas Limit in ZKsync Chains -In contrast, the ZKsync Stack simplifies the fee structure by using a single `gasLimit` +In contrast, the ZK Stack simplifies the fee structure by using a single `gasLimit` field for all transaction-related costs. This unified `gasLimit` must be adequately set to cover: diff --git a/content/_partials/_zksyncos/_overview.md b/content/_partials/_zksyncos/_overview.md new file mode 100644 index 00000000..e22a814e --- /dev/null +++ b/content/_partials/_zksyncos/_overview.md @@ -0,0 +1,38 @@ +--- +title: ZKsync OS Overview +description: Introduction to ZKsync OS +--- + +ZKsync OS is a system-level implementation for ZKsync's state transition function. +Under ZKsync's new architecture, execution is decoupled from proving. +ZKsync OS acts as the operation layer in this new architecture. +It takes block data and an initial state as input and computes the +new state after the application of the block. + +ZKsync OS is implemented as a Rust program that will be compiled to two targets. This first one, x86, is used for running in the sequencer. +The second, RISC-V, is fed as an input to the [ZKsync Airbender](/zk-stack/components/zksync-airbender) +prover to produce the validity proof of the state transition. + +## Components of ZKsync OS + +ZKsync OS is designed to support multiple VMs. +The main components of ZKsync OS are: + +- [**Bootloader**](/zksync-protocol/zksyncos/bootloader): The entry point program. It initializes the system and then +runs transactions using two components: the system and the execution environment interpreters. +- [**Execution Environments**](/zksync-protocol/zksyncos/execution-environment): Regular interpreters that take bytecode, +calldata, resources (similar to gas) and some other call context values +as its input. Interpreters are instantiated with some local state to execute a frame. When an interpreter sees a call to another contract, +return/revert from current frame, or contract creation it triggers special functionality to process it, as a potentially different +interpreter should be run. +- [**System**](/zksync-protocol/zksyncos/system): Common for all environments and the bootloader. Provides an abstract interface for +low-level handling of IO (storage, events, +L1 messages, oracles) and memory management. The system communicates with the external oracle (non-determinism source), which is needed to read block data +, and also for some IO operations, e.g. to perform the initial read for a storage slot. + +::centered-container +![zksyncOS.png](/images/zksyncos-airbender/zksyncOS.png) +:: + +This modular design enables us to isolate a minimal interface required to implement an Execution Environment. In addition, the system abstraction +makes the storage model customizable and allows for different instances of the entire system. diff --git a/content/index.yml b/content/index.yml index 712a9b7e..bf0d237e 100644 --- a/content/index.yml +++ b/content/index.yml @@ -1,23 +1,23 @@ title: 'ZKsync Docs' description: - ZKsync Docs bring you all information you need about our protocol, APIs, SDKs, ZKsync Stack, and ZKsync chains. Start - with our guides and tutorials, or go deep into our architecture and protocol specification. + ZKsync Docs bring you all information you need about our protocol, APIs, SDKs, ZK Stack, and ZKsync chains. Start with + our guides and tutorials, or go deep into our architecture and protocol specification. navigation: false hero: title: 'A network of interoperable chains, secured by ZK.' description: 'Explore comprehensive guides, developer tools, and resources to innovate on ZKsync.' orientation: vertical links: - - label: Build Apps on ZKsync + - label: Launch Your Chain icon: i-heroicons-arrow-right-20-solid trailing: true - to: '/zksync-network' + to: '/zk-stack' size: xl color: primary - - label: Launch Your Chain + - label: Build Apps on ZKsync icon: i-heroicons-arrow-right-20-solid trailing: true - to: '/zk-stack' + to: '/zksync-network' size: xl color: primary variant: outline @@ -44,7 +44,7 @@ stackfeatures: icon: 'i-heroicons-link-16-solid' to: '/zk-stack/zk-chains' - title: 'Running a ZKsync Chain' - description: 'Get your first ZKsync chain running locally using ZKsync Stack CLI.' + description: 'Get your first ZKsync chain running locally using ZK Stack CLI.' icon: 'i-zkicon-zksync' to: '/zk-stack/running/quickstart' - title: 'Prividium' diff --git a/error.vue b/error.vue index f3d18d1a..74532116 100644 --- a/error.vue +++ b/error.vue @@ -32,7 +32,7 @@ const cards = [ icon: 'i-heroicons-code-bracket-16-solid', }, { - title: 'ZKsync Stack', + title: 'ZK Stack', description: 'Learn how to run your own ZKsync chain with our chain operator quickstart guide.', to: '/zk-stack/running/quickstart', icon: 'i-heroicons-square-3-stack-3d-16-solid', @@ -40,7 +40,7 @@ const cards = [ { title: 'ZKsync Airbender', description: 'Explore the fastest RISC-V prover powering the next-generation of ZKsync chains.', - to: '/zksync-protocol/zksync-airbender/overview', + to: '/zk-stack/components/zksync-airbender', icon: 'i-heroicons-rocket-launch-solid', }, { diff --git a/firebase.json b/firebase.json index cf2bece2..5f45585c 100644 --- a/firebase.json +++ b/firebase.json @@ -525,6 +525,56 @@ "source": "/zksync-era", "destination": "/zksync-network", "type": 301 + }, + { + "source": "/zksync-protocol/zksyncos/overview", + "destination": "/zksync-protocol/zksyncos", + "type": 301 + }, + { + "source": "/zk-stack/extending", + "destination": "/zk-stack/customizations/configurations", + "type": 301 + }, + { + "source": "/zk-stack/extending/node-framework", + "destination": "/zk-stack/customizations/configurations", + "type": 301 + }, + { + "source": "/zk-stack/running/configurations", + "destination": "/zk-stack/customizations/configurations", + "type": 301 + }, + { + "source": "/zk-stack/extending/transaction-filtering", + "destination": "/zk-stack/customizations/transaction-filtering", + "type": 301 + }, + { + "source": "/zk-stack/running/custom-base-tokens", + "destination": "/zk-stack/customizations/custom-base-tokens", + "type": 301 + }, + { + "source": "/zk-stack/running/validium", + "destination": "/zk-stack/customizations/validium", + "type": 301 + }, + { + "source": "/zk-stack/components/portal-wallet-bridge", + "destination": "/zk-stack/components/portal", + "type": 301 + }, + { + "source": "/zksync-protocol/zksync-airbender/overview", + "destination": "/zk-stack/components/zksync-airbender", + "type": 301 + }, + { + "source": "/zksync-protocol/zksync-airbender/deepdive", + "destination": "/zk-stack/components/zksync-airbender/deepdive", + "type": 301 } ] } diff --git a/header-links.ts b/header-links.ts index eeeb663a..5498fb01 100644 --- a/header-links.ts +++ b/header-links.ts @@ -13,7 +13,7 @@ export const headerLinks = () => { active: route.path.startsWith('/zksync-network'), }, { - label: 'ZKsync Stack', + label: 'ZK Stack', to: isDocsApp ? '/zk-stack' : `${config.public.urls.docs}/zk-stack`, active: route.path.startsWith('/zk-stack'), }, diff --git a/nuxt.config.ts b/nuxt.config.ts index 817a4e0d..e3048a90 100644 --- a/nuxt.config.ts +++ b/nuxt.config.ts @@ -42,7 +42,7 @@ export default defineNuxtConfig({ name: 'ZKsync Developer Documentation', short_name: 'ZKsync Docs', description: - 'ZKsync Docs bring you all information you need about our protocol, APIs, SDKs, ZKsync Stack, and ZKsync chains. Start with our guides and tutorials, or go deep into our architecture and protocol specification.', + 'ZKsync Docs bring you all information you need about our protocol, APIs, SDKs, ZK Stack, and ZKsync chains. Start with our guides and tutorials, or go deep into our architecture and protocol specification.', theme_color: '#F2F2F2', icons: [ { diff --git a/pages/index.vue b/pages/index.vue index 2231057b..6120bc95 100644 --- a/pages/index.vue +++ b/pages/index.vue @@ -71,13 +71,13 @@ defineOgImage({ @@ -85,13 +85,13 @@ defineOgImage({ diff --git a/redirects.ts b/redirects.ts index 9fe4f063..61d68e7d 100644 --- a/redirects.ts +++ b/redirects.ts @@ -243,7 +243,7 @@ const docsReorgRedirects = { '/zk-stack/components/zksync-evm/bootloader': { redirect: '/zksync-protocol/contracts/bootloader' }, '/zk-stack/components/zksync-evm': { redirect: '/zksync-protocol/vm' }, '/zk-stack/components/zksync-evm/vm-specification': { redirect: '/zksync-protocol/vm' }, - '/zk-stack/components/transaction-filtering': { redirect: '/zk-stack/extending/transaction-filtering' }, + '/zk-stack/components/transaction-filtering': { redirect: '/zk-stack/customizations/transaction-filtering' }, // ZK Stack components: prover // `/zk-stack/components/prover` doesn't get a redirect: it contains a new page at the same path that works better