This package includes the base Zodiac contracts and interfaces from which Zodiac components are derived. It also includes a typescript SDK for encoding, deploying, and managing mastercopies and module instances.
Modules are contracts enabled by an Avatar that implement some decision making logic. They should import Module.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.
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
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.
The SDK provides functions at three levels of abstraction: encoding, deployment, and artifact management.
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.
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>",
});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>",
});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.
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";
await deployFactories({
provider, // an EIP1193 compliant provider
});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";
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
});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";
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
});Functions in this section assist module authors in collecting, persisting, and retrieving mastercopy artifact data to disk. Components should retain all necessary data to deploy and verify mastercopies on a target network and its block explorer. Every released version should be tracked.
Extracts and stores current Mastercopy data from the contract build and adds it to the artifacts file, which defaults to mastercopies.json. This function is particularly useful when compiling contracts locally.
Inputs
• contractVersion - The version of the contract.
• contractName - The name of the contract.
• constructorArgs - The constructor arguments required for deployment.
• salt - A 32-byte value used for mastercopy deployment.
• factory - (Optional) The address of the factory contract used to deploy the mastercopy. Defaults to erc2470FactoryAddress.
• compilerInput - (Optional) The minimal compiler input.
• buildDirPath - (Optional) The path to the build directory. Defaults to defaultBuildDir().
• mastercopyArtifactsFile - (Optional) The path to the mastercopy artifacts file. Defaults to defaultMastercopyArtifactsFile().
Retrieves
• Compiled Bytecode
• Source Code - If compilerInput is not provided, it will be retrieved from the build directory.
import { writeMastercopyFromBuild } from "@gnosis-guild/zodiac-core";
writeMastercopyFromBuild({
contractVersion: "1.0.0",
contractName: "MyNewMod",
constructorArgs: {
types: ["uint256", "address"],
values: [0, "0x<address>"],
},
salt: "0x<bytes32>",
});Fetches and stores the Mastercopy data from a deployed contract on a blockchain by querying an explorer like Etherscan. This function is ideal for contracts already deployed.
Inputs
• contractVersion - The version of the contract.
• address - The address of the deployed contract.
• bytecode - The bytecode of the contract.
• constructorArgs - The constructor arguments used for deployment.
• salt - A 32-byte value used for mastercopy deployment.
• apiUrlOrChainId - The API URL or Chain ID of the explorer service.
• apiKey - The API key for accessing the explorer service.
• factory - (Optional) The address of the factory contract used to deploy the mastercopy. Defaults to erc2470FactoryAddress.
• mastercopyArtifactsFile - (Optional) The path to the mastercopy artifacts file. Defaults to defaultMastercopyArtifactsFile().
import { writeMastercopyFromExplorer } from "@gnosis-guild/zodiac-core";
await writeMastercopyFromExplorer({
contractVersion: "1.0.0",
address: "0x1234567890abcdef1234567890abcdef12345678",
bytecode: "0x608060405234801561001057600080fd5b506040516020806101...",
constructorArgs: {
types: ["address", "uint256"],
values: ["0x<address>", 0],
},
salt: "0xabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdef",
apiUrlOrChainId: "1",
apiKey: "YourEtherscanApiKey",
});Retrieves a collection of Mastercopy artifacts from a JSON artifacts file. This function allows access to stored mastercopy data, with optional filters for contractName and contractVersion to refine the results. If no filters are provided, all artifacts are returned.
Inputs
• contractName - (Optional) The name of the contract.
• contractVersion - (Optional) The version of the contract or "latest". If not provided, all versions will be retrieved.
• mastercopyArtifactsFile - (Optional) The path to the mastercopy artifacts file. Defaults to defaultMastercopyArtifactsFile().
import { readMastercopies } from "@gnosis-guild/zodiac-core";
const artifact = readMastercopy({
contractName: "MyNewMod",
contractVersion: "1.0.0",
});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 chain configuration 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. The function pauses for 500ms between verifications to prevent rate-limiting issues.
import verifyMastercopy from "@gnosis-guild/zodiac-core";
const result = await verifyMastercopy({
apiUrlOrChainId: "1", // or chain ID as a string
apiKey: "YourEtherscanApiKey",
artifact: {
contractName: "MyContract",
sourceName: "MyContract.sol",
compilerVersion: "v0.8.0+commit.c7dfd78e",
compilerInput: "{}",
address: "0x1234567890abcdef1234567890abcdef12345678",
constructorArgs: {
types: ["uint256"],
values: [42],
},
},
customChainConfig: { // Optional custom chain configuration
network: "customnet",
chainId: 1337,
urls: {
apiURL: "https://api.customnet.io/api",
browserURL: "https://customnet.io",
},
},
});
console.log(result);Note: In most cases, you will directly use verifyMastercopy for verifying mastercopies.