{"id":30105678,"url":"https://github.com/dutterbutter/zkstack-cli","last_synced_at":"2025-08-10T00:17:39.131Z","repository":{"id":302699689,"uuid":"1013345541","full_name":"dutterbutter/zkstack-cli","owner":"dutterbutter","description":"Fork mirror of zkstack-cli from zksync-era repo ","archived":false,"fork":false,"pushed_at":"2025-08-04T04:01:18.000Z","size":1072,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-04T07:25:05.060Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","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/dutterbutter.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"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,"zenodo":null}},"created_at":"2025-07-03T18:38:40.000Z","updated_at":"2025-07-04T13:33:45.000Z","dependencies_parsed_at":"2025-08-04T06:06:01.212Z","dependency_job_id":"035d8d1d-9e45-45d8-b4c8-aeabf4b0ce72","html_url":"https://github.com/dutterbutter/zkstack-cli","commit_stats":null,"previous_names":["dutterbutter/zkstack-cli"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/dutterbutter/zkstack-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dutterbutter%2Fzkstack-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dutterbutter%2Fzkstack-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dutterbutter%2Fzkstack-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dutterbutter%2Fzkstack-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dutterbutter","download_url":"https://codeload.github.com/dutterbutter/zkstack-cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dutterbutter%2Fzkstack-cli/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269656418,"owners_count":24454640,"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","status":"online","status_checked_at":"2025-08-09T02:00:10.424Z","response_time":111,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":"2025-08-10T00:17:34.306Z","updated_at":"2025-08-10T00:17:38.936Z","avatar_url":"https://github.com/dutterbutter.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ZK Stack CLI\n\nToolkit for creating and managing ZK Stack chains. `ZK Stack CLI` facilitates the creation and management of ZK Stack\necosystems. Commands are interactive but can also accept arguments via the command line.\n\n### Dependencies\n\nFollow [these instructions](https://github.com/matter-labs/zksync-era/blob/main/docs/src/guides/setup-dev.md) to set up\ndependencies on your machine. Ignore the Environment section for now.\n\n### Installation\n\nYou can use `zkstackup` to install and manage `zkstack`:\n\n```bash\ncurl -L https://raw.githubusercontent.com/matter-labs/zksync-era/main/zkstack_cli/zkstackup/install | bash\n```\n\nThen install the most recent version with:\n\n```bash\nzkstackup\n```\n\nOr manually build from a local copy of the [ZKsync](https://github.com/matter-labs/zksync-era/) repository:\n\n```bash\nzkstackup  --local\n```\n\nThis command installs `zkstack` from the current repository.\n\n#### Manual installation\n\nRun from the repository root:\n\n```bash\ncargo install --path zkstack_cli/crates/zkstack --force --locked\n```\n\nAnd make sure that `.cargo/bin` is included into `PATH`.\n\n### Foundry Integration\n\nFoundry is used for deploying smart contracts. Pass flags for Foundry integration with the `-a` option, e.g.,\n`-a --gas-estimate-multiplier=500`.\n\n### Ecosystem\n\nZK Stack allows you to create a new ecosystem or connect to an existing one. An ecosystem includes components like the\nBridgeHub, shared bridges, and state transition managers. Multiple ZK chains can be registered to an ecosystem.\n[Learn more](https://docs.zksync.io/zk-stack/components/shared-bridges).\n\n#### Global Config\n\n- `--verbose`: Show all output from all commands.\n- `--chain`: Use a specific chain for ecosystem operations.\n- `--ignore-prerequisites`: Do not verify prerequisites. !!!WARNING!!! This option won't show errors if required tools\n  for network deployment and operation are missing.\n\n#### Create\n\nTo create a ZK Stack project, start by creating an ecosystem:\n\n```bash\nzkstack ecosystem create\n```\n\nIf you choose not to start database \u0026 L1 containers after creating the ecosystem, you can later run:\n\n```bash\nzkstack containers\n```\n\nExecute subsequent commands from within the created ecosystem folder:\n\n```bash\ncd path/to/ecosystem/name\n```\n\n#### Init\n\nIf the ecosystem has never been deployed before, initialize it:\n\n```bash\nzkstack ecosystem init\n```\n\nThis initializes the first ZK chain, which becomes the default. Override with `--chain \u003cname\u003e` if needed. For default\nparams, use:\n\n```bash\nzkstack ecosystem init --dev\n```\n\nIf the process gets stuck, resume it with `--resume`. This flag keeps track of already sent transactions and sends new\nones with provided params.\n\n#### Verifying Contracts\n\nTo verify contracts, use the `--verify` flag.\n\n- `--verifier name`: Verification provider. Options: etherscan, sourcify, blockscout (default: etherscan). Note: Add \"\n  /api?\" to the end of the Blockscout homepage explorer URL.\n- `--verifier-url` url: Optional verifier URL for submitting the verification request.\n- `--verifier-api-key`: Verifier API key.\n\n#### Changing Default Chain\n\nTo change the default ZK chain:\n\n```bash\nzkstack ecosystem change-default-chain\n```\n\nIMPORTANT: Currently, you cannot use an existing ecosystem to register a new chain. This feature will be added in the\nfuture.\n\n#### Observability\n\nTo setup [era-observability](https://github.com/matter-labs/era-observability):\n\n```bash\nzkstack ecosystem setup-observability\n```\n\nOr run:\n\n```bash\nzkstack ecosystem init --observability\n```\n\nTo start observability containers:\n\n```bash\nzkstack containers --observability\n```\n\n### ZK Chain\n\n#### Create\n\nThe first ZK chain is generated upon ecosystem creation. You can also create additional chains and switch between them:\n\n```bash\nzkstack chain create\n```\n\n#### Init\n\nDeploy contracts and initialize ZK chain:\n\n```bash\nzkstack chain init\n```\n\nThis registers the chain in the BridgeHub and deploys all necessary contracts. Manual initialization steps:\n\n`init`: Register in BridgeHub, deploy L2 contracts, and create genesis (preferred method). `deploy-l2-contracts`: Deploy\nL2 bridge and Default Upgrade Contracts. `initialize-bridges`: Deploy L2 bridge. `upgrader`: Deploy Default Upgrade\nContract. `deploy-paymaster`: Deploy paymaster. `genesis`: Run genesis after deploying contracts (preferred if deployed\nby a third party).\n\n### ZK Server\n\nTo run the chain:\n\n```bash\nzkstack server\n```\n\nYou can specify the component you want to run using `--components` flag\n\nSpecify the chain with `--chain \u003cchain_name\u003e`.\n\n### Prover\n\n#### Requirements\n\nEnsure you have installed:\n\n- [gcloud](https://cloud.google.com/sdk/docs/install)\n- [wget](https://www.gnu.org/software/wget/)\n- [cmake](https://apt.kitware.com/)\n- [nvcc (CUDA toolkit)](https://developer.nvidia.com/cuda-downloads)\n\nRefer to the [prover docs](https://github.com/matter-labs/zksync-era/blob/main/prover/docs/src/02_setup.md) for more\ninformation.\n\n#### Running the Prover\n\nInitialize the prover:\n\n```bash\nzkstack prover init\n```\n\nRun the prover:\n\n```bash\nzkstack prover run\n```\n\nSpecify the prover component with `--component \u003ccomponent\u003e`. Components:\n`gateway, witness-generator, witness-vector-generator, prover, compressor`.\n\nFor `witness-vector-generator`, specify the number of WVG jobs with `--threads \u003cthreads\u003e`.\n\nFor `witness-generator`, specify the round with `--round \u003cround\u003e`. Rounds:\n`all-rounds, basic-circuits, leaf-aggregation, node-aggregation, recursion-tip, scheduler`.\n\n### Migrating to and from Gateway\n\nzkstack_cli provides several commands for migrating to and from ZK Gateway. To get the full list of commands, please\nuse:\n\n```bash\nzkstack chain gateway --help\n```\n\nTo get params of each of the provided commands, please use `--help`.\n\n\u003e Note that at the time of this writing, ZK Gateway is not available yet on public networks\n\n#### Migrating to Gateway\n\nFirstly, we need to generate the calldata to notify the server:\n\n```bash\nzkstack chain gateway notify-about-to-gateway-update-calldata\n```\n\nIt will provide you with the calldata to call the chain admin with to notify the server about imminent migration on top\nof Gateway. This is a step needed to ensure smooth migration.\n\n\u003e Note that even though the notification step is not strictly necessary, it is required for the server to migrate\n\u003e properly and the zkstack_cli tool may not be ready to handle migrations without a priority notification.\n\nSecondly, you will have to generate the calldata to start the actual migration:\n\n```bash\nzkstack chain gateway migrate-to-gateway-calldata\n```\n\nNote that by default this command will check the status of the migration to Gateway and will only output the calldata\nafter the notification has passed and the server is ready to migrate. To prepare the calldata even before the server is\nready (helpful for multisigs), please provide `--no-cross-check` option.\n\nFor `--gateway-config-path` please use the corresponding files for ZK Gateway inside the `./etc/env/ecosystems/gateway`\nfolder.\n\nWhen the calldata for the migration to the ZK Gateway is executed, it will generate the following L1-\u003eGW transactions:\n\n- One from the L1 asset router (to migrate the chain).\n- The other ones from the chain admin.\n\nTo track their status, please use the standard tool to track L2 txs status described\n[here](#tracking-l1-l2-transactions-status).\n\n#### Migrate from Gateway\n\nFirstly, we need to generate the calldata to notify the server:\n\n```bash\nzkstack chain gateway notify-about-from-gateway-update-calldata\n```\n\nIt will provide you with the calldata to call the chain admin with to notify the server about imminent migration on top\nof Gateway. This is a step needed to ensure smooth migration.\n\n\u003e Note that even though the notification step is not strictly necessary, it is required for the server to migrate\n\u003e properly and the zkstack_cli tool may not be ready to handle migrations without a priority notification.\n\nAfter that, you will need to prepare the calldata to finalize the migration:\n\n```bash\nzkstack chain gateway migrate-from-gateway-calldata\n```\n\nFor `--ecosystem-contracts-config-path` please use the corresponding file inside the `./etc/env/ecosystems` folder.\n\nNote that by default this command will check the status of the migration from Gateway and will only output the calldata\nafter the notification has passed and the server is ready to migrate. To prepare the calldata even before the server is\nready (helpful for multisigs), please provide `--no-cross-check` option.\n\nWhen the calldata for the migration from the ZK Gateway is executed, it will generate the L1-\u003eGW transactions from the\nL1 chain admin to the chain's diamond proxy on ZK Gateway. To track its status, please use the standard tool to track L2\ntxs status described [here](#tracking-l1-l2-transactions-status).\n\nAfter the migration transaction is processed and the corresponding GW batch is finalized on L1, anyone can finalize the\nmigration:\n\n```bash\nzkstack chain gateway finalize-chain-migration-from-gateway\n```\n\nNote that after migration to L1, the DA validators will be reset. To generate the calldata to reset the DA validators,\ndo the following:\n\n```bash\nzkstack chain set-da-validator-pair-calldata\n```\n\n\u003e So when preparing a migration from GW for a multisig-controlled ChainAdmin, the calldata for the following steps\n\u003e should be signed as different transactions: the notification, the migration and the setting of the DA validators.\n\n### Contract Verifier\n\nDownload required binaries (`solc`, `zksolc`, `vyper`, `zkvyper`):\n\n```bash\nzkstack contract-verifier init\n```\n\nRun the contract verifier:\n\n```bash\nzkstack contract-verifier run\n```\n\n### External Node\n\nCommands for running an external node:\n\n#### Configs\n\nPrepare configs:\n\n```bash\nzkstack en configs\n```\n\nThis ensures no port conflicts with the main node.\n\n#### Init\n\nPrepare the databases:\n\n```bash\nzkstack en init\n```\n\n#### Run\n\nRun the external node:\n\n```bash\nzkstack en run\n```\n\n### Portal\n\nOnce you have at least one chain initialized, you can run the [portal](https://github.com/matter-labs/dapp-portal) - a\nweb-app to bridge tokens between L1 and L2 and more:\n\n```bash\nzkstack portal\n```\n\nThis command will start the dockerized portal app using configuration from `apps/portal.config.json` file inside your\necosystem directory. You can edit this file to configure the portal app if needed. By default, portal starts on\n`http://localhost:3030`, you can configure the port in `apps.yaml` file.\n\n### Explorer\n\nFor better understanding of the blockchain data, you can use the\n[explorer](https://github.com/matter-labs/block-explorer) - a web-app to view and inspect transactions, blocks,\ncontracts and more.\n\nFirst, each chain should be initialized:\n\n```bash\nzkstack explorer init\n```\n\nThis command creates a database to store explorer data and generatesdocker compose file with explorer services\n(`explorer-docker-compose.yml`).\n\nNext, for each chain you want to have an explorer, you need to start its backend services:\n\n```bash\nzkstack explorer backend --chain \u003cchain_name\u003e\n```\n\nThis command uses previously created docker compose file to start the services (api, data fetcher, worker) required for\nthe explorer.\n\nFinally, you can run the explorer app:\n\n```bash\nzkstack explorer run\n```\n\nThis command will start the dockerized explorer app using configuration from `apps/explorer.config.json` file inside\nyour ecosystem directory. You can edit this file to configure the app if needed. By default, explorer starts on\n`http://localhost:3010`, you can configure the port in `apps.yaml` file.\n\n### Update\n\nTo update your node:\n\n```bash\nzkstack update\n```\n\nThis command pulls the latest changes, syncs the general config for all chains, and raises a warning if L1 upgrades are\nneeded.\n\n## Dev\n\nThe subcommand `zkstack dev` offers tools for developing.\n\n### Database\n\nCommands for database manipulation:\n\n```bash\nzkstack dev db\n```\n\nPossible commands:\n\n- `check-sqlx-data`: Check if sqlx-data.json is up to date.\n- `drop`: Drop databases.\n- `migrate`: Migrate databases.\n- `new-migration`: Create a new migration.\n- `prepare`: Prepare sqlx-data.json.\n- `reset`: Reset databases.\n- `setup`: Set up databases.\n\n### Clean\n\nClean artifacts:\n\n```bash\nzkstack dev clean\n```\n\nPossible commands:\n\n- `all`: Remove containers and contracts cache.\n- `containers`: Remove containers and Docker volumes.\n- `contracts-cache`: Remove contracts cache.\n\n### Tests\n\nRun ZKsync tests:\n\n```bash\nzkstack dev test\n```\n\nPossible commands:\n\n- `integration`: Run integration tests.\n- `revert`: Run revert tests.\n- `recovery`: Run recovery tests.\n- `upgrade`: Run upgrade tests.\n- `rust`: Run unit tests.\n- `l1-contracts`: Run L1 contracts tests.\n- `prover`: Run prover tests.\n\n### Snapshot Commands\n\nCreate a snapshot of the current chain:\n\n```bash\nzkstack dev snapshot create\n```\n\n### Contracts\n\nBuild contracts:\n\n```bash\nzkstack dev contracts\n```\n\n### Format\n\nFormat code:\n\n```bash\nzkstack dev fmt\n```\n\nBy default, this command runs all formatters. To run a specific fomatter use the following subcommands:\n\n- `rustfmt`: Runs `cargo fmt`.\n- `prettier`: Runs `prettier`.\n- `contract`: Runs `prettier` on contracts.\n\n### Lint\n\nLint code:\n\n```bash\nzkstack dev lint\n```\n\nBy default, this command runs the linter on all files. To target specific file types, use the `--target` option.\nSupported extensions include:\n\n- `rs`: Rust files.\n- `md`: Markdown files.\n- `sol`: Solidity files.\n- `js`: JavaScript files.\n- `ts`: TypeScript files.\n- `contracts`: files in `contracts` directory.\n\n### Tracking L1-\u003eL2 transactions status\n\nUse the following command to track L1-\u003eL2 (or L1-\u003eGW) transactions that came out of a certain address / l1 transaction\nhash, etc:\n\n```\nzkstack dev track-priority-ops\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdutterbutter%2Fzkstack-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdutterbutter%2Fzkstack-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdutterbutter%2Fzkstack-cli/lists"}