@gnosis-guild/zodiac 4.2.1 → 5.0.0

package/dist/esm/networks.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Source-of-truth network registry.
+ *
+ * One entry per chain referenced across the Zodiac repos (the in-repo chain
+ * list plus the chains served by `ser` and `rolesSubgraph`). Each entry carries:
+ *
+ *  - `chainId`          the canonical chain id
+ *  - `alchemyRpcUrl`    Alchemy JSON-RPC endpoint, or null when Alchemy does
+ *                       not serve the chain. The key is read from `ALCHEMY_KEY`.
+ *  - `publicRpc`        public JSON-RPC endpoint, or null when no public
+ *                       fallback is configured.
+ *  - `etherscanApiUrl`  Etherscan V2 multichain explorer API endpoint (with
+ *                       `?chainid=`), or null when the chain is not supported
+ *                       by Etherscan V2. V2 support was checked against
+ *                       api.etherscan.io/v2/chainlist.
+ *
+ * Entries are sorted by `chainId`.
+ *
+ * Not wired into anything yet — this is a config drop, intentionally standalone.
+ */
+export interface NetworkConfig {
+    name: string;
+    chainId: number;
+    /** Alchemy JSON-RPC URL, or null when Alchemy does not serve this chain. */
+    alchemyRpcUrl: string | null;
+    /** Public JSON-RPC endpoint, or null when no fallback is configured. */
+    publicRpc: string | null;
+    /** Etherscan V2 multichain API URL, or null when V2 does not support it. */
+    etherscanApiUrl: string | null;
+}
+export declare const networks: NetworkConfig[];
+/**
+ * Resolve a network name or chain id (string or number) to its config. An
+ * unknown name throws; an unknown numeric chain id resolves to an Etherscan V2
+ * entry only when that chain is listed by Etherscan V2.
+ */
+export declare function resolveNetwork(networkOrChainId: string | number): NetworkConfig;

package/dist/esm/networks.js

