feat(zkstack): Deploy 2 ctms and deploy chain for each of them (#4458)

## What ❔

**Support for deploying and managing multiple CTM (Contract Template
Manager) contracts, and allowing selection between them when creating
chains.**

### Flow of execution

#### 1. Create a new ecosystem

```bash
zkstack ecosystem create
```

This command creates a **new ecosystem**.
You’ll specify the link to the code repository (by default, this points
to the **Era** codebase).
Contracts will be used as a submodule within this repository.

After creating the ecosystem, initialize it:

```bash
zkstack ecosystem init
```

This command deploys a **new ecosystem** and **one default Era chain**.

---

#### 2. Initialize another CTM

Once everything is deployed, you can deploy an additional CTM:

```bash
zkstack ctm init-new-ctm --zksync-os --contracts-src-path <path> --default-configs-src-path <path>
```

**Parameters:**

* `--contracts-src-path` — Path to the **Era contracts** (you must clone
and manage this repository manually).
Use a branch or tag matching the desired **zkSync OS** or **Era**
version.
* `--default-configs-src-path` — Path to **default configs** (in Era
this is typically `etc/env/file_based`).
  Only one file is required: `genesis.yaml` (in the old format).

The data from these paths will be used during CTM deployment.

---

#### 3. Register the CTM

Once deployed, register the CTM within the ecosystem:

```bash
zkstack ecosystem register-ctm --zksync-os
```

> ⚠️ **Important:**
> `register-ctm` is an **ecosystem-level** subcommand — it must be
called from within the ecosystem context.

After registration, any chain can be created using this CTM.

---

#### 4. Create a new chain using the selected CTM

```bash
zkstack chain create --zksync-os
```

From this point on, all subsequent commands and scripts will use
**zkSync OS contracts** by default.

Then initialize the chain:

```bash
zkstack chain init
```

This finalizes the chain initialization.

---

#### 5. Development mode

If you use the `--dev` flag during ecosystem initialization:

```bash
zkstack ecosystem init --dev
```

All available CTMs and chains will be automatically initialized.

---

#### 6. Optional shortcut

Immediately after creating the ecosystem, you can predefine CTM
contracts:

```bash
zkstack ctm set-ctm-contracts --zksync-os
```

This sets the contracts path for the CTM so you don’t need to specify
`--contracts-src-path` later during CTM initialization.

---

## Why ❔

This change enables ecosystems to:

* Manage **multiple CTM contract versions** (e.g., Era and zkSync OS)
side-by-side.
* Flexibly choose which CTM to use when deploying new chains.
* Simplify migration testing and allow **parallel evolution** of
contract versions.
* Support **gradual transition** to zkSync OS while maintaining Era
compatibility.

It also decouples contract source management from code releases, letting
developers point to any desired version manually.

---

## Is this a breaking change?

* [ ] Yes
* [x] No

---

## Operational changes

* New commands added:

  * `zkstack ctm init-new-ctm`
  * `zkstack ecosystem register-ctm`
  * `zkstack ctm set-ctm-contracts`
* `ecosystem init --dev` now initializes all allowed CTMs and chains
automatically.
* Ecosystem can now host multiple CTMs (e.g., Era and zkSync OS).
* Paths to contract sources and default configs must be managed manually
when deploying additional CTMs.

---

## Checklist

* [ ] PR title accurately reflects the body and purpose of the change.
* [ ] Tests have been added or updated.
* [ ] Documentation comments have been added or updated.
* [ ] Code formatted with `zkstack dev fmt` and linted with `zkstack dev
lint`.

---------

Signed-off-by: Danil <[email protected]>

Author: Deniallugo

.github/workflows/ci-prover-e2e.yml

@@ -47,10 +47,9 @@ jobs:
             --base-token-price-denominator 1 \
             --set-as-default true \
             --ignore-prerequisites \
-            --evm-emulator false \
-            --update-submodules=true
+            --evm-emulator false 
 
-          ci_run zkstack ecosystem init --dev --update-submodules=true --verbose
+          ci_run zkstack ecosystem init --dev  --verbose
 
           ci_run zkstack prover init --dev --verbose
           WEB3_HTTP_URL=$(yq -e '.api.web3_json_rpc.http_url' < ./chains/proving_chain/configs/general.yaml)

core/tests/highlevel-test-tools/src/create-chain.ts

@@ -179,8 +179,6 @@ export async function createChainAndStartServer(chainType: ChainType, testSuiteN
                 [
                     'chain',
                     'create',
-                    '--update-submodules',
-                    'false',
                     '--chain-name',
                     chainConfig.chainName,
                     '--chain-id',
@@ -228,8 +226,6 @@ export async function createChainAndStartServer(chainType: ChainType, testSuiteN
                     chainConfig.chainName,
                     '--validium-type',
                     'no-da',
-                    '--update-submodules',
-                    'false',
                     '--verbose'
                 ],
                 chainConfig.chainName,

docs/src/guides/launch.md

@@ -71,7 +71,7 @@ To completely reset the dev environment:
     --base-token-price-denominator 1 \
     --set-as-default false \
     --evm-emulator false \
-    --ignore-prerequisites --update-submodules false
+    --ignore-prerequisites
   ```
 
 - Initialise `gateway` chain:

infrastructure/scripts/interop.sh

@@ -32,7 +32,7 @@ zkstack chain create \
         --base-token-price-denominator 1 \
         --set-as-default false \
         --evm-emulator false \
-        --ignore-prerequisites --update-submodules false 
+        --ignore-prerequisites
 
 zkstack chain init \
             --deploy-paymaster \
@@ -53,7 +53,7 @@ zkstack chain create \
         --base-token-price-denominator 1 \
         --set-as-default false \
         --evm-emulator false \
-        --ignore-prerequisites --update-submodules false 
+        --ignore-prerequisites
 
 zkstack chain init \
             --deploy-paymaster \

zkstack_cli/crates/common/src/contracts.rs

@@ -1,6 +1,8 @@
 use std::path::Path;
 
 use xshell::{cmd, Shell};
+use zksync_system_constants::L2_NATIVE_TOKEN_VAULT_ADDRESS;
+use zksync_types::{ethabi::encode, web3::keccak256, Address, H256, U256};
 
 use crate::cmd::Cmd;
 
@@ -27,3 +29,33 @@ pub fn build_system_contracts(shell: Shell, link_to_contracts: &Path) -> anyhow:
     let _dir_guard = shell.push_dir(link_to_contracts.join("system-contracts"));
     Ok(Cmd::new(cmd!(shell, "yarn build:foundry")).run()?)
 }
+
+pub fn install_yarn_dependencies(shell: &Shell, link_to_code: &Path) -> anyhow::Result<()> {
+    let _dir_guard = shell.push_dir(link_to_code);
+    Ok(Cmd::new(cmd!(shell, "yarn install")).run()?)
+}
+
+pub fn build_da_contracts(shell: &Shell, link_to_contracts: &Path) -> anyhow::Result<()> {
+    let _dir_guard = shell.push_dir(link_to_contracts);
+    Ok(Cmd::new(cmd!(shell, "yarn da build:foundry")).run()?)
+}
+
+pub fn rebuild_all_contracts(shell: &Shell, link_to_contracts: &Path) -> anyhow::Result<()> {
+    install_yarn_dependencies(shell, link_to_contracts)?;
+    build_l1_contracts(shell.clone(), link_to_contracts)?;
+    build_l1_da_contracts(shell.clone(), link_to_contracts)?;
+    build_l2_contracts(shell.clone(), link_to_contracts)?;
+    build_system_contracts(shell.clone(), link_to_contracts)?;
+    build_da_contracts(shell, link_to_contracts)?;
+    Ok(())
+}
+
+pub fn encode_ntv_asset_id(l1_chain_id: U256, addr: Address) -> H256 {
+    let encoded_data = encode(&[
+        ethers::abi::Token::Uint(l1_chain_id),
+        ethers::abi::Token::Address(L2_NATIVE_TOKEN_VAULT_ADDRESS),
+        ethers::abi::Token::Address(addr),
+    ]);
+
+    H256(keccak256(&encoded_data))
+}

zkstack_cli/crates/config/src/chain.rs

@@ -7,7 +7,9 @@ use anyhow::Context;
 use serde::{Deserialize, Serialize, Serializer};
 use xshell::Shell;
 use zkstack_cli_common::files::find_file;
-use zkstack_cli_types::{BaseToken, L1BatchCommitmentMode, L1Network, ProverMode, WalletCreation};
+use zkstack_cli_types::{
+    BaseToken, L1BatchCommitmentMode, L1Network, ProverMode, VMOption, WalletCreation,
+};
 use zksync_basic_types::L2ChainId;
 
 use crate::{
@@ -51,7 +53,9 @@ pub struct ChainConfigInternal {
     #[serde(default)] // for backward compatibility
     pub tight_ports: bool,
     #[serde(default)] // for backward compatibility
-    pub zksync_os: bool,
+    pub vm_option: VMOption,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub contracts_source_path: Option<PathBuf>,
 }
 
 /// Chain configuration file. This file is created in the chain
@@ -73,10 +77,11 @@ pub struct ChainConfig {
     pub legacy_bridge: Option<bool>,
     pub evm_emulator: bool,
     pub tight_ports: bool,
-    pub zksync_os: bool,
+    pub vm_option: VMOption,
     shell: OnceCell<Shell>,
     self_path: PathBuf,
     link_to_code: PathBuf,
+    contracts_source_path: Option<PathBuf>,
 }
 
 #[derive(Debug, Clone)]
@@ -116,7 +121,8 @@ impl ChainConfig {
         legacy_bridge: Option<bool>,
         evm_emulator: bool,
         tight_ports: bool,
-        zksync_os: bool,
+        vm_option: VMOption,
+        contracts_source_path: Option<PathBuf>,
     ) -> Self {
         Self {
             id,
@@ -137,7 +143,8 @@ impl ChainConfig {
             legacy_bridge,
             evm_emulator,
             tight_ports,
-            zksync_os,
+            vm_option,
+            contracts_source_path,
         }
     }
 
@@ -239,7 +246,8 @@ impl ChainConfig {
             legacy_bridge: self.legacy_bridge,
             evm_emulator: self.evm_emulator,
             tight_ports: self.tight_ports,
-            zksync_os: self.zksync_os,
+            vm_option: self.vm_option,
+            contracts_source_path: self.contracts_source_path.clone(),
         }
     }
     pub(crate) fn from_internal(
@@ -273,7 +281,8 @@ impl ChainConfig {
             tight_ports: chain_internal.tight_ports,
             self_path: shell.current_dir(),
             shell: shell.into(),
-            zksync_os: chain_internal.zksync_os,
+            vm_option: chain_internal.vm_option,
+            contracts_source_path: chain_internal.contracts_source_path.clone(),
         })
     }
 }
@@ -316,7 +325,11 @@ impl ZkStackConfigTrait for ChainConfig {
     }
 
     fn contracts_path(&self) -> PathBuf {
-        self.link_to_code().join(CONTRACTS_PATH)
+        if let Some(contracts_path) = &self.contracts_source_path {
+            contracts_path.clone()
+        } else {
+            self.link_to_code().join(CONTRACTS_PATH)
+        }
     }
 
     fn path_to_foundry_scripts(&self) -> PathBuf {