@gnosis-guild/zodiac 4.2.0 → 5.0.0

package/dist/esm/explorer.js

@@ -0,0 +1,256 @@
+import { resolveNetwork } from "./networks.js";
+function isOk(status) {
+    return String(status) === "1";
+}
+/**
+ * Etherscan double-wraps the standard-JSON source in extra braces. Parse
+ * tolerantly so both `{{...}}` and `{...}` payloads succeed.
+ */
+function safeJsonParse(input) {
+    const trimmed = input.trim();
+    try {
+        return JSON.parse(trimmed);
+    }
+    catch {
+        return JSON.parse(trimmed.replace(/^\{|\}$/g, "").trim());
+    }
+}
+function parseLibraries(input) {
+    const libraries = {};
+    for (const entry of (input || "").split(/[;,]/)) {
+        const match = entry.trim().match(/^(.+?)(?::|\s)+(0x[0-9a-fA-F]{40})$/);
+        if (match)
+            libraries[match[1].trim()] = match[2];
+    }
+    return libraries;
+}
+function compilerInputFromExplorerEntry(entry) {
+    const sourceCode = entry.SourceCode.trim();
+    const contractName = entry.ContractName;
+    if (sourceCode.startsWith("{")) {
+        const compilerInput = safeJsonParse(sourceCode);
+        return {
+            compilerInput,
+            sourceName: sourceNameFor(compilerInput, contractName),
+        };
+    }
+    const sourceName = entry.ContractFileName || `${contractName}.sol`;
+    const settings = {};
+    if (entry.OptimizationUsed !== "") {
+        settings.optimizer = {
+            enabled: String(entry.OptimizationUsed) === "1",
+            runs: Number(entry.Runs) || 200,
+        };
+    }
+    if (entry.EVMVersion && entry.EVMVersion !== "Default") {
+        settings.evmVersion = entry.EVMVersion;
+    }
+    const libraries = parseLibraries(entry.Library);
+    if (Object.keys(libraries).length > 0) {
+        settings.libraries = { [sourceName]: libraries };
+    }
+    return {
+        sourceName,
+        compilerInput: {
+            language: "Solidity",
+            sources: {
+                [sourceName]: { content: sourceCode },
+            },
+            settings,
+        },
+    };
+}
+function resolveApiKey(network, explicit) {
+    return (explicit ||
+        process.env[`ETHERSCAN_API_KEY_${network.toUpperCase()}`] ||
+        process.env.ETHERSCAN_API_KEY ||
+        "");
+}
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+function isRateLimited(body) {
+    const text = `${body?.message ?? ""} ${body?.result ?? ""}`.toLowerCase();
+    return text.includes("rate limit");
+}
+/**
+ * Internal helper to perform a GET against the explorer API.
+ * Resolves network, API key, and handles rate-limiting retries.
+ */
+async function explorerGet(networkOrChainId, params, apiKey, attempt = 0) {
+    const network = resolveNetwork(networkOrChainId);
+    if (!network.etherscanApiUrl) {
+        throw new Error(`${network.name} (chain ${network.chainId}) is not supported by Etherscan V2.`);
+    }
+    const url = new URL(network.etherscanApiUrl);
+    url.searchParams.set("apikey", resolveApiKey(network.name, apiKey));
+    for (const [key, value] of Object.entries(params)) {
+        url.searchParams.set(key, value);
+    }
+    const response = await fetch(url);
+    if (!response.ok) {
+        throw new Error(`Explorer request failed: ${response.status}`);
+    }
+    const body = (await response.json());
+    if (isRateLimited(body) && attempt < 5) {
+        await sleep(1000 * (attempt + 1));
+        return explorerGet(networkOrChainId, params, apiKey, attempt + 1);
+    }
+    return body;
+}
+async function explorerPost(networkOrChainId, params, apiKey, attempt = 0) {
+    const network = resolveNetwork(networkOrChainId);
+    if (!network.etherscanApiUrl) {
+        throw new Error(`${network.name} (chain ${network.chainId}) is not supported by Etherscan V2.`);
+    }
+    const body = new URLSearchParams();
+    body.set("apikey", resolveApiKey(network.name, apiKey));
+    for (const [key, value] of new URL(network.etherscanApiUrl).searchParams) {
+        body.set(key, value);
+    }
+    for (const [key, value] of Object.entries(params)) {
+        body.set(key, value);
+    }
+    const response = await fetch(network.etherscanApiUrl, {
+        method: "POST",
+        headers: {
+            "content-type": "application/x-www-form-urlencoded",
+        },
+        body,
+    });
+    if (!response.ok) {
+        throw new Error(`Explorer request failed: ${response.status}`);
+    }
+    const responseBody = (await response.json());
+    if (isRateLimited(responseBody) && attempt < 5) {
+        await sleep(1000 * (attempt + 1));
+        return explorerPost(networkOrChainId, params, apiKey, attempt + 1);
+    }
+    return responseBody;
+}
+/**
+ * Fetch verified source, ABI and compiler input for a deployed contract.
+ */
+export async function getSourceCode({ address, network, apiKey, }) {
+    const { status, message, result } = await explorerGet(network, {
+        module: "contract",
+        action: "getsourcecode",
+        address,
+    }, apiKey);
+    if (!isOk(status)) {
+        throw new Error(`getsourcecode failed for ${address}: ${message}${result ? ` (${result})` : ""}`);
+    }
+    const entry = result[0];
+    if (!entry?.SourceCode) {
+        throw new Error(`Contract ${address} is not verified on ${network}`);
+    }
+    const { compilerInput, sourceName } = compilerInputFromExplorerEntry(entry);
+    return {
+        contractName: entry.ContractName,
+        sourceName,
+        compilerVersion: entry.CompilerVersion,
+        compilerInput,
+        abi: entry.ABI ? safeJsonParse(entry.ABI) : undefined,
+        constructorArguments: entry.ConstructorArguments || "",
+    };
+}
+/**
+ * Resolve the full source path for a contract name within a standard-JSON input.
+ */
+function sourceNameFor(compilerInput, contractName) {
+    const sources = compilerInput?.sources || {};
+    // Prefer a source file whose path basename matches the contract name.
+    const match = Object.keys(sources).find((path) => path
+        .split("/")
+        .pop()
+        ?.replace(/\.sol$/, "") === contractName);
+    if (match)
+        return match;
+    const [only] = Object.keys(sources);
+    if (only)
+        return only;
+    throw new Error(`Could not resolve sourceName for ${contractName}`);
+}
+/**
+ * Get creation metadata (tx hash and bytecode) for a contract.
+ */
+export async function getContractCreation({ address, network, apiKey, }) {
+    const { status, result } = await explorerGet(network, {
+        module: "contract",
+        action: "getcontractcreation",
+        contractaddresses: address,
+    }, apiKey);
+    if (!isOk(status) || !Array.isArray(result) || result.length === 0) {
+        return undefined;
+    }
+    return {
+        txHash: result[0].txHash,
+        creationBytecode: result[0].creationBytecode,
+    };
+}
+/**
+ * Fetch a transaction (input + to) via the explorer's proxy module.
+ */
+export async function getTransaction({ txHash, network, apiKey, }) {
+    const { result } = await explorerGet(network, {
+        module: "proxy",
+        action: "eth_getTransactionByHash",
+        txhash: txHash,
+    }, apiKey);
+    if (!result?.input)
+        return undefined;
+    return { to: result.to ?? null, input: result.input };
+}
+/**
+ * Fetch the deployed (runtime) bytecode at an address via the proxy module.
+ */
+export async function getCode({ address, network, apiKey, }) {
+    const { result } = await explorerGet(network, {
+        module: "proxy",
+        action: "eth_getCode",
+        address,
+        tag: "latest",
+    }, apiKey);
+    return result ?? "0x";
+}
+/**
+ * Submit standard-JSON Solidity source for verification.
+ */
+export async function verifySourceCode({ address, network, sourceCode, contractName, compilerVersion, constructorArguments = "", evmVersion = "default", licenseType = "1", apiKey, }) {
+    const { status, message, result } = await explorerPost(network, {
+        module: "contract",
+        action: "verifysourcecode",
+        contractaddress: address,
+        sourceCode,
+        codeformat: "solidity-standard-json-input",
+        contractname: contractName,
+        compilerversion: compilerVersion,
+        optimizationUsed: "0",
+        runs: "200",
+        constructorArguments,
+        evmVersion,
+        licenseType,
+    }, apiKey);
+    if (!isOk(status)) {
+        if (typeof result === "string" &&
+            result.toLowerCase().includes("already")) {
+            return result;
+        }
+        throw new Error(`${message}${result ? ` (${result})` : ""}`);
+    }
+    return result;
+}
+/**
+ * Check the async source verification status for a submitted GUID.
+ */
+export async function checkVerificationStatus({ guid, network, apiKey, }) {
+    const { status, message, result } = await explorerPost(network, {
+        module: "contract",
+        action: "checkverifystatus",
+        guid,
+    }, apiKey);
+    if (!isOk(status)) {
+        if (typeof result === "string" && result)
+            return result;
+        throw new Error(`${message}${result ? ` (${result})` : ""}`);
+    }
+    return result;
+}