@@ -0,0 +1,229 @@
+/**
+ * Source-of-truth network registry.
+ *
+ * One entry per chain referenced across the Zodiac repos (the in-repo chain
+ * list plus the chains served by `ser` and `rolesSubgraph`). Each entry carries:
+ *
+ *  - `chainId`          the canonical chain id
+ *  - `alchemyRpcUrl`    Alchemy JSON-RPC endpoint, or null when Alchemy does
+ *                       not serve the chain. The key is read from `ALCHEMY_KEY`.
+ *  - `publicRpc`        public JSON-RPC endpoint, or null when no public
+ *                       fallback is configured.
+ *  - `etherscanApiUrl`  Etherscan V2 multichain explorer API endpoint (with
+ *                       `?chainid=`), or null when the chain is not supported
+ *                       by Etherscan V2. V2 support was checked against
+ *                       api.etherscan.io/v2/chainlist.
+ *
+ * Entries are sorted by `chainId`.
+ *
+ * Not wired into anything yet — this is a config drop, intentionally standalone.
+ */
+const ETHERSCAN_V2_API = "https://api.etherscan.io/v2/api";
+const alchemyKey = typeof process !== "undefined" ? process.env.ALCHEMY_KEY ?? "" : "";
+const ETHERSCAN_V2_CHAIN_IDS = new Set([
+    1, 10, 50, 51, 56, 100, 130, 143, 146, 199, 204, 252, 480, 988, 999, 1029,
+    1284, 1285, 1287, 1328, 1329, 2201, 2523, 2741, 4326, 4352, 5000, 5611, 6343,
+    8453, 9745, 9746, 10143, 11124, 33111, 33139, 42161, 42220, 43114, 43522,
+    59144, 80069, 80094, 81457, 167000, 167013, 560048, 737373, 747474, 11155111,
+    168587773,
+]);
+/** Build an Alchemy RPC URL from its endpoint subdomain. */
+const alchemy = (subdomain) => `https://${subdomain}.g.alchemy.com/v2/${alchemyKey}`;
+/** Build the Etherscan V2 multichain API URL for a chain. */
+const etherscanV2 = (chainId) => ETHERSCAN_V2_CHAIN_IDS.has(chainId)
+    ? `${ETHERSCAN_V2_API}?chainid=${chainId}`
+    : null;
+export const networks = [
+    {
+        name: "mainnet",
+        chainId: 1,
+        alchemyRpcUrl: alchemy("eth-mainnet"),
+        publicRpc: null,
+        etherscanApiUrl: etherscanV2(1),
+    },
+    {
+        name: "optimism",
+        chainId: 10,
+        alchemyRpcUrl: alchemy("opt-mainnet"),
+        publicRpc: null,
+        etherscanApiUrl: etherscanV2(10),
+    },
+    {
+        name: "flare",
+        chainId: 14,
+        alchemyRpcUrl: null,
+        publicRpc: "https://flare-api.flare.network/ext/C/rpc",
+        etherscanApiUrl: null,
+    },
+    {
+        name: "bnb",
+        chainId: 56,
+        alchemyRpcUrl: alchemy("bnb-mainnet"),
+        publicRpc: "https://bsc-dataseed.bnbchain.org",
+        etherscanApiUrl: etherscanV2(56),
+    },
+    {
+        name: "gnosis",
+        chainId: 100,
+        alchemyRpcUrl: null,
+        publicRpc: "https://rpc.gnosischain.com",
+        etherscanApiUrl: etherscanV2(100),
+    },
+    {
+        name: "unichain",
+        chainId: 130,
+        alchemyRpcUrl: alchemy("unichain-mainnet"),
+        publicRpc: "https://mainnet.unichain.org",
+        etherscanApiUrl: etherscanV2(130),
+    },
+    {
+        name: "polygon",
+        chainId: 137,
+        alchemyRpcUrl: alchemy("polygon-mainnet"),
+        publicRpc: null,
+        etherscanApiUrl: etherscanV2(137),
+    },
+    {
+        name: "sonic",
+        chainId: 146,
+        alchemyRpcUrl: null,
+        publicRpc: "https://rpc.soniclabs.com",
+        etherscanApiUrl: etherscanV2(146),
+    },
+    {
+        name: "worldchain",
+        chainId: 480,
+        alchemyRpcUrl: null,
+        publicRpc: "https://worldchain-mainnet.g.alchemy.com/public",
+        etherscanApiUrl: etherscanV2(480),
+    },
+    {
+        name: "hyperevm",
+        chainId: 999,
+        alchemyRpcUrl: null, //alchemy("hyperliquid-mainnet"),
+        publicRpc: null,
+        etherscanApiUrl: etherscanV2(999),
+    },
+    {
+        name: "megaeth",
+        chainId: 4326,
+        alchemyRpcUrl: alchemy("megaeth-mainnet"),
+        publicRpc: null,
+        etherscanApiUrl: etherscanV2(4326),
+    },
+    {
+        name: "mantle",
+        chainId: 5000,
+        alchemyRpcUrl: alchemy("mantle-mainnet"),
+        publicRpc: null,
+        etherscanApiUrl: etherscanV2(5000),
+    },
+    {
+        name: "base",
+        chainId: 8453,
+        alchemyRpcUrl: alchemy("base-mainnet"),
+        publicRpc: null,
+        etherscanApiUrl: etherscanV2(8453),
+    },
+    {
+        name: "plasma",
+        chainId: 9745,
+        alchemyRpcUrl: null,
+        publicRpc: "https://rpc.plasma.to",
+        etherscanApiUrl: etherscanV2(9745),
+    },
+    {
+        name: "arbitrum",
+        chainId: 42161,
+        alchemyRpcUrl: alchemy("arb-mainnet"),
+        publicRpc: null,
+        etherscanApiUrl: etherscanV2(42161),
+    },
+    {
+        name: "celo",
+        chainId: 42220,
+        alchemyRpcUrl: alchemy("celo-mainnet"),
+        publicRpc: null,
+        etherscanApiUrl: etherscanV2(42220),
+    },
+    {
+        name: "avalanche",
+        chainId: 43114,
+        alchemyRpcUrl: alchemy("avax-mainnet"),
+        publicRpc: null,
+        etherscanApiUrl: etherscanV2(43114),
+    },
+    {
+        name: "ink",
+        chainId: 57073,
+        alchemyRpcUrl: alchemy("ink-mainnet"),
+        publicRpc: "https://rpc-gel.inkonchain.com",
+        etherscanApiUrl: null,
+    },
+    {
+        name: "linea",
+        chainId: 59144,
+        alchemyRpcUrl: alchemy("linea-mainnet"),
+        publicRpc: null,
+        etherscanApiUrl: etherscanV2(59144),
+    },
+    {
+        name: "bob",
+        chainId: 60808,
+        alchemyRpcUrl: null,
+        publicRpc: "https://rpc.gobob.xyz",
+        etherscanApiUrl: null,
+    },
+    {
+        name: "berachain",
+        chainId: 80094,
+        alchemyRpcUrl: null,
+        publicRpc: "https://rpc.berachain.com",
+        etherscanApiUrl: etherscanV2(80094),
+    },
+    {
+        name: "scroll",
+        chainId: 534352,
+        alchemyRpcUrl: alchemy("scroll-mainnet"),
+        publicRpc: null,
+        etherscanApiUrl: null,
+    },
+    {
+        name: "katana",
+        chainId: 747474,
+        alchemyRpcUrl: null,
+        publicRpc: "https://rpc.katana.network",
+        etherscanApiUrl: etherscanV2(747474),
+    },
+    {
+        name: "sepolia",
+        chainId: 11155111,
+        alchemyRpcUrl: alchemy("eth-sepolia"),
+        publicRpc: null,
+        etherscanApiUrl: etherscanV2(11155111),
+    },
+];
+/**
+ * Resolve a network name or chain id (string or number) to its config. An
+ * unknown name throws; an unknown numeric chain id resolves to an Etherscan V2
+ * entry only when that chain is listed by Etherscan V2.
+ */
+export function resolveNetwork(networkOrChainId) {
+    const key = String(networkOrChainId).toLowerCase();
+    const found = networks.find((n) => n.name.toLowerCase() === key || String(n.chainId) === key);
+    if (found)
+        return found;
+    if (/^\d+$/.test(key)) {
+        const chainId = Number(key);
+        return {
+            name: key,
+            chainId,
+            alchemyRpcUrl: null,
+            publicRpc: null,
+            etherscanApiUrl: etherscanV2(chainId),
+        };
+    }
+    throw new Error(`Unknown network "${networkOrChainId}". Known networks: ${networks
+        .map((n) => n.name)
+        .join(", ")} (or pass a numeric chain id).`);
+}

