本文档介绍了如何将项目从OpenZeppelin CLI迁移到OpenZeppelin Upgrades Plugins(适用于Truffle或Hardhat)。重点介绍了CLI和插件之间的主要区别,即插件允许开发者更灵活地管理代理合约,并提供了详细的迁移步骤和升级合约的示例。
本指南适用于从已弃用的旧CLI迁移。 |
本指南将引导你把项目从 OpenZeppelin CLI 迁移到用于 Truffle 或 Hardhat 的 OpenZeppelin Upgrades 插件。
这里有适用于 Truffle 和 Hardhat 的说明。使用此切换来选择你的偏好!<br>切换 Hardhat 或 Truffle |
如果你想在一个示例的 OpenZeppelin CLI 项目上尝试这些说明,可以克隆 OpenZeppelin/openzeppelin-upgrades-migration-example 并在继续之前按照 readme 中的设置指令操作。 |
CLI 和插件之间的主要区别在于,前者用于跟踪你的可升级(和不可升级)部署。这在某些情况下很方便,因为你不需要太担心代理、实现或地址,你可以只关注诸如升级或仅通过合约名称向你的合约发送交易等操作。
但是让 CLI 跟踪你的部署,其代价是限制了你与不同工具和工作流程集成的自由。并且由于插件被设计为独立于 CLI 工作,我们取消了该限制,因此现在你可以灵活地按照你认为最好的方式来跟踪你的代理。
撇开这一点,其他一切都保持不变,因为 CLI 和插件都在底层使用了相同的已知 Proxy
和 ProxyAdmin
合约,从而构成了管理它们的两种不同的接口。这意味着迁移你的项目不会触及链上的任何东西,一切都是安全和本地的。
安装 Hardhat 并在初始化时,选择 Create an empty hardhat.config.js
选项。
$ npm install --save-dev hardhat
$ npx hardhat
然后安装 Upgrades 插件:
$ npm install --save-dev @openzeppelin/hardhat-upgrades
$ npm install --save-dev @nomiclabs/hardhat-ethers ethers # peer dependencies
完成后,通过添加以下行在 Hardhat 配置文件中注册该插件:
// hardhat.config.js
require('@openzeppelin/hardhat-upgrades');
module.exports = {
// ...
};
安装 Truffle 并初始化你的项目。
当 Truffle 询问时,选择不覆盖合约或测试目录。通过不覆盖,你将不会得到一个 初始迁移。确保你创建 Migrations.sol 和初始迁移。 |
$ npm install --save-dev truffle
$ npx truffle init
然后安装 Upgrades 插件:
$ npm install --save-dev @openzeppelin/truffle-upgrades
这是一个单向过程。确保你保留 .openzeppelin/ 文件夹的备份或版本控制副本。 |
现在,让我们通过运行以下命令来迁移我们的项目:
$ npx migrate-oz-cli-project
✔ Successfully migrated .openzeppelin/rinkeby.json
✔ Migration data exported to openzeppelin-cli-export.json
✔ Deleting .openzeppelin/project.json
These were your project's compiler options:
{
"compilerSettings": {
"optimizer": {
"enabled": false,
"runs": "200"
}
},
"typechain": {
"enabled": false
},
"manager": "openzeppelin",
"solcVersion": "0.6.12",
"artifactsDir": "build/contracts",
"contractsDir": "contracts"
}
此脚本与插件一起安装,它的作用是删除 CLI 项目文件,并将你的旧网络文件(所有这些文件都位于 .openzeppelin
目录下)转换为其 Upgrades 插件的等效文件。同样,链上的任何内容都不会更改,只有本地文件会更改。另请注意,一旦你运行此命令,除非你通过备份或版本控制来恢复更改,否则你将无法再使用 CLI 来管理该项目的合约。
迁移脚本还会将 openzeppelin-cli-export.json
文件导出到你的工作目录中,其中包含 CLI 过去为你管理的所有数据,现在你可以随意使用你认为最好的方式来使用它。这包括你的编译器设置,为了方便起见,这些设置也会在迁移结束时打印出来。让我们将它们添加到我们的新项目配置中:
将编译器设置复制到 Hardhat 配置文件中的 solidity
字段 中
// hardhat.config.js
// ...
module.exports = {
// ...
solidity: {
version: "0.6.12",
settings: {
optimizer: {
enabled: false,
runs: 200
}
}
}
}
将编译器设置复制到我们的 Truffle 配置文件中的 compilers
字段 中
// truffle-config.js
module.exports = {
// ...
compilers: {
solc: {
version: "0.6.12",
settings: {
optimizer: {
enabled: false,
runs: 200
}
}
}
}
}
solidity 编译器配置格式在 truffle-config.js 和 hardhat.config.js 文件中是不同的 |
就这样,你已经成功迁移了你的 CLI 项目。现在让我们尝试你的新设置,升级你迁移的合约之一。
假设我们在 CLI 项目中有一个 Box
合约,已部署到 Rinkeby 网络。然后,如果我们打开我们的导出文件,我们会看到这样的内容:
// openzeppelin-cli-export.json
{
"networks": {
"rinkeby": {
"proxies": {
"openzeppelin-upgrades-migration-example/Box": [\
{\
"address": "0x500D1d6A4c7D8Ae28240b47c8FCde034D827fD5e",\
"version": "1.0.0",\
"implementation": "0x038B86d9d8FAFdd0a02ebd1A476432877b0107C8",\
"admin": "0x1A1FEe7EeD918BD762173e4dc5EfDB8a78C924A8",\
"kind": "Upgradeable"\
}\
]
}
}
},
"compiler": {
// we'll ignore compiler settings for this
}
}
我们在这里看到的是我们的可升级合约的 JSON 表示,以地址表示:
address
:代理地址(代理合约包含你的可升级合约状态)
implementation
:实现地址(你的可升级合约逻辑)
admin
:代理管理员的地址,它可能属于一个 ProxyAdmin
合约,除非你另行设置
如果我们决定使用插件和这个导出文件将我们的 Box
合约升级到 BoxV2
合约,它会是这样:
这些脚本只是如何使用导出数据的例子。我们不对是否保留该文件或如何处理其数据提出任何建议。这现在取决于用户。
使用 Hardhat,我们将编写一个脚本(你可以在这里阅读更多关于 Hardhat 脚本的信息,在这里阅读更多关于使用 hardhat-upgrades
插件的信息):
// scripts/upgradeBoxToV2.js
const { ethers, upgrades } = require("hardhat");
const OZ_SDK_EXPORT = require("../openzeppelin-cli-export.json");
async function main() {
const [ Box ] = OZ_SDK_EXPORT.networks.rinkeby.proxies["openzeppelin-upgrades-migration-example/Box"];
const BoxV2 = await ethers.getContractFactory("BoxV2");
await upgrades.upgradeProxy(Box.address, BoxV2);
}
main();
$ npx hardhat run scripts/upgradeBoxToV2.js --network rinkeby
使用 Truffle,我们将编写一个迁移(你可以在这里阅读更多关于 Truffle 迁移的信息,在这里阅读更多关于使用 truffle-upgrades
插件的信息):
// migrations/2_upgrade_box_contract.js
const { upgradeProxy } = require('@openzeppelin/truffle-upgrades');
const OZ_SDK_EXPORT = require("../openzeppelin-cli-export.json");
const BoxV2 = artifacts.require('BoxV2');
module.exports = async function (deployer) {
const [ Box ] = OZ_SDK_EXPORT.networks.rinkeby.proxies["openzeppelin-upgrades-migration-example/Box"];
const instance = await upgradeProxy(Box.address, BoxV2, { deployer });
console.log("Upgraded", instance.address);
};
$ npx truffle migrate --network rinkeby
就是这样! 你已经将 OpenZeppelin CLI 项目迁移到 Truffle 或 Hardhat,并使用插件执行了升级。
- 原文链接: docs.openzeppelin.com/up...
- 登链社区 AI 助手,为大家转译优秀英文文章,如有翻译不通的地方,还请包涵~
如果觉得我的文章对您有用,请随意打赏。你的支持将鼓励我继续创作!