package/dist/esm/extract.d.ts

@@ -0,0 +1,15 @@
+import { Asset } from "./types.js";
+/**
+ * Extract an asset (and, recursively, every library it links) from a block
+ * explorer.
+ *
+ * Recursion is depth-first and deduplicated by address, so a library shared by
+ * several contracts is fetched once.
+ *
+ * @returns every asset produced, keyed by lower-cased address.
+ */
+export declare function extract({ network, address, apiKey, }: {
+    network: string | number;
+    address: string;
+    apiKey?: string;
+}): Promise<Map<string, Asset>>;

package/dist/esm/extract.js

@@ -0,0 +1,114 @@
+import { getAddress } from "ethers";
+import { predictSingletonAddress } from "@gnosis-guild/zodiac-core";
+import { resolveNetwork } from "./networks.js";
+import { getCode, getContractCreation, getSourceCode, getTransaction, } from "./explorer.js";
+import { recoverDeployment } from "./singleton.js";
+/**
+ * Enumerate the libraries a contract links, from its standard-JSON compiler
+ * input. Shape: `settings.libraries = { [sourceName]: { [libName]: address } }`.
+ */
+function enumerateLibraries(input) {
+    const libraries = input?.settings?.libraries || {};
+    const out = [];
+    for (const sourceName of Object.keys(libraries)) {
+        for (const libraryName of Object.keys(libraries[sourceName] || {})) {
+            const address = libraries[sourceName][libraryName];
+            if (address)
+                out.push({ sourceName, libraryName, address });
+        }
+    }
+    return out;
+}
+/**
+ * Extract an asset (and, recursively, every library it links) from a block
+ * explorer.
+ *
+ * Recursion is depth-first and deduplicated by address, so a library shared by
+ * several contracts is fetched once.
+ *
+ * @returns every asset produced, keyed by lower-cased address.
+ */
+export async function extract({ network, address, apiKey, }) {
+    const net = resolveNetwork(network);
+    const visited = new Map();
+    await extractOne({
+        address,
+        networkName: net.name,
+        apiKey,
+        visited,
+    });
+    return visited;
+}
+async function extractOne({ address, nameHint, networkName, apiKey, visited, }) {
+    const key = getAddress(address).toLowerCase();
+    const existing = visited.get(key);
+    if (existing)
+        return existing;
+    const source = await getSourceCode({ address, network: networkName, apiKey });
+    const name = nameHint || source.contractName;
+    const creation = await getContractCreation({
+        address,
+        network: networkName,
+        apiKey,
+    });
+    const tx = creation?.txHash
+        ? await getTransaction({
+            txHash: creation.txHash,
+            network: networkName,
+            apiKey,
+        })
+        : undefined;
+    const recovered = tx && recoverDeployment(tx);
+    if (!recovered) {
+        throw new Error(`${name} @ ${address} was not deployed via a known singleton factory.`);
+    }
+    const { factory, initCode: creationBytecode, salt } = recovered;
+    // Sanity: the recovered creation bytecode must reproduce the on-chain address
+    // via CREATE2. By construction it always does — a failure means a parsing bug.
+    // zodiac-core's helper concatenates bytecode + encoded constructor args; we
+    // already hold the full creation bytecode, so pass it as `bytecode` with empty
+    // args (the concat is then a no-op).
+    const predicted = predictSingletonAddress({
+        factory,
+        bytecode: creationBytecode,
+        constructorArgs: { types: [], values: [] },
+        salt,
+    });
+    if (predicted.toLowerCase() !== key) {
+        throw new Error(`${name} @ ${address}: recovered creation bytecode reproduces ` +
+            `${predicted}, not the on-chain address. Refusing to write.`);
+    }
+    // Deployed (runtime) bytecode actually stored at the address.
+    const bytecode = await getCode({ address, network: networkName, apiKey });
+    // Record this asset before recursing so shared libraries dedupe correctly.
+    const asset = {
+        name,
+        abi: source.abi,
+        sourceCode: {
+            contractName: source.contractName,
+            sourceName: source.sourceName,
+            compilerVersion: source.compilerVersion,
+            constructorArguments: source.constructorArguments,
+            input: source.compilerInput,
+        },
+        bytecode: {
+            address: predicted,
+            factory,
+            salt,
+            creationBytecode,
+            bytecode,
+        },
+    };
+    visited.set(key, asset);
+    // Recurse into linked libraries.
+    for (const lib of enumerateLibraries(source.compilerInput)) {
+        await extractOne({
+            address: lib.address,
+            nameHint: lib.libraryName,
+            networkName,
+            apiKey,
+            visited,
+        });
+    }
+    return asset;
+}

