Update verification keys
Updates era-contracts repository with new set of verification keys generated from the latest ZKsync OS binary and trusted setup.
Use this script when you need to update verification keys for your contracts after a new ZKsync OS or contracts release.
Usually, the script is used by the protocol upgrade operator or automation to perform the protocol upgrade.
Script performs the following steps:
- Downloads the trusted setup (CRS) file
- Downloads the updated ZKsync OS binary for a specified release tag
- Generates a new SNARK verification key using the trusted setup and ZKsync OS binary
- Regenerates verifier smart contracts
- Produces updated Solidity verifier contracts for ZKsync OS
- Recomputes contracts hashes affected by the verifier changes
The script updates the following files in the era-contracts repository:
l1-contracts/contracts/state-transition/verifiers/ZKsyncOSVerifierPlonk.sol- Plonk verifier contracttools/verifier-gen/data/ZKsyncOS_plonk_scheduler_key.json- Plonk verifier key dataAllContractsHashes.json- recomputed contract hashes
Here is an example of a successful commit for the reference.
Commit example here is just for the reference.
The script itself does not perform any git operations (commit/push/PR creation). It is expected that the caller (manual operator or automation) will handle these operations after the script successfully completes.
Local use
REPO_DIR="/path/to/era-contracts" \
ZKOS_WRAPPER_PATH="/path/to/zkos-wrapper" \
ZKSYNC_OS_TAG=latest \
uv run -m scripts.update_vk
To run the script, you will need:
- General prerequisites including uv, Rust and NodeJS
- Specific release tag of ZKsync OS from
zksync-osreleases specified throughZKSYNC_OS_TAGenv variable
In addition, the script requires access to the following repositories, which should be specified via corresponding path environment variables:
| Repository | Env Variable | Protocol version → Branch Mapping |
|---|---|---|
| era-contracts | REPO_DIR | v30.2 → zksync-os-stablev31.0 → draft-v31-with-zksync-os |
| zkos-wrapper | ZKOS_WRAPPER_PATH | all versions → main (latest) |
Please, additionally check protocol compatibility to ensure the correct versions are used.
GitHub Actions
The script supports execution via GitHub Actions update-vk.yaml workflow
that can be triggered manually via GitHub Actions UI interface.
Input parameters
| Name | Required | Description |
|---|---|---|
protocol_version | ✅ | Protocol version to update verification keys for. |
zksync_os_tag | ✅ | Git tag of zksync-os used to generate the keys. |
era_contracts_branch | ❌ | Explicit era-contracts branch. Defaults to protocol mapping. |
zkos_wrapper_version | ❌ | Explicit zkos-wrapper version. Defaults to protocol mapping. |
commit_changes | ❌ | Whether to commit the updated keys. Defaults to true. |
open_pr | ❌ | Whether to open a PR. Defaults to true. |
Follow more detailed tutorial in the GitHub Actions guide.
Outputs
On successful runs, the workflow uploads contracts_<protocol_version>.patch Git patch file with the changes made to the era-contracts repository.
If commit_changes and open_pr are set to true, a PR is opened automatically with the changes.
On failed runs, the workflow saves logs from the workspace .logs directory as an artifact.
Script dependencies
The script relies on the following external resources:
- Trusted setup CRS file
setup_2^24.key - ZKsync OS
multiblock_batch.binbinary from zksync-os releases - zkos-wrapper part to generate verification keys
- Plonk and Flonk verifier contract generator
recompute_hashes.shscript to recompute contract hashes after update
If the script fails, it means that one of the dependencies is changed or unavailable. In this case, the script needs to be updated accordingly.
- CRS checksum mismatch → trusted setup file updated upstream
- To fix: check with DevOps, and update the expected checksum in the script
- Contracts regeneration failure → incompatible tooling on the
era-contractsbranch- To fix: align new
era-contractstooling updates with the scripts
- To fix: align new