gem-hunter
Language: TypeScript
A library for composable tooling for onchain entities
A composable design philosophy for DAOs, Zodiac is a collection of tools built according to an open standard.
The Zodiac collection of tools can be accessed through the Zodiac App available on Safe, as well as through the repositories below. If you have any questions about Zodiac, join the Gnosis Guild Discord.
This repository links to technical tutorials on how to configure each using the CLI. (For operator tutorials, visit zodiac.wiki.)
Zodiac enables:
The Zodiac open standard consists of Avatars, Modules, Modifiers, and Guards architecture:
1. Avatars are programmable Ethereum accounts, like Safe. Avatars are the address that holds balances, owns systems, executes transaction, is referenced externally, and ultimately represents your DAO. Avatars must expose an interface like IAvatar.sol.
2. Modules are contracts enabled by an Avatar that implement some decision making logic. They should import Module.sol.
3. 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
4. Guards are contracts that can be enabled on Modules and implement pre- or post-checks on each transaction that the Module executes. This allows Avatars to do things like limit the scope of addresses and functions that a module can call or ensure a certain state is never changed by a module. Guards should import BaseGuard.sol.
This repository contains the Zodiac mastercopy tooling: a CLI and TypeScript SDK to extract deployed mastercopies (sources, ABI and bytecode) from block explorers into a versioned mastercopies/ folder, plus a registry of known Zodiac contracts and their canonical addresses.
The Zodiac core contracts (Module.sol, Modifier.sol, BaseGuard.sol, ModuleProxyFactory.sol, etc.), along with their tests and audits, live in zodiac-core. If you are building a module, modifier, or guard, use the @gnosis-guild/zodiac-core package.
yarn add @gnosis-guild/zodiac
To build your own contract based on the Zodiac core contracts, install zodiac-core and import from it:
pragma solidity ^0.8.6; import "@gnosis-guild/zodiac-core/contracts/core/Module.sol"; contract MyModule is Module { /// insert your code here }
The npm package publishes a small TypeScript SDK: the known-contract registry,
canonical mastercopy addresses, the supported-network list, and per-version
ABIs. The versioned mastercopies/ folder (the extracted source, ABI and
bytecode artifacts) is repo-maintenance data and is not published to npm —
neither are the maintenance commands/.
import { Contract } from "ethers"; import { getZodiacModuleAbi, // helper to get a specific ABI by name and version getZodiacModuleAddress, // helper to get a specific mastercopy address by name and version sanityCheckZodiacModuleAddress, // throw when an address is unknown or known faulty KnownContracts, // enum of known Zodiac contract names CanonicalAddresses, // canonical mastercopy addresses, by name@version SupportedNetworks, // chain name -> chainId } from "@gnosis-guild/zodiac"; // To interact with a specific version of a Zodiac module: const delayModule = new Contract( getZodiacModuleAddress(KnownContracts.DELAY, "1.1.1"), getZodiacModuleAbi(KnownContracts.DELAY, "1.1.1"), provider );
The package also re-exports the modern encoding and prediction helpers from
@gnosis-guild/zodiac-core. These
functions are the recommended way to handle deployments in the v5 paradigm,
replacing the legacy deployAndSetUpModule helper:
encodeDeployProxy: generate payload for the Zodiac factory.predictProxyAddress: predict the address of a proxy before deployment.encodeDeploySingleton: generate payload for singleton factories.predictSingletonAddress: predict the address of a singleton.The mastercopies/ artifacts are produced and managed with a CLI that runs the
TypeScript source locally via tsx (no build needed). Every command is driven
by the known-contract registry — you pass a name/version, not an address, and
unknown names/versions error out.
yarn extract [name] [version] [network] [--force] # explorer -> mastercopies/ yarn deploy <name> [version] [--all] # deploy missing artifacts on each network yarn deploy:list <name> [version] [--all] # report per-network deployment status yarn verify <name> [version] [--all] # verify deployed artifacts on each explorer yarn verify:list <name> [version] [--all] # report per-network verification status
extract captures mastercopy artifacts into mastercopies/:
yarn extract [name] [version] [network] [--force] # (no args) every known contract + version # <name> every version of that contract # <name> <ver> just that one
Existing folders are skipped unless --force is passed, which removes and
regenerates them. Source is read from [network] or, by default, the default
explorer set. It works entirely through the explorer: it fetches the verified
source and tries to recover the exact init code and salt from the deployment
transaction. When that succeeds, the contract can later reproduce at the same
address on every chain. If deployment recovery fails, the ABI and source are
still written, but the asset cannot be redeployed. Linked libraries are
discovered from the compiler input and extracted recursively. One folder is
written per asset (the main contract and each linked library):
mastercopies/<module>/<version>/<asset>/abi.json
mastercopies/<module>/<version>/<asset>/sourcecode.json # standard-JSON compiler input
mastercopies/<module>/<version>/<asset>/bytecode.json # optional: address, factory, salt, creationBytecode
deploy redeploys those artifacts to their canonical addresses on each
configured network (via the ERC-2470 / Nick CREATE2 singleton factories),
skipping any that already exist; verify submits the bundled source to each
configured explorer (Etherscan V2, or a chain-specific Etherscan-compatible
explorer — e.g. a Blockscout instance — where Etherscan V2 is unavailable). The
list subcommands report status without making changes. Without [version]
these commands target only the latest canonical version; pass --all to
include legacy versions, too.
Configure these in your env — see .env.sample:
ETHERSCAN_API_KEY — Etherscan V2 key (works across all supported chains).
Override per network with ETHERSCAN_API_KEY_<NETWORK>. Used by extract and
verify.ALCHEMY_KEY / INFURA_KEY — used to build RPC endpoints.MNEMONIC — signer used by deploy (local signing, the default).DEPLOY_VIA_FRAME — set to a truthy value (1/true/yes/on) to sign
deploy transactions through a locally running Frame
wallet instead of MNEMONIC (e.g. to use a hardware wallet). When enabled,
Frame must be running and MNEMONIC is ignored.The legacy bundled-ABI SDK (
MasterCopyInitData,ContractFactories,deployAndSetUpModule, …) was removed in v5; the known-contracts and canonical-address registry (KnownContracts,CanonicalAddresses) is kept.
Have you built something cool that belongs in this collection of Zodiac tools and want to add it to the list? Follow our contribution guidelines to open a PR!
If you have any questions about Zodiac, join the Gnosis Guild Discord. Follow @GnosisGuild on Twitter for updates.
The Zodiac documentation offers tutorials on how to use the Zodiac App, and detailed developer resources on how to build your own Zodiac module, modifier, or guard will be available soon.
Show your support for Zodiac by adding a badge or banner to your website or repository. Check out the preview images below, and select your preferred design for download. Please wrap the image with a hyperlink to Zodiac.
NOTE: To guarantee the most current design, copy the image URL and use the hosted version for embedding on your platform.
Your support through these badges and banners is greatly appreciated!
Banners
Badges
Copy and paste markdown (for README's) These snippets will render an image that links to this github repo.
[](https://github.com/gnosisguild/zodiac)
[](https://github.com/gnosisguild/zodiac)
Zodiac has been audited by the G0 group.
All issues and notes of the audit have been addressed in the release candidate v0.1.0 with commit hash 8a77e7b224af8004bd9f2ff4e2919642e93ffd85 and the subsequent release v1.0.0.
The audit results are available as a pdf in this repo or in the g0-group's github repo.
All contracts are WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
Zodiac is created under the LGPL-3.0+ license.