From aa9c14cbd7a2ff35de86186dcda063fcb8a64677 Mon Sep 17 00:00:00 2001 From: Juan Rigada <62958725+Jrigada@users.noreply.github.com> Date: Wed, 12 Nov 2025 15:33:29 -0300 Subject: [PATCH 1/4] Update 20.migrating-to-zksync.md Based on a user-reported issue with @matterlabs/hardhat-zksync, we realized that executing deployProxy on non-ZKsync chains requires the @openzeppelin/hardhat-upgrades package to be installed. Link to the issue: https://github.com/matter-labs/hardhat-zksync/issues/1863 --- .../40.tooling/20.hardhat/20.guides/20.migrating-to-zksync.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/content/00.zksync-network/40.tooling/20.hardhat/20.guides/20.migrating-to-zksync.md b/content/00.zksync-network/40.tooling/20.hardhat/20.guides/20.migrating-to-zksync.md index 37383940..bf2e4eb8 100644 --- a/content/00.zksync-network/40.tooling/20.hardhat/20.guides/20.migrating-to-zksync.md +++ b/content/00.zksync-network/40.tooling/20.hardhat/20.guides/20.migrating-to-zksync.md @@ -56,13 +56,14 @@ You can learn more about each plugin in the [Getting started section](/zksync-ne - `@nomicfoundation/hardhat-ethers`: `@matterlabs/hardhat-zksync` includes `hardhat-ethers` extended with support for ZKsync and non-ZKsync networks. - `@openzeppelin/hardhat-upgrades`: `@matterlabs/hardhat-zksync` includes `hardhat-upgrades` extended with support for ZKsync and non-ZKsync networks. + - **For multichain projects** that deploy to both ZKsync and regular Ethereum networks, you still need to install `@openzeppelin/hardhat-upgrades` as the plugin delegates to it for non-ZKsync networks. - `@nomicfoundation/hardhat-toolbox`: this plugin includes `@nomicfoundation/hardhat-ethers` which can cause conflicts. Import necessary components separately excluding `@nomicfoundation/hardhat-ethers`. ```ts // import "@nomicfoundation/hardhat-toolbox" // import "@nomicfoundation/hardhat-ethers" - // import "@openzeppelin/hardhat-upgrades" + // import "@openzeppelin/hardhat-upgrades" // Keep this import for multichain projects :code-import{filePath="hardhat-sol-template/hardhat.config.ts:zksync-import"} ``` @@ -395,6 +396,7 @@ The [following example project](https://github.com/uF4No/hardhat-evm-zksync-exam Here are some recommendations for projects that target multiple chains: - Add the desired ZKsync networks with the `zksync:true` flag to the `hardhat.config.ts`. +- Install `@openzeppelin/hardhat-upgrades` explicitly if you're using proxy contracts and deploying to both ZKsync and regular Ethereum networks. The `@matterlabs/hardhat-zksync` plugin uses its own implementation for ZKsync networks but delegates to OpenZeppelin's implementation for non-ZKsync networks. - Make sure to run the compilation task with the `--network` flag when targeting ZKsync networks to use the custom compiler. - When targeting ZKsync chains, the `@matterlabs/hardhat-zksync` plugin overrides the following plugins: `@nomiclabs/hardhat-ethers`, `@openzeppelin/hardhat-upgrades`. - To avoid typescript collision errors between `@nomiclabs/hardhat-ethers` and From d1b2d6e323ec7d8f18d3a4b59685d74f3de813ef Mon Sep 17 00:00:00 2001 From: Juan Rigada <62958725+Jrigada@users.noreply.github.com> Date: Wed, 12 Nov 2025 15:40:48 -0300 Subject: [PATCH 2/4] Update 20.migrating-to-zksync.md --- .../40.tooling/20.hardhat/20.guides/20.migrating-to-zksync.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/00.zksync-network/40.tooling/20.hardhat/20.guides/20.migrating-to-zksync.md b/content/00.zksync-network/40.tooling/20.hardhat/20.guides/20.migrating-to-zksync.md index bf2e4eb8..9b11b0f0 100644 --- a/content/00.zksync-network/40.tooling/20.hardhat/20.guides/20.migrating-to-zksync.md +++ b/content/00.zksync-network/40.tooling/20.hardhat/20.guides/20.migrating-to-zksync.md @@ -56,7 +56,7 @@ You can learn more about each plugin in the [Getting started section](/zksync-ne - `@nomicfoundation/hardhat-ethers`: `@matterlabs/hardhat-zksync` includes `hardhat-ethers` extended with support for ZKsync and non-ZKsync networks. - `@openzeppelin/hardhat-upgrades`: `@matterlabs/hardhat-zksync` includes `hardhat-upgrades` extended with support for ZKsync and non-ZKsync networks. - - **For multichain projects** that deploy to both ZKsync and regular Ethereum networks, you still need to install `@openzeppelin/hardhat-upgrades` as the plugin delegates to it for non-ZKsync networks. + - **For multichain projects** that deploy to both ZKsync and regular Ethereum networks, `@openzeppelin/hardhat-upgrades` must still be installed as the ZKsync plugin delegates to it for non-ZKsync networks. - `@nomicfoundation/hardhat-toolbox`: this plugin includes `@nomicfoundation/hardhat-ethers` which can cause conflicts. Import necessary components separately excluding `@nomicfoundation/hardhat-ethers`. From 901f4a27618bc7dda85921bfbe087552f0908e2c Mon Sep 17 00:00:00 2001 From: Juan Rigada <62958725+Jrigada@users.noreply.github.com> Date: Wed, 12 Nov 2025 15:42:41 -0300 Subject: [PATCH 3/4] Update 20.migrating-to-zksync.md --- .../20.hardhat/20.guides/20.migrating-to-zksync.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/content/00.zksync-network/40.tooling/20.hardhat/20.guides/20.migrating-to-zksync.md b/content/00.zksync-network/40.tooling/20.hardhat/20.guides/20.migrating-to-zksync.md index 9b11b0f0..cb940c22 100644 --- a/content/00.zksync-network/40.tooling/20.hardhat/20.guides/20.migrating-to-zksync.md +++ b/content/00.zksync-network/40.tooling/20.hardhat/20.guides/20.migrating-to-zksync.md @@ -56,7 +56,8 @@ You can learn more about each plugin in the [Getting started section](/zksync-ne - `@nomicfoundation/hardhat-ethers`: `@matterlabs/hardhat-zksync` includes `hardhat-ethers` extended with support for ZKsync and non-ZKsync networks. - `@openzeppelin/hardhat-upgrades`: `@matterlabs/hardhat-zksync` includes `hardhat-upgrades` extended with support for ZKsync and non-ZKsync networks. - - **For multichain projects** that deploy to both ZKsync and regular Ethereum networks, `@openzeppelin/hardhat-upgrades` must still be installed as the ZKsync plugin delegates to it for non-ZKsync networks. + - **For multichain projects** that deploy to both ZKsync and regular Ethereum networks, `@openzeppelin/hardhat-upgrades` + must still be installed as the ZKsync plugin delegates to it for non-ZKsync networks. - `@nomicfoundation/hardhat-toolbox`: this plugin includes `@nomicfoundation/hardhat-ethers` which can cause conflicts. Import necessary components separately excluding `@nomicfoundation/hardhat-ethers`. @@ -396,7 +397,8 @@ The [following example project](https://github.com/uF4No/hardhat-evm-zksync-exam Here are some recommendations for projects that target multiple chains: - Add the desired ZKsync networks with the `zksync:true` flag to the `hardhat.config.ts`. -- Install `@openzeppelin/hardhat-upgrades` explicitly if you're using proxy contracts and deploying to both ZKsync and regular Ethereum networks. The `@matterlabs/hardhat-zksync` plugin uses its own implementation for ZKsync networks but delegates to OpenZeppelin's implementation for non-ZKsync networks. +- Install `@openzeppelin/hardhat-upgrades` explicitly if you're using proxy contracts and deploying to both ZKsync and regular Ethereum networks. + The `@matterlabs/hardhat-zksync` plugin uses its own implementation for ZKsync networks but delegates to OpenZeppelin's implementation for non-ZKsync networks. - Make sure to run the compilation task with the `--network` flag when targeting ZKsync networks to use the custom compiler. - When targeting ZKsync chains, the `@matterlabs/hardhat-zksync` plugin overrides the following plugins: `@nomiclabs/hardhat-ethers`, `@openzeppelin/hardhat-upgrades`. - To avoid typescript collision errors between `@nomiclabs/hardhat-ethers` and From ea4bb49caf19010f654b95bbc65c1a0114e2458c Mon Sep 17 00:00:00 2001 From: Juan Rigada <62958725+Jrigada@users.noreply.github.com> Date: Wed, 12 Nov 2025 15:43:58 -0300 Subject: [PATCH 4/4] Update 20.migrating-to-zksync.md --- .../40.tooling/20.hardhat/20.guides/20.migrating-to-zksync.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/content/00.zksync-network/40.tooling/20.hardhat/20.guides/20.migrating-to-zksync.md b/content/00.zksync-network/40.tooling/20.hardhat/20.guides/20.migrating-to-zksync.md index cb940c22..bcb944cc 100644 --- a/content/00.zksync-network/40.tooling/20.hardhat/20.guides/20.migrating-to-zksync.md +++ b/content/00.zksync-network/40.tooling/20.hardhat/20.guides/20.migrating-to-zksync.md @@ -398,7 +398,8 @@ Here are some recommendations for projects that target multiple chains: - Add the desired ZKsync networks with the `zksync:true` flag to the `hardhat.config.ts`. - Install `@openzeppelin/hardhat-upgrades` explicitly if you're using proxy contracts and deploying to both ZKsync and regular Ethereum networks. - The `@matterlabs/hardhat-zksync` plugin uses its own implementation for ZKsync networks but delegates to OpenZeppelin's implementation for non-ZKsync networks. + The `@matterlabs/hardhat-zksync` plugin uses its own implementation for ZKsync networks but delegates to OpenZeppelin's implementation + for non-ZKsync networks. - Make sure to run the compilation task with the `--network` flag when targeting ZKsync networks to use the custom compiler. - When targeting ZKsync chains, the `@matterlabs/hardhat-zksync` plugin overrides the following plugins: `@nomiclabs/hardhat-ethers`, `@openzeppelin/hardhat-upgrades`. - To avoid typescript collision errors between `@nomiclabs/hardhat-ethers` and