package/dist/esm/index.d.ts

@@ -1 +1,3 @@
-export * from "./factory";
+export { encodeDeployProxy, encodeDeploySingleton, predictProxyAddress, predictSingletonAddress, } from "@gnosis-guild/zodiac-core";
+export { CanonicalAddresses, KnownContracts, SupportedNetworks, } from "./contracts.js";
+export { getZodiacModuleAbi, getZodiacModuleAddress, sanityCheckZodiacModuleAddress, } from "./zodiacModule.js";

package/dist/esm/index.js

@@ -1 +1,3 @@
-export * from "./factory";
+export { encodeDeployProxy, encodeDeploySingleton, predictProxyAddress, predictSingletonAddress, } from "@gnosis-guild/zodiac-core";
+export { CanonicalAddresses, KnownContracts, SupportedNetworks, } from "./contracts.js";
+export { getZodiacModuleAbi, getZodiacModuleAddress, sanityCheckZodiacModuleAddress, } from "./zodiacModule.js";

package/dist/esm/mastercopies.d.ts

@@ -0,0 +1,21 @@
+import { Asset } from "./types.js";
+/**
+ * The on-disk layout:
+ *
+ *   mastercopies/<module>/<version>/<asset>/abi.json
+ *   mastercopies/<module>/<version>/<asset>/sourcecode.json
+ *   mastercopies/<module>/<version>/<asset>/bytecode.json
+ *
+ * where <asset> is the main contract name or a linked-library name.
+ */
+export declare function defaultMastercopiesDir(): string;
+/**
+ * Write one asset's three files, creating directories as needed.
+ * Returns the asset directory.
+ */
+export declare function writeAsset({ module, version, asset, mastercopiesDir, }: {
+    module: string;
+    version: string;
+    asset: Asset;
+    mastercopiesDir?: string;
+}): string;

