@gnosis-guild/zodiac-core

中文文档
4.3.0发布于 2026/07/14LGPL-3.0+TypeScriptESM + CJS近 30 天下载 2799

Zodiac is a composable design philosophy and collection of standards for building DAO ecosystem tooling.

原始使用文档
文档目录5 节
  1. Base Contracts
  2. SDK
  3. Encoding
  4. Deployment
  5. Verification

Zodiac-Core

Build Status Coverage Status Contributor Covenant

This package includes the base Zodiac contracts and interfaces from which Zodiac components are derived. It also includes a browser-safe TypeScript SDK for encoding module deployments and a separate tooling entrypoint for deployment and verification workflows.

Base Contracts

Module.sol

Modules are contracts enabled by an Avatar that implement some decision making logic. They should import Module.sol.

GuardableModule.sol

A module with a guard enabled that can check transactions before and after execution. Useful for limiting the scope of addresses and functions that a module can call or ensure a certain state is never changed by a module.

Modifier.sol

Modifiers are contracts that sit between Modules and Avatars to modify the Module's behavior. For example, they might enforce a delay on all functions a Module attempts to execute. Modifiers should import Modifier.sol and must expose an interface like IAvatar.sol

GuardableModifier.sol

A modifier with a guard enabled that can check transactions before and after execution. Useful for limiting the scope of addresses and functions that a modifier can call or ensure a certain state is never changed by a modifier.

SDK

The SDK provides functions for encoding, deploying, and verifying Zodiac modules.

Encoding

The functions in this section produce (but do not execute) payloads that when executed create mastercopies and module instances. These functions are commonly used in apps for deploying new instances of a Zodiac compliant module or modifier, as their payloads can be deployed by any connected account.

encodeDeployProxy

Generates a payload for deploying a new instance of a module/modifier - the new instance is a minimal proxy, deploy via ZodiacModuleProxyFactory and pointing to a module/modifier mastercopy.

import { encodeDeployProxy } from "@gnosis-guild/zodiac-core";

const transaction = await encodeDeployProxy({
  mastercopy: "0x<address>",
  setupArgs: { types: ["address", "uint256"], values: ["0x<address>", 0] },
  salt: "0x<bytes32>",
});

predictProxyAddress

Predicts the address of a new module instance, deployed via ZodiacModuleProxyFactory. Useful for deploying and making calls to a module or modifier in one multisend transaction.

import { predictProxyAddress } from "@gnosis-guild/zodiac-core";

const transaction = await predictProxyAddress({
  mastercopy: "0x<address>",
  setupArgs: { types: ["address", "uint256"], values: ["0x<address>", 0] },
  salt: "0x<bytes32>",
});

Deployment

The functions in this section accept an EIP1193-compliant provider and execute transactions that create mastercopies and module instances. Commonly used in contract infrastructure with a provider like hardhat when developing new modules or modifiers.

deployFactories

Deploys all factories within a specified network. Typically, these factories are already deployed across networks; however, this function is useful for test setups.

import { deployFactories } from "@gnosis-guild/zodiac-core/tooling";

await deployFactories({
  provider, // an EIP1193 compliant provider
});

deployMastercopy

Deploys a mastercopy using the ERC2470 factory. If the master copy is already deployed, this script will perform no operation. Returns an object containing the mastercopy address and a boolean indicating whether the master copy was previously deployed.

import { deployMastercopy } from "@gnosis-guild/zodiac-core/tooling";

await deployMastercopy({
  bytecode, // the mastercopy bytecode
  constructorArgs: { // mastercopy creation args
    types: ["uint256", "...more constructor types"]
    values: ["0", "...more constructor values"]
  },
  salt, // create2 salt
  provider, // an EIP1193 compliant provider
});

deployProxy

Deploys a module instance as a proxy using the ZodiacModuleProxyFactory. If an instance with the same saltNonce already exists, this function does nothing. Returns an object containing the module instance address and a boolean indicating whether the master copy was previously deployed.

import { deployProxy } from "@gnosis-guild/zodiac-core/tooling";

await deployProxy({
  mastercopy, // the mastercopy address
  setupArgs: { // instance setup args
    types: ["uint256", "...more setup types"]
    values: ["0", "...more setup values"]
  },
  saltNonce, // an integer, used to salt proxy deployment
  provider, // an EIP1193 compliant provider
});

Verification

The verification functions allow you to confirm that a deployed contract’s source code and metadata match what is expected on a blockchain explorer (such as Etherscan). These functions ensure that the API URL is reachable, the provided API key is valid, and check if the contract has already been verified. They also support an optional custom API URL for explorers that are not part of the default configuration.

verifyMastercopy

Verifies a Mastercopy contract by checking if it’s already verified on the explorer, and if not, submits the contract’s source code and metadata for verification.

import { verifyMastercopy } from "@gnosis-guild/zodiac-core/tooling";

const result = await verifyMastercopy({
  chainId: 1,
  apiKey: "YourEtherscanApiKey",
  artifact: {
    contractName: "MyContract",
    sourceName: "MyContract.sol",
    compilerVersion: "v0.8.0+commit.c7dfd78e",
    compilerInput: {},
    address: "0x1234567890abcdef1234567890abcdef12345678",
    constructorArgs: {
      types: ["uint256"],
      values: [42],
    },
  },
  apiUrl: "https://api.customnet.io/api", // Optional custom API URL
});

console.log(result);

版本与发布记录

@gnosis-guild/zodiac-core 共发布 23 个版本,首次发布于 2024/08/09;过去 12 个月发布了 9 个版本。

版本发布日期距今
4.3.0latest2026/07/144 个月前
4.2.02026/07/134 个月前
4.1.02026/06/184 个月前
4.0.12026/06/174 个月前
3.0.2v-32026/06/055 个月前
4.0.02026/06/035 个月前

关于 @gnosis-guild/zodiac-core 的常见问题

@gnosis-guild/zodiac-core 是什么?

Zodiac is a composable design philosophy and collection of standards for building DAO ecosystem tooling.

如何安装 @gnosis-guild/zodiac-core?

在项目目录运行 npm install @gnosis-guild/zodiac-core,或使用 pnpm add / yarn add / bun add。

@gnosis-guild/zodiac-core 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@gnosis-guild/zodiac-core 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@gnosis-guild/zodiac-core 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=24.0.0。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@gnosis-guild/zodiac-core 可以商用吗?

@gnosis-guild/zodiac-core 使用 LGPL-3.0+ 许可。弱 Copyleft:作为库被调用时通常不要求开源你自己的代码,但修改库本身需以 LGPL 开源;前端打包合并后的适用边界存在不同理解。以上为概括,不构成法律意见,请以许可原文为准。

@gnosis-guild/zodiac-core 的下载量有多少?

根据 npm 官方下载统计,@gnosis-guild/zodiac-core 在 2026/10/17 – 2026/11/15 这 30 天内被下载 2,799 次,日均约 93 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@gnosis-guild/zodiac-core 还在维护吗?

最新版本 4.3.0 发布于 2026/07/14(4 个月前);至今共发布 23 个版本,其中过去 12 个月发布了 9 个;首次发布于 2024/08/09。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。