From 714501a1b2e94f1e25d69b7d8c87d606101bff18 Mon Sep 17 00:00:00 2001 From: Manuel Mauro Date: Mon, 21 Oct 2024 12:16:41 +0200 Subject: [PATCH 01/68] docs: recommend foundry-zksync installation --- docs/guides/setup-dev.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/guides/setup-dev.md b/docs/guides/setup-dev.md index 4eef211cd3d1..f3496c9a090e 100644 --- a/docs/guides/setup-dev.md +++ b/docs/guides/setup-dev.md @@ -45,9 +45,9 @@ cargo install cargo-nextest # SQL tools cargo install sqlx-cli --version 0.8.1 -# Foundry -curl -L https://foundry.paradigm.xyz | bash -foundryup --branch master +# Foundry ZKsync +curl -L https://raw.githubusercontent.com/matter-labs/foundry-zksync/main/install-foundry-zksync | bash +foundryup-zksync --branch master # Non CUDA (GPU) setup, can be skipped if the machine has a CUDA installed for provers # Don't do that if you intend to run provers on your machine. Check the prover docs for a setup instead. @@ -236,10 +236,10 @@ enable nix-ld. Go to the zksync folder and run `nix develop`. After it finishes, you are in a shell that has all the dependencies. -## Foundry +## Foundry ZKsync -[Foundry](https://book.getfoundry.sh/getting-started/installation) can be utilized for deploying smart contracts. For -commands related to deployment, you can pass flags for Foundry integration. +[Foundry ZKsync](https://foundry-book.zksync.io/getting-started/installation) can be utilized for deploying smart +contracts. For commands related to deployment, you can pass flags for Foundry integration. ## Non-GPU setup From bb5844190ee13c2191a2d60f7a32ca9718e73d41 Mon Sep 17 00:00:00 2001 From: Manuel Mauro Date: Mon, 21 Oct 2024 12:17:11 +0200 Subject: [PATCH 02/68] docs: remove mention to ZKSYNC_HOME --- docs/guides/setup-dev.md | 11 ----------- 1 file changed, 11 deletions(-) diff --git a/docs/guides/setup-dev.md b/docs/guides/setup-dev.md index f3496c9a090e..156572bf7efb 100644 --- a/docs/guides/setup-dev.md +++ b/docs/guides/setup-dev.md @@ -266,17 +266,6 @@ RUSTFLAGS as env var, or pass it in `config.toml` (either project level or globa rustflags = ["--cfg=no_cuda"] ``` -## Environment - -Edit the lines below and add them to your shell profile file (e.g. `~/.bash_profile`, `~/.zshrc`): - -```bash -# Add path here: -export ZKSYNC_HOME=/path/to/zksync - -export PATH=$ZKSYNC_HOME/bin:$PATH -``` - ## Tips ### Tip: `mold` From b57a31cf73a4fd5535c063c03b4a172eb7ca334c Mon Sep 17 00:00:00 2001 From: Manuel Mauro Date: Mon, 21 Oct 2024 12:23:36 +0200 Subject: [PATCH 03/68] docs: update mention to foundry-zksync --- docs/guides/advanced/05_how_call_works.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/advanced/05_how_call_works.md b/docs/guides/advanced/05_how_call_works.md index 5b9458ddce8e..0126c5349e90 100644 --- a/docs/guides/advanced/05_how_call_works.md +++ b/docs/guides/advanced/05_how_call_works.md @@ -12,7 +12,7 @@ Since the 'call' method is only for reading data, all the calculations will happ ### Calling the 'call' method If you need to make calls quickly, you can use the 'cast' binary from the -[foundry](https://github.com/foundry-rs/foundry) suite: +[Foundry ZKsync](https://foundry-book.zksync.io/getting-started/installation) suite: ```shell= cast call 0x23DF7589897C2C9cBa1C3282be2ee6a938138f10 "myfunction()()" --rpc-url http://localhost:3050 From 4c6026f465e252029d6122e204d8af108f92df21 Mon Sep 17 00:00:00 2001 From: Manuel Mauro Date: Mon, 21 Oct 2024 13:37:33 +0200 Subject: [PATCH 04/68] docs: update development guide --- docs/guides/development.md | 146 ++++++++++++------------------------- 1 file changed, 48 insertions(+), 98 deletions(-) diff --git a/docs/guides/development.md b/docs/guides/development.md index c859017848b5..d16a1c7103d2 100644 --- a/docs/guides/development.md +++ b/docs/guides/development.md @@ -1,82 +1,61 @@ # Development guide -This document covers development-related actions in ZKsync. +This document outlines the steps for setting up and working with ZKsync. ## Initializing the project -To setup the main toolkit, `zk`, simply run: +To set up the local toolkit, begin by installing `zkstackup`. From the project's root directory, run the following +commands: -``` -zk +```bash +cd ./zkstack_cli/zkstackup +./install --local ``` -You may also configure autocompletion for your shell via: - -``` -zk completion install -``` +This installs `zkstackup` in your user binaries directory (e.g., `$HOME/.local/bin/`) and adds it to your `PATH`. -Once all the dependencies were installed, project can be initialized: +After installation, open a new terminal or reload your shell profile. From the project's root directory, you can now +run: -``` -zk init +```bash +zkstackup --local ``` -This command will do the following: +This command installs `zkstack` from the current source directory. -- Generate `$ZKSYNC_HOME/etc/env/target/dev.env` file with settings for the applications. -- Initialize docker containers with `reth` Ethereum node for local development. -- Download and unpack files for cryptographical backend. -- Generate required smart contracts. -- Compile all the smart contracts. -- Deploy smart contracts to the local Ethereum network. -- Create “genesis block” for server. +The root directory includes configuration files for an ecosystem with a single chain, `era`. To initialize the +ecosystem, first start the required containers: -Initializing may take pretty long, but many steps (such as downloading & unpacking keys and initializing containers) are -required to be done only once. - -Usually, it is a good idea to do `zk init` once after each merge to the `main` branch (as application setup may change). +```bash +zkstack containers +``` -Additionally, there is a subcommand `zk clean` to remove previously generated data. Examples: +Next, run: -``` -zk clean --all # Remove generated configs, database and backups. -zk clean --config # Remove configs only. -zk clean --database # Remove database. -zk clean --backups # Remove backups. -zk clean --database --backups # Remove database *and* backups, but not configs. +```bash +zkstack ecosystem init ``` -**When do you need it?** +These commands will guide you through the configuration options for setting up the ecosystem. -1. If you have an initialized database and want to run `zk init`, you have to remove the database first. -2. If after getting new functionality from the `main` branch your code stopped working and `zk init` doesn't help, you - may try removing `$ZKSYNC_HOME/etc/env/target/dev.env` and running `zk init` once again. This may help if the - application configuration has changed. +Initialization may take some time, but key steps (such as downloading and unpacking keys or setting up containers) only +need to be completed once. -If you don’t need all of the `zk init` functionality, but just need to start/stop containers, use the following -commands: +## Cleanup -``` -zk up # Set up `reth` and `postgres` containers -zk down # Shut down `reth` and `postgres` containers -``` +To clean up the local ecosystem (e.g., removing containers and clearing the contract cache), run: -## Reinitializing +```bash +zkstack dev clean all +``` -When actively changing something that affects infrastructure (for example, contracts code), you normally don't need the -whole `init` functionality, as it contains many external steps (e.g. deploying ERC20 tokens) which don't have to be -redone. +## Re-initialization -For this case, there is an additional command: +You can reinitialize the ecosystem afterward by running: +```bash +zkstack ecosystem init ``` -zk reinit -``` - -This command does the minimal subset of `zk init` actions required to "reinitialize" the network. It assumes that -`zk init` was called in the current environment before. If `zk reinit` doesn't work for you, you may want to run -`zk init` instead. ## Committing changes @@ -85,64 +64,35 @@ the workspace initialization process. These hooks will not allow to commit the c Currently the following criteria are checked: -- Rust code should always be formatted via `cargo fmt`. -- Other code should always be formatted via `zk fmt`. -- Dummy Prover should not be staged for commit (see below for the explanation). - -## Using Dummy Prover - -By default, the chosen prover is a "dummy" one, meaning that it doesn't actually compute proofs but rather uses mocks to -avoid expensive computations in the development environment. - -To switch dummy prover to real prover, one must change `dummy_verifier` to `false` in `contracts.toml` for your env -(most likely, `etc/env/base/contracts.toml`) and run `zk init` to redeploy smart contracts. +- Code must be formatted via `zkstack dev fmt`. +- Code must be linted via `zkstack dev lint`. ## Testing -- Running the `rust` unit-tests: - - ``` - zk test rust - ``` - -- Running a specific `rust` unit-test: - - ``` - zk test rust --package --lib ::tests:: - # e.g. zk test rust --package zksync_core --lib eth_sender::tests::resend_each_block - ``` - -- Running the integration test: - - ``` - zk server # Has to be run in the 1st terminal - zk test i server # Has to be run in the 2nd terminal - ``` +You can run tests using `zkstack dev test` subcommand. Just run: -- Running the benchmarks: - - ``` - zk f cargo bench - ``` - -- Running the loadtest: +```bash +zkstack dev test --help` +``` - ``` - zk server # Has to be run in the 1st terminal - zk prover # Has to be run in the 2nd terminal if you want to use real prover, otherwise it's not required. - zk run loadtest # Has to be run in the 3rd terminal - ``` +to see all the options. ## Contracts -### Re-build contracts +### Build contracts +Run: + +```bash +zkstack dev contracts --help ``` -zk contract build -``` + +to see all the options. ### Publish source code on etherscan +TODO: check the new way to do this + ``` zk contract publish ``` From 002e4bd4be5414098f823f41fb08559beae0cfe4 Mon Sep 17 00:00:00 2001 From: Manuel Mauro Date: Mon, 21 Oct 2024 13:39:37 +0200 Subject: [PATCH 05/68] docs: add convenience note --- docs/guides/development.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/guides/development.md b/docs/guides/development.md index d16a1c7103d2..18c4e98d80d4 100644 --- a/docs/guides/development.md +++ b/docs/guides/development.md @@ -21,6 +21,11 @@ run: zkstackup --local ``` +> NOTE: you might find convenient to add this alias to your shell profile: +> +> `alias zkstackup='zkstackup --path $ZKSYNC_HOME'` +> + This command installs `zkstack` from the current source directory. The root directory includes configuration files for an ecosystem with a single chain, `era`. To initialize the From 0070e8873f11afbfe424ea608fa6e8aee11c14ee Mon Sep 17 00:00:00 2001 From: Manuel Mauro Date: Mon, 21 Oct 2024 13:40:26 +0200 Subject: [PATCH 06/68] style: format code --- docs/guides/development.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/guides/development.md b/docs/guides/development.md index 18c4e98d80d4..0168efade7df 100644 --- a/docs/guides/development.md +++ b/docs/guides/development.md @@ -22,9 +22,8 @@ zkstackup --local ``` > NOTE: you might find convenient to add this alias to your shell profile: -> -> `alias zkstackup='zkstackup --path $ZKSYNC_HOME'` > +> `alias zkstackup='zkstackup --path $ZKSYNC_HOME'` This command installs `zkstack` from the current source directory. From 5e116a8b7836f91a8bf70de83a333ce2bf42947f Mon Sep 17 00:00:00 2001 From: Manuel Mauro Date: Mon, 21 Oct 2024 17:46:31 +0200 Subject: [PATCH 07/68] docs: add re-installation note --- docs/guides/development.md | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/docs/guides/development.md b/docs/guides/development.md index 0168efade7df..58d53b52388a 100644 --- a/docs/guides/development.md +++ b/docs/guides/development.md @@ -2,7 +2,7 @@ This document outlines the steps for setting up and working with ZKsync. -## Initializing the project +## Installing the local ZK Stack CLI To set up the local toolkit, begin by installing `zkstackup`. From the project's root directory, run the following commands: @@ -25,7 +25,16 @@ zkstackup --local > > `alias zkstackup='zkstackup --path $ZKSYNC_HOME'` -This command installs `zkstack` from the current source directory. +This command installs `zkstack` from the current source directory. + +> Whenever you want to update you local installation +> with your changes, just rerun: +> +> ```bash +> zkstackup --local +> ``` + +## Configure Ecosystem The root directory includes configuration files for an ecosystem with a single chain, `era`. To initialize the ecosystem, first start the required containers: From 528a3442ac4f689d3d30d986af64eb7666dd11ac Mon Sep 17 00:00:00 2001 From: Manuel Mauro Date: Mon, 21 Oct 2024 17:46:50 +0200 Subject: [PATCH 08/68] style: format code --- docs/guides/development.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/guides/development.md b/docs/guides/development.md index 58d53b52388a..d60257e9d95e 100644 --- a/docs/guides/development.md +++ b/docs/guides/development.md @@ -25,11 +25,10 @@ zkstackup --local > > `alias zkstackup='zkstackup --path $ZKSYNC_HOME'` -This command installs `zkstack` from the current source directory. +This command installs `zkstack` from the current source directory. -> Whenever you want to update you local installation -> with your changes, just rerun: -> +> Whenever you want to update you local installation with your changes, just rerun: +> > ```bash > zkstackup --local > ``` From 7296abb4fcc09c168dd118e06a9c7b4f24c55475 Mon Sep 17 00:00:00 2001 From: Manuel Mauro Date: Mon, 21 Oct 2024 17:49:34 +0200 Subject: [PATCH 09/68] docs: improve readability --- docs/guides/development.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/guides/development.md b/docs/guides/development.md index d60257e9d95e..72dbfdf9cb9d 100644 --- a/docs/guides/development.md +++ b/docs/guides/development.md @@ -21,17 +21,17 @@ run: zkstackup --local ``` -> NOTE: you might find convenient to add this alias to your shell profile: -> -> `alias zkstackup='zkstackup --path $ZKSYNC_HOME'` - This command installs `zkstack` from the current source directory. -> Whenever you want to update you local installation with your changes, just rerun: +> NOTE: Whenever you want to update you local installation with your changes, just rerun: > > ```bash > zkstackup --local > ``` +> +> You might find convenient to add this alias to your shell profile: +> +> `alias zkstackup='zkstackup --path $ZKSYNC_HOME'` ## Configure Ecosystem From d488e1ee3ec077239f17addb2158f772a88d680d Mon Sep 17 00:00:00 2001 From: Manuel Mauro Date: Mon, 21 Oct 2024 18:46:40 +0200 Subject: [PATCH 10/68] docs: update launch.md to use zkstack commands --- docs/guides/launch.md | 287 ++++++------------------------------------ 1 file changed, 41 insertions(+), 246 deletions(-) diff --git a/docs/guides/launch.md b/docs/guides/launch.md index 10c0b10f5d84..1feaecb2ab76 100644 --- a/docs/guides/launch.md +++ b/docs/guides/launch.md @@ -10,43 +10,43 @@ Prepare dev environment prerequisites: see ## Setup local dev environment -Setup: +Run the required containers with: +```bash +zkstack containers ``` -zk # installs and builds zk itself -zk init -``` -If you face any other problems with the `zk init` command, go to the -[Troubleshooting](https://github.com/matter-labs/zksync-era/blob/main/docs/guides/launch.md#troubleshooting) section at -the end of this file. There are solutions for some common error cases. +Setup: + +```bash +zkstack ecosystem init +``` To completely reset the dev environment: - Stop services: - ``` - zk down + ```bash + zkstack dev clean all ``` - Repeat the setup procedure above -If `zk init` has already been executed, and now you only need to start docker containers (e.g. after reboot), simply -launch: - -``` -zk up -``` + ```bash + zkstack ecosystem init + ``` ### Run observability stack If you want to run [Dockprom](https://github.com/stefanprodan/dockprom/) stack (Prometheus, Grafana) alongside other containers - add `--run-observability` parameter during initialisation. -``` -zk init --run-observability +```bash +zkstack containers --observability ``` +or select `yes` when prompted during the interactive execution of the command. + That will also provision Grafana with [era-observability](https://github.com/matter-labs/era-observability/tree/main/dashboards) dashboards. You can then access it at `http://127.0.0.1:3000/` under credentials `admin/admin`. @@ -57,287 +57,82 @@ access it at `http://127.0.0.1:3000/` under credentials `admin/admin`. ## (Re)deploy db and contracts ``` -zk contract redeploy +zkstack dev contracts ``` -## Environment configurations - -Env config files are held in `etc/env/target/` - -List configurations: - -``` -zk env -``` +## Ecosystem Configuration -Switch between configurations: +Ecosystem configuration can be found in: -``` -zk env -``` +- `/ZkStack.yaml` +- `/configs` folder +- `/chains` folder -Default configuration is `dev.env`, which is generated automatically from `dev.env.example` during `zk init` command -execution. +These files are created at ecosystem initialization `zkstack ecosystem init` and at chain initialization `zkstack chain init`. ## Build and run server Run server: +```bash +zkstack server ``` -zk server -``` - -Server is configured using env files in `./etc/env` directory. After the first initialization, file -`./etc/env/target/dev.env`will be created. By default, this file is copied from the `./etc/env/target/dev.env.example` -template. - -Make sure you have environment variables set right, you can check it by running: `zk env`. You should see `* dev` in -output. ## Running server using Google cloud storage object store instead of default In memory store +TODO: check the new way to do this + Get the service_account.json file containing the GCP credentials from kubernetes secret for relevant environment(stage2/ testnet2) add that file to the default location ~/gcloud/service_account.json or update object_store.toml with the file location -``` -zk server +```bash +zkstack server ``` ## Running prover server Running on machine without GPU -```shell -zk f cargo +nightly run --release --bin zksync_prover +```bash +zkstack prover run ``` +TODO: check the new way to do this + Running on machine with GPU -```shell +```bash zk f cargo +nightly run --features gpu --release --bin zksync_prover ``` ## Running the verification key generator -```shell +```bash # ensure that the setup_2^26.key in the current directory, the file can be download from https://storage.googleapis.com/matterlabs-setup-keys-us/setup-keys/setup_2\^26.key # To generate all verification keys cargo run --release --bin zksync_verification_key_generator - - ``` ## Generating binary verification keys for existing json verification keys -```shell +```bash cargo run --release --bin zksync_json_to_binary_vk_converter -- -o /path/to/output-binary-vk ``` ## Generating commitment for existing verification keys -```shell +```bash cargo run --release --bin zksync_commitment_generator ``` ## Running the contract verifier -```shell -# To process fixed number of jobs -cargo run --release --bin zksync_contract_verifier -- --jobs-number X - -# To run until manual exit -zk contract_verifier +```bash +zkstack contract-verifier run ``` ## Troubleshooting -### SSL error: certificate verify failed - -**Problem**. `zk init` fails with the following error: - -``` -Initializing download: https://storage.googleapis.com/matterlabs-setup-keys-us/setup-keys/setup_2%5E20.key -SSL error: certificate verify failed -``` - -**Solution**. Make sure that the version of `axel` on your computer is `2.17.10` or higher. - -### rmSync is not a function - -**Problem**. `zk init` fails with the following error: - -``` -fs_1.default.rmSync is not a function -``` - -**Solution**. Make sure that the version of `node.js` installed on your computer is `14.14.0` or higher. - -### Invalid bytecode: () - -**Problem**. `zk init` fails with an error similar to: - -``` -Running `target/release/zksync_server --genesis` -2023-04-05T14:23:40.291277Z INFO zksync_core::genesis: running regenesis -thread 'main' panicked at 'Invalid bytecode: ()', core/lib/utils/src/bytecode.rs:159:10 -stack backtrace: - 0: 0x104551410 - std::backtrace_rs::backtrace::libunwind::trace::hf9c5171f212b04e2 - at /rustc/d5a82bbd26e1ad8b7401f6a718a9c57c96905483/library/std/src/../../backtrace/src/backtrace/libunwind.rs:93:5 - 1: 0x104551410 - std::backtrace_rs::backtrace::trace_unsynchronized::h179003f6ec753118 - at /rustc/d5a82bbd26e1ad8b7401f6a718a9c57c96905483/library/std/src/../../backtrace/src/backtrace/mod.rs:66:5 - 2: 0x104551410 - std::sys_common::backtrace::_print_fmt::h92d38f701cf42b17 - at /rustc/d5a82bbd26e1ad8b7401f6a718a9c57c96905483/library/std/src/sys_common/backtrace.rs:65:5 - 3: 0x104551410 - ::fmt::hb33e6e8152f78c95 - at /rustc/d5a82bbd26e1ad8b7401f6a718a9c57c96905483/library/std/src/sys_common/backtrace.rs:44:22 - 4: 0x10456cdb0 - core::fmt::write::hd33da007f7a27e39 - at /rustc/d5a82bbd26e1ad8b7401f6a718a9c57c96905483/library/core/src/fmt/mod.rs:1208:17 - 5: 0x10454b41c - std::io::Write::write_fmt::h7edc10723862001e - at /rustc/d5a82bbd26e1ad8b7401f6a718a9c57c96905483/library/std/src/io/mod.rs:1682:15 - 6: 0x104551224 - std::sys_common::backtrace::_print::h5e00f05f436af01f - at /rustc/d5a82bbd26e1ad8b7401f6a718a9c57c96905483/library/std/src/sys_common/backtrace.rs:47:5 - 7: 0x104551224 - std::sys_common::backtrace::print::h895ee35b3f17b334 - at /rustc/d5a82bbd26e1ad8b7401f6a718a9c57c96905483/library/std/src/sys_common/backtrace.rs:34:9 - 8: 0x104552d84 - std::panicking::default_hook::{{closure}}::h3b7ee083edc2ea3e - at /rustc/d5a82bbd26e1ad8b7401f6a718a9c57c96905483/library/std/src/panicking.rs:267:22 - 9: 0x104552adc - std::panicking::default_hook::h4e7c2c28eba716f5 - at /rustc/d5a82bbd26e1ad8b7401f6a718a9c57c96905483/library/std/src/panicking.rs:286:9 - 10: 0x1045533a8 - std::panicking::rust_panic_with_hook::h1672176227032c45 - at /rustc/d5a82bbd26e1ad8b7401f6a718a9c57c96905483/library/std/src/panicking.rs:688:13 - 11: 0x1045531c8 - std::panicking::begin_panic_handler::{{closure}}::h0b2d072f9624d32e - at /rustc/d5a82bbd26e1ad8b7401f6a718a9c57c96905483/library/std/src/panicking.rs:579:13 - 12: 0x104551878 - std::sys_common::backtrace::__rust_end_short_backtrace::he9abda779115b93c - at /rustc/d5a82bbd26e1ad8b7401f6a718a9c57c96905483/library/std/src/sys_common/backtrace.rs:137:18 - 13: 0x104552f24 - rust_begin_unwind - at /rustc/d5a82bbd26e1ad8b7401f6a718a9c57c96905483/library/std/src/panicking.rs:575:5 - 14: 0x1045f89c0 - core::panicking::panic_fmt::h23ae44661fec0889 - at /rustc/d5a82bbd26e1ad8b7401f6a718a9c57c96905483/library/core/src/panicking.rs:64:14 - 15: 0x1045f8ce0 - core::result::unwrap_failed::h414a6cbb12b1e143 - at /rustc/d5a82bbd26e1ad8b7401f6a718a9c57c96905483/library/core/src/result.rs:1791:5 - 16: 0x103f79a30 - zksync_utils::bytecode::hash_bytecode::h397dd7c5b6202bf4 - 17: 0x103e47e78 - zksync_contracts::BaseSystemContracts::load_from_disk::h0e2da8f63292ac46 - 18: 0x102d885a0 - zksync_core::genesis::ensure_genesis_state::{{closure}}::h5143873f2c337e11 - 19: 0x102d7dee0 - zksync_core::genesis_init::{{closure}}::h4e94f3d4ad984788 - 20: 0x102d9c048 - zksync_server::main::{{closure}}::h3fe943a3627d31e1 - 21: 0x102d966f8 - tokio::runtime::park::CachedParkThread::block_on::h2f2fdf7edaf08470 - 22: 0x102df0dd4 - tokio::runtime::runtime::Runtime::block_on::h1fd1d83272a23194 - 23: 0x102e21470 - zksync_server::main::h500621fd4d160768 - 24: 0x102d328f0 - std::sys_common::backtrace::__rust_begin_short_backtrace::h52973e519e2e8a0d - 25: 0x102e08ea8 - std::rt::lang_start::{{closure}}::hbd395afe0ab3b799 - 26: 0x10454508c - core::ops::function::impls:: for &F>::call_once::ha1c2447b9b665e13 - at /rustc/d5a82bbd26e1ad8b7401f6a718a9c57c96905483/library/core/src/ops/function.rs:606:13 - 27: 0x10454508c - std::panicking::try::do_call::ha57d6d1e9532dc1f - at /rustc/d5a82bbd26e1ad8b7401f6a718a9c57c96905483/library/std/src/panicking.rs:483:40 - 28: 0x10454508c - std::panicking::try::hca0526f287961ecd - at /rustc/d5a82bbd26e1ad8b7401f6a718a9c57c96905483/library/std/src/panicking.rs:447:19 - 29: 0x10454508c - std::panic::catch_unwind::hdcaa7fa896e0496a - at /rustc/d5a82bbd26e1ad8b7401f6a718a9c57c96905483/library/std/src/panic.rs:137:14 - 30: 0x10454508c - std::rt::lang_start_internal::{{closure}}::h142ec071d3766871 - at /rustc/d5a82bbd26e1ad8b7401f6a718a9c57c96905483/library/std/src/rt.rs:148:48 - 31: 0x10454508c - std::panicking::try::do_call::h95f5e55d6f048978 - at /rustc/d5a82bbd26e1ad8b7401f6a718a9c57c96905483/library/std/src/panicking.rs:483:40 - 32: 0x10454508c - std::panicking::try::h0fa00e2f7b4a5c64 - at /rustc/d5a82bbd26e1ad8b7401f6a718a9c57c96905483/library/std/src/panicking.rs:447:19 - 33: 0x10454508c - std::panic::catch_unwind::h1765f149814d4d3e - at /rustc/d5a82bbd26e1ad8b7401f6a718a9c57c96905483/library/std/src/panic.rs:137:14 - 34: 0x10454508c - std::rt::lang_start_internal::h00a235e820a7f01c - at /rustc/d5a82bbd26e1ad8b7401f6a718a9c57c96905483/library/std/src/rt.rs:148:20 - 35: 0x102e21578 - _main -Error: Genesis is not needed (either Postgres DB or tree's Rocks DB is not empty) -``` - -**Description**. This means that your bytecode config file has an empty entry: `"bytecode": "0x"`. This happens because -your `zksync-2-dev/etc/system-contracts/package.json`'s dependency on `"@matterlabs/hardhat-zksync-solc"` is outdated. -We don't expect this error to happen as we've updated to latest version which fixes the problem. - -**Solution**. Update your dependency and reinit: - -``` -yarn add -D @matterlabs/hardhat-zksync-solc # in the system-contracts folder -zk clean --all && zk init -``` - -On the run, it moved from: - -``` - "@matterlabs/hardhat-zksync-solc": "^0.3.14-beta.3", -``` - -to: - -``` - "@matterlabs/hardhat-zksync-solc": "^0.3.15", -``` - -### Error: Bytecode length in 32-byte words must be odd - -**Problem**. `zk init` fails with an error similar to: - -``` -Successfully generated Typechain artifacts! -Error: Error: Bytecode length in 32-byte words must be odd - at hashL2Bytecode (/Users/emilluta/code/zksync-2-dev/contracts/zksync/src/utils.ts:29:15) - at computeL2Create2Address (/Users/emilluta/code/zksync-2-dev/contracts/zksync/src/utils.ts:53:26) - at /Users/emilluta/code/zksync-2-dev/contracts/zksync/src/compileAndDeployLibs.ts:50:63 - at step (/Users/emilluta/code/zksync-2-dev/contracts/zksync/src/compileAndDeployLibs.ts:33:23) - at Object.next (/Users/emilluta/code/zksync-2-dev/contracts/zksync/src/compileAndDeployLibs.ts:14:53) - at fulfilled (/Users/emilluta/code/zksync-2-dev/contracts/zksync/src/compileAndDeployLibs.ts:5:58) -error Command failed with exit code 1. -info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command. -error Command failed. -Exit code: 1 -Command: /Users/emilluta/.nvm/versions/node/v16.19.1/bin/node -Arguments: /opt/homebrew/Cellar/yarn/1.22.19/libexec/lib/cli.js compile-and-deploy-libs -Directory: /Users/emilluta/code/zksync-2-dev/contracts/zksync -Output: - -info Visit https://yarnpkg.com/en/docs/cli/workspace for documentation about this command. -error Command failed with exit code 1. -info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command. -Error: Child process exited with code 1 -``` - -**Description**. This means that your bytecode config file has an empty entry: `"bytecode": "0x"`. This happens because -your `zksync-2-dev/contracts/zksync/package.json`'s dependency on `"@matterlabs/hardhat-zksync-solc"` is outdated. We -don't expect this error to happen as we've updated to latest version which fixes the problem. - -**Solution**. Update your dependency and reinit: - -``` -yarn add -D @matterlabs/hardhat-zksync-solc # in the system-contracts folder -zk clean --all && zk init -``` - -On the run, it moved from: - -``` - "@matterlabs/hardhat-zksync-solc": "^0.3.14-beta.3", -``` - -to: - -``` - "@matterlabs/hardhat-zksync-solc": "^0.3.15", -``` - -### Error: Cannot read properties of undefined (reading 'compilerPath') - -**Problem**. `zk init` fails with an error similar to the following: - -```text -Yarn project directory: /Users//Projects/zksync-era/contracts/system-contracts -Error: Cannot read properties of undefined (reading 'compilerPath') -error Command failed with exit code 1. -``` - -**Description**. The compiler downloader -[could not verify](https://github.com/NomicFoundation/hardhat/blob/0d850d021f3ab33b59b1ea2ae70d1e659e579e40/packages/hardhat-core/src/internal/solidity/compiler/downloader.ts#L336-L383) -that the Solidity compiler it downloaded actually works. - -**Solution**. Delete the cached `*.does.not.work` file to run the check again: - -```sh -# NOTE: Compiler version, commit hash may differ. -rm $HOME/Library/Caches/hardhat-nodejs/compilers-v2/macosx-amd64/solc-macosx-amd64-v0.8.20+commit.a1b79de6.does.not.work -``` +TODO From 62f4344d3967716505e3680777be26e92a394d04 Mon Sep 17 00:00:00 2001 From: Manuel Mauro Date: Mon, 21 Oct 2024 18:47:23 +0200 Subject: [PATCH 11/68] style: format code --- docs/guides/launch.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/guides/launch.md b/docs/guides/launch.md index 1feaecb2ab76..28f2d0933b19 100644 --- a/docs/guides/launch.md +++ b/docs/guides/launch.md @@ -68,7 +68,8 @@ Ecosystem configuration can be found in: - `/configs` folder - `/chains` folder -These files are created at ecosystem initialization `zkstack ecosystem init` and at chain initialization `zkstack chain init`. +These files are created at ecosystem initialization `zkstack ecosystem init` and at chain initialization +`zkstack chain init`. ## Build and run server From c9f891b32eca847382513a40343e8c7fa0e4fe2a Mon Sep 17 00:00:00 2001 From: Manuel Mauro Date: Tue, 22 Oct 2024 10:33:49 +0200 Subject: [PATCH 12/68] docs: remove dead refs --- docs/guides/setup-dev.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/guides/setup-dev.md b/docs/guides/setup-dev.md index 156572bf7efb..4f75d9fc5ace 100644 --- a/docs/guides/setup-dev.md +++ b/docs/guides/setup-dev.md @@ -60,7 +60,7 @@ cd zksync-era git submodule update --init --recursive ``` -Don't forget to [add env variables](#Environment) and look at [tips](#tips). +Don't forget to look at [tips](#tips). ## Supported operating systems @@ -72,7 +72,7 @@ Additionally, if you are going to use WSL 2, make sure that your project is loca accessing NTFS partitions from within WSL is very slow. If you're using MacOS with an ARM processor (e.g. M1/M2), make sure that you are working in the _native_ environment -(e.g. your terminal and IDE don't run in Rosetta, and your toolchain is native). Trying to work with ZKsync code via +(e.g., your terminal and IDE don't run in Rosetta, and your toolchain is native). Trying to work with ZKsync code via Rosetta may cause problems that are hard to spot and debug, so make sure to check everything before you start. If you are a NixOS user or would like to have a reproducible environment, skip to the section about `nix`. @@ -208,7 +208,7 @@ sudo apt-get install postgresql ### Cargo nextest -[cargo-nextest](https://nexte.st/) is the next-generation test runner for Rust projects. `zk test rust` uses +[cargo-nextest](https://nexte.st/) is the next-generation test runner for Rust projects. `zkstack dev test rust` uses `cargo nextest` by default. ```bash From 1ba533bcbf20df0c44bbdec760e9337df720b584 Mon Sep 17 00:00:00 2001 From: Manuel Mauro Date: Tue, 22 Oct 2024 10:38:01 +0200 Subject: [PATCH 13/68] docs: remove mention to zk --- docs/guides/advanced/91_docker_and_ci.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/guides/advanced/91_docker_and_ci.md b/docs/guides/advanced/91_docker_and_ci.md index ff1c7843b8b1..885d3155dd6c 100644 --- a/docs/guides/advanced/91_docker_and_ci.md +++ b/docs/guides/advanced/91_docker_and_ci.md @@ -64,8 +64,8 @@ zk After this, you can run any commands you need. -When you see a command like `ci_run zk contract build` in the CI - this simply means that it executed -`zk contract build` inside that docker container. +When you see a command like `ci_run zkstack dev contracts` in the CI - this simply means that it executed +`zkstack dev contracts` inside that docker container. **IMPORTANT** - by default, docker is running in the mode, where it does NOT persist the changes. So if you exit that shell, all the changes will be removed (so when you restart, you'll end up in the same pristine condition). You can From 18d6bd8b64a027d9b1575a88dbcab1e3ba68f8b9 Mon Sep 17 00:00:00 2001 From: Manuel Mauro Date: Tue, 22 Oct 2024 11:04:27 +0200 Subject: [PATCH 14/68] docs: fix initialization chapter --- docs/guides/advanced/01_initialization.md | 62 ++++++++++------------- 1 file changed, 26 insertions(+), 36 deletions(-) diff --git a/docs/guides/advanced/01_initialization.md b/docs/guides/advanced/01_initialization.md index 79c33434d3b5..1dc00af7dee5 100644 --- a/docs/guides/advanced/01_initialization.md +++ b/docs/guides/advanced/01_initialization.md @@ -1,4 +1,4 @@ -# ZKsync deeper dive +# ZKsync Deeper Dive The goal of this doc is to show you some more details on how ZKsync works internally. @@ -7,18 +7,21 @@ system). Now let's take a look at what's inside: -### Initialization (zk init) +### Initialization -Let's take a deeper look into what `zk init` does. +Let's take a deeper look into what `zkstack ecosystem init` does. -#### zk tool +#### ZK Stack CLI -`zk` itself is implemented in typescript (you can see the code in `infrastructure` directory). If you change anything -there, make sure to run `zk` (that compiles this code), before re-running `zk init`. +`zkstack` itself is implemented in Rust (you can see the code in `/zkstack_cli` directory). If you change anything +there, make sure to run `zkstackup --local` from the root folder (that compiles and installs this code), before +re-running any `zkstack` command. -#### zk init +#### Containers -As first step, it gets the docker images for postgres and reth. +As first step, running `zkstack containers` gets the docker images for postgres and reth. If the `--observability` +option is passed to the command, or the corresponding option is selected in the interactive prompt, then Prometheus, +Grafana and other observability-related images are downloaded and run. Reth (one of the Ethereum clients) will be used to setup our own copy of L1 chain (that our local ZKsync would use). @@ -26,33 +29,20 @@ Postgres is one of the two databases, that is used by ZKsync (the other one is R stored in postgres (blocks, transactions etc) - while RocksDB is only storing the state (Tree & Map) - and it used by VM. -Then we compile JS packages (these include our web3 sdk, tools and testing infrastructure). +#### Ecosystem -Then L1 & L2 contracts. +Then, running `zkstack ecosystem init`:. -And now we're ready to start setting up the system. +- Collects and finalize the ecosystem configuration. +- Builds and deploys L1 & L2 contracts. +- Initialize each chain defined in the `/chains` folder. (Currently, a single chain `era` is defined there, but you can + create your own chains running `zkstack chain create`). +- Sets up observability. +- Runs the genesis process. +- Initializes the database. #### Postgres -First - postgres database: you'll be able to see something like - -``` -DATABASE_URL = postgres://postgres:notsecurepassword@localhost/zksync_local -``` - -After which we setup the schema (lots of lines with `Applied XX`). - -You can try connecting to postgres now, to see what's inside: - -```shell -psql postgres://postgres:notsecurepassword@localhost/zksync_local -``` - -(and then commands like `\dt` to see the tables, `\d TABLE_NAME` to see the schema, and `select * from XX` to see the -contents). - -As our network has just started, the database would be quite empty. - You can see the schema for the database in [dal/README.md](../../../core/lib/dal/README.md) TODO: add the link to the document with DB schema. @@ -83,8 +73,8 @@ If everything goes well, you should see that L1 blocks are being produced. Now we can start the main server: -```shell -zk server +```bash +zkstack server ``` This will actually run a cargo binary (`zksync_server`). @@ -96,7 +86,7 @@ Currently we don't send any transactions there (so the logs might be empty). But you should see some initial blocks in postgres: -``` +```sql select * from miniblocks; ``` @@ -107,7 +97,7 @@ Let's finish this article, by taking a look at our L1: We will use the `web3` tool to communicate with the L1, have a look at [02_deposits.md](02_deposits.md) for installation instructions. You can check that you're a (localnet) crypto trillionaire, by running: -```shell +```bash ./web3 --rpc-url http://localhost:8545 balance 0x36615Cf349d7F6344891B1e7CA7C72883F5dc049 ``` @@ -120,14 +110,14 @@ In order to communicate with L2 (our ZKsync) - we have to deploy multiple contra Ethereum). You can look on the `deployL1.log` file - to see the list of contracts that were deployed and their accounts. First thing in the file, is the deployer/governor wallet - this is the account that can change, freeze and unfreeze the -contracts (basically the owner). You can also verify (using the getBalance method above), that is has a lot of tokens. +contracts (basically the owner). You can also verify (using the getBalance method above), that has a lot of tokens. Then, there are a bunch of contracts (CRATE2_FACTOR, DIAMOND_PROXY, L1_ALLOW_LIST etc etc) - for each one, the file contains the address. You can quickly verify that they were really deployed, by calling: -```shell +```bash ./web3 --rpc-url http://localhost:8545 address XXX ``` From b37a18cc651951d11c21f1bb65c6b164df00b46a Mon Sep 17 00:00:00 2001 From: Manuel Mauro Date: Tue, 22 Oct 2024 15:04:42 +0200 Subject: [PATCH 15/68] docs: improve style --- docs/guides/launch.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/guides/launch.md b/docs/guides/launch.md index 28f2d0933b19..5f7bd8322292 100644 --- a/docs/guides/launch.md +++ b/docs/guides/launch.md @@ -83,9 +83,9 @@ zkstack server TODO: check the new way to do this -Get the service_account.json file containing the GCP credentials from kubernetes secret for relevant environment(stage2/ -testnet2) add that file to the default location ~/gcloud/service_account.json or update object_store.toml with the file -location +Get the `service_account.json` file containing the GCP credentials from kubernetes secret for relevant +environment(stage2/ testnet2) add that file to the default location `~/gcloud/service_account.json` or update +`object_store.toml` with the file location ```bash zkstack server From 4d2eae204b2cb24069908c5cb856a3ec3c6af489 Mon Sep 17 00:00:00 2001 From: Manuel Mauro Date: Wed, 23 Oct 2024 16:12:15 +0200 Subject: [PATCH 16/68] style: format code --- prover/crates/bin/prover_autoscaler/src/global/watcher.rs | 1 - 1 file changed, 1 deletion(-) diff --git a/prover/crates/bin/prover_autoscaler/src/global/watcher.rs b/prover/crates/bin/prover_autoscaler/src/global/watcher.rs index 1b54d332ebb1..6e02c0fe2fdc 100644 --- a/prover/crates/bin/prover_autoscaler/src/global/watcher.rs +++ b/prover/crates/bin/prover_autoscaler/src/global/watcher.rs @@ -6,7 +6,6 @@ use reqwest::{ header::{HeaderMap, HeaderValue, CONTENT_TYPE}, Method, }; - use tokio::sync::Mutex; use url::Url; use zksync_utils::http_with_retries::send_request_with_retries; From da2734c2177c400dff4184a572135a41900a8433 Mon Sep 17 00:00:00 2001 From: Manuel Mauro Date: Thu, 24 Oct 2024 11:25:47 +0200 Subject: [PATCH 17/68] docs: keep postgres section --- docs/guides/advanced/01_initialization.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/docs/guides/advanced/01_initialization.md b/docs/guides/advanced/01_initialization.md index 1dc00af7dee5..529ab09d62f8 100644 --- a/docs/guides/advanced/01_initialization.md +++ b/docs/guides/advanced/01_initialization.md @@ -43,6 +43,25 @@ Then, running `zkstack ecosystem init`:. #### Postgres +First - postgres database: you'll be able to see something like + +``` +DATABASE_URL = postgres://postgres:notsecurepassword@localhost/zksync_local +``` + +After which we setup the schema (lots of lines with `Applied XX`). + +You can try connecting to postgres now, to see what's inside: + +```shell +psql postgres://postgres:notsecurepassword@localhost/zksync_local +``` + +(and then commands like `\dt` to see the tables, `\d TABLE_NAME` to see the schema, and `select * from XX` to see the +contents). + +As our network has just started, the database would be quite empty. + You can see the schema for the database in [dal/README.md](../../../core/lib/dal/README.md) TODO: add the link to the document with DB schema. From f98931a9f8cf6be00f55c6ba1096e4cef0ee4bee Mon Sep 17 00:00:00 2001 From: Manuel Mauro Date: Thu, 24 Oct 2024 11:28:02 +0200 Subject: [PATCH 18/68] docs: do not mention ZKSYNC_HOME --- docs/guides/development.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/development.md b/docs/guides/development.md index 72dbfdf9cb9d..f4bb23e8933e 100644 --- a/docs/guides/development.md +++ b/docs/guides/development.md @@ -31,7 +31,7 @@ This command installs `zkstack` from the current source directory. > > You might find convenient to add this alias to your shell profile: > -> `alias zkstackup='zkstackup --path $ZKSYNC_HOME'` +> `alias zkstackup='zkstackup --path /path/to/zksync-era'` ## Configure Ecosystem From 3dfc55eb2a4b489afd1eef24c1eff82721662776 Mon Sep 17 00:00:00 2001 From: Manuel Mauro Date: Thu, 24 Oct 2024 11:30:13 +0200 Subject: [PATCH 19/68] docs: no need to build contracts manually --- docs/guides/launch.md | 6 ------ 1 file changed, 6 deletions(-) diff --git a/docs/guides/launch.md b/docs/guides/launch.md index 5f7bd8322292..47384671a565 100644 --- a/docs/guides/launch.md +++ b/docs/guides/launch.md @@ -54,12 +54,6 @@ access it at `http://127.0.0.1:3000/` under credentials `admin/admin`. > If you don't see any data displayed on the Grafana dashboards - try setting the timeframe to "Last 30 minutes". You > will also have to have `jq` installed on your system. -## (Re)deploy db and contracts - -``` -zkstack dev contracts -``` - ## Ecosystem Configuration Ecosystem configuration can be found in: From 9b44cdefbcb4d627a4c25bdbcb5e99ff174ff5e8 Mon Sep 17 00:00:00 2001 From: Manuel Mauro Date: Thu, 24 Oct 2024 11:56:47 +0200 Subject: [PATCH 20/68] docs: mention location of server's configuration files --- docs/guides/launch.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/guides/launch.md b/docs/guides/launch.md index 47384671a565..c0fbc1538d07 100644 --- a/docs/guides/launch.md +++ b/docs/guides/launch.md @@ -73,6 +73,9 @@ Run server: zkstack server ``` +The server's configuration files can be found in `/chains//configs` directory. These files are created when +running `zkstack chain init` command. + ## Running server using Google cloud storage object store instead of default In memory store TODO: check the new way to do this From 9f144312bb1ed18fcf794fafaf983208225e2b7d Mon Sep 17 00:00:00 2001 From: Manuel Mauro Date: Thu, 24 Oct 2024 12:10:49 +0200 Subject: [PATCH 21/68] docs: add two troubleshoot items --- docs/guides/launch.md | 37 ++++++++++++++++++++++++++++++++++++- 1 file changed, 36 insertions(+), 1 deletion(-) diff --git a/docs/guides/launch.md b/docs/guides/launch.md index c0fbc1538d07..4179737df770 100644 --- a/docs/guides/launch.md +++ b/docs/guides/launch.md @@ -133,4 +133,39 @@ zkstack contract-verifier run ## Troubleshooting -TODO +### Connection Refused + +#### Problem + +```bash +error sending request for url (http://127.0.0.1:8545/): error trying to connect: tcp connect error: Connection refused (os error 61) +``` + +#### Description + +It appears that no containers are currently running, which is likely the reason you're encountering this error. + +#### Solution + +Ensure that the necessary containers have been started and are functioning correctly to resolve the issue. + +```bash +zkstack containers +``` + + +### Failed To Remove Volumes + +#### Problem + +```bash +failed to remove path `/home//workspace/current/zksync-era/volumes`: Permission denied (os error 13) +``` + +#### Description + +This issue may occur because the process doesn't have the necessary permissions to delete certain files or directories. + +#### Solution + +It is a common problem in Linux environments, and users will need to remove the path manually. From fa323b2dbe3bbe73c61e3d95d3215cb04418c219 Mon Sep 17 00:00:00 2001 From: Manuel Mauro Date: Thu, 24 Oct 2024 12:11:43 +0200 Subject: [PATCH 22/68] style: format --- docs/guides/launch.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/guides/launch.md b/docs/guides/launch.md index 4179737df770..98e0b853a766 100644 --- a/docs/guides/launch.md +++ b/docs/guides/launch.md @@ -153,7 +153,6 @@ Ensure that the necessary containers have been started and are functioning corre zkstack containers ``` - ### Failed To Remove Volumes #### Problem @@ -164,7 +163,7 @@ failed to remove path `/home//workspace/current/zksync-era/volumes`: Permi #### Description -This issue may occur because the process doesn't have the necessary permissions to delete certain files or directories. +This issue may occur because the process doesn't have the necessary permissions to delete certain files or directories. #### Solution From 3b9ba4724d02d2d1ac642d621acf9571a66a8e67 Mon Sep 17 00:00:00 2001 From: Manuel Mauro Date: Thu, 24 Oct 2024 12:23:32 +0200 Subject: [PATCH 23/68] docs: running prover without a GPU is currently unsupported --- docs/guides/launch.md | 10 ++-------- 1 file changed, 2 insertions(+), 8 deletions(-) diff --git a/docs/guides/launch.md b/docs/guides/launch.md index 98e0b853a766..c02a634cac62 100644 --- a/docs/guides/launch.md +++ b/docs/guides/launch.md @@ -90,19 +90,13 @@ zkstack server ## Running prover server -Running on machine without GPU +Running on a machine with GPU ```bash zkstack prover run ``` -TODO: check the new way to do this - -Running on machine with GPU - -```bash -zk f cargo +nightly run --features gpu --release --bin zksync_prover -``` +> NOTE: Running on machine without GPU is currently not supported by `zkstack`. ## Running the verification key generator From 30f399101a1421fbfa4ac3994b463de9242a6762 Mon Sep 17 00:00:00 2001 From: Manuel Mauro Date: Thu, 24 Oct 2024 12:28:36 +0200 Subject: [PATCH 24/68] docs: document how to run prover on GCP --- docs/guides/launch.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/guides/launch.md b/docs/guides/launch.md index c02a634cac62..b8b59529edd9 100644 --- a/docs/guides/launch.md +++ b/docs/guides/launch.md @@ -78,14 +78,12 @@ running `zkstack chain init` command. ## Running server using Google cloud storage object store instead of default In memory store -TODO: check the new way to do this - Get the `service_account.json` file containing the GCP credentials from kubernetes secret for relevant environment(stage2/ testnet2) add that file to the default location `~/gcloud/service_account.json` or update `object_store.toml` with the file location ```bash -zkstack server +zkstack prover init --bucket-base-url={url} --credentials-file={path/to/service_account.json} ``` ## Running prover server From 26626de952ba959ba8bd9234e5c4a3bebdfa6882 Mon Sep 17 00:00:00 2001 From: Manuel Mauro Date: Thu, 24 Oct 2024 14:58:19 +0200 Subject: [PATCH 25/68] docs: add section on contract verification with foundry --- docs/guides/development.md | 20 ++++++++++++++++---- 1 file changed, 16 insertions(+), 4 deletions(-) diff --git a/docs/guides/development.md b/docs/guides/development.md index f4bb23e8933e..10071d7718ef 100644 --- a/docs/guides/development.md +++ b/docs/guides/development.md @@ -101,10 +101,22 @@ zkstack dev contracts --help to see all the options. -### Publish source code on etherscan +### Publish source code on Etherscan -TODO: check the new way to do this +#### Using Foundry +You can use `foundry` to verify the source code of the contracts. + +```bash +forge verify-contract ``` -zk contract publish -``` + +Verifies a smart contract on a chosen verification provider. + +You must provide: +- The contract address +- The contract name or the path to the contract. +- In case of Etherscan verification, you must also provide: + - Your Etherscan API key, either by passing it as an argument or setting `ETHERSCAN_API_KEY` + +For more information check [Foundry's documentation](https://book.getfoundry.sh/reference/forge/forge-verify-contract). From d1f62a436404a89f6ed44f422c81df17af0263b1 Mon Sep 17 00:00:00 2001 From: Manuel Mauro Date: Thu, 24 Oct 2024 15:17:06 +0200 Subject: [PATCH 26/68] docs: add more information on verification options --- docs/guides/development.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/docs/guides/development.md b/docs/guides/development.md index 10071d7718ef..311945cdf945 100644 --- a/docs/guides/development.md +++ b/docs/guides/development.md @@ -103,6 +103,17 @@ to see all the options. ### Publish source code on Etherscan +#### Verifier Options + +Most commands interacting with smart contracts support the same verification options as Foundry's `forge` command. Just +double check if the following options are available in the subcommand: + +```bash +--verifier -- Verifier to use +--verifier-api-key -- Verifier API key +--verifier-url -- Verifier URL, if using a custom provider +``` + #### Using Foundry You can use `foundry` to verify the source code of the contracts. @@ -114,6 +125,7 @@ forge verify-contract Verifies a smart contract on a chosen verification provider. You must provide: + - The contract address - The contract name or the path to the contract. - In case of Etherscan verification, you must also provide: From fb56e18b43e5361293b5791b629b5f212baff21f Mon Sep 17 00:00:00 2001 From: Manuel Mauro Date: Thu, 24 Oct 2024 16:30:09 +0200 Subject: [PATCH 27/68] docs: update launch docs to use zkstack --- prover/docs/03_launch.md | 50 +++++++++++++++------------------------- 1 file changed, 19 insertions(+), 31 deletions(-) diff --git a/prover/docs/03_launch.md b/prover/docs/03_launch.md index 0465d888f612..dc7a25192ac9 100644 --- a/prover/docs/03_launch.md +++ b/prover/docs/03_launch.md @@ -2,37 +2,25 @@ ## Preparing -First, run the following command: +First, create a new chain with prover mode `GPU`: -``` -zk env prover-local +```bash +zkstack chain create --prover-mode gpu ``` -It will create a config similar to `dev`, but with: +It will create a config similar to `era`, but with: - Proof sending mode set to `OnlyRealProofs` - Prover mode set to `Local` instead of `GCS`. -You can always switch back to dev config via `zk env dev`. - -**Important:** If you change environments, you have to do `zk init` again. - -## Enter the prover workspace - -All the commands for binaries in the prover workspace must be done from the prover folder: - -``` -cd $ZKSYNC_HOME/prover -``` - ## Key generation This operation should only be done once; if you already generated keys, you can skip it. The following command will generate the required keys: -``` -zk f cargo run --features gpu --release --bin key_generator -- generate-sk-gpu all --recompute-if-missing +```bash +zkstack prover setup-keys ``` With that, you should be ready to run the prover. @@ -40,20 +28,20 @@ With that, you should be ready to run the prover. ## Running Important! Generating a proof takes a lot of time, so if you just want to see whether you can generate a proof, do it -against clean sequencer state (e.g. right after `zk init`). +against clean sequencer state (e.g. right after `zkstack chain init`). We will be running a bunch of binaries, it's recommended to run each in a separate terminal. ### Server -``` -zk server --components=api,tree,eth,state_keeper,housekeeper,commitment_generator,da_dispatcher,proof_data_handler,vm_runner_protective_reads,vm_runner_bwip +```bash +zkstack server --components=api,tree,eth,state_keeper,housekeeper,commitment_generator,da_dispatcher,proof_data_handler,vm_runner_protective_reads,vm_runner_bwip ``` ### Proof data handler -``` -zk f cargo run --release --bin zksync_prover_fri_gateway +```bash +zkstack prover run --component=gateway ``` Then wait until the first job is picked up. Prover gateway has to insert protocol information into the database, and @@ -63,8 +51,8 @@ until it happens, witness generators will panic and won't be able to start. Once a job is created, start witness generators: -``` -zk f cargo run --release --bin zksync_witness_generator -- --all_rounds +```bash +zkstack prover run --component=witness-generator --round=all-rounds ``` `--all_rounds` means that witness generator will produce witnesses of all kinds. You can run a witness generator for @@ -72,8 +60,8 @@ each round separately, but it's mostly useful in production environments. ### Witness vector generator -``` -zk f cargo run --release --bin zksync_witness_vector_generator -- --threads 10 +```bash +zkstack prover run --component=witness-vector-generator --threads 10 ``` WVG prepares inputs for prover, and it's a single-threaded time-consuming operation. You may run several jobs by @@ -82,8 +70,8 @@ ballpark estimate (useful for local development) is 10 WVGs per prover. ### Prover -``` -zk f cargo run --features "gpu" --release --bin zksync_prover_fri +```bash +zkstack prover run --component=prover ``` Prover can prove any kinds of circuits, so you only need a single instance. @@ -96,8 +84,8 @@ GPU. So unless you have a GPU with 48GB of VRAM, you won't be able to run both a You should wait until the proof is generated, and once you see in the server logs that it tries to find available compressor, you can shut the prover down, and run the proof compressor: -``` -zk f cargo run --features "gpu" --release --bin zksync_proof_fri_compressor +```bash +zkstack prover run --component=compressor ``` Once the proof is compressed, proof gateway will see that and will send the generated proof back to core. From 76300be2ccd2e9e195c3b3d9cd804caab99b7404 Mon Sep 17 00:00:00 2001 From: Manuel Mauro Date: Mon, 28 Oct 2024 11:47:47 +0100 Subject: [PATCH 28/68] Update docs/guides/launch.md Co-authored-by: Daniyar Itegulov --- docs/guides/launch.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/launch.md b/docs/guides/launch.md index b8b59529edd9..132b68265cbf 100644 --- a/docs/guides/launch.md +++ b/docs/guides/launch.md @@ -39,7 +39,7 @@ To completely reset the dev environment: ### Run observability stack If you want to run [Dockprom](https://github.com/stefanprodan/dockprom/) stack (Prometheus, Grafana) alongside other -containers - add `--run-observability` parameter during initialisation. +containers - add `--observability` parameter during initialisation. ```bash zkstack containers --observability From 3216bb10654f2143b2466aaa00ec89f52b02c8e5 Mon Sep 17 00:00:00 2001 From: Manuel Mauro Date: Mon, 28 Oct 2024 11:49:58 +0100 Subject: [PATCH 29/68] docs: remove outdated section --- docs/guides/launch.md | 16 ---------------- 1 file changed, 16 deletions(-) diff --git a/docs/guides/launch.md b/docs/guides/launch.md index 132b68265cbf..8db13a6d07d6 100644 --- a/docs/guides/launch.md +++ b/docs/guides/launch.md @@ -144,19 +144,3 @@ Ensure that the necessary containers have been started and are functioning corre ```bash zkstack containers ``` - -### Failed To Remove Volumes - -#### Problem - -```bash -failed to remove path `/home//workspace/current/zksync-era/volumes`: Permission denied (os error 13) -``` - -#### Description - -This issue may occur because the process doesn't have the necessary permissions to delete certain files or directories. - -#### Solution - -It is a common problem in Linux environments, and users will need to remove the path manually. From 7d65381a2983eb6426a341fe49613dfce72218a1 Mon Sep 17 00:00:00 2001 From: Manuel Mauro Date: Tue, 29 Oct 2024 10:10:47 +0100 Subject: [PATCH 30/68] Update docs/guides/launch.md Co-authored-by: Devashish Dixit --- docs/guides/launch.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/launch.md b/docs/guides/launch.md index 8db13a6d07d6..1824f101b3ec 100644 --- a/docs/guides/launch.md +++ b/docs/guides/launch.md @@ -91,7 +91,7 @@ zkstack prover init --bucket-base-url={url} --credentials-file={path/to/service_ Running on a machine with GPU ```bash -zkstack prover run +zkstack prover run --component=prover ``` > NOTE: Running on machine without GPU is currently not supported by `zkstack`. From 0c2bfc35ba48bfa7597213ebeb56ef6bde01e29c Mon Sep 17 00:00:00 2001 From: Manuel Mauro Date: Tue, 29 Oct 2024 10:11:10 +0100 Subject: [PATCH 31/68] Update prover/docs/03_launch.md Co-authored-by: Devashish Dixit --- prover/docs/03_launch.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/prover/docs/03_launch.md b/prover/docs/03_launch.md index dc7a25192ac9..9e9cbdb94d34 100644 --- a/prover/docs/03_launch.md +++ b/prover/docs/03_launch.md @@ -38,7 +38,7 @@ We will be running a bunch of binaries, it's recommended to run each in a separa zkstack server --components=api,tree,eth,state_keeper,housekeeper,commitment_generator,da_dispatcher,proof_data_handler,vm_runner_protective_reads,vm_runner_bwip ``` -### Proof data handler +### Prover gateway ```bash zkstack prover run --component=gateway From 1187124d2544d5abe0280f7eb5aefca49b18bec9 Mon Sep 17 00:00:00 2001 From: Manuel Mauro Date: Tue, 29 Oct 2024 10:13:48 +0100 Subject: [PATCH 32/68] docs: add note on WVG memory footprint --- prover/docs/03_launch.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/prover/docs/03_launch.md b/prover/docs/03_launch.md index 9e9cbdb94d34..e26d56cf0190 100644 --- a/prover/docs/03_launch.md +++ b/prover/docs/03_launch.md @@ -68,6 +68,8 @@ WVG prepares inputs for prover, and it's a single-threaded time-consuming operat changing the `threads` parameter. The exact amount of WVGs needed to "feed" one prover depends on CPU/GPU specs, but a ballpark estimate (useful for local development) is 10 WVGs per prover. +> NOTE: The WVG thread typically uses approximately 10GB of RAM. + ### Prover ```bash From 1d9d7244db7e7771bc25ed0aa45c52c78b49c832 Mon Sep 17 00:00:00 2001 From: Manuel Mauro Date: Tue, 29 Oct 2024 10:18:30 +0100 Subject: [PATCH 33/68] docs: add section on prover job monitor --- prover/docs/03_launch.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/prover/docs/03_launch.md b/prover/docs/03_launch.md index e26d56cf0190..28641349343f 100644 --- a/prover/docs/03_launch.md +++ b/prover/docs/03_launch.md @@ -78,6 +78,14 @@ zkstack prover run --component=prover Prover can prove any kinds of circuits, so you only need a single instance. +### Prover job monitor + +You can start the prover job monitor by specifying its component as follows. + +```bash +zkstack prover run --component=prover-job-monitor +``` + ### Proof compressor ⚠️ Both prover and proof compressor require 24GB of VRAM, and currently it's not possible to make them use different From 830a3add810df2a6d51b92e98eebc4ecd8441bf6 Mon Sep 17 00:00:00 2001 From: Manuel Mauro Date: Tue, 29 Oct 2024 10:22:21 +0100 Subject: [PATCH 34/68] docs: add section on inserting/querying protocol version in prover DB --- prover/docs/03_launch.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/prover/docs/03_launch.md b/prover/docs/03_launch.md index 28641349343f..81c2de648e18 100644 --- a/prover/docs/03_launch.md +++ b/prover/docs/03_launch.md @@ -86,6 +86,21 @@ You can start the prover job monitor by specifying its component as follows. zkstack prover run --component=prover-job-monitor ``` +### Insert protocol version in prover database + +Before running the prover, you can insert the protocol version in the prover database by executing the following command: + +```bash +zkstack dev prover insert-version --version --snark-wrapper= +``` + +To query this information, use the following command: + +```bash +zkstack dev prover info +``` + + ### Proof compressor ⚠️ Both prover and proof compressor require 24GB of VRAM, and currently it's not possible to make them use different From 82951c17fbf405de773e565e4c472c3cf5d3bb4c Mon Sep 17 00:00:00 2001 From: Manuel Mauro Date: Tue, 29 Oct 2024 10:22:51 +0100 Subject: [PATCH 35/68] style: format code --- prover/docs/03_launch.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/prover/docs/03_launch.md b/prover/docs/03_launch.md index 81c2de648e18..fcddf93174b9 100644 --- a/prover/docs/03_launch.md +++ b/prover/docs/03_launch.md @@ -88,7 +88,8 @@ zkstack prover run --component=prover-job-monitor ### Insert protocol version in prover database -Before running the prover, you can insert the protocol version in the prover database by executing the following command: +Before running the prover, you can insert the protocol version in the prover database by executing the following +command: ```bash zkstack dev prover insert-version --version --snark-wrapper= @@ -100,7 +101,6 @@ To query this information, use the following command: zkstack dev prover info ``` - ### Proof compressor ⚠️ Both prover and proof compressor require 24GB of VRAM, and currently it's not possible to make them use different From f8ec22b0bd76d6566b5371e43117737e9d3cd663 Mon Sep 17 00:00:00 2001 From: Manuel Mauro Date: Wed, 30 Oct 2024 10:34:13 +0100 Subject: [PATCH 36/68] Update docs/guides/development.md Co-authored-by: Artur Puzio --- docs/guides/development.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/development.md b/docs/guides/development.md index 311945cdf945..dfa55227d146 100644 --- a/docs/guides/development.md +++ b/docs/guides/development.md @@ -35,7 +35,7 @@ This command installs `zkstack` from the current source directory. ## Configure Ecosystem -The root directory includes configuration files for an ecosystem with a single chain, `era`. To initialize the +The project root directory includes configuration files for an ecosystem with a single chain, `era`. To initialize the ecosystem, first start the required containers: ```bash From 032da8fe955862bc0e41ae75b6c21ce60e5f4ca8 Mon Sep 17 00:00:00 2001 From: Manuel Mauro Date: Thu, 31 Oct 2024 11:23:50 +0100 Subject: [PATCH 37/68] docs: instruct users to install the porject's dependency Foundry ZKsync --- docs/guides/setup-dev.md | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/docs/guides/setup-dev.md b/docs/guides/setup-dev.md index 4f75d9fc5ace..8924f6e932d7 100644 --- a/docs/guides/setup-dev.md +++ b/docs/guides/setup-dev.md @@ -238,8 +238,16 @@ Go to the zksync folder and run `nix develop`. After it finishes, you are in a s ## Foundry ZKsync -[Foundry ZKsync](https://foundry-book.zksync.io/getting-started/installation) can be utilized for deploying smart -contracts. For commands related to deployment, you can pass flags for Foundry integration. +[Foundry ZKsync](https://foundry-book.zksync.io/getting-started/installation) is a dependency of the project and can be +installed as follows: + +```bash +curl -L https://raw.githubusercontent.com/matter-labs/foundry-zksync/main/install-foundry-zksync | bash +foundryup-zksync --branch master +``` + +Foundry ZKsync can also be used for deploying smart contracts. For commands related to deployment, you can pass flags +for Foundry integration. ## Non-GPU setup From daae0a3faed7a1817474f4597bce3becebe72035 Mon Sep 17 00:00:00 2001 From: Manuel Mauro Date: Thu, 31 Oct 2024 11:26:30 +0100 Subject: [PATCH 38/68] docs: suggest the use of --dev flag for local development --- docs/guides/development.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/guides/development.md b/docs/guides/development.md index dfa55227d146..d7e3270e7046 100644 --- a/docs/guides/development.md +++ b/docs/guides/development.md @@ -50,6 +50,8 @@ zkstack ecosystem init These commands will guide you through the configuration options for setting up the ecosystem. +> NOTE: For local development only. You can also use the development defaults by supplying the `--dev` flag. + Initialization may take some time, but key steps (such as downloading and unpacking keys or setting up containers) only need to be completed once. From 154e6e0e2a7ee896ed0975fe7316c8238507c332 Mon Sep 17 00:00:00 2001 From: Manuel Mauro Date: Thu, 31 Oct 2024 11:29:04 +0100 Subject: [PATCH 39/68] docs: invite users to supply the --verbose option for long-running commands --- docs/guides/development.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/guides/development.md b/docs/guides/development.md index d7e3270e7046..9e77a4e73b4b 100644 --- a/docs/guides/development.md +++ b/docs/guides/development.md @@ -54,6 +54,7 @@ These commands will guide you through the configuration options for setting up t Initialization may take some time, but key steps (such as downloading and unpacking keys or setting up containers) only need to be completed once. +You may find useful to run this (and other) commands with the `--verbose` flag to see more detailed output. ## Cleanup From 0f309bde9ca671d248dc5bc2362ad95389e5ff71 Mon Sep 17 00:00:00 2001 From: Manuel Mauro Date: Thu, 31 Oct 2024 11:30:44 +0100 Subject: [PATCH 40/68] style: format code --- docs/guides/development.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/guides/development.md b/docs/guides/development.md index 9e77a4e73b4b..c7329518ffb7 100644 --- a/docs/guides/development.md +++ b/docs/guides/development.md @@ -54,6 +54,7 @@ These commands will guide you through the configuration options for setting up t Initialization may take some time, but key steps (such as downloading and unpacking keys or setting up containers) only need to be completed once. + You may find useful to run this (and other) commands with the `--verbose` flag to see more detailed output. ## Cleanup From 010e7a9ccfb73ab8f7baee83ea2f4c04f8f2c023 Mon Sep 17 00:00:00 2001 From: Manuel Mauro Date: Thu, 31 Oct 2024 11:35:47 +0100 Subject: [PATCH 41/68] docs: remove Re-initialization section --- docs/guides/development.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/guides/development.md b/docs/guides/development.md index c7329518ffb7..4b345bbe4411 100644 --- a/docs/guides/development.md +++ b/docs/guides/development.md @@ -65,11 +65,10 @@ To clean up the local ecosystem (e.g., removing containers and clearing the cont zkstack dev clean all ``` -## Re-initialization - -You can reinitialize the ecosystem afterward by running: +You can then reinitialize the ecosystem as described in the [Configure Ecosystem](#configure-ecosystem) section. ```bash +zkstack containers zkstack ecosystem init ``` From 027c7d5df92186550f631f61962a951588380285 Mon Sep 17 00:00:00 2001 From: Manuel Mauro Date: Thu, 31 Oct 2024 11:36:41 +0100 Subject: [PATCH 42/68] style: format code --- docs/guides/development.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/development.md b/docs/guides/development.md index 4b345bbe4411..bdbea3f3a4df 100644 --- a/docs/guides/development.md +++ b/docs/guides/development.md @@ -68,7 +68,7 @@ zkstack dev clean all You can then reinitialize the ecosystem as described in the [Configure Ecosystem](#configure-ecosystem) section. ```bash -zkstack containers +zkstack containers zkstack ecosystem init ``` From a1903e9e6d9f3803abcaae4577ae11895fb0f149 Mon Sep 17 00:00:00 2001 From: Manuel Mauro Date: Thu, 31 Oct 2024 11:38:36 +0100 Subject: [PATCH 43/68] Update docs/guides/launch.md Co-authored-by: Artur Puzio --- docs/guides/launch.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/guides/launch.md b/docs/guides/launch.md index 1824f101b3ec..cfb5c273e979 100644 --- a/docs/guides/launch.md +++ b/docs/guides/launch.md @@ -33,6 +33,7 @@ To completely reset the dev environment: - Repeat the setup procedure above ```bash + zkstack containers zkstack ecosystem init ``` From acc12ee1ee73ec84af03802b4d6beb6ef0ff6c9c Mon Sep 17 00:00:00 2001 From: Manuel Mauro Date: Thu, 31 Oct 2024 11:56:13 +0100 Subject: [PATCH 44/68] docs: change recommendation on rust's toolchain version --- docs/guides/setup-dev.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/setup-dev.md b/docs/guides/setup-dev.md index 8924f6e932d7..63314ccee3c5 100644 --- a/docs/guides/setup-dev.md +++ b/docs/guides/setup-dev.md @@ -156,7 +156,7 @@ sudo apt-get install libssl-dev ## `Rust` -Install the latest `rust` version. +Install `Rust`'s toolchain version reported in `/rust-toolchain.toml` (also a later stable version should work). Instructions can be found on the [official site](https://www.rust-lang.org/tools/install). From cd62bfca3c3a3c7cf7584dd7be43eb749fb503de Mon Sep 17 00:00:00 2001 From: Manuel Mauro Date: Thu, 31 Oct 2024 15:08:15 +0100 Subject: [PATCH 45/68] docs: improve "Installing the local ZK Stack CLI" section --- docs/guides/development.md | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/docs/guides/development.md b/docs/guides/development.md index bdbea3f3a4df..2528653eaecd 100644 --- a/docs/guides/development.md +++ b/docs/guides/development.md @@ -4,8 +4,9 @@ This document outlines the steps for setting up and working with ZKsync. ## Installing the local ZK Stack CLI -To set up the local toolkit, begin by installing `zkstackup`. From the project's root directory, run the following -commands: +To set up local development, begin by installing +[ZK Stack CLI](https://github.com/matter-labs/zksync-era/blob/main/zkstack_cli/README.md). From the project's root +directory, run the following commands: ```bash cd ./zkstack_cli/zkstackup @@ -23,6 +24,12 @@ zkstackup --local This command installs `zkstack` from the current source directory. +You can proceed to verify the installation and start familiarizing qith the CLI by running: + +```bash +zkstack --help +``` + > NOTE: Whenever you want to update you local installation with your changes, just rerun: > > ```bash From 11fee43f381b9fadecae2eae7b7cedb1c94495bd Mon Sep 17 00:00:00 2001 From: Manuel Mauro Date: Thu, 31 Oct 2024 15:20:41 +0100 Subject: [PATCH 46/68] docs: refer to setup-dev.md in development.md --- docs/guides/development.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/guides/development.md b/docs/guides/development.md index 2528653eaecd..1eabfd2e0fe9 100644 --- a/docs/guides/development.md +++ b/docs/guides/development.md @@ -2,6 +2,10 @@ This document outlines the steps for setting up and working with ZKsync. +## Prerequisites + +If you haven't already, install the prerequisites as described in [Install Dependencies](./setup-dev.md). + ## Installing the local ZK Stack CLI To set up local development, begin by installing From af79a06fa9360df51b20337e8ac8754c6d61ad92 Mon Sep 17 00:00:00 2001 From: Manuel Mauro Date: Thu, 31 Oct 2024 15:21:03 +0100 Subject: [PATCH 47/68] docs: improve spelling --- docs/guides/setup-dev.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/guides/setup-dev.md b/docs/guides/setup-dev.md index 63314ccee3c5..1c1d22a55502 100644 --- a/docs/guides/setup-dev.md +++ b/docs/guides/setup-dev.md @@ -194,13 +194,13 @@ Rust toolchain as well. Install the latest postgres: -On mac: +On macOS: ```bash brew install postgresql@14 ``` -On debian-based linux: +On Debian-based linux: ```bash sudo apt-get install postgresql From 5b6cd894d78cb0882f2f07a6156961f29efdffee Mon Sep 17 00:00:00 2001 From: Manuel Mauro Date: Tue, 5 Nov 2024 11:52:26 +0100 Subject: [PATCH 48/68] docs: recommend client-only PostgreSQL installation --- docs/guides/setup-dev.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/guides/setup-dev.md b/docs/guides/setup-dev.md index 1c1d22a55502..377719915dfb 100644 --- a/docs/guides/setup-dev.md +++ b/docs/guides/setup-dev.md @@ -190,20 +190,20 @@ If you see `x86_64` mentioned in the output, probably you're running (or used to that's the case, you should probably change the way you run terminal, and/or reinstall your IDE, and then reinstall the Rust toolchain as well. -## Postgres +## PostgreSQL Client Library -Install the latest postgres: +For development purposes, you typically only need the PostgreSQL client library, not the full server installation. Here's how to install it: On macOS: ```bash -brew install postgresql@14 +brew install libpq ``` -On Debian-based linux: +On Debian-based Linux: ```bash -sudo apt-get install postgresql +sudo apt-get install libpq-dev ``` ### Cargo nextest From e9381f9440df61778e8c7df90cde91a73a8859c8 Mon Sep 17 00:00:00 2001 From: Manuel Mauro Date: Tue, 5 Nov 2024 11:53:06 +0100 Subject: [PATCH 49/68] style: format --- docs/guides/setup-dev.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/guides/setup-dev.md b/docs/guides/setup-dev.md index 377719915dfb..8c84e96ba898 100644 --- a/docs/guides/setup-dev.md +++ b/docs/guides/setup-dev.md @@ -192,7 +192,8 @@ Rust toolchain as well. ## PostgreSQL Client Library -For development purposes, you typically only need the PostgreSQL client library, not the full server installation. Here's how to install it: +For development purposes, you typically only need the PostgreSQL client library, not the full server installation. +Here's how to install it: On macOS: From 27e8a301ac07eccba37e74c18e1e63bd6c86ac57 Mon Sep 17 00:00:00 2001 From: Manuel Mauro Date: Tue, 5 Nov 2024 11:33:30 +0000 Subject: [PATCH 50/68] docs: update TL;DR --- docs/guides/setup-dev.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/docs/guides/setup-dev.md b/docs/guides/setup-dev.md index 8c84e96ba898..504d2464299b 100644 --- a/docs/guides/setup-dev.md +++ b/docs/guides/setup-dev.md @@ -18,16 +18,13 @@ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.5/install.sh | bash # All necessary stuff sudo apt-get update -sudo apt-get install build-essential pkg-config cmake clang lldb lld libssl-dev postgresql apt-transport-https ca-certificates curl software-properties-common +sudo apt-get install build-essential pkg-config cmake clang lldb lld libssl-dev libpq-dev apt-transport-https ca-certificates curl software-properties-common # Install docker curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add - sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu focal stable" sudo apt install docker-ce sudo usermod -aG docker ${USER} -# Stop default postgres (as we'll use the docker one) -sudo systemctl stop postgresql -sudo systemctl disable postgresql # Start docker. sudo systemctl start docker From 09063ccfcfd3fde526025db16bfd193a0ac06baf Mon Sep 17 00:00:00 2001 From: Manuel Mauro Date: Tue, 5 Nov 2024 14:31:50 +0100 Subject: [PATCH 51/68] docs: improve formatting/style --- docs/guides/setup-dev.md | 23 +++++++++++++---------- 1 file changed, 13 insertions(+), 10 deletions(-) diff --git a/docs/guides/setup-dev.md b/docs/guides/setup-dev.md index 504d2464299b..96496e36ed69 100644 --- a/docs/guides/setup-dev.md +++ b/docs/guides/setup-dev.md @@ -14,11 +14,14 @@ git config --global url."https://".insteadOf git:// # Rust curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh + # NVM curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.5/install.sh | bash + # All necessary stuff sudo apt-get update -sudo apt-get install build-essential pkg-config cmake clang lldb lld libssl-dev libpq-dev apt-transport-https ca-certificates curl software-properties-common +sudo apt-get install -y build-essential pkg-config cmake clang lldb lld libssl-dev libpq-dev apt-transport-https ca-certificates curl software-properties-common + # Install docker curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add - sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu focal stable" @@ -61,20 +64,20 @@ Don't forget to look at [tips](#tips). ## Supported operating systems -ZKsync currently can be launched on any \*nix operating system (e.g. any linux distribution or MacOS). +ZKsync currently can be launched on any \*nix operating system (e.g. any linux distribution or macOS). If you're using Windows, then make sure to use WSL 2. Additionally, if you are going to use WSL 2, make sure that your project is located in the _linux filesystem_, since accessing NTFS partitions from within WSL is very slow. -If you're using MacOS with an ARM processor (e.g. M1/M2), make sure that you are working in the _native_ environment +If you're using macOS with an ARM processor (e.g. M1/M2), make sure that you are working in the _native_ environment (e.g., your terminal and IDE don't run in Rosetta, and your toolchain is native). Trying to work with ZKsync code via Rosetta may cause problems that are hard to spot and debug, so make sure to check everything before you start. If you are a NixOS user or would like to have a reproducible environment, skip to the section about `nix`. -## `Docker` +## Docker Install `docker`. It is recommended to follow the instructions from the [official site](https://docs.docker.com/install/). @@ -114,13 +117,13 @@ at this step. If logging out does not resolve the issue, restarting the computer should. -## `Node` & `Yarn` +## Node.js & Yarn 1. Install `Node` (requires version `v20`). The recommended way is via [nvm](https://github.com/nvm-sh/nvm). 2. Install `yarn`. Can be done via `npm install -g yarn`. Make sure to get version 1.22.19 - you can change the version by running `yarn set version 1.22.19`. -## `clang` +## clang In order to compile RocksDB, you must have LLVM available. On debian-based linux it can be installed as follows: @@ -130,12 +133,12 @@ On debian-based linux: sudo apt-get install build-essential pkg-config cmake clang lldb lld ``` -On mac: +On macOS: You need to have an up-to-date `Xcode`. You can install it directly from `App Store`. With Xcode command line tools, you get the Clang compiler installed by default. Thus, having XCode you don't need to install `clang`. -## `OpenSSL` +## OpenSSL Install OpenSSL: @@ -151,7 +154,7 @@ On debian-based linux: sudo apt-get install libssl-dev ``` -## `Rust` +## Rust Install `Rust`'s toolchain version reported in `/rust-toolchain.toml` (also a later stable version should work). @@ -164,7 +167,7 @@ rustc --version rustc 1.xx.y (xxxxxx 20xx-yy-zz) # Output may vary depending on actual version of rust ``` -If you are using MacOS with ARM processor (e.g. M1/M2), make sure that you use an `aarch64` toolchain. For example, when +If you are using macOS with ARM processor (e.g. M1/M2), make sure that you use an `aarch64` toolchain. For example, when you run `rustup show`, you should see a similar input: ```bash From 1956a2e21c61e3801c6348bac9dbd75897c53eb5 Mon Sep 17 00:00:00 2001 From: Manuel Mauro Date: Wed, 6 Nov 2024 10:43:43 +0100 Subject: [PATCH 52/68] docs: add section on manually editing config files --- docs/guides/launch.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/docs/guides/launch.md b/docs/guides/launch.md index cfb5c273e979..8bc8acb0ea5d 100644 --- a/docs/guides/launch.md +++ b/docs/guides/launch.md @@ -77,6 +77,26 @@ zkstack server The server's configuration files can be found in `/chains//configs` directory. These files are created when running `zkstack chain init` command. +### Modifying configuration files manually + +To manually modify configuration files: + +1. Locate the relevant config file in `/chains//configs` +2. Open the file in a text editor +3. Make necessary changes, following the existing format +4. Save the file +5. Restart the relevant services for changes to take effect: + +```bash +zkstack server +``` + +> NOTE: Manual changes to configuration files may be overwritten if the ecosystem is reinitialized or the chain is +> reinitialized. + +> WARNING: Some properties, such as ports, may require manual modification across different configuration files to +> ensure consistency and avoid conflicts. + ## Running server using Google cloud storage object store instead of default In memory store Get the `service_account.json` file containing the GCP credentials from kubernetes secret for relevant From d0f641520ca8e4d219c441fd8d8ca6d01e13fcbd Mon Sep 17 00:00:00 2001 From: Manuel Mauro Date: Wed, 6 Nov 2024 12:14:56 +0100 Subject: [PATCH 53/68] Update docs/guides/advanced/01_initialization.md Co-authored-by: Sarah Schwartz <58856580+sarahschwartz@users.noreply.github.com> --- docs/guides/advanced/01_initialization.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/advanced/01_initialization.md b/docs/guides/advanced/01_initialization.md index 529ab09d62f8..bc5fe8fbc973 100644 --- a/docs/guides/advanced/01_initialization.md +++ b/docs/guides/advanced/01_initialization.md @@ -19,7 +19,7 @@ re-running any `zkstack` command. #### Containers -As first step, running `zkstack containers` gets the docker images for postgres and reth. If the `--observability` +The first step to initialize a ZK Stack ecosystem is to run the command `zkstack containers`. This command gets the docker images for `postgres` and `reth`. If the `--observability` option is passed to the command, or the corresponding option is selected in the interactive prompt, then Prometheus, Grafana and other observability-related images are downloaded and run. From 8dc0d0313ddd87b970c0837bb723e7a716498ebb Mon Sep 17 00:00:00 2001 From: Manuel Mauro Date: Wed, 6 Nov 2024 12:15:20 +0100 Subject: [PATCH 54/68] Update docs/guides/advanced/01_initialization.md Co-authored-by: Sarah Schwartz <58856580+sarahschwartz@users.noreply.github.com> --- docs/guides/advanced/01_initialization.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/guides/advanced/01_initialization.md b/docs/guides/advanced/01_initialization.md index bc5fe8fbc973..963373aa162f 100644 --- a/docs/guides/advanced/01_initialization.md +++ b/docs/guides/advanced/01_initialization.md @@ -31,7 +31,9 @@ VM. #### Ecosystem -Then, running `zkstack ecosystem init`:. +The next step is to run the command `zkstack ecosystem init`. + +This command: - Collects and finalize the ecosystem configuration. - Builds and deploys L1 & L2 contracts. From 01f7960d3ee9cbf5076d50eaa6d7edf808836ae8 Mon Sep 17 00:00:00 2001 From: Manuel Mauro Date: Wed, 6 Nov 2024 12:15:47 +0100 Subject: [PATCH 55/68] Update docs/guides/advanced/01_initialization.md Co-authored-by: Sarah Schwartz <58856580+sarahschwartz@users.noreply.github.com> --- docs/guides/advanced/01_initialization.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/advanced/01_initialization.md b/docs/guides/advanced/01_initialization.md index 963373aa162f..6fc715129044 100644 --- a/docs/guides/advanced/01_initialization.md +++ b/docs/guides/advanced/01_initialization.md @@ -131,7 +131,7 @@ In order to communicate with L2 (our ZKsync) - we have to deploy multiple contra Ethereum). You can look on the `deployL1.log` file - to see the list of contracts that were deployed and their accounts. First thing in the file, is the deployer/governor wallet - this is the account that can change, freeze and unfreeze the -contracts (basically the owner). You can also verify (using the getBalance method above), that has a lot of tokens. +contracts (basically the owner). You can verify the token balance using the `getBalance` method above. Then, there are a bunch of contracts (CRATE2_FACTOR, DIAMOND_PROXY, L1_ALLOW_LIST etc etc) - for each one, the file contains the address. From fe4dc528f5a1144bafcda93c323cac9a24e4dbfd Mon Sep 17 00:00:00 2001 From: Manuel Mauro Date: Wed, 6 Nov 2024 12:16:05 +0100 Subject: [PATCH 56/68] Update docs/guides/development.md Co-authored-by: Sarah Schwartz <58856580+sarahschwartz@users.noreply.github.com> --- docs/guides/development.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/development.md b/docs/guides/development.md index 1eabfd2e0fe9..e7f04c127755 100644 --- a/docs/guides/development.md +++ b/docs/guides/development.md @@ -28,7 +28,7 @@ zkstackup --local This command installs `zkstack` from the current source directory. -You can proceed to verify the installation and start familiarizing qith the CLI by running: +You can proceed to verify the installation and start familiarizing with the CLI by running: ```bash zkstack --help From 1585f8c7e42314808f06c240e162c44588b1194d Mon Sep 17 00:00:00 2001 From: Manuel Mauro Date: Wed, 6 Nov 2024 12:16:22 +0100 Subject: [PATCH 57/68] Update docs/guides/development.md Co-authored-by: Sarah Schwartz <58856580+sarahschwartz@users.noreply.github.com> --- docs/guides/development.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/development.md b/docs/guides/development.md index e7f04c127755..2fe32f13985c 100644 --- a/docs/guides/development.md +++ b/docs/guides/development.md @@ -66,7 +66,7 @@ These commands will guide you through the configuration options for setting up t Initialization may take some time, but key steps (such as downloading and unpacking keys or setting up containers) only need to be completed once. -You may find useful to run this (and other) commands with the `--verbose` flag to see more detailed output. +To see more detailed output, you can run commands with the `--verbose` flag. ## Cleanup From f47ecc3734be86378831b818b422506c848c4054 Mon Sep 17 00:00:00 2001 From: Manuel Mauro Date: Wed, 6 Nov 2024 12:16:54 +0100 Subject: [PATCH 58/68] Update docs/guides/launch.md Co-authored-by: Sarah Schwartz <58856580+sarahschwartz@users.noreply.github.com> --- docs/guides/launch.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/launch.md b/docs/guides/launch.md index 8bc8acb0ea5d..215076aa83ba 100644 --- a/docs/guides/launch.md +++ b/docs/guides/launch.md @@ -57,7 +57,7 @@ access it at `http://127.0.0.1:3000/` under credentials `admin/admin`. ## Ecosystem Configuration -Ecosystem configuration can be found in: +The ecosystem configurations can be found in the following folders: - `/ZkStack.yaml` - `/configs` folder From f1041fe4fe83d1fd97487531770df686600a1905 Mon Sep 17 00:00:00 2001 From: Manuel Mauro Date: Wed, 6 Nov 2024 12:18:10 +0100 Subject: [PATCH 59/68] style: format code --- docs/guides/advanced/01_initialization.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/guides/advanced/01_initialization.md b/docs/guides/advanced/01_initialization.md index 6fc715129044..d39f8808d7ad 100644 --- a/docs/guides/advanced/01_initialization.md +++ b/docs/guides/advanced/01_initialization.md @@ -19,9 +19,10 @@ re-running any `zkstack` command. #### Containers -The first step to initialize a ZK Stack ecosystem is to run the command `zkstack containers`. This command gets the docker images for `postgres` and `reth`. If the `--observability` -option is passed to the command, or the corresponding option is selected in the interactive prompt, then Prometheus, -Grafana and other observability-related images are downloaded and run. +The first step to initialize a ZK Stack ecosystem is to run the command `zkstack containers`. This command gets the +docker images for `postgres` and `reth`. If the `--observability` option is passed to the command, or the corresponding +option is selected in the interactive prompt, then Prometheus, Grafana and other observability-related images are +downloaded and run. Reth (one of the Ethereum clients) will be used to setup our own copy of L1 chain (that our local ZKsync would use). From a931c1bbc6cce2b52384b46bb83c36eca59037f5 Mon Sep 17 00:00:00 2001 From: Manuel Mauro Date: Tue, 12 Nov 2024 11:39:15 +0100 Subject: [PATCH 60/68] docs: do not suggest a command to install Foundry Zksync --- docs/guides/setup-dev.md | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) diff --git a/docs/guides/setup-dev.md b/docs/guides/setup-dev.md index 96496e36ed69..6ca321449ad4 100644 --- a/docs/guides/setup-dev.md +++ b/docs/guides/setup-dev.md @@ -239,13 +239,7 @@ Go to the zksync folder and run `nix develop`. After it finishes, you are in a s ## Foundry ZKsync -[Foundry ZKsync](https://foundry-book.zksync.io/getting-started/installation) is a dependency of the project and can be -installed as follows: - -```bash -curl -L https://raw.githubusercontent.com/matter-labs/foundry-zksync/main/install-foundry-zksync | bash -foundryup-zksync --branch master -``` +ZKSync depends on Foundry ZKsync (which is is a specialized fork of Foundry, tailored for ZKsync). Please follow this [installation guide](https://foundry-book.zksync.io/getting-started/installation) to get started with Foundry ZKsync. Foundry ZKsync can also be used for deploying smart contracts. For commands related to deployment, you can pass flags for Foundry integration. From c888bb4bed6bed0402d42cc196e371f30dc5d446 Mon Sep 17 00:00:00 2001 From: Manuel Mauro Date: Tue, 12 Nov 2024 11:40:24 +0100 Subject: [PATCH 61/68] style: format docs --- docs/guides/setup-dev.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/guides/setup-dev.md b/docs/guides/setup-dev.md index 6ca321449ad4..9d9d2f2a177b 100644 --- a/docs/guides/setup-dev.md +++ b/docs/guides/setup-dev.md @@ -239,7 +239,8 @@ Go to the zksync folder and run `nix develop`. After it finishes, you are in a s ## Foundry ZKsync -ZKSync depends on Foundry ZKsync (which is is a specialized fork of Foundry, tailored for ZKsync). Please follow this [installation guide](https://foundry-book.zksync.io/getting-started/installation) to get started with Foundry ZKsync. +ZKSync depends on Foundry ZKsync (which is is a specialized fork of Foundry, tailored for ZKsync). Please follow this +[installation guide](https://foundry-book.zksync.io/getting-started/installation) to get started with Foundry ZKsync. Foundry ZKsync can also be used for deploying smart contracts. For commands related to deployment, you can pass flags for Foundry integration. From 6101949c7eb74c1920f12d1ad87a5a0d86e02123 Mon Sep 17 00:00:00 2001 From: Manuel Mauro Date: Tue, 12 Nov 2024 11:46:37 +0100 Subject: [PATCH 62/68] Update docs/guides/advanced/01_initialization.md Co-authored-by: Antonio --- docs/guides/advanced/01_initialization.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/advanced/01_initialization.md b/docs/guides/advanced/01_initialization.md index d39f8808d7ad..2bc4a9c3a459 100644 --- a/docs/guides/advanced/01_initialization.md +++ b/docs/guides/advanced/01_initialization.md @@ -38,7 +38,7 @@ This command: - Collects and finalize the ecosystem configuration. - Builds and deploys L1 & L2 contracts. -- Initialize each chain defined in the `/chains` folder. (Currently, a single chain `era` is defined there, but you can +- Initializes each chain defined in the `/chains` folder. (Currently, a single chain `era` is defined there, but you can create your own chains running `zkstack chain create`). - Sets up observability. - Runs the genesis process. From d808f3dcd6a749700c3c0c5b5375a02d7ea1c827 Mon Sep 17 00:00:00 2001 From: Manuel Mauro Date: Tue, 12 Nov 2024 11:48:17 +0100 Subject: [PATCH 63/68] docs: fix tips H level --- docs/guides/setup-dev.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/setup-dev.md b/docs/guides/setup-dev.md index 9d9d2f2a177b..a74f976c2b73 100644 --- a/docs/guides/setup-dev.md +++ b/docs/guides/setup-dev.md @@ -287,7 +287,7 @@ export RUSTFLAGS='-C link-arg=-fuse-ld=/usr/local/bin/mold' export CARGO_TARGET_X86_64_UNKNOWN_LINUX_GNU_LINKER="clang" ``` -## Tip: Speeding up building `RocksDB` +### Tip: Speeding up building `RocksDB` By default, each time you compile `rocksdb` crate, it will compile required C++ sources from scratch. It can be avoided by using precompiled versions of library, and it will significantly improve your build times. From fc8d95864891b15c325e7623ba91ba92e6c4c525 Mon Sep 17 00:00:00 2001 From: Manuel Mauro Date: Tue, 12 Nov 2024 12:08:13 +0100 Subject: [PATCH 64/68] docs: expand section on ecosystem configuration --- docs/guides/launch.md | 44 +++++++++++++++++++++++++++++++++++-------- 1 file changed, 36 insertions(+), 8 deletions(-) diff --git a/docs/guides/launch.md b/docs/guides/launch.md index 215076aa83ba..4301ba85ab8c 100644 --- a/docs/guides/launch.md +++ b/docs/guides/launch.md @@ -57,14 +57,42 @@ access it at `http://127.0.0.1:3000/` under credentials `admin/admin`. ## Ecosystem Configuration -The ecosystem configurations can be found in the following folders: - -- `/ZkStack.yaml` -- `/configs` folder -- `/chains` folder - -These files are created at ecosystem initialization `zkstack ecosystem init` and at chain initialization -`zkstack chain init`. +The ecosystem configuration is spread across multiple files and directories: + +1. Root level: + - `ZkStack.yaml`: Main configuration file for the entire ecosystem. + +2. `configs/` directory: + - `apps/`: + - `portal_config.json`: Configuration for the portal application. + - `contracts.yaml`: Defines smart contract settings and addresses. + - `erc20.yaml`: Configuration for ERC20 tokens. + - `initial_deployments.yaml`: Specifies initial ERC20 token deployments. + - `wallets.yaml`: Contains wallet configurations. + +3. `chains//` directory: + - `artifacts/`: Contains build/execution artifacts. + - `configs/`: Chain-specific configuration files. + - `contracts.yaml`: Chain-specific smart contract settings. + - `external_node.yaml`: Configuration for external nodes. + - `general.yaml`: General chain configuration. + - `genesis.yaml`: Genesis configuration for the chain. + - `secrets.yaml`: Secrets and private keys for the chain. + - `wallets.yaml`: Wallet configurations for the chain. + - `db/main/`: Database files for the chain. + - `ZkStack.yaml`: Chain-specific ZkStack configuration. + +These configuration files are automatically generated during the ecosystem initialization (`zkstack ecosystem init`) and chain initialization (`zkstack chain init`) processes. They control various aspects of the ZKsync ecosystem, including: + +- Network settings +- Smart contract deployments +- Token configurations +- Database settings +- Application/Service-specific parameters + +It's important to note that while these files can be manually edited, any changes may be overwritten if the ecosystem or chain is reinitialized. Always back up your modifications and exercise caution when making direct changes to these files. + +For specific configuration needs, it's recommended to use the appropriate `zkstack` commands or consult the documentation for safe ways to customize your setup. ## Build and run server From 1ce117b56e365f9813aa859f2eb4285ecbf81e95 Mon Sep 17 00:00:00 2001 From: Manuel Mauro Date: Tue, 12 Nov 2024 12:13:38 +0100 Subject: [PATCH 65/68] style: format docs --- docs/guides/launch.md | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/docs/guides/launch.md b/docs/guides/launch.md index 4301ba85ab8c..52872a53cf2a 100644 --- a/docs/guides/launch.md +++ b/docs/guides/launch.md @@ -60,9 +60,11 @@ access it at `http://127.0.0.1:3000/` under credentials `admin/admin`. The ecosystem configuration is spread across multiple files and directories: 1. Root level: + - `ZkStack.yaml`: Main configuration file for the entire ecosystem. 2. `configs/` directory: + - `apps/`: - `portal_config.json`: Configuration for the portal application. - `contracts.yaml`: Defines smart contract settings and addresses. @@ -71,6 +73,7 @@ The ecosystem configuration is spread across multiple files and directories: - `wallets.yaml`: Contains wallet configurations. 3. `chains//` directory: + - `artifacts/`: Contains build/execution artifacts. - `configs/`: Chain-specific configuration files. - `contracts.yaml`: Chain-specific smart contract settings. @@ -82,7 +85,8 @@ The ecosystem configuration is spread across multiple files and directories: - `db/main/`: Database files for the chain. - `ZkStack.yaml`: Chain-specific ZkStack configuration. -These configuration files are automatically generated during the ecosystem initialization (`zkstack ecosystem init`) and chain initialization (`zkstack chain init`) processes. They control various aspects of the ZKsync ecosystem, including: +These configuration files are automatically generated during the ecosystem initialization (`zkstack ecosystem init`) and +chain initialization (`zkstack chain init`) processes. They control various aspects of the ZKsync ecosystem, including: - Network settings - Smart contract deployments @@ -90,9 +94,12 @@ These configuration files are automatically generated during the ecosystem initi - Database settings - Application/Service-specific parameters -It's important to note that while these files can be manually edited, any changes may be overwritten if the ecosystem or chain is reinitialized. Always back up your modifications and exercise caution when making direct changes to these files. +It's important to note that while these files can be manually edited, any changes may be overwritten if the ecosystem or +chain is reinitialized. Always back up your modifications and exercise caution when making direct changes to these +files. -For specific configuration needs, it's recommended to use the appropriate `zkstack` commands or consult the documentation for safe ways to customize your setup. +For specific configuration needs, it's recommended to use the appropriate `zkstack` commands or consult the +documentation for safe ways to customize your setup. ## Build and run server From 4bde05c210ec120ac57803336c4f320f74fe4ca2 Mon Sep 17 00:00:00 2001 From: Manuel Mauro Date: Tue, 12 Nov 2024 13:39:42 +0100 Subject: [PATCH 66/68] docs: give more guidance on running tests --- docs/guides/development.md | 33 ++++++++++++++++++++++++++++++--- 1 file changed, 30 insertions(+), 3 deletions(-) diff --git a/docs/guides/development.md b/docs/guides/development.md index 2fe32f13985c..fa29629f72d8 100644 --- a/docs/guides/development.md +++ b/docs/guides/development.md @@ -95,13 +95,40 @@ Currently the following criteria are checked: ## Testing -You can run tests using `zkstack dev test` subcommand. Just run: +ZKstack CLI offers multiple subcommands to run specific integration and unit test: ```bash -zkstack dev test --help` +zkstack dev test --help ``` -to see all the options. +```bash +Usage: zkstack dev test [OPTIONS] + +Commands: + integration Run integration tests + fees Run fees test + revert Run revert tests + recovery Run recovery tests + upgrade Run upgrade tests + build Build all test dependencies + rust Run unit-tests, accepts optional cargo test flags + l1-contracts Run L1 contracts tests + prover Run prover tests + wallet Print test wallets information + loadtest Run loadtest + help Print this message or the help of the given subcommand(s) +``` + +You can run unit tests for the Rust crates in the project by running: + +```bash +zkstack dev test rust +``` + +Running integration tests is more complex. Some tests require a running server, while others need the system to be in a +specific state. Please refer to our CI scripts +[ci-core-reusable.yml](https://github.com/matter-labs/zksync-era/blob/main/.github/workflows/ci-core-reusable.yml) to +have a better understanding of the process. ## Contracts From d170f4cd6e9173378362b255524a2e87264b6b6c Mon Sep 17 00:00:00 2001 From: Manuel Mauro Date: Tue, 12 Nov 2024 13:45:19 +0100 Subject: [PATCH 67/68] docs: add load test section --- docs/guides/development.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/docs/guides/development.md b/docs/guides/development.md index fa29629f72d8..c52f9978bde1 100644 --- a/docs/guides/development.md +++ b/docs/guides/development.md @@ -119,17 +119,39 @@ Commands: help Print this message or the help of the given subcommand(s) ``` +### Running unit tests + You can run unit tests for the Rust crates in the project by running: ```bash zkstack dev test rust ``` +### Running integration tests + Running integration tests is more complex. Some tests require a running server, while others need the system to be in a specific state. Please refer to our CI scripts [ci-core-reusable.yml](https://github.com/matter-labs/zksync-era/blob/main/.github/workflows/ci-core-reusable.yml) to have a better understanding of the process. +### Running load tests + +The current load test implementation only supports the legacy bridge. To use it, you need to create a new chain with +legacy bridge support: + +```bash +zk_inception chain create --legacy-bridge +zk_inception chain init +``` + +After initializing the chain with a legacy bridge, you can run the load test against it. + +```bash +zk_supervisor test loadtest +``` + +> WARNING: Never use legacy bridges in non-testing environments. + ## Contracts ### Build contracts From adbdf50fd55cd64c56741aeff355b4525ed3edc2 Mon Sep 17 00:00:00 2001 From: Manuel Mauro Date: Tue, 12 Nov 2024 13:46:30 +0100 Subject: [PATCH 68/68] docs: remove zk_inception and zk_supervisor wording --- docs/guides/development.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/guides/development.md b/docs/guides/development.md index c52f9978bde1..fb8dd44a6c7a 100644 --- a/docs/guides/development.md +++ b/docs/guides/development.md @@ -140,14 +140,14 @@ The current load test implementation only supports the legacy bridge. To use it, legacy bridge support: ```bash -zk_inception chain create --legacy-bridge -zk_inception chain init +zkstack chain create --legacy-bridge +zkstack chain init ``` After initializing the chain with a legacy bridge, you can run the load test against it. ```bash -zk_supervisor test loadtest +zkstack dev test loadtest ``` > WARNING: Never use legacy bridges in non-testing environments.