package/dist/esm/package.json

@@ -0,0 +1 @@
+{"type":"module"}

package/dist/esm/rpc.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Perform a raw JSON-RPC eth_getCode call using fetch.
+ * This is used for fast, low-overhead status checks across many networks
+ * without initializing a full Ethers provider.
+ */
+export declare function getCode(rpcUrl: string, address: string): Promise<string>;

package/dist/esm/rpc.js

@@ -0,0 +1,33 @@
+/**
+ * Perform a raw JSON-RPC eth_getCode call using fetch.
+ * This is used for fast, low-overhead status checks across many networks
+ * without initializing a full Ethers provider.
+ */
+export async function getCode(rpcUrl, address) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 5_000);
+    try {
+        const response = await fetch(rpcUrl, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({
+                jsonrpc: "2.0",
+                id: 1,
+                method: "eth_getCode",
+                params: [address, "latest"],
+            }),
+            signal: controller.signal,
+        });
+        if (!response.ok) {
+            throw new Error(`RPC returned HTTP ${response.status}`);
+        }
+        const payload = (await response.json());
+        if (payload.error || typeof payload.result !== "string") {
+            throw new Error("RPC returned an invalid eth_getCode response");
+        }
+        return payload.result;
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}

package/dist/esm/singleton.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Known CREATE2 singleton factories used across the Zodiac ecosystem. Both
+ * yield identical addresses on every chain, which is what makes mastercopy
+ * replication address-stable.
+ */
+export declare const ERC2470_FACTORY = "0xce0042B868300000d44A59004Da54A005ffdcf9f";
+export declare const NICK_FACTORY = "0x4e59b44847b379578588920cA78FbF26c0B4956C";
+export interface RecoveredDeployment {
+    factory: string;
+    initCode: string;
+    salt: string;
+}
+/**
+ * Recover the init code and salt from a singleton-factory deployment
+ * transaction. Supports the ERC-2470 factory (an abi-encoded `deploy` call)
+ * and Nick's factory (raw `salt ++ initCode` calldata).
+ *
+ * Returns undefined when the transaction does not target a known factory, in
+ * which case the deployment cannot be replicated address-stably.
+ */
+export declare function recoverDeployment({ to, input, }: {
+    to: string | null;
+    input: string;
+}): RecoveredDeployment | undefined;

package/dist/esm/singleton.js

