尧图网站设计 尧图网站设计YAOTU DESIGN
ARTICLE DETAIL

资讯详情

深耕网站设计与一线实操的经验洞察。

Hardhat Ignition viem 集成插件 hardhat-ignition-viem:从模块部署到类型安全合约实例的完整指南

Hardhat Ignition viem 集成插件 hardhat-ignition-viem:从模块部署到类型安全合约实例的完整指南 Hardhat Ignition viem 集成插件 hardhat-ignition-viem从模块部署到类型安全合约实例的完整指南【免费下载链接】hardhatHardhat is a development environment to compile, deploy, test, and debug your Ethereum software.项目地址: https://gitcode.com/GitHub_Trending/ha/hardhatnomicfoundation/hardhat-ignition-viem是 Hardhat 生态中把 Hardhat Ignition声明式智能合约部署系统与 viem 客户端库桥接起来的官方插件。它通过在每条网络连接上注入ignition对象让开发者用一条ignition.deploy()调用部署整个 Ignition 模块并直接拿到类型安全的 viem 合约实例省去手工拼接 ABI、地址与客户端的样板代码。本文以该插件当前仓库中的 CHANGELOG.md 为主体脉络结合 源码 与 测试完整梳理其安装配置、核心用法、deploy全部选项、底层实现原理以及从 0.13.0 到 3.1.6 的能力演进帮助你在 Hardhat 3 项目中快速上手并理解其运行机制。插件定位Ignition 的 viem 前端Hardhat Ignition 本身是一套与具体客户端库解耦的部署引擎负责模块定义、依赖图规划、执行、重试与部署状态持久化。hardhat-ignition-viem则是它的 viem 前端它不重复实现部署逻辑而是把 ignition-core 的deploy调用、Hardhat 的 artifact 解析、网络连接和 viem 的合约封装粘合在一起。从包描述可以看出其边界见 package.jsonHardhat Ignition is a declarative system for deploying smart contracts on Ethereum. It enables you to define smart contract instances you want to deploy, and any operation you want to run on them.插件通过 Hardhat 3 的插件机制注册见 src/index.tsconst hardhatIgnitionViemPlugin: HardhatPlugin definePlugin({ id: hardhat-ignition-viem, dependencies: () [ import(nomicfoundation/hardhat-ignition), import(nomicfoundation/hardhat-viem), ], hookHandlers: { network: () import(./internal/hook-handlers/network.js), }, npmPackage: nomicfoundation/hardhat-ignition-viem, });它显式声明对hardhat-ignition部署引擎与hardhat-viemviem 网络能力两个插件的依赖并通过networkhook 在每次建立网络连接时注入 viem 版的 Ignition helper。同时自 3.1.6 起插件在index.ts中使用hardhat/plugins提供的definePlugin定义使其纳入 Hardhat 新的已导入但未使用插件告警体系对应 CHANGELOG 3.1.6 条目——如果你的项目 import 了它却没有把它放进plugins数组Hardhat 会给出提示。安装与配置如果你的项目使用了 Viem Hardhat Toolboxnomicfoundation/hardhat-toolbox-viem该插件已被打包在内无需额外安装。独立安装见 README.mdnpm install --save-dev nomicfoundation/hardhat-ignition-viem在hardhat.config.ts中导入并注册import { defineConfig } from hardhat/config; import hardhatIgnitionViem from nomicfoundation/hardhat-ignition-viem; export default defineConfig({ plugins: [hardhatIgnitionViem], });插件的 peerDependencies 要求见 package.jsonhardhat^3.8.0、nomicfoundation/hardhat-ignition^3.1.2、nomicfoundation/hardhat-viem^3.0.4、nomicfoundation/ignition-core^3.0.7、viem^2.47.6即它面向 Hardhat 3 与 viem 2.x。安装时请保证上述版本匹配。核心用法一条命令部署并拿到类型安全合约插件的核心贡献是为每条网络连接增加ignition属性类型定义见 src/type-extensions.ts用法如下摘自 README.mdimport { network } from hardhat; import Counter from ../ignition/modules/Counter.js; const { ignition } await network.create(); const { counter } await ignition.deploy(Counter); await counter.write.inc(); console.log(await counter.read.x());这里需要注意两点连接优先自 Hardhat 3 起推荐使用network.create()建立网络连接3.1.2 起hre.network.connect()被标记为弃用功能完全一致create的名称更明确地表达创建新连接的语义见 CHANGELOG 3.1.2。类型安全返回值deploy返回的不是普通对象而是IgnitionModuleResultsToViemContracts类型——模块results中每个 future 都会被映射为对应的GetContractReturnType见 src/types.ts因此counter.write.inc()/counter.read.x()都带有编译期校验错误方法名会直接报类型错误运行期调用也会失败。仓库测试 test/viem-results.ts 专门验证了这种类型隔离模块返回foo、bar、baz三个不同合约后result.foo上调用bar的方法如result.foo.read.isBar()会在类型系统报错并在运行时被拒绝。deploy 选项全解析ignition.deploy()的签名定义在 src/types.ts实际实现在 src/internal/viem-ignition-helper.ts以下是全部选项及默认值选项类型默认值说明parametersDeploymentParameters \| string{}模块参数对象传入字符串时视为绝对路径的 JSON/JSON5 参数文件由readDeploymentParameters读取0.15.9 起支持0.15.6 起支持 JSON50.14.0 起 BigInt 可用/dn/字符串格式编码configPartialDeployConfig{}单次部署级配置会与hre.config.ignition合并3.0.4 修复了脚本部署时未读取全局hre.config.ignition的 bugdefaultSenderstring网络默认账户指定部署使用的默认发送账户0.13.0 起支持strategykeyof StrategyConfigbasic部署策略如 create20.15.0 起通过 strategies 支持strategyConfigStrategyConfig[StrategyT]取自hre.config.ignition策略配置未显式传入时回退到全局配置见#resolveStrategyConfig实现viem-ignition-helper.ts 第 394-411 行deploymentIdstring由 chainId 解析部署 ID决定paths.ignition/deployments/deploymentId下的状态与产物目录displayUibooleanfalse是否在脚本部署时展示 Ignition 可视化 UI0.15.9 起支持关于config合并的细节getResolvedConfig采用按次覆盖全局策略{...this.#config, ...perDeployConfig}网络配置中的ignition.maxRetries/ignition.retryInterval3.0.6 起可在用户配置中暴露重试循环变量与maxFeePerGasLimit/maxPriorityFeePerGas也会在部署前被读取并注入见 viem-ignition-helper.ts 第 199-231 行。底层实现从 hook 注入到 viem 合约封装惰性加载加速非 Ignition 工作流插件通过networkhook 的newConnection钩子在每次连接创建后为connection.ignition赋值见 src/internal/hook-handlers/network.ts。这里使用了LazyViemIgnitionHelper代理真正的ViemIgnitionHelperImpl通过await import()延迟到第一次调用deploy才加载3.1.4 的优化目标正是推迟 Ignition 加载直到首次部署加速不含 Ignition 的常规流程并通过模块级缓存避免并发调用者各自构造实例导致的并发问题。此外hook 内会检查connection.ignition是否已被占用——同一连接上同时挂载hardhat-ignition-ethers与hardhat-ignition-viem会抛出ONLY_ONE_IGNITION_EXTENSION_PLUGIN_ALLOWED错误测试见 test/ignition-helper-exclusivity.ts。deploy 的内部调用链ViemIgnitionHelperImpl.deploy()viem-ignition-helper.ts 第 92-259 行的核心流程互斥保护用#mutex标志阻止同一 helper 上并发调用deploy3.0.2 引入的守卫违反时抛ALREADY_IN_PROGRESS错误finally中必定释放互斥锁因此首次部署失败后仍可继续部署对应测试 should allow subsequent deploys if the first deploy fails。准备上下文通过eth_accounts获取账户列表、eth_chainId解析部署 ID、构建HardhatArtifactResolver。状态目录EDR 模拟网络edr-simulated不写部署目录其余网络写入paths.ignition/deployments/deploymentId0.15.1 起支持在测试和脚本中读写 deployments 目录。事件与中断displayUi为 true 时注册PrettyEventHandler与用户中断钩子3.1.2 起接入 Hardhat 3 的用户中断流程修复了 Ignition 与 Ledger 的 UI 交互。执行部署调用 ignition-core 的deploy()传入解析后的配置、provider、artifact resolver、参数、账户与默认发送者结果为DeploymentResultType.SUCCESSFUL_DEPLOYMENT之外的失败类型时用errorDeploymentResultToExceptionMessage转成可读错误。结果转换#toViemContracts遍历模块results把每个部署结果地址转换为 viem 合约实例——命名 artifact 走connection.viem.getContractAt(contractName, address)内联 artifact模块内直接给定 ABI 的 future则用 viem 的getContract({ address, abi, client })手动构造地址统一经#ensureAddressFormat规范为0x前缀小写形式。错误处理细节3.1.2 将 JSON-RPC revert 错误码统一为3与标准节点行为对齐并保留 viem/ethers 侧的 error cause同时该版本还包含等待所有返回的 Promise 以提升可调试性3.1.3与优化 type extensions 处理以加速 Hardhat 启动3.1.5等工程性改进。版本演进中的能力地图该插件的演进对应 CHANGELOG.md从 0.13.0 的nomicfoundation/hardhat-plugin-viem起步在 3.0.0 随 Hardhat 3 首版发布后迁入packages/目录并更名为当前包名。按主题可归为以下几类部署体验与参数模块参数全局级$global0.15.7、JSON5 支持0.15.6、BigInt 编码0.14.0、脚本部署时直接传入参数文件绝对路径0.15.9。策略与 create20.15.0 起通过 strategies 支持create2m.encodeFunctionCall被加入不提交交易的类型守卫0.15.5、3.0.1并修正了带数组参数的重载函数正则匹配0.15.5。默认发送者0.13.0 起支持从测试/脚本设置默认发送账户测试见 test/default-sender.ts——不传defaultSender时默认使用第一个 Hardhat 账户显式传入第二个账户地址后合约 owner 变为该地址。Gas 与链兼容支持maxPriorityFeePerGas配置、优先使用eth_maxPriorityFeePerGasRPC0.15.2零 gas 费链如私有 Besu可用0.15.2BNB 与 BNB Test 链从零费配置中排除0.15.3/0.15.5gasPrice、disableFeeBumping配置与 L2 gas 逻辑更新0.15.6maxFeePerGas可配置上限0.15.1Polygon 使用 EIP-1559 前交易避免掉交易0.15.2。3.0.9 起支持 viem 内置链列表之外的自定义链需自行提供链配置。CLI 与部署产物ignition transactions命令列出指定部署的所有交易并附区块浏览器链接0.15.7/0.15.90.15.8 修复其 bigint 序列化。ignition deployments列出所有部署0.15.1。ignition deploy --reset清空部署状态后重跑0.13.1。writeLocalhostDeployment标志允许向临时 Hardhat 网络部署时保存部署产物0.15.6清除本地 Hardhat 节点后部署会忽略旧部署状态0.15.1。验证与集成3.1.0 起支持在所有已启用的验证服务上验证如 Sourcify3.0.9 修复使用全限定名FQN合约的验证3.0.3 增加 Linea 验证支持0.15.9/0.15.8 修复外部 artifact 部署的验证与ignition status。0.15.9 起模块可作为after选项中的依赖0.15.5 修复环形/深层嵌套导入下的验证解析0.15.6 可视化 UI 支持缩放和平移 mermaid 图并与 Ledger 等插件良好协作3.0.5。可靠性修复地址参数大小写不一致的归一化0.15.4、更清晰的余额不足错误0.15.4、内存池查找重试降低慢传播错误0.13.2、anvilhardhat_setBalance响应兼容0.15.5、非 tty 下process.stdout修复0.13.1等。测试验证与可靠性保障仓库以 node:test 组织测试见 package.json覆盖了关键契约test/viem-results.ts结果仅含模块 results 声明的属性、不同类型合约的类型隔离、并发部署互斥与失败后的继续部署。test/default-sender.ts默认发送者账户行为。test/ignition-helper-exclusivity.ts与 ethers 版 Ignition 插件互斥。test/fixture-projects/minimal与create2两个 fixture 项目用于端到端验证其中 MyModule.js 展示了模块定义与部署结果读取的完整链路。如果你希望在实际工程中快速体验仓库中的 example-project 提供了完整的 Ignition 模块与脚本示例如 deploy-rocket-from-script.ts可对照本文内容进一步实践。小结hardhat-ignition-viem的价值在于把声明式部署与类型安全客户端无缝衔接模块定义交给 ignition-core网络交互交给 hardhat-viem而插件本身只做一层薄而严谨的粘合——惰性加载、互斥部署、配置合并、错误码对齐与 viem 合约实例转换。结合 CHANGELOG 中近两年的迭代记录可以看出其重点始终围绕部署可靠性重试、gas、非标准链、验证能力Sourcify、Linea、FQN与开发体验UI、Ledger、CLI三大方向持续演进是 Hardhat 3 viem 技术栈下进行 Ignition 部署的首选入口。【免费下载链接】hardhatHardhat is a development environment to compile, deploy, test, and debug your Ethereum software.项目地址: https://gitcode.com/GitHub_Trending/ha/hardhat创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表