@matterlabs/hardhat-zksync-upgradable
Advanced tools
Readme
zkSync Era's Hardhat plugin to deploy and upgrade smart contracts easily.
Ensure you are using the correct version of the plugin with ethers:
For plugin version <1.0.0:
For plugin version ≥1.0.0:
To install hardhat-zksync-upgradable plugin, run:
npm install -D @matterlabs/hardhat-zksync-upgradable
or
yarn add -D @matterlabs/hardhat-zksync-upgradable @openzeppelin/contracts @openzeppelin/contracts-upgradeable
The plugin supports three types of proxies: Transparent upgradable proxies, UUPS proxies, and beacon proxies.
Upgradability methods are all part of the zkUpgrades property in the HardhatRuntimeEnvironment and you only need to interact with it in order to deploy or upgrade your contracts.
To deploy a simple upgradable contract on zkSync Era local setup, first create a test wallet and add it to the new Deployer. After that, load the your contract artifact and call the deployProxy method from the zkUpgrades hre property.
const zkWallet = new Wallet("PRIVATE_KEY");
const deployer = new Deployer(hre, zkWallet);
const contract = await deployer.loadArtifact("YourContractName");
await hre.zkUpgrades.deployProxy(deployer.zkWallet, contract, [initializerFunctionArguments], { initializer: "initialize" });
The deployProxy method deploys your implementation contract on zkSync Era, deploys the proxy admin contract, and finally, deploys the transparent proxy.
The UUPS proxy pattern is similar to the transparent proxy pattern, except that the upgrade is triggered via the logic contract instead of from the proxy contract. To deploy the UUPS contract, use the same script as for the transparent upgradable proxy. When you run the script, the plugin detects that the proxy type is UUPS, it executes the deployment, and saves the deployment info in your manifest file.
Beacon proxies enable a more advanced upgrade pattern, where multiple implementation contracts can be deployed and "hot-swapped" on the fly with no disruption to the contract's operation.
Start by creating a Deployer for the zkSync Era network and load the Box artifact:
In order for a smart contract implementation to be upgradable, it has to follow specific rules.
To upgrade the implementation of the transparent upgradeable contract, use the upgradeProxy method from the zkUpgrades.
const myContractV2 = await deployer.loadArtifact('contractV2');
await hre.zkUpgrades.upgradeProxy(deployer.zkWallet, <PROXY_ADDRESS>, myContractV2);
Similar to the deployment script, there are no modifications needed to upgrade the implementation of the UUPS contract, compared to upgrading the transparent upgradable contract.
Beacon proxy implementation can be upgraded using a similarly structured method from the zkUpgrades called upgradeBeacon
const myContractV2 = await deployer.loadArtifact('contractV2');
await hre.zkUpgrades.upgradeBeacon(deployer.zkWallet, <BEACON_PROXY_ADDRESS>, myContractV2);
The hardhat-zksync-upgradable plugin supports proxy verification, which means you can verify all the contracts deployed during the proxy deployment with a single verify command. Check how to verify on this link
The hardhat-zksync-upgradable plugin has built-in checks to ensure that your smart contract's newest implementation version follows the necessary requirements when upgrading your smart contract.
You can learn more about what those restrictions are in OpenZeppelin's documentation.
Should you wish to estimate the total gas used throughout the proxy deployment process, consider utilizing the upgradable plugin's gas estimation functions. We offer three types of gas estimation functions for your convenience:
To estimate the deployment fee for the Transparent upgradable proxies and UUPS proxies, use the estimateGasProxy method from the zkUpgrades.estimation. This method calculates the fee for deploying the implementation contract, transparent proxy/UUPS contract, and the ProxyAdmin smart contract.
const totalGasEstimation = await hre.zkUpgrades.estimation.estimateGasProxy(deployer, contract, [], { kind: "transparent" });
To estimate the deployment fee for the beacon contract and its corresponding implementation, use the estimateGasBeacon method:
const totalGasEstimation = await hre.zkUpgrades.estimation.estimateGasBeacon(deployer, contract, []);
If you want to get the estimation for the beacon proxy contract, please use the estimateGasBeaconProxy method:
const totalGasEstimation = await hre.zkUpgrades.estimation.estimateGasBeacon(deployer, contract, []);
Please consider that while the provided commands enable contract deployment and upgrading, not all arguments may be available. If these commands lack the required functionality, it may be necessary to utilize scripting for a more comprehensive approach.
To extend the configuration to support commands, we need to add an accounts field to the specific network configuration in the networks section of the hardhat.config.ts file. This accounts field can support an array of private keys or a mnemonic object and represents accounts that will be used as wallet automaticlly.
const config: HardhatUserConfig = {
networks: {
sepolia: {
url: "https://sepolia.infura.io/v3/<API_KEY>" // The Ethereum Web3 RPC URL (optional).
},
zkTestnet: {
url: "https://sepolia.era.zksync.dev", // The testnet RPC URL of zkSync Era network.
ethNetwork: "sepolia", // The Ethereum Web3 RPC URL, or the identifier of the network (e.g. `mainnet` or `sepolia`)
zksync: true,
// ADDITON
// The private keys for the accounts used in the deployment or in the upgradation process.
accounts: ['0xac1e735be8536c6534bb4f17f06f6afc73b2b5ba84ac2cfb12f7461b20c0bbe3', '0x28a574ab2de8a00364d5dd4b07c4f2f574ef7fcc2a86a197f65abaec836d1959'],
// Mnemonic used in the deployment or in the upgradation process
// accounts: {
// mnemonic: 'stuff slice staff easily soup parent arm payment cotton trade scatter struggle'
// }
}
},
};
accounts object will be automaticly be populated with rich accounts if used network is zkSync Era Test Node or zksync-cli Local Node
To establish a default index per network, which is by default 0, you can include a deployerAccounts section in your hardhat.config.ts file.
const config: HardhatUserConfig = {
// ADDITON
deployerAccounts: {
'zkTestnet': 1, // The default index of the account for the specified network.
//default: 0 // The default value for not specified networks. Automatically set by plugin to the index 0.
},
networks: {
sepolia: {
url: "https://sepolia.infura.io/v3/<API_KEY>" // The Ethereum Web3 RPC URL (optional).
},
zkTestnet: {
url: "https://sepolia.era.zksync.dev", // The testnet RPC URL of zkSync Era network.
ethNetwork: "sepolia", // The Ethereum Web3 RPC URL, or the identifier of the network (e.g. `mainnet` or `sepolia`)
zksync: true,
// The private keys for the accounts used in the deployment process.
accounts: ['0xac1e735be8536c6534bb4f17f06f6afc73b2b5ba84ac2cfb12f7461b20c0bbe3', '0x28a574ab2de8a00364d5dd4b07c4f2f574ef7fcc2a86a197f65abaec836d1959'],
// Mnemonic used in the deployment process
// accounts: {
// mnemonic: 'stuff slice staff easily soup parent arm payment cotton trade scatter struggle'
// }
}
},
};
deployerAccounts represents an object where the default index of the accounts is provided and automatically used in the upgradable commands described below. If the network name is not specified inside the object, the default index of the account will be 0. We can change and deafult index for not specified networks if we override default name with index that we want.yarn hardhat deploy-zksync:proxy --contract-name <contract name or FQN> [<constructor arguments>] [--constructor-args <javascript module name>] [--deployment-type <deployment type>] [--initializer <initialize method>] [--no-compile]
When executed, this command will automatically determine whether the deployment is for a Transparent or UUPS proxy. If the Transparent proxy is chosen, it will deploy implementation, admin, and proxy. If the UUPS proxy is chosen, it will deploy implementation and proxy.
yarn hardhat upgrade-zksync:proxy --contract-name <contract name or FQN> --proxy-address <proxy address> [--deployment-type <deployment type>] [--no-compile]
When executed, this command upgrade UUPS or Transparent implementation.
To upgrade a implementation we need to specify proxy address, add --proxy-address <proxy address> argument, e.g. yarn hardhat upgrade-zksync:proxy --contract-name BoxV2 --proxy-address 0x4bbeEB066eD09B7AEd07bF39EEe0460DFa261520.
yarn hardhat deploy-zksync:beacon --contract-name <contract name or FQN> [<constructor arguments>] [--constructor-args <javascript module name>] [--deployment-type <deployment type>] [--initializer <initialize method>] [--no-compile]
When executed, this command deploys the provided implementation, beacon and proxy on the specified network, using the provided contract constructor arguments.
yarn hardhat upgrade-zksync:beacon --contract-name <contract name or FQN> --beacon-address <beacon address> [--deployment-type <deployment type>] [--no-compile]
When executed, this command upgrade beacon implementation.
To upgrade a implementation we need to specify beacon address, add --beacon-address <beacon address> argument, e.g. yarn hardhat upgrade-zksync:beacon --contract-name BoxV2 --beacon-address 0x4bbeEB066eD09B7AEd07bF39EEe0460DFa261520.
--contract-name <contract name or FQN> argument, e.g. hardhat deploy-zksync:proxy --contract-name SomeContract.--contract-name argument, e.g. hardhat deploy-zksync:proxy --contract-name Greeter 'Hello'.--constructor-args <module name> argument, e.g.
hardhat deploy-zksync:contract --contract-name ComplexContract --constructor-args args.js. Example of args.js :module.exports = [
"a string argument",
"0xabcdef",
"42",
{
property1: "one",
property2: 2,
},
];
--initializer <initializer method>, e.g. hardhat deploy-zksync:proxy --contract-name Contract --initializer store. If this parameter is omitted, the default value will be initialize.--no-compile argument, e.g. hardhat deploy-zksync:beacon --contract-name Contract --no-compile.--deployment-type argument. Permissible values for this parameter include create, create2, createAccount, and create2Account. If this parameter is omitted, the default value will be create, e.g. hardhat deploy-zksync:beacon --contract-name Greeter 'Hello' --deployment-type create2.The account used for deployment will be the one specified by the deployerAccount configuration within the hardhat.config.ts file. If no such configuration is present, the account with index 0 will be used.
In addition to the hardhat-zksync-upgradable, zkSync's Era website offers a variety of resources including:
Guides to get started: Learn how to start building on zkSync Era.
Hardhat zkSync Era plugins: Overview and guides for all Hardhat zkSync Era plugins.
Hyperscaling: Deep dive into hyperscaling on zkSync Era.
Contributions are always welcome! Feel free to open any issue or send a pull request.
Go to CONTRIBUTING.md to learn about steps and best practices for contributing to zkSync hardhat tooling base repository.
zkSync Era Discord server: for questions and feedback.
Follow zkSync Era on Twitter
FAQs
Hardhat plugin to deploy and update upgradable smart contracts for the zkSync network
The npm package @matterlabs/hardhat-zksync-upgradable receives a total of 1,359 weekly downloads. As such, @matterlabs/hardhat-zksync-upgradable popularity was classified as popular.
We found that @matterlabs/hardhat-zksync-upgradable demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 3 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Product
Streamline your login process and enhance security by enabling Single Sign-On (SSO) on the Socket platform, now available for all customers on the Enterprise plan, supporting 20+ identity providers.
Security News
Tea.xyz, a crypto project aimed at rewarding open source contributions, is once again facing backlash due to an influx of spam packages flooding public package registries.
Security News
As cyber threats become more autonomous, AI-powered defenses are crucial for businesses to stay ahead of attackers who can exploit software vulnerabilities at scale.