hardhat-ignition-ethers用 ethers.js 结果类型优雅落地 Hardhat Ignition 部署【免费下载链接】hardhatHardhat is a development environment to compile, deploy, test, and debug your Ethereum software.项目地址: https://gitcode.com/GitHub_Trending/ha/hardhat导读本文围绕开源仓库 hardhat 中nomicfoundation/hardhat-ignition-ethers插件展开它把声明式部署框架 Hardhat Ignition 与 ethers.js 无缝集成你只需写一份 Ignition 模块deploy之后拿到的就是可直接调用的 ethersContract实例。读完本文你将掌握该插件的安装、配置与在脚本/测试中使用connection.ignition.deploy()的完整流程并能理解它从模块定义到返回合约实例的底层实现链路。插件是什么Ignition 与 ethers.js 之间的胶水层hardhat-ignition-ethers是 Hardhat 官方生态中把两个能力缝合起来的插件Hardhat Ignition声明式智能合约部署系统。你定义要部署的合约实例、要执行的调用m.call以及合约间的依赖关系Ignition 负责解析依赖顺序、保存部署状态、支持失败重试与按部署 ID 复用。ethers.js当前最主流的以太坊 JavaScript 库之一提供Contract、Wallet、Provider等对象是脚本与测试中与链上合约交互的标准方式。该插件所做的就是让deploy的返回值从 Ignition 原生的“部署结果”自动映射为对应合约 ABI 的 ethers 合约实例开发者拿到手即可直接调用合约方法。插件包描述也印证了这一职责定位“The Ethers extension to Hardhat Ignition”其peerDependencies同时声明了对nomicfoundation/hardhat-ignition、nomicfoundation/hardhat-ethers、nomicfoundation/ignition-core与ethers的依赖见 package.json。从源码入口看插件通过definePlugin声明自身依赖并注册网络级 hooksrc/index.tsconst hardhatIgnitionEthersPlugin: HardhatPlugin definePlugin({ id: hardhat-ignition-ethers, dependencies: () [ import(nomicfoundation/hardhat-ignition), import(nomicfoundation/hardhat-ethers), ], hookHandlers: { network: () import(./internal/hook-handlers/network.js), }, npmPackage: nomicfoundation/hardhat-ignition-ethers, });也就是说它不是一个独立运行的工具而是建立在hardhat-ignition与hardhat-ethers之上的扩展层——这正是它能直接复用两边的部署引擎与合约实例化能力的原因。安装与配置安装命令在项目根目录执行npm install --save-dev nomicfoundation/hardhat-ignition-ethers提示该插件是 EthersMocha Hardhat Toolboxnomicfoundation/hardhat-toolbox-mocha-ethers的组成部分。如果你已经使用了这个 Toolbox则无需再单独安装与配置本插件Toolbox 已替你完成这一切。在 hardhat.config.ts 中注册以 Hardhat 3 的配置风格为例在hardhat.config.ts中导入插件并加入plugins数组import { defineConfig } from hardhat/config; import hardhatIgnitionEthers from nomicfoundation/hardhat-ignition-ethers; export default defineConfig({ plugins: [hardhatIgnitionEthers], });配置完成后插件会在每次创建网络连接network connection时通过newConnectionhook 将ignition属性注入到连接对象上src/internal/hook-handlers/network.ts。类型层面则通过模块增强在hardhat/types/network的NetworkConnection接口上声明ignition: EthersIgnitionHelpersrc/type-extensions.ts因此 TypeScript 用户在脚本与测试中都能获得完整的类型提示。一个值得注意的约束若同一连接上已有其他 Ignition 扩展插件注入过ignition属性例如 viem 版本hook 会抛出ONLY_ONE_IGNITION_EXTENSION_PLUGIN_ALLOWED错误保证同一网络连接上只能存在一种 Ignition 结果类型扩展避免 ethers 与 viem 两种结果模型相互冲突。核心用法connection.ignition.deploy()插件为每个网络连接添加ignition属性其核心方法为deploy。官方 README 给出的最小用法如下import { network } from hardhat; import Counter from ../ignition/modules/Counter.js; const { ignition } await network.create(); const { counter } await ignition.deploy(Counter); await counter.inc(); console.log(await counter.x());拆解这段代码的执行语义network.create()创建一条网络连接返回的ignition即插件注入的EthersIgnitionHelperignition.deploy(Counter)部署 Ignition 模块并把模块return的每个合约 future 转成对应的 ethersContract实例解构出counter之后counter.inc()、counter.x()就是标准的 ethers 合约调用——部署与交互共用同一套对象模型无需再手动用地址getContractAt二次接线。模块Counter用buildModule定义例如import { buildModule } from nomicfoundation/hardhat-ignition/modules; export default buildModule(Counter, (m) { const counter m.contract(Counter); return { counter }; });仓库示例项目中的 Apollo.ts 展示了带构造参数与链上调用的完整模块形态import { buildModule } from nomicfoundation/hardhat-ignition/modules; export default buildModule(Apollo, (m) { const apollo m.contract(Rocket, [Saturn V]); m.call(apollo, launch, []); return { apollo }; });deploy 方法的完整签名与选项EthersIgnitionHelper.deploy的完整签名定义在 src/types.tsdeployModuleIdT, ContractNameT, IgnitionModuleResultsT, StrategyT basic( ignitionModule: IgnitionModuleModuleIdT, ContractNameT, IgnitionModuleResultsT, options?: { parameters?: DeploymentParameters | string; // 部署参数对象或指向参数 JSON 文件的路径字符串 config?: PartialDeployConfig; // 本次部署的配置覆盖 defaultSender?: string; // 部署交易的默认发送者地址 strategy?: StrategyT; // 部署策略名默认 basic strategyConfig?: StrategyConfig[StrategyT]; // 策略专属配置 deploymentId?: string; // 手动指定部署 ID覆盖自动生成值 displayUi?: boolean; // 是否显示 Pretty 部署进度 UI }, ): PromiseIgnitionModuleResultsTToEthersContractsContractNameT, IgnitionModuleResultsT;各选项的实际处理逻辑可以在核心实现 src/internal/ethers-ignition-helper.ts 中逐一对号入座parameters传入字符串时插件会调用readDeploymentParameters从 JSON 文件加载参数L185-L191传入对象则直接使用缺省为{}。config / maxRetries / retryIntervalgetResolvedConfig会把构造时注入的全局配置来自hardhatConfig.ignition与本次config合并若maxRetries、retryInterval未在本次配置中显式给出还会回落到网络配置networkConfig.ignition上的同名选项L193-L207。gas 相关上限maxFeePerGasLimit、maxPriorityFeePerGas也取自网络配置。strategy / strategyConfig策略名缺省为basic若未提供strategyConfig会从hardhatConfig.ignition?.strategyConfig?.[strategyName]读取全局策略配置L323-L340。deploymentId缺省时由resolveDeploymentId(givenDeploymentId, chainId)结合当前链 ID 生成。只有在网络类型为edr-simulated模拟网络时部署目录为undefined即不做持久化其余情况部署状态会写入paths.ignition/deployments/deploymentId目录L161-L170这正是 Ignition 失败续跑与状态复用能力的基础。displayUi为true时创建PrettyEventHandler并临时注册用户中断userInterruptions处理钩子部署结束后自动注销L172-L183。返回值从部署结果到 ethers 合约实例deploy的类型定义保证了返回结构的精确性src/types.ts模块results中每个合约部署 futureNamedArtifactContractDeploymentFuture或合约地址 futureNamedArtifactContractAtFuture都会被映射为对应合约名的 ethers 合约类型其他类型的 future 则退化为通用的Contract。运行时转换发生在#toEthersContracts与#getContract两个私有方法中ethers-ignition-helper.ts#L264-L321遍历ignitionModule.results中的每个 future从部署结果result.contracts[future.id]取实际地址若 future 携带内联 artifact例如外部加载的合约 artifact则用其abi直接getContractAt(abi, address)否则按合约名getContractAt(contractName, address)由hardhat-ethers负责从 artifacts 解析 ABI 并实例化。测试文件 deploy-with-ethers-result.ts 用真实 fixture 验证了这些行为m.contract(Foo)部署、m.contractAt(Foo, foo)地址引用、外部 artifact 加载等场景返回的实例都能直接调用x()、isFoo()、isExternallyLoaded()等合约方法且类型系统能区分不同合约的方法集result.foo.isBar为undefined。并发安全同一连接上一次只能有一个部署在途实现中使用布尔互斥锁#mutex保护deploy若并发调用直接抛出IGNITION.DEPLOY.ALREADY_IN_PROGRESS错误若首次部署失败如合约 artifact 不存在finally中会释放锁允许随后再次部署ethers-ignition-helper.ts#L126-L132。对应测试见 deploy-with-ethers-result.ts#L107-L161。惰性加载LazyEthersIgnitionHelperhook 注入的连接属性是LazyEthersIgnitionHelperhook-handlers/network.ts#L27-L124它把真正的实现EthersIgnitionHelperImpl推迟到首次deploy时才await import并缓存实例。这样做的收益是创建网络连接时不触发额外模块加载同时所有调用共享同一个实现实例避免并发调用各持一份状态导致的竞争问题。与 Toolbox 的关系及版本前提根据 README本插件已被nomicfoundation/hardhat-toolbox-mocha-ethers打包收录。该 Toolbox 的src/index.tspackages/hardhat-toolbox-mocha-ethers/src/index.ts聚合了 mocha 测试、ethers、Ignition 等常用组件使用 Toolbox 的项目开箱即得connection.ignition。总结hardhat-ignition-ethers的价值在于消除了部署与交互之间的类型鸿沟用 Ignition 声明部署拓扑、用 ethers 的结果对象直接操作合约二者通过一个network连接上的ignition属性统一起来。本文覆盖了它的安装配置、deploy方法全参数、返回值类型映射、并发保护与惰性加载机制并给出了 fixture 模块 与 测试用例 作为可运行的参考起点。若你的脚本与测试已基于 ethers.js那么在 Hardhat 3 项目中它就是衔接 Ignition 部署引擎的最直接方案。【免费下载链接】hardhatHardhat is a development environment to compile, deploy, test, and debug your Ethereum software.项目地址: https://gitcode.com/GitHub_Trending/ha/hardhat创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 hardhat-ignition-ethers：用 ethers.js 结果类型优雅落地 Hardhat Ignition 部署
hardhat-ignition-ethers用 ethers.js 结果类型优雅落地 Hardhat Ignition 部署【免费下载链接】hardhatHardhat is a development environment to compile, deploy, test, and debug your Ethereum software.项目地址: https://gitcode.com/GitHub_Trending/ha/hardhat导读本文围绕开源仓库 hardhat 中nomicfoundation/hardhat-ignition-ethers插件展开它把声明式部署框架 Hardhat Ignition 与 ethers.js 无缝集成你只需写一份 Ignition 模块deploy之后拿到的就是可直接调用的 ethersContract实例。读完本文你将掌握该插件的安装、配置与在脚本/测试中使用connection.ignition.deploy()的完整流程并能理解它从模块定义到返回合约实例的底层实现链路。插件是什么Ignition 与 ethers.js 之间的胶水层hardhat-ignition-ethers是 Hardhat 官方生态中把两个能力缝合起来的插件Hardhat Ignition声明式智能合约部署系统。你定义要部署的合约实例、要执行的调用m.call以及合约间的依赖关系Ignition 负责解析依赖顺序、保存部署状态、支持失败重试与按部署 ID 复用。ethers.js当前最主流的以太坊 JavaScript 库之一提供Contract、Wallet、Provider等对象是脚本与测试中与链上合约交互的标准方式。该插件所做的就是让deploy的返回值从 Ignition 原生的“部署结果”自动映射为对应合约 ABI 的 ethers 合约实例开发者拿到手即可直接调用合约方法。插件包描述也印证了这一职责定位“The Ethers extension to Hardhat Ignition”其peerDependencies同时声明了对nomicfoundation/hardhat-ignition、nomicfoundation/hardhat-ethers、nomicfoundation/ignition-core与ethers的依赖见 package.json。从源码入口看插件通过definePlugin声明自身依赖并注册网络级 hooksrc/index.tsconst hardhatIgnitionEthersPlugin: HardhatPlugin definePlugin({ id: hardhat-ignition-ethers, dependencies: () [ import(nomicfoundation/hardhat-ignition), import(nomicfoundation/hardhat-ethers), ], hookHandlers: { network: () import(./internal/hook-handlers/network.js), }, npmPackage: nomicfoundation/hardhat-ignition-ethers, });也就是说它不是一个独立运行的工具而是建立在hardhat-ignition与hardhat-ethers之上的扩展层——这正是它能直接复用两边的部署引擎与合约实例化能力的原因。安装与配置安装命令在项目根目录执行npm install --save-dev nomicfoundation/hardhat-ignition-ethers提示该插件是 EthersMocha Hardhat Toolboxnomicfoundation/hardhat-toolbox-mocha-ethers的组成部分。如果你已经使用了这个 Toolbox则无需再单独安装与配置本插件Toolbox 已替你完成这一切。在 hardhat.config.ts 中注册以 Hardhat 3 的配置风格为例在hardhat.config.ts中导入插件并加入plugins数组import { defineConfig } from hardhat/config; import hardhatIgnitionEthers from nomicfoundation/hardhat-ignition-ethers; export default defineConfig({ plugins: [hardhatIgnitionEthers], });配置完成后插件会在每次创建网络连接network connection时通过newConnectionhook 将ignition属性注入到连接对象上src/internal/hook-handlers/network.ts。类型层面则通过模块增强在hardhat/types/network的NetworkConnection接口上声明ignition: EthersIgnitionHelpersrc/type-extensions.ts因此 TypeScript 用户在脚本与测试中都能获得完整的类型提示。一个值得注意的约束若同一连接上已有其他 Ignition 扩展插件注入过ignition属性例如 viem 版本hook 会抛出ONLY_ONE_IGNITION_EXTENSION_PLUGIN_ALLOWED错误保证同一网络连接上只能存在一种 Ignition 结果类型扩展避免 ethers 与 viem 两种结果模型相互冲突。核心用法connection.ignition.deploy()插件为每个网络连接添加ignition属性其核心方法为deploy。官方 README 给出的最小用法如下import { network } from hardhat; import Counter from ../ignition/modules/Counter.js; const { ignition } await network.create(); const { counter } await ignition.deploy(Counter); await counter.inc(); console.log(await counter.x());拆解这段代码的执行语义network.create()创建一条网络连接返回的ignition即插件注入的EthersIgnitionHelperignition.deploy(Counter)部署 Ignition 模块并把模块return的每个合约 future 转成对应的 ethersContract实例解构出counter之后counter.inc()、counter.x()就是标准的 ethers 合约调用——部署与交互共用同一套对象模型无需再手动用地址getContractAt二次接线。模块Counter用buildModule定义例如import { buildModule } from nomicfoundation/hardhat-ignition/modules; export default buildModule(Counter, (m) { const counter m.contract(Counter); return { counter }; });仓库示例项目中的 Apollo.ts 展示了带构造参数与链上调用的完整模块形态import { buildModule } from nomicfoundation/hardhat-ignition/modules; export default buildModule(Apollo, (m) { const apollo m.contract(Rocket, [Saturn V]); m.call(apollo, launch, []); return { apollo }; });deploy 方法的完整签名与选项EthersIgnitionHelper.deploy的完整签名定义在 src/types.tsdeployModuleIdT, ContractNameT, IgnitionModuleResultsT, StrategyT basic( ignitionModule: IgnitionModuleModuleIdT, ContractNameT, IgnitionModuleResultsT, options?: { parameters?: DeploymentParameters | string; // 部署参数对象或指向参数 JSON 文件的路径字符串 config?: PartialDeployConfig; // 本次部署的配置覆盖 defaultSender?: string; // 部署交易的默认发送者地址 strategy?: StrategyT; // 部署策略名默认 basic strategyConfig?: StrategyConfig[StrategyT]; // 策略专属配置 deploymentId?: string; // 手动指定部署 ID覆盖自动生成值 displayUi?: boolean; // 是否显示 Pretty 部署进度 UI }, ): PromiseIgnitionModuleResultsTToEthersContractsContractNameT, IgnitionModuleResultsT;各选项的实际处理逻辑可以在核心实现 src/internal/ethers-ignition-helper.ts 中逐一对号入座parameters传入字符串时插件会调用readDeploymentParameters从 JSON 文件加载参数L185-L191传入对象则直接使用缺省为{}。config / maxRetries / retryIntervalgetResolvedConfig会把构造时注入的全局配置来自hardhatConfig.ignition与本次config合并若maxRetries、retryInterval未在本次配置中显式给出还会回落到网络配置networkConfig.ignition上的同名选项L193-L207。gas 相关上限maxFeePerGasLimit、maxPriorityFeePerGas也取自网络配置。strategy / strategyConfig策略名缺省为basic若未提供strategyConfig会从hardhatConfig.ignition?.strategyConfig?.[strategyName]读取全局策略配置L323-L340。deploymentId缺省时由resolveDeploymentId(givenDeploymentId, chainId)结合当前链 ID 生成。只有在网络类型为edr-simulated模拟网络时部署目录为undefined即不做持久化其余情况部署状态会写入paths.ignition/deployments/deploymentId目录L161-L170这正是 Ignition 失败续跑与状态复用能力的基础。displayUi为true时创建PrettyEventHandler并临时注册用户中断userInterruptions处理钩子部署结束后自动注销L172-L183。返回值从部署结果到 ethers 合约实例deploy的类型定义保证了返回结构的精确性src/types.ts模块results中每个合约部署 futureNamedArtifactContractDeploymentFuture或合约地址 futureNamedArtifactContractAtFuture都会被映射为对应合约名的 ethers 合约类型其他类型的 future 则退化为通用的Contract。运行时转换发生在#toEthersContracts与#getContract两个私有方法中ethers-ignition-helper.ts#L264-L321遍历ignitionModule.results中的每个 future从部署结果result.contracts[future.id]取实际地址若 future 携带内联 artifact例如外部加载的合约 artifact则用其abi直接getContractAt(abi, address)否则按合约名getContractAt(contractName, address)由hardhat-ethers负责从 artifacts 解析 ABI 并实例化。测试文件 deploy-with-ethers-result.ts 用真实 fixture 验证了这些行为m.contract(Foo)部署、m.contractAt(Foo, foo)地址引用、外部 artifact 加载等场景返回的实例都能直接调用x()、isFoo()、isExternallyLoaded()等合约方法且类型系统能区分不同合约的方法集result.foo.isBar为undefined。并发安全同一连接上一次只能有一个部署在途实现中使用布尔互斥锁#mutex保护deploy若并发调用直接抛出IGNITION.DEPLOY.ALREADY_IN_PROGRESS错误若首次部署失败如合约 artifact 不存在finally中会释放锁允许随后再次部署ethers-ignition-helper.ts#L126-L132。对应测试见 deploy-with-ethers-result.ts#L107-L161。惰性加载LazyEthersIgnitionHelperhook 注入的连接属性是LazyEthersIgnitionHelperhook-handlers/network.ts#L27-L124它把真正的实现EthersIgnitionHelperImpl推迟到首次deploy时才await import并缓存实例。这样做的收益是创建网络连接时不触发额外模块加载同时所有调用共享同一个实现实例避免并发调用各持一份状态导致的竞争问题。与 Toolbox 的关系及版本前提根据 README本插件已被nomicfoundation/hardhat-toolbox-mocha-ethers打包收录。该 Toolbox 的src/index.tspackages/hardhat-toolbox-mocha-ethers/src/index.ts聚合了 mocha 测试、ethers、Ignition 等常用组件使用 Toolbox 的项目开箱即得connection.ignition。总结hardhat-ignition-ethers的价值在于消除了部署与交互之间的类型鸿沟用 Ignition 声明部署拓扑、用 ethers 的结果对象直接操作合约二者通过一个network连接上的ignition属性统一起来。本文覆盖了它的安装配置、deploy方法全参数、返回值类型映射、并发保护与惰性加载机制并给出了 fixture 模块 与 测试用例 作为可运行的参考起点。若你的脚本与测试已基于 ethers.js那么在 Hardhat 3 项目中它就是衔接 Ignition 部署引擎的最直接方案。【免费下载链接】hardhatHardhat is a development environment to compile, deploy, test, and debug your Ethereum software.项目地址: https://gitcode.com/GitHub_Trending/ha/hardhat创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考