{"id":21526905,"url":"https://github.com/lambdaclass/zksync_local_stack","last_synced_at":"2026-01-04T11:08:31.891Z","repository":{"id":206039347,"uuid":"711936935","full_name":"lambdaclass/zksync_local_stack","owner":"lambdaclass","description":null,"archived":false,"fork":false,"pushed_at":"2024-01-29T17:36:00.000Z","size":8536,"stargazers_count":9,"open_issues_count":4,"forks_count":4,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-01-24T05:42:46.678Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Makefile","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lambdaclass.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-10-30T13:27:12.000Z","updated_at":"2024-09-19T08:13:03.000Z","dependencies_parsed_at":"2024-06-05T17:41:17.512Z","dependency_job_id":null,"html_url":"https://github.com/lambdaclass/zksync_local_stack","commit_stats":null,"previous_names":["lambdaclass/zksync_stack"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lambdaclass%2Fzksync_local_stack","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lambdaclass%2Fzksync_local_stack/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lambdaclass%2Fzksync_local_stack/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lambdaclass%2Fzksync_local_stack/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lambdaclass","download_url":"https://codeload.github.com/lambdaclass/zksync_local_stack/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244090797,"owners_count":20396486,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-24T01:47:12.193Z","updated_at":"2026-01-04T11:08:31.810Z","avatar_url":"https://github.com/lambdaclass.png","language":"Makefile","funding_links":[],"categories":[],"sub_categories":[],"readme":"# zkSync stack \n\n```mermaid\nflowchart LR\n    A[\"Operator\"] --\u003e |Produces block| F[Prover Gateway]\n    F --\u003e |Inserts into DB| B[\"Postgress DB\"]\n    B --\u003e |Retrieves proven block \\nafter compression| F\n    B --\u003e C[\"Witness\"]\n    C --- C1[\"Basic Circuits\"]\n    C --- C2[\"Leaf Aggregation\"]\n    C --- C3[\"Node Aggregation\"]\n    C --- C4[\"Scheduler\"]\n    C --\u003e B\n    B --\u003e D[\"Prover\"]\n    D --\u003e |Proven Block| B\n    B --\u003e E[\"Compressor\"]\n    E --\u003e |Compressed block| B\n```\n\nThe `zkSync` stack covers a set of tools designed to facilitate the interaction with the complete development cycle on the zkSync Layer-2 blockchain.\n\nThe stack consists of:\n- [Dockerized L1 node and a zkSync L2 node](https://github.com/matter-labs/zksync-era)\n- [Block explorer](https://github.com/matter-labs/block-explorer#%EF%B8%8F-setting-up-env-variables)\n- A Prometheus + Grafana setup for observability.\n- [Prover with CPU and GPU support](https://github.com/matter-labs/zksync-era/tree/main/prover)\n\n## Starting the stack\n\n**Please note that Docker and Docker-Compose are required to run the following commands.**\n\nTo get started, we need to install all the essential dependencies. You can achieve this by running the following command:\n\n```bash\nmake deps\n```\n\nThis command not only installs the necessary dependencies for running all the tools in the stack but also downloads the binaries for the `zksolc` and `solc` compilers. These compilers are crucial for executing some of the examples provided in the subsequent sections.\n\nOnce all the dependencies are successfully installed, you can initiate the entire stack with a single command:\n\n```bash\nmake run\n```\n\nThis will launch all the components of the ZKSync full stack except the prover, allowing you to dive into the development environment quickly.\n\nTo run it with the CPU prover as well, run\n\n```bash\nmake run PROVER=cpu\n```\n\ninstead. See the requirements section below to check if you meet the requirements to run in prover mode.\n\n## Requirements\n\n### CPU Prover Setup\n\n- A CPU with at least 8 physical cores.\n- 50 GB of RAM.\n- 400 GB of free disk space.\n\n### GPU Prover Setup\n\n- A CPU with at least 8 physical cores.\n- 16 GB of RAM.\n- 30 GB of free disk space.\n- An Nvidia L4/T4 GPU with 16GB of RAM\n\nThe non-prover should run on any decent modern machine.\n\n## Local Nodes\n\nThe mentioned command facilitates the creation of essential Docker containers for your development environment. This includes setting up a `PostgreSQL` database and the L1 local Geth node. Moreover, it compiles and deploys all the necessary contracts for the L2 local node to function. Please note that this process may take a moment to complete.\n\nIn this context, it's essential to mention that many of the tools used will take control of the terminal. Therefore, we've installed `tmux` in the previous step to manage different commands and sessions for each tool. For the L2 node, the session is named `zksync-server`. To view the logs and observe the server in action, you can use the following command: `tmux a -t zksync-server`.\n\nThe L1 Geth node runs at `http://localhost:8545`, while the L2 node is available at `http://localhost:3050`.\n\n## Block Explorer\n\nThe development environment includes a block explorer to inspect transactions and proofs within the nodes. This explorer runs within a `tmux` session named `zksync-explorer`. You can view it by executing the following command: `tmux a -t zksync-explorer`. To access the explorer in your web browser, navigate to `http://localhost:3010`.\n\nAdditionally, you can access the API at `http:localhost/3020` and the worker at `http://localhost:3001`.\n\n## Grafana and Observability\n\nOther Docker containers are running Grafana and Prometheus, tools for monitoring and creating dashboards. To access a helpful dashboard that provides information about every transaction executed by the node, open your web browser and visit `http://localhost:3000`. Once in that page, click on the hamburger menu on the top left of the screen, on the menu that will slide on, head on over to \"Dashboards\" to see the available dashboards. You can also use the python script `automate_transactions.py` to generate data.\n\n## Prover\n\nWhen the stack is initiated in prover mode, various binaries execute, each containing one of the tools involved in the process of block proof generation. Here's a list of all the binaries and different components being executed, along with their corresponding `tmux` session since all these components take control of the terminal:\n\n- **Prover**: The main prover. The `tmux` session for this part is `zksync-prover`.\n- **Prover gateway**: Acts as a communication layer between the server running the state keeper and the proving subsystem. The `tmux` session for this part is `zksync-prover-gateway`.\n- **Witness generator**: Responsible for creating prover jobs. The `tmux` session for this part is `zksync-witness-generator`.\n- **Proof compressor**: The final step that compresses/wraps the FRI proof into a SNARK. The `tmux` session for this part is `zksync-block-compressor`.\n\n## Deployment and Contract Interaction\n\nTo begin testing the local nodes and interacting with them, this repository offers a basic `ERC20` contract for your use.\n\nTo deploy the contract and call its functions, start by cloning the [zksync-era-cli](https://github.com/lambdaclass/zksync_era_cli) tool repository. This tool provides a range of useful commands, but for this example, you'll primarily use `deploy`, `call` and `send` commands.\n\nIn all the following examples, we'll rely on a specific private key: `0x27593fea79697e947890ecbecce7901b0008345e5d7259710d0dd5e500d040be`. This key belongs to one of the rich wallets deployed in the local node for testing purposes. The address derived from this private key is `0xde03a0b5963f75f1c8485b355ff6d30f3093bde7`, we use it as argument for the constructor to initialize with a certain number of tokens. \n\nOnce the node is up and running, use the following command to deploy our `ERC20` contract, a standard token:\n\n```bash\nzksync-era-cli --l2-port 3050 deploy \\\n--project-root contracts/ \\\n--contract contracts/ERC20.sol \\\n--contract-name ERC20 \\\n--constructor-args 0xde03a0b5963f75f1c8485b355ff6d30f3093bde7 \\\n--private-key 0x27593fea79697e947890ecbecce7901b0008345e5d7259710d0dd5e500d040be \\\n--chain-id 270\n```\n\nIf the deployment is successful, you'll receive the transaction receipt and an output similar to this:\n\n```\nINFO: `0x...`\n```\n\nThis address represents where the contract is now deployed. After deploying the contract, you can interact with it in various ways. For instance, you can retrieve the name of the deployed token by calling the following function:\n\n```bash\nzksync-era-cli --l2-port 3050 call \\\n--contract \u003caddress\u003e \\\n--function \"name()\" \\\n--output-types string \\\n--chain-id 270\n```\n\nWhere the `address` corresponds to the address of the deployed `ERC20` contract.\nThe output will look like this:\n\n```\nINFO: String(`lambdacoin`)\n```\n\nThis is the initial name of your token. Additionally, you can examine the initial balance of the address you passed as an argument for deployment using the `constructor-args` flag. To check the initial balance, execute the following command:\n\n```bash\nzksync-era-cli --l2-port 3050 call \\\n--contract \u003caddress\u003e \\\n--function \"balanceOf(address)\" \\\n--args \"0xde03a0b5963f75f1c8485b355ff6d30f3093bde7\" \\\n--output-types uint256 \\\n--chain-id 270\n```\n\nThe output will look like this:\n\n```\nINFO: UINT256(1000000)\n```\n\nThis indicates the initial balavnce of the specified address: 1,000,000 tokens.\n\nThere's another function to transfer some of the tokens to another address, in order to do that we will send a transaction calling that function.\n\n```bash\nzksync-era-cli --l2-port 3050 send \\\n--contract \u003caddress\u003e \\\n--function \"transfer(address, uint256)\" \\\n--args \u003cto_address\u003e 200 \\\n--output-types bool \\\n--private-key 0x27593fea79697e947890ecbecce7901b0008345e5d7259710d0dd5e500d040be \\\n--chain-id 270\n```\n\nWhere the `to_address` would be the receiver address.\nThe output should look like the following:\n\n```\nINFO: `0x...`\n```\n\nRepresenting the hash of the executed transaction.\n\n## Validium Mode\n\nDisclaimer: this feature is still in early development, expect bugs and missing features.\n\nThe stack can be run in `Validium mode`. In this mode, data availability is pushed to the L2, which means state diffs are not stored on the L1 anymore. To run the stack in validium mode, pass the `VALIDIUM` flag as `true` to the `deps` target, like so:\n\n```bash\nmake deps VALIDIUM=true\n```\n\nYou can find more info on validium mode [here](https://github.com/matter-labs/zksync-era/pull/459).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flambdaclass%2Fzksync_local_stack","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flambdaclass%2Fzksync_local_stack","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flambdaclass%2Fzksync_local_stack/lists"}