package/dist/esm/mastercopies.js

@@ -0,0 +1,27 @@
+import { mkdirSync, writeFileSync } from "fs";
+import path from "path";
+import { cwd } from "process";
+/**
+ * The on-disk layout:
+ *
+ *   mastercopies/<module>/<version>/<asset>/abi.json
+ *   mastercopies/<module>/<version>/<asset>/sourcecode.json
+ *   mastercopies/<module>/<version>/<asset>/bytecode.json
+ *
+ * where <asset> is the main contract name or a linked-library name.
+ */
+export function defaultMastercopiesDir() {
+    return path.join(cwd(), "mastercopies");
+}
+/**
+ * Write one asset's three files, creating directories as needed.
+ * Returns the asset directory.
+ */
+export function writeAsset({ module, version, asset, mastercopiesDir = defaultMastercopiesDir(), }) {
+    const dir = path.join(mastercopiesDir, module, version, asset.name);
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(path.join(dir, "abi.json"), JSON.stringify(asset.abi, null, 2), "utf8");
+    writeFileSync(path.join(dir, "sourcecode.json"), JSON.stringify(asset.sourceCode, null, 2), "utf8");
+    writeFileSync(path.join(dir, "bytecode.json"), JSON.stringify(asset.bytecode, null, 2), "utf8");
+    return dir;
+}

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;