The zkSync Era Upgrade Verification Tool is a CLI tool crafted to decode and present zkSync Era upgrade proposals in a human-readable format.
๐๏ธ
Work In Progress
: This repo is being actively developed and does not represent final quality of the tool!
- [L1] Facets: Identifies contract upgrades including additions or removals of functions.
- [L1] Verifier : Detects upgrades and parameter changes in contracts.
- [L2] System Contracts: Lists changes and validates bytecode hashes.
- [L2] Bootloader and DefaultAccount: Validates bytecode hash.
- Solidity Diff Tool: Compares current contracts with upgrade proposals for verification. Currently available for Facets, Verifier & System Contracts.
node --version # Checks the installed version of Node.js
pnpm --version # Checks the installed version of pnpm
yarn --version # Checks the installed version of yarn
If you do not have Node.js installed, please install it from nodejs.org. For example:
brew install node
If you do not have pnpm
installed, please install it from pnpm installation guide. For example:
npm install -g pnpm
If you do not have yarn
installed, please install it from yarn installation guide. For example:
npm install -g yarn
For the <upgradeDir>
parameter, you need access to a upgrade directory. For example, zksync-era upgrades directory
You can clone zkSync Era Repo to access this directory:
git clone https://github.com/matter-labs/zksync-era.git
Later you can define the target <upgradeDir>
in tool commands using the path to a specific upgrade, for example:
path-to-directory/zksync-era/etc/upgrades/1699353977-boojum
git clone https://github.com/Moonsong-Labs/era-l1-upgrade-checker.git && cd era-l1-upgrade-checker
pnpm install
pnpm build
You can create an Etherscan API key at Etherscan API Key.
export ETHERSCAN_API_KEY="<your_etherscan_api_key>"
Alternatively, you can copy env.example file and complete it with your keys:
cp env.example .env
This file should contain the following entries:
# .env
ETHERSCAN_API_KEY=your_etherscan_api_key
You can also specify your API keys directly as command line arguments when running commands that require them. For example:
pnpm validate --ethscanApiKey=your_etherscan_api_key
The zkSync Era Upgrade Verification Tool provides a range of commands for interacting with and verifying zkSync protocol upgrade data.
*Etherscan API Key required.
Checks the validity of the upgrade and prints a summary of the changes.
pnpm validate check <upgradeDir>
pnpm validate check ../zksync-era/etc/upgrades/1699353977-boojum #Example of check command with Boojum upgrade.
Shows the proposed changes in a specified facet.
pnpm validate show-diff <upgradeDir> <facetName>
pnpm validate facet-diff ../zksync-era/etc/upgrades/1699353977-boojum GettersFacet --ref=e77971dba8f589b625e72e69dd7e33ccbe697cc0 #Example with GettersFacet in Boojum upgrade with specific commit reference.
Shows the proposed changes between current verifier source code and the proposed one.
pnpm validate verifier-diff <upgradeDir>
pnpm validate verifier-diff ../zksync-era/etc/upgrades/1699353977-boojum #Example of verifier-diff command for Boojum upgrade.
Downloads both the current and proposed versions of each contract being upgraded for comparison.
-
Run the Command:
pnpm validate download-diff <upgradeDir> <targetSourceCodeDir>
<targetSourceCodeDir>
: The directory where you wish to save the downloaded differences.Note: Depending on the specific upgrade referenced, the
--ref
option might be necessary. For more info, please refer to --ref in options section. -
Navigate to Directory: After running the command, navigate to the
<targetSourceCodeDir>
directory.
- Use Your Preferred Diff Tool: Once in the
<targetSourceCodeDir>
, you can use your preferred diff tool to compare the 'old' (current) versus 'new' (upgrade) directory structure or specific files.- For example:
diff -r old new
meld old new
vimdiff old new
- For example:
The following options are available to configure the zkSync Era Upgrade Verification Tool:
Specifies the target network where the tool will perform the checks.
- Values:
mainnet
,sepolia
- Default:
mainnet
- Example: Protodanksharding upgrade in sepolia
pnpm validate check ../zksync-era/etc/upgrades/1709067445-protodanksharding --network=sepolia
Specifies the Ethereum RPC URL to be used for connecting to the blockchain.
- Default:
mainnet
:https://ethereum-rpc.publicnode.com
sepolia
:https://ethereum-sepolia-rpc.publicnode.com
Specifies the GitHub commit reference from which the L2 code will be downloaded.
-
Default: The last commit on the
main
branch. -
Example:
--ref
to commit (related toboojum
upgrade indownload_dif
command).pnpm validate download-diff ../zksync-era/etc/upgrades/1699353977-boojum boojumDiff --ref=e77971dba8f589b625e72e69dd7e33ccbe697cc0
help
: Provides usage information and displays help for all commands.
pnpm validate help
Unit tests are located inside the cli package. To run:
pnpm run --filter=./cli test
Integration tests are inside "test" package. In order to run them it's important to config api keys for testing. That can be done with a dotenv file inside the test directory:
cp env.example test/.env
vim .env # complete with real api keys
Once it's completed you can run the integration tests with:
pnpm run --filter=./test test
Lastly, this command will execute all automated tests associated with the tool:
pnpm test
-
Extended Support for L2 Upgrades: We plan to expand the capabilities of the Solidity Diff Tool to include Bootloader and DefaultAccount contracts.
-
Improve Error Handling: We plan to improve error messages and handling throughout the tool.
-
Add HTML File Output Option: Implementing HTML file output option to improve diff visualization and user experience.
We welcome community feedback and suggestions which can be submitted via our GitHub repository.
This project is licensed under the MIT License. For more details, see the LICENSE file in the repository.