feat: add zksync os dev preview section (#433)

Adds a new section in the zksync-network docs with an overview of ZKsync
OS, network details, quickstart, and FAQ. Also adds the network to the
chains list



- ~~depends on
matter-labs/docs-nuxt-template#116 to add
support for MM button~~
- ~~waiting for block explorer URL~~
- missing contract verification url

---------

Co-authored-by: krinza.eth <[email protected]>
Co-authored-by: Antonio <[email protected]>

Author: 3 people

bun.lockb

@@ -1,7 +1,10 @@
 <template>
   <div class="space-y-6">
     <!-- Mainnet Details -->
-    <div class="not-prose overflow-x-auto">
+    <div
+      v-if="!props.showzksyncos"
+      class="not-prose overflow-x-auto"
+    >
       <UTable
         :columns="columns"
         :rows="mainnetDetails"
@@ -53,7 +56,7 @@
     <div class="not-prose overflow-x-auto">
       <UTable
         :columns="columns"
-        :rows="testnetDetails"
+        :rows="props.showzksyncos ? zksyncOSTestnetDetails : testnetDetails"
         class="min-w-full divide-y divide-gray-200 rounded-lg border border-gray-200 dark:divide-gray-700 dark:border-gray-700"
         :ui="{
           table: 'w-full table-auto',
@@ -109,6 +112,10 @@ interface NetworkDetail {
   isLink?: boolean;
 }
 
+const props = defineProps<{
+  showzksyncos?: boolean;
+}>();
+
 const columns = [
   {
     key: 'property',
@@ -147,4 +154,22 @@ const testnetDetails: NetworkDetail[] = [
     isCopyable: true,
   },
 ];
+
+const zksyncOSTestnetDetails: NetworkDetail[] = [
+  { property: 'Network Name', value: 'ZKsync OS Devnet', isCode: true },
+  { property: 'RPC URL', value: 'https://zksync-os-testnet-alpha.zksync.dev/', isCopyable: true },
+  { property: 'WebSocket URL', value: 'wss://zksync-os-testnet-alpha.zksync.dev/ws', isCopyable: true },
+  { property: 'Chain ID', value: '8022833', isCode: true },
+  { property: 'Currency Symbol', value: 'ETH', isCode: true },
+  {
+    property: 'Block Explorer URL',
+    value: 'https://zksync-os-testnet-alpha.staging-scan-v2.zksync.dev/',
+    isLink: true,
+  },
+  {
+    property: 'Explorer Verification API',
+    value: '(coming soon)',
+    isCopyable: false,
+  },
+];
 </script>

components/ZksyncEraNetworkDetails.vue

@@ -21,8 +21,7 @@ To manually add ZKsync Era as a custom network in your wallet, follow these step
 
 ### Network details
 
-::zksync-era-network-details
-::
+:zksync-era-network-details
 
 ## Get testnet funds for your wallet
 

content/00.zksync-network/20.environment/03.zksync-era.md

@@ -0,0 +1,75 @@
+---
+title: Overview
+description: Get started learning about ZKsync OS.
+---
+
+ZKsync OS is the modular execution layer of the ZKsync stack. It defines the system-level state transition function of a chain
+and supports multiple execution environments (VMs).
+
+Unlike earlier implementations, ZKsync OS separates execution from proving,
+making both layers independently upgradable and easier to optimize. This design improves performance, ensures EVM equivalence, and enables
+new execution environments to be added for application-specific use cases.
+
+## Architecture
+
+The core of the protocol is built around a two-layer architecture:
+
+- a modular execution layer,
+- and the proving layer.
+
+The execution layer defines the logic of execution, memory handling, and IO. It takes block data and an initial state as input
+and computes the new state after the block is applied. The proving layer then generates validity proofs of this state transition.
+
+ZKsync OS is implemented in Rust and compiled to two targets. The **x86 target** is used by the sequencer to run execution directly,
+while the **RISC-V target** is provided to the ZKsync Airbender prover to generate proofs of correctness. This ensures consistency between
+the sequencer’s runtime behavior and the proof system, while keeping execution and proving cleanly separated.
+
+By isolating these layers, ZKsync OS makes it possible to evolve execution logic independently from the prover.
+This separation also shifts focus to the execution layer, an area often neglected in rollup design. While many efforts
+in the ecosystem concentrate on prover efficiency, ZKsync OS demonstrates that significant performance gains can also be
+achieved by optimizing how execution itself is structured.
+
+## Components of ZKsync OS
+
+The main components of ZKsync OS are:
+
+1. **[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.
+
+2. **[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.
+
+ZKsync OS will initially only support EVM.
+In the future, it will include the following EEs:
+
+- **EVM:** Provides full native EVM-equivalence to ZKsync.
+- **WASM:** Allows ZKsync to support contracts written in any language that compiles to WASM (e.g. Rust).
+- **Native RISC-V:** User-mode RISC V code execution unlocks highest proving performance due to not having any interpretation overhead.
+
+<!-- markdownlint-disable -->
+3. **[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.
+
+## System Design Goals
+
+The design of ZKsync OS focuses on delivering high throughput and low cost.
+The Rust implementation enables low-level optimizations for memory access,
+IO, and execution paths, ensuring that performance can scale in line with network demands.
+
+ZKsync OS serves as the foundation of the Elastic Network. For builders, it offers full EVM equivalence and tooling,
+while also unlocking new programming models through WASM and RISC-V.
+
+For users, ZKsync OS provides a consistent experience across chains, with security underpinned by ZK proofs.
+And for the broader ecosystem, its modular design allows for application-specific specialization without fragmentation,
+while maintaining interoperability across all ZKsync Stack chains.

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

@@ -0,0 +1,60 @@
+---
+title: ZKsync OS Network
+description: Get connected to ZKsync OS Devnet
+---
+
+## Add ZKsync OS Devnet to your MetaMask wallet
+
+You can add ZKsync OS Devnet to your MetaMask wallet using the buttons below:
+
+<!-- // cspell: disable -->
+:network-adder{ network="ostestnet" }
+<!-- // cspell: enable -->
+
+If you are using a different in-browser wallet, the buttons above may also work for them.
+
+## Manually add ZKsync OS Devnet
+
+To manually add ZKsync OS Devnet as a custom network in your wallet, follow these steps:
+
+1. Find the “Add Network” option in your wallet (in MetaMask, you can find this in the networks dropdown).
+1. Click on “Add Network" and "Add network manually".
+1. Fill in the following details for the ZKsync OS Devnet environment:
+
+### Network details
+
+<!-- // cspell: disable -->
+:zksync-era-network-details{showzksyncos}
+<!-- // cspell: enable -->
+
+## Get devnet funds for your wallet
+
+Once you have your wallet connected to the ZKsync OS Devnet environment,
+you can bridge testnet ETH from Sepolia Testnet to ZKsync OS Devnet.
+You can get testnet funds from one of many [testnet faucets](/zksync-network/ecosystem/network-faucets#sepolia-faucets).
+
+### Bridging testnet ETH
+
+The ZKsync portal is not yet updated to support ZKsync OS.
+Until then, you can use `cast` or `zksync-sdk` to manually bridge funds over as shown in the examples below:
+
+#### Bridging with `cast`
+
+<!-- // cspell: disable -->
+```bash
+export BRIDGEHUB_ADDRESS=0xc4fd2580c3487bba18d63f50301020132342fdbd
+export CHAIN_ID=8022833
+export SEPOLIA_RPC=<YOUR_SEPOLIA_RPC_ENDPOINT>
+export ZKOS_DEVNET_RPC=https://zksync-os-testnet-alpha.zksync.dev/
+export ADDRESS=<YOUR_WALLET_ADDRESS>
+export VALUE_TO_BRIDGE=<AMOUNT_TO_BRIDGE_IN_WEI>
+```
+<!-- // cspell: enable -->
+
+```bash
+cast send -r $SEPOLIA_RPC $BRIDGEHUB_ADDRESS "requestL2TransactionDirect((uint256,uint256,address,uint256,bytes,uint256,uint256,bytes[],address))" "($CHAIN_ID,$VALUE_TO_BRIDGE,$ADDRESS,50,0x,300000,800,[],$ADDRESS)" --value $VALUE_TO_BRIDGE --private-key=$PRIVATE_KEY
+```
+
+#### Bridging with `@zksync-sdk`
+
+You can find examples for bridging with `ethers` or `viem` in the [`@zksync-sdk` docs](https://dutterbutter.github.io/zksync-sdk/overview/index.html).

content/00.zksync-network/65.zksync-os/05.network-details.md

@@ -0,0 +1,20 @@
+---
+title: Developer Quickstart
+description: Getting starting developing with ZKsync OS
+---
+
+You can use all standard EVM tooling for ZKsync OS.
+
+To get started with Hardhat, follow the steps below:
+
+::content-switcher
+---
+items: [{
+  label: 'Hardhat 3 with Viem',
+  partial: '_partials/_viem'
+}, {
+  label: 'Hardhat 3 with Ethers',
+  partial: '_partials/_ethers'
+}]
+---
+::

content/00.zksync-network/65.zksync-os/07.quickstart.md

@@ -0,0 +1,81 @@
+---
+title: FAQs
+description: Answers to frequently asked questions about ZKsync OS.
+---
+
+## What are the main benefits of ZKsync OS?
+
+The main benefits of ZKsync OS over the previous system include faster performance, higher TPS,
+the ability to support multiple execution environments,
+and the decoupling of the prover from execution to enable faster upgrades.
+
+## What changes to development workflows will be required to use ZKsync OS?
+
+Developers will be able to use standard EVM tooling and compilers for contract deployment and interaction
+instead of ZKsync-specific tooling and compilers like `zksolc` and `zkvyper`.
+
+## For app developers, are there any differences from the Ethereum EVM?
+
+ZKsync OS is fully EVM equivalent.
+Like with other EVM equivalent L2 solutions, there are a few distinctions that app developers should take note of:
+
+- ZKsync OS will initially target Cancun for the first version.
+  Support for Pectra will be added soon after.
+- ZKsync OS provides some additional L2-specific functionality like sending messages to the L1 and interoperability via [ZKsync Gateway](/zksync-protocol/gateway/overview).
+- ZKsync OS can charge additional gas at the end of a transaction to cover pubdata and some additional costs.
+  This doesn’t affect the behavior of contracts,
+  but can require higher gas limits / gas price.
+  See the [Double Resource Accounting](https://docs.zksync.io/zksync-protocol/zksyncos/double-accounting) doc for more information.
+- A different state model is used.
+  For app developers this only affects storage proofs.
+  More details about the storage model can be found in the [`zksync-os` repository](https://github.com/matter-labs/zksync-os/blob/main/docs/system/io/io.md).
+- Blake2f (`0x09`) and KZG point evaluation (`0x0a`) precompiles are not yet supported.
+
+## Is ZKsync OS replacing EraVM? Will existing chains upgrade to it?
+
+Yes, ZKsync OS will replace EraVM for ZKsync chains.
+Eventually chains that use EraVM with the legacy system will be deprecated.
+
+## If there are multiple execution environments, why can’t ZKsync OS run EraVM?
+
+It is feasibly possible to run EraVM with ZKsync OS in the future.
+However, to enable chains to use ZKsync OS earlier, EVM was prioritized as the first and only execution environment for the initial version.
+
+## What will it mean for projects that use native account abstraction on EraVM?
+
+ZKsync OS will use EVM.
+EraVM and native EraVM account abstraction will not be supported.
+Any projects that currently rely on native account abstraction on EraVM that wish to switch to ZKsync OS must be migrated.
+
+[ERC-4337](https://docs.erc4337.io/) will be supported with ZKsync OS.
+ZKsync SSO contracts will be upgraded for ERC-4337,
+so projects that rely of ZKsync SSO will be able to continue using it.
+
+EIP-7702 will not be supported in the initial version of ZKsync OS, but will be in a later version.
+
+## How can builders leverage any new features or capabilities?
+
+In the initial version of ZKsync OS, capabilities will be similar to those of other EVM L2 chains.
+However, in the future support for multiple execution environments
+will enable builders to use alternative programming languages to write smart contracts.
+
+## Will chains that use ZKsync OS be able to use interop and Gateway?
+
+Yes, chains that use ZKsync OS will also be able to use ZKsync Gateway and interop.
+
+## Does ZKsync OS change what stage ZKsync chains are at?
+
+No, on its own chains that use ZKsync OS will not affect their stage level.
+However, it may make it easier to move to stages 1 and 2 because improvements to the prover can be deployed more efficiently.
+
+## Is there a public testnet and mainnet?
+
+A public devnet is live and ready for testing.
+You can find the more information in this section of the docs for the [network details](/zksync-network/zksync-os/network-details)
+and [getting started](/zksync-network/zksync-os/quickstart) with development.
+Currently there is no public mainnet.
+
+## How can I run it locally?
+
+Running a ZKsync OS chain is not yet supported using `zkstack`.
+A full guide for running a ZKsync OS chain will be available soon.

content/00.zksync-network/65.zksync-os/10.faqs.md

@@ -0,0 +1 @@
+title: ZKsync OS Developer Preview

content/00.zksync-network/65.zksync-os/_dir.yml

@@ -0,0 +1,21 @@
+---
+title: Hardhat 3 with Ethers
+---
+
+:display_partial{path="_partials/_zksyncos/_setup-folder"}
+
+2. Initialize a new Hardhat 3 project with Mocha and Ethers.js. <!-- markdownlint-disable-line -->
+
+    ```bash
+    npx hardhat --init
+    ```
+
+:display_partial{path="_partials/_zksyncos/_setup"}
+
+7. Copy/paste the script below. <!-- markdownlint-disable-line -->
+
+    ```ts [increment.ts]
+    :code-import{filePath="zksync-os/scripts/increment-ethers.ts"}
+    ```
+
+:display_partial{path="_partials/_zksyncos/_run-script"}

content/00.zksync-network/65.zksync-os/_partials/_ethers.md

@@ -0,0 +1,21 @@
+---
+title: Hardhat 3 with Viem
+---
+
+:display_partial{path="_partials/_zksyncos/_setup-folder"}
+
+2. Initialize a new Hardhat 3 project with Node Test Runner and Viem. <!-- markdownlint-disable-line -->
+
+    ```bash
+    npx hardhat --init
+    ```
+
+:display_partial{path="_partials/_zksyncos/_setup"}
+
+7. Copy/paste the script below. <!-- markdownlint-disable-line -->
+
+    ```ts [increment.ts]
+    :code-import{filePath="zksync-os/scripts/increment-viem.ts"}
+    ```
+
+:display_partial{path="_partials/_zksyncos/_run-script"}