@@ -0,0 +1,38 @@
+import { Interface, getAddress, dataSlice, hexlify } from "ethers";
+/**
+ * Known CREATE2 singleton factories used across the Zodiac ecosystem. Both
+ * yield identical addresses on every chain, which is what makes mastercopy
+ * replication address-stable.
+ */
+export const ERC2470_FACTORY = "0xce0042B868300000d44A59004Da54A005ffdcf9f";
+export const NICK_FACTORY = "0x4e59b44847b379578588920cA78FbF26c0B4956C";
+const erc2470Interface = new Interface([
+    "function deploy(bytes _initCode, bytes32 _salt) returns (address)",
+]);
+/**
+ * Recover the init code and salt from a singleton-factory deployment
+ * transaction. Supports the ERC-2470 factory (an abi-encoded `deploy` call)
+ * and Nick's factory (raw `salt ++ initCode` calldata).
+ *
+ * Returns undefined when the transaction does not target a known factory, in
+ * which case the deployment cannot be replicated address-stably.
+ */
+export function recoverDeployment({ to, input, }) {
+    const factory = to ? getAddress(to) : null;
+    if (factory === getAddress(ERC2470_FACTORY)) {
+        try {
+            const [initCode, salt] = erc2470Interface.decodeFunctionData("deploy", input);
+            return { factory: ERC2470_FACTORY, initCode: hexlify(initCode), salt };
+        }
+        catch {
+            return undefined;
+        }
+    }
+    if (factory === getAddress(NICK_FACTORY)) {
+        // Nick's factory: calldata is salt (32 bytes) followed by the init code.
+        const salt = dataSlice(input, 0, 32);
+        const initCode = dataSlice(input, 32);
+        return { factory: NICK_FACTORY, initCode, salt };
+    }
+    return undefined;
+}

package/dist/esm/types.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Artifacts written for a single asset (the main contract or a linked library)
+ * under `mastercopies/<module>/<version>/<asset>/`. Each field maps to one file:
+ * `abi.json`, `sourcecode.json`, `bytecode.json`.
+ */
+/** Contents of `sourcecode.json`. */
+export interface SourceCodeFile {
+    contractName: string;
+    sourceName: string;
+    compilerVersion: string;
+    /** abi-encoded constructor arguments (hex, no leading 0x). */
+    constructorArguments?: string;
+    /** Solidity standard-JSON compiler input (verified source + settings). */
+    input: any;
+}
+/** Contents of `bytecode.json` — reproducible factory deployment metadata. */
+export interface BytecodeFile {
+    /** CREATE2 address. Reproduces on every chain from factory + salt + creationBytecode. */
+    address: string;
+    /** CREATE2 singleton factory the creation bytecode was relayed through. */
+    factory: string;
+    /** Salt recovered from the singleton-factory deployment transaction. */
+    salt: string;
+    /**
+     * Creation bytecode: the exact init code (creation code + abi-encoded
+     * constructor args, with any libraries linked). Relay this, with the same
+     * factory + salt, to redeploy at `address` on any other network.
+     */
+    creationBytecode: string;
+    /**
+     * Deployed (runtime) bytecode stored at `address` (`eth_getCode`). Not used
+     * to deploy — it's the on-chain identity, for comparison/verification.
+     */
+    bytecode: string;
+}
+/** A single extracted asset: one folder, three files. */
+export interface Asset {
+    /** Folder name: the main contract name or a linked-library name. */
+    name: string;
+    abi: any;
+    sourceCode: SourceCodeFile;
+    bytecode: BytecodeFile;
+}

package/dist/esm/types.js

@@ -0,0 +1,6 @@
+/**
+ * Artifacts written for a single asset (the main contract or a linked library)
+ * under `mastercopies/<module>/<version>/<asset>/`. Each field maps to one file:
+ * `abi.json`, `sourcecode.json`, `bytecode.json`.
+ */
+export {};

package/dist/esm/ui.d.ts

@@ -0,0 +1,16 @@
+export declare const CHECK = "\u2713";
+export declare const CROSS = "\u2717";
+export declare const QUESTION = "?";
+export declare function color(value: string, colorName: "green" | "red" | "yellow"): string;
+export declare function visibleLength(value: string): number;
+export declare function formatRow(row: string[], widths: number[]): string;
+export declare function printTable(headers: string[], rows: {
+    network: string;
+    cells: {
+        label: string;
+    }[];
+}[], caption: string[]): void;
+export declare function renderProgress(completed: number, total: number, label?: string): void;
+export declare function clearProgress(): void;
+export declare function showTransient(message: string): void;
+export declare function printStatusLine(message: string): void;

package/dist/esm/ui.js

