@gnosis-guild/zodiac 4.2.1 → 5.0.0

package/README.md

@@ -1,7 +1,6 @@
 # Zodiac: The expansion pack for DAOs
 
 [![Build Status](https://github.com/gnosisguild/zodiac/workflows/zodiac/badge.svg?branch=master)](https://github.com/gnosisguild/zodiac/actions?branch=master)
-[![Coverage Status](https://coveralls.io/repos/github/gnosis/zodiac/badge.svg?branch=master)](https://coveralls.io/github/gnosisguild/zodiac?branch=master)
 [![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](https://github.com/gnosisguild/CODE_OF_CONDUCT)
 
 A composable design philosophy for DAOs, [Zodiac](https://gnosisguild.mirror.xyz/OuhG5s2X5uSVBx1EK4tKPhnUc91Wh9YM0fwSnC8UNcg) is a collection of tools built according to an open standard.
@@ -30,6 +29,10 @@ The Zodiac open standard consists of Avatars, Modules, Modifiers, and Guards arc
 
 ## Overview
 
+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](https://github.com/gnosisguild/zodiac-core). If you are building a module, modifier, or guard, use the `@gnosis-guild/zodiac-core` package.
+
 ### Installation
 
 ```bash
@@ -38,12 +41,12 @@ yarn add @gnosis-guild/zodiac
 
 ### Usage
 
-Once installed, you can use the contracts in the library by importing them to your contract:
+To build your own contract based on the Zodiac core contracts, install [zodiac-core](https://github.com/gnosisguild/zodiac-core) and import from it:
 
 ```solidity
 pragma solidity ^0.8.6;
 
-import "@gnosis-guild/zodiac/contracts/core/Module.sol";
+import "@gnosis-guild/zodiac-core/contracts/core/Module.sol";
 
 contract MyModule is Module {
   /// insert your code here
@@ -51,11 +54,111 @@ contract MyModule is Module {
 
 ```
 
+### Mastercopies
+
+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/`.
+
+```ts
+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`](https://github.com/gnosisguild/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.
+
+#### Maintenance CLI
+
+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.
+
+```bash
+yarn extract [name] [version] [network] [--force]   # explorer -> mastercopies/
+yarn deploy  <name> [version]                        # deploy missing artifacts on each network
+yarn deploy:list <name> [version]                    # report per-network deployment status
+yarn verify  <name> [version]                        # verify deployed artifacts on each explorer
+yarn verify:list <name> [version]                    # report per-network verification status
+```
+
+**`extract`** captures mastercopy artifacts into `mastercopies/`:
+
+```bash
+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 recovers the exact init code and salt from the deployment
+transaction, so a contract can later reproduce at the same address on every
+chain. 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     # 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 Etherscan V2 explorer. The `list` subcommands report status without
+making changes.
+
+#### Environment
+
+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](https://frame.sh)
+  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.
+
 ### Zodiac compliant tools
 
 #### Avatars
 
-- **[Safe](https://safe.global)**: The most trusted platform for managing digital assets on Ethereum. Zodiac embraces Safe as a powerful, extensible and programmable account standard. Safe is the reference implementation of the [IAvatar.sol](contracts/interfaces/IAvatar.sol) interface specified in this library. However, all Zodiac tools are framework agnostic, and they can be plugged into any programmable account that implements the IAvatar interface.
+- **[Safe](https://safe.global)**: The most trusted platform for managing digital assets on Ethereum. Zodiac embraces Safe as a powerful, extensible and programmable account standard. Safe is the reference implementation of the [IAvatar.sol](https://github.com/gnosisguild/zodiac-core/blob/main/contracts/interfaces/IAvatar.sol) interface specified in this library. However, all Zodiac tools are framework agnostic, and they can be plugged into any programmable account that implements the IAvatar interface.
 
 #### Modules
 

package/dist/cjs/abis/bridge/1.0.0.js

@@ -0,0 +1,385 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.bridge_1_0_0_ABI = void 0;
+exports.bridge_1_0_0_ABI = [
+    {
+        "inputs": [
+            {
+                "internalType": "address",
+                "name": "_owner",
+                "type": "address"
+            },
+            {
+                "internalType": "address",
+                "name": "_avatar",
+                "type": "address"
+            },
+            {
+                "internalType": "address",
+                "name": "_target",
+                "type": "address"
+            },
+            {
+                "internalType": "contract IAMB",
+                "name": "_amb",
+                "type": "address"
+            },
+            {
+                "internalType": "address",
+                "name": "_controller",
+                "type": "address"
+            },
+            {
+                "internalType": "bytes32",
+                "name": "_chainId",
+                "type": "bytes32"
+            }
+        ],
+        "stateMutability": "nonpayable",
+        "type": "constructor"
+    },
+    {
+        "anonymous": false,
+        "inputs": [
+            {
+                "indexed": true,
+                "internalType": "address",
+                "name": "initiator",
+                "type": "address"
+            },
+            {
+                "indexed": true,
+                "internalType": "address",
+                "name": "owner",
+                "type": "address"
+            },
+            {
+                "indexed": true,
+                "internalType": "address",
+                "name": "avatar",
+                "type": "address"
+            },
+            {
+                "indexed": false,
+                "internalType": "address",
+                "name": "target",
+                "type": "address"
+            }
+        ],
+        "name": "AmbModuleSetup",
+        "type": "event"
+    },
+    {
+        "anonymous": false,
+        "inputs": [
+            {
+                "indexed": true,
+                "internalType": "address",
+                "name": "previousAvatar",
+                "type": "address"
+            },
+            {
+                "indexed": true,
+                "internalType": "address",
+                "name": "newAvatar",
+                "type": "address"
+            }
+        ],
+        "name": "AvatarSet",
+        "type": "event"
+    },
+    {
+        "anonymous": false,
+        "inputs": [
+            {
+                "indexed": false,
+                "internalType": "address",
+                "name": "guard",
+                "type": "address"
+            }
+        ],
+        "name": "ChangedGuard",
+        "type": "event"
+    },
+    {
+        "anonymous": false,
+        "inputs": [
+            {
+                "indexed": true,
+                "internalType": "address",
+                "name": "previousOwner",
+                "type": "address"
+            },
+            {
+                "indexed": true,
+                "internalType": "address",
+                "name": "newOwner",
+                "type": "address"
+            }
+        ],
+        "name": "OwnershipTransferred",
+        "type": "event"
+    },
+    {
+        "anonymous": false,
+        "inputs": [
+            {
+                "indexed": true,
+                "internalType": "address",
+                "name": "previousTarget",
+                "type": "address"
+            },
+            {
+                "indexed": true,
+                "internalType": "address",
+                "name": "newTarget",
+                "type": "address"
+            }
+        ],
+        "name": "TargetSet",
+        "type": "event"
+    },
+    {
+        "inputs": [],
+        "name": "amb",
+        "outputs": [
+            {
+                "internalType": "contract IAMB",
+                "name": "",
+                "type": "address"
+            }
+        ],
+        "stateMutability": "view",
+        "type": "function"
+    },
+    {
+        "inputs": [],
+        "name": "avatar",
+        "outputs": [
+            {
+                "internalType": "address",
+                "name": "",
+                "type": "address"
+            }
+        ],
+        "stateMutability": "view",
+        "type": "function"
+    },
+    {
+        "inputs": [],
+        "name": "chainId",
+        "outputs": [
+            {
+                "internalType": "bytes32",
+                "name": "",
+                "type": "bytes32"
+            }
+        ],
+        "stateMutability": "view",
+        "type": "function"
+    },
+    {
+        "inputs": [],
+        "name": "controller",
+        "outputs": [
+            {
+                "internalType": "address",
+                "name": "",
+                "type": "address"
+            }
+        ],
+        "stateMutability": "view",
+        "type": "function"
+    },
+    {
+        "inputs": [
+            {
+                "internalType": "address",
+                "name": "to",
+                "type": "address"
+            },
+            {
+                "internalType": "uint256",
+                "name": "value",
+                "type": "uint256"
+            },
+            {
+                "internalType": "bytes",
+                "name": "data",
+                "type": "bytes"
+            },
+            {
+                "internalType": "enum Enum.Operation",
+                "name": "operation",
+                "type": "uint8"
+            }
+        ],
+        "name": "executeTransaction",
+        "outputs": [],
+        "stateMutability": "nonpayable",
+        "type": "function"
+    },
+    {
+        "inputs": [],
+        "name": "getGuard",
+        "outputs": [
+            {
+                "internalType": "address",
+                "name": "_guard",
+                "type": "address"
+            }
+        ],
+        "stateMutability": "view",
+        "type": "function"
+    },
+    {
+        "inputs": [],
+        "name": "guard",
+        "outputs": [
+            {
+                "internalType": "address",
+                "name": "",
+                "type": "address"
+            }
+        ],
+        "stateMutability": "view",
+        "type": "function"
+    },
+    {
+        "inputs": [],
+        "name": "owner",
+        "outputs": [
+            {
+                "internalType": "address",
+                "name": "",
+                "type": "address"
+            }
+        ],
+        "stateMutability": "view",
+        "type": "function"
+    },
+    {
+        "inputs": [],
+        "name": "renounceOwnership",
+        "outputs": [],
+        "stateMutability": "nonpayable",
+        "type": "function"
+    },
+    {
+        "inputs": [
+            {
+                "internalType": "address",
+                "name": "_amb",
+                "type": "address"
+            }
+        ],
+        "name": "setAmb",
+        "outputs": [],
+        "stateMutability": "nonpayable",
+        "type": "function"
+    },
+    {
+        "inputs": [
+            {
+                "internalType": "address",
+                "name": "_avatar",
+                "type": "address"
+            }
+        ],
+        "name": "setAvatar",
+        "outputs": [],
+        "stateMutability": "nonpayable",
+        "type": "function"
+    },
+    {
+        "inputs": [
+            {
+                "internalType": "bytes32",
+                "name": "_chainId",
+                "type": "bytes32"
+            }
+        ],
+        "name": "setChainId",
+        "outputs": [],
+        "stateMutability": "nonpayable",
+        "type": "function"
+    },
+    {
+        "inputs": [
+            {
+                "internalType": "address",
+                "name": "_controller",
+                "type": "address"
+            }
+        ],
+        "name": "setController",
+        "outputs": [],
+        "stateMutability": "nonpayable",
+        "type": "function"
+    },
+    {
+        "inputs": [
+            {
+                "internalType": "address",
+                "name": "_guard",
+                "type": "address"
+            }
+        ],
+        "name": "setGuard",
+        "outputs": [],
+        "stateMutability": "nonpayable",
+        "type": "function"
+    },
+    {
+        "inputs": [
+            {
+                "internalType": "address",
+                "name": "_target",
+                "type": "address"
+            }
+        ],
+        "name": "setTarget",
+        "outputs": [],
+        "stateMutability": "nonpayable",
+        "type": "function"
+    },
+    {
+        "inputs": [
+            {
+                "internalType": "bytes",
+                "name": "initParams",
+                "type": "bytes"
+            }
+        ],
+        "name": "setUp",
+        "outputs": [],
+        "stateMutability": "nonpayable",
+        "type": "function"
+    },
+    {
+        "inputs": [],
+        "name": "target",
+        "outputs": [
+            {
+                "internalType": "address",
+                "name": "",
+                "type": "address"
+            }
+        ],
+        "stateMutability": "view",
+        "type": "function"
+    },
+    {
+        "inputs": [
+            {
+                "internalType": "address",
+                "name": "newOwner",
+                "type": "address"
+            }
+        ],
+        "name": "transferOwnership",
+        "outputs": [],
+        "stateMutability": "nonpayable",
+        "type": "function"
+    }
+];