Skip to content

docs: Add disclaimer to migrating-to-zksync.md #470

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
Open

docs: Add disclaimer to migrating-to-zksync.md #470

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
aa9c14c
Update 20.migrating-to-zksync.md
Jrigada Nov 12, 2025
d1b2d6e
Update 20.migrating-to-zksync.md
Jrigada Nov 12, 2025
901f4a2
Update 20.migrating-to-zksync.md
Jrigada Nov 12, 2025
ea4bb49
Update 20.migrating-to-zksync.md
Jrigada Nov 12, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 6 additions & 1 deletion ...ent/00.zksync-network/40.tooling/20.hardhat/20.guides/20.migrating-to-zksync.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,13 +56,15 @@ 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.
- `@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"}
```

Expand Down Expand Up @@ -395,6 +397,9 @@ 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
Expand Down
Loading