@@ -0,0 +1,53 @@
+import { clearLine, cursorTo } from "readline";
+export const CHECK = "✓";
+export const CROSS = "✗";
+export const QUESTION = "?";
+export function color(value, colorName) {
+    const code = colorName === "green" ? 32 : colorName === "red" ? 31 : 33;
+    return `\u001b[${code}m${value}\u001b[0m`;
+}
+export function visibleLength(value) {
+    return value.replace(/\u001b\[[0-9;]*m/g, "").length;
+}
+export function formatRow(row, widths) {
+    return row
+        .map((value, index) => value + " ".repeat(widths[index] - visibleLength(value)))
+        .join("  ");
+}
+export function printTable(headers, rows, caption) {
+    const body = rows.map((row) => [
+        row.network,
+        ...row.cells.map((c) => c.label),
+    ]);
+    const widths = headers.map((header, index) => Math.max(header.length, ...body.map((row) => visibleLength(row[index]))));
+    console.log(formatRow(headers, widths));
+    console.log(widths.map((width) => "-".repeat(width)).join("  "));
+    for (const row of body) {
+        console.log(formatRow(row, widths));
+    }
+    console.log();
+    console.log(caption.join("  "));
+}
+export function renderProgress(completed, total, label = "Checking deployments") {
+    if (!process.stderr.isTTY)
+        return;
+    cursorTo(process.stderr, 0);
+    process.stderr.write(`${label}: ${completed}/${total} requests`);
+}
+export function clearProgress() {
+    if (!process.stderr.isTTY)
+        return;
+    cursorTo(process.stderr, 0);
+    clearLine(process.stderr, 0);
+}
+export function showTransient(message) {
+    if (!process.stderr.isTTY)
+        return;
+    clearProgress();
+    cursorTo(process.stderr, 0);
+    process.stderr.write(message);
+}
+export function printStatusLine(message) {
+    clearProgress();
+    console.log(message);
+}

package/dist/esm/zodiacModule.d.ts

@@ -0,0 +1,4 @@
+import { KnownContracts } from "./contracts.js";
+export declare function getZodiacModuleAbi(name: KnownContracts, versionRange?: string): readonly unknown[];
+export declare function getZodiacModuleAddress(name: KnownContracts, versionRange?: string): string;
+export declare function sanityCheckZodiacModuleAddress(address: string): void;

package/dist/esm/zodiacModule.js

@@ -0,0 +1,56 @@
+import { compare, satisfies, valid } from "semver";
+import { ABIs } from "./abis/index.js";
+import { CanonicalAddresses, FAULTY } from "./contracts.js";
+export function getZodiacModuleAbi(name, versionRange = "*") {
+    const versions = ABIs[name];
+    if (!versions) {
+        throw new Error(`No ABI registry for ${name}`);
+    }
+    const version = matchingVersion(versions, versionRange);
+    if (!version) {
+        throw new Error(`No ABI for ${name}@${versionRange}`);
+    }
+    const address = CanonicalAddresses[name]?.[version];
+    if (!address) {
+        throw new Error(`No address for ${name}@${version}`);
+    }
+    sanityCheckZodiacModuleAddress(address);
+    return versions[version];
+}
+export function getZodiacModuleAddress(name, versionRange = "*") {
+    const versions = CanonicalAddresses[name];
+    if (!versions) {
+        throw new Error(`No address registry for ${name}`);
+    }
+    const version = matchingVersion(versions, versionRange, Boolean);
+    if (!version) {
+        throw new Error(`No address for ${name}@${versionRange}`);
+    }
+    sanityCheckZodiacModuleAddress(versions[version]);
+    return versions[version];
+}
+export function sanityCheckZodiacModuleAddress(address) {
+    const normalizedAddress = address.toLowerCase();
+    const canonicalAddresses = flattenAddresses(CanonicalAddresses);
+    const faultyAddresses = flattenAddresses(FAULTY);
+    if (!canonicalAddresses.has(normalizedAddress)) {
+        throw new Error(`Unknown Zodiac module address: ${address}`);
+    }
+    if (faultyAddresses.has(normalizedAddress)) {
+        throw new Error(`Faulty Zodiac module address: ${address}`);
+    }
+}
+function matchingVersion(versions, versionRange, predicate = () => true) {
+    return Object.entries(versions)
+        .filter(([, value]) => predicate(value))
+        .map(([entry]) => entry)
+        .sort(compare)
+        .reverse()
+        .find((entry) => satisfies(entry, valid(versionRange) ? `=${versionRange}` : versionRange));
+}
+function flattenAddresses(addresses) {
+    return new Set(Object.values(addresses)
+        .flatMap((versions) => Object.values(versions ?? {}))
+        .filter(Boolean)
+        .map((address) => address.toLowerCase()));
+}