Add support for ContractFileName for "Import from Etherscan" (#2312)

marcocastignoli · web-flow · commit 7dd6878e37c3 · 2025-08-20T10:10:04.000+02:00
* Add support for `ContractFileName` for Vyper "Import from Etherscan"

* Make `ContractFileName` optional in EtherscanResult type

* Remove solidity parser from lib-sourcify, move it back to server.

* Update the etherscanMocks file to include the `ContractFileName` parameter

* Remove `getContractPathFromSourcesOrThrow` in lib-sourcify tests

* Remove unused "etherscan_missing_contract_definition" error

* Fix contractName generation in etherscan vyper jsonInput
diff --git a/package-lock.json b/package-lock.json
diff --git a/packages/lib-sourcify/package.json b/packages/lib-sourcify/package.json
@@ -44,7 +44,6 @@
     "@ethersproject/bignumber": "5.8.0",
     "@ethersproject/bytes": "5.8.0",
     "@fairdatasociety/bmt-js": "2.1.0",
-    "@solidity-parser/parser": "0.20.2",
     "bs58": "5.0.0",
     "ethers": "6.15.0",
     "jszip": "3.10.1",
diff --git a/packages/lib-sourcify/src/utils/etherscan/EtherscanTypes.ts b/packages/lib-sourcify/src/utils/etherscan/EtherscanTypes.ts
@@ -9,7 +9,6 @@ export type EtherscanImportErrorCode =
   | 'etherscan_rate_limit'
   | 'etherscan_api_error'
   | 'etherscan_not_verified'
-  | 'etherscan_missing_contract_definition'
   | 'etherscan_vyper_version_mapping_failed'
   | 'etherscan_missing_contract_in_json'
   | 'etherscan_missing_vyper_settings';
@@ -35,9 +34,7 @@ export type EtherscanImportErrorParameters =
       code: 'etherscan_api_error';
     } & Pick<EtherscanImportErrorDataRequired, 'apiErrorMessage'>)
   | ({
-      code:
-        | 'etherscan_missing_contract_definition'
-        | 'etherscan_missing_contract_in_json';
+      code: 'etherscan_missing_contract_in_json';
     } & Pick<EtherscanImportErrorDataRequired, 'contractName'>)
   | ({
       code: 'etherscan_vyper_version_mapping_failed';
@@ -58,8 +55,6 @@ function getErrorMessageFromCode(params: EtherscanImportErrorParameters) {
       return `Error in Etherscan API response. Result message: Invalid API Key`;
     case 'etherscan_not_verified':
       return `This contract is not verified on Etherscan.`;
-    case 'etherscan_missing_contract_definition':
-      return `Contract definition for "${params.contractName}" not found in Etherscan response sources.`;
     case 'etherscan_vyper_version_mapping_failed':
       return `Failed to map Vyper version "${params.compilerVersion}" from Etherscan to valid compiler version.`;
     case 'etherscan_missing_contract_in_json':
@@ -86,6 +81,7 @@ export type EtherscanResult = {
   SourceCode: string;
   ABI: string;
   ContractName: string;
+  ContractFileName?: string;
   CompilerVersion: string;
   OptimizationUsed: string;
   Runs: string;
diff --git a/packages/lib-sourcify/src/utils/etherscan/etherscan-util.ts b/packages/lib-sourcify/src/utils/etherscan/etherscan-util.ts
@@ -7,7 +7,6 @@ import {
   SolidityCompilation,
   Sources,
 } from '../..';
-import { getContractPathFromSources } from '../..';
 import { logInfo, logDebug, logWarn, logError } from '../../logger';
 import {
   EtherscanImportError,
@@ -138,20 +137,6 @@ export const getSolcJsonInputFromEtherscanResult = (
   };
 };
 
-export const getContractPathFromSourcesOrThrow = (
-  contractName: string,
-  sources: Sources,
-): string => {
-  const contractPath = getContractPathFromSources(contractName, sources);
-  if (contractPath === undefined) {
-    throw new EtherscanImportError({
-      code: 'etherscan_missing_contract_definition',
-      contractName,
-    });
-  }
-  return contractPath;
-};
-
 export const getVyperJsonInputFromSingleFileResult = (
   etherscanResult: EtherscanResult,
   sources: VyperJsonInput['sources'],
@@ -263,6 +248,19 @@ export const fetchFromEtherscan = async (
   return contractResultJson;
 };
 
+// We use the new Etherscan API field `ContractFileName`, see https://github.com/ethereum/sourcify/issues/2239
+export const getContractFileNameFromEtherscanResultOrThrow = (
+  contractResultJson: EtherscanResult,
+): string => {
+  if (!contractResultJson.ContractFileName) {
+    throw new EtherscanImportError({
+      code: 'etherscan_missing_contract_in_json',
+      contractName: contractResultJson.ContractName,
+    });
+  }
+  return contractResultJson.ContractFileName;
+};
+
 export const processSolidityResultFromEtherscan = (
   contractResultJson: EtherscanResult,
 ): ProcessedEtherscanResult => {
@@ -279,18 +277,17 @@ export const processSolidityResultFromEtherscan = (
   if (isEtherscanJsonInput(sourceCodeObject)) {
     logDebug('Etherscan solcJsonInput contract found');
     solcJsonInput = parseEtherscanJsonInput(sourceCodeObject);
-    contractPath = getContractPathFromSourcesOrThrow(
-      contractName,
-      solcJsonInput.sources,
-    );
+    contractPath =
+      getContractFileNameFromEtherscanResultOrThrow(contractResultJson);
   } else if (isEtherscanMultipleFilesObject(sourceCodeObject)) {
     logDebug('Etherscan Solidity multiple file contract found');
     const sources = JSON.parse(sourceCodeObject) as Sources;
     solcJsonInput = getSolcJsonInputFromEtherscanResult(
       contractResultJson,
       sources,
     );
-    contractPath = getContractPathFromSourcesOrThrow(contractName, sources);
+    contractPath =
+      getContractFileNameFromEtherscanResultOrThrow(contractResultJson);
   } else {
     logDebug('Etherscan Solidity single file contract found');
     contractPath = contractResultJson.ContractName + '.sol';
@@ -333,19 +330,15 @@ export const processVyperResultFromEtherscan = async (
   if (isJsonInput) {
     logDebug('Etherscan vyperJsonInput contract found');
     const parsedJsonInput = parseEtherscanJsonInput(sourceCodeProperty);
-    contractPath = Object.keys(parsedJsonInput.settings.outputSelection)[0];
-    if (contractPath === '*') {
-      contractPath = Object.keys(parsedJsonInput.sources).find((source) =>
-        source.includes(contractResultJson.ContractName),
-      )!;
-      if (!contractPath) {
-        throw new EtherscanImportError({
-          code: 'etherscan_missing_contract_in_json',
-          contractName: contractResultJson.ContractName,
-        });
-      }
-    }
-    contractName = contractPath.split('/').pop()!.split('.')[0];
+    contractPath =
+      getContractFileNameFromEtherscanResultOrThrow(contractResultJson);
+    // contractName: path/to/my.weird.contract.vy should be my.weird.contract
+    contractName = contractPath
+      .split('/')
+      .pop()!
+      .split('.')
+      .slice(0, -1)
+      .join('.');
     vyperJsonInput = {
       language: 'Vyper',
       sources: parsedJsonInput.sources,
diff --git a/packages/lib-sourcify/src/utils/utils.ts b/packages/lib-sourcify/src/utils/utils.ts
@@ -1,7 +1,3 @@
-import SolidityParser from '@solidity-parser/parser';
-import { Sources } from '..';
-import { logDebug, logWarn } from '../logger';
-
 /**
  * Checks whether the provided object contains any keys or not.
  * @param obj The object whose emptiness is tested.
@@ -25,49 +21,3 @@ export function splitFullyQualifiedName(fullyQualifiedName: string): {
   const contractPath = splitIdentifier.slice(0, -1).join(':');
   return { contractPath, contractName };
 }
-
-/**
- * Returns undefined if the contract is not found in the sources
- */
-export const getContractPathFromSources = (
-  contractName: string,
-  sources: Sources,
-): string | undefined => {
-  logDebug('parsing-util: Parsing sources for finding the contract path', {
-    contractName,
-  });
-  const startTime = Date.now();
-  let contractPath: string | undefined;
-  for (const [path, { content }] of Object.entries(sources)) {
-    try {
-      const ast = SolidityParser.parse(content);
-      SolidityParser.visit(ast, {
-        ContractDefinition: (node: any): any => {
-          if (node.name === contractName) {
-            contractPath = path;
-            return false; // Stop visiting
-          }
-          return undefined;
-        },
-      });
-      if (contractPath) break;
-    } catch (error) {
-      // Just continue, because the relevant contract might be in a different source file.
-      logWarn(
-        'parsing-util: Error parsing source code. Ignoring this source.',
-        {
-          path,
-          error,
-        },
-      );
-    }
-  }
-  const endTime = Date.now();
-  logDebug('parsing-util: Parsing for all sources done', {
-    contractName,
-    contractPath,
-    timeInMs: endTime - startTime,
-  });
-
-  return contractPath;
-};
diff --git a/packages/lib-sourcify/test/utils/etherscan-util.spec.ts b/packages/lib-sourcify/test/utils/etherscan-util.spec.ts
@@ -193,10 +193,8 @@ describe('etherscan util (lib)', function () {
         },
         contractName: (MULTIPLE_CONTRACT_RESPONSE.result[0] as any)
           .ContractName,
-        contractPath: EtherscanUtils.getContractPathFromSourcesOrThrow(
-          (MULTIPLE_CONTRACT_RESPONSE.result[0] as any).ContractName,
-          expectedSources,
-        ),
+        contractPath: (MULTIPLE_CONTRACT_RESPONSE.result[0] as any)
+          .ContractFileName,
       });
     });
 
@@ -223,10 +221,8 @@ describe('etherscan util (lib)', function () {
         jsonInput: expectedJsonInput,
         contractName: (STANDARD_JSON_CONTRACT_RESPONSE.result[0] as any)
           .ContractName,
-        contractPath: EtherscanUtils.getContractPathFromSourcesOrThrow(
-          (STANDARD_JSON_CONTRACT_RESPONSE.result[0] as any).ContractName,
-          expectedJsonInput.sources,
-        ),
+        contractPath: (STANDARD_JSON_CONTRACT_RESPONSE.result[0] as any)
+          .ContractFileName,
       });
     });
   });
@@ -323,22 +319,6 @@ describe('etherscan util (lib)', function () {
     });
   });
 
-  describe('getContractPathFromSourcesOrThrow', () => {
-    it('should throw when the contract path is not found in the provided sources', () => {
-      const sources = {
-        'path/file.sol': { content: 'contract SolidityContract {}' },
-      };
-      expect(() =>
-        EtherscanUtils.getContractPathFromSourcesOrThrow(
-          'AnotherSolidityContract',
-          sources,
-        ),
-      )
-        .to.throw(EtherscanImportError)
-        .with.property('code', 'etherscan_missing_contract_definition');
-    });
-  });
-
   describe('getCompilationFromEtherscanResult', () => {
     it('should return a SolidityCompilation', async () => {
       const solidityResult = EtherscanUtils.processSolidityResultFromEtherscan(
diff --git a/packages/lib-sourcify/test/utils/parsing-util.spec.ts b/packages/lib-sourcify/test/utils/parsing-util.spec.ts
diff --git a/services/server/package.json b/services/server/package.json
@@ -55,6 +55,7 @@
     "@ethereum-sourcify/lib-sourcify": "^2.2.2",
     "@google-cloud/cloud-sql-connector": "1.8.3",
     "@shazow/whatsabi": "0.22.2",
+    "@solidity-parser/parser": "^0.20.2",
     "bunyan": "1.8.15",
     "chalk": "4.1.2",
     "config": "3.3.12",
diff --git a/services/server/src/server/apiv1/verification/solc-json/stateless/solc-json.stateless.handlers.ts b/services/server/src/server/apiv1/verification/solc-json/stateless/solc-json.stateless.handlers.ts
@@ -10,7 +10,7 @@ import { Services } from "../../../../services/services";
 import { ChainRepository } from "../../../../../sourcify-chain-repository";
 import { getApiV1ResponseFromVerification } from "../../../controllers.common";
 import logger from "../../../../../common/logger";
-import { getContractPathFromSources } from "@ethereum-sourcify/lib-sourcify";
+import { getContractPathFromSources } from "../../../../services/utils/parsing-util";
 
 export async function verifySolcJsonEndpoint(req: Request, res: Response) {
   const services = req.app.get("services") as Services;
diff --git a/services/server/src/server/services/utils/etherscan-util.ts b/services/server/src/server/services/utils/etherscan-util.ts
@@ -40,7 +40,6 @@ function mapLibError(err: any, throwV2Errors: boolean): never {
           ? new EtherscanRequestFailedError(message)
           : new BadGatewayError(message);
 
-      case "etherscan_missing_contract_definition":
       case "etherscan_vyper_version_mapping_failed":
       case "etherscan_missing_contract_in_json":
       case "etherscan_missing_vyper_settings":
diff --git a/services/server/src/server/services/utils/parsing-util.ts b/services/server/src/server/services/utils/parsing-util.ts
@@ -0,0 +1,49 @@
+import SolidityParser from "@solidity-parser/parser";
+import { Sources } from "@ethereum-sourcify/lib-sourcify";
+import logger from "../../../common/logger";
+
+/**
+ * Returns undefined if the contract is not found in the sources
+ */
+export const getContractPathFromSources = (
+  contractName: string,
+  sources: Sources,
+): string | undefined => {
+  logger.debug("parsing-util: Parsing sources for finding the contract path", {
+    contractName,
+  });
+  const startTime = Date.now();
+  let contractPath: string | undefined;
+  for (const [path, { content }] of Object.entries(sources)) {
+    try {
+      const ast = SolidityParser.parse(content);
+      SolidityParser.visit(ast, {
+        ContractDefinition: (node: any): any => {
+          if (node.name === contractName) {
+            contractPath = path;
+            return false; // Stop visiting
+          }
+          return undefined;
+        },
+      });
+      if (contractPath) break;
+    } catch (error) {
+      // Just continue, because the relevant contract might be in a different source file.
+      logger.warn(
+        "parsing-util: Error parsing source code. Ignoring this source.",
+        {
+          path,
+          error,
+        },
+      );
+    }
+  }
+  const endTime = Date.now();
+  logger.debug("parsing-util: Parsing for all sources done", {
+    contractName,
+    contractPath,
+    timeInMs: endTime - startTime,
+  });
+
+  return contractPath;
+};
diff --git a/services/server/test/helpers/etherscanResponseMocks.ts b/services/server/test/helpers/etherscanResponseMocks.ts
diff --git a/services/server/test/unit/utils/parsing-util.spec.ts b/services/server/test/unit/utils/parsing-util.spec.ts
@@ -0,0 +1,26 @@
+import { expect } from "chai";
+import { getContractPathFromSources } from "../../../src/server/services/utils/parsing-util";
+
+describe("getContractPathFromSources (lib)", () => {
+  it("should return the correct contract path", () => {
+    const sources = {
+      "SolidityContract.sol": { content: "contract WrongContract {}" },
+      "path/file.sol": {
+        content: "contract WrongContract {}\ncontract SolidityContract {}",
+      },
+    } as any;
+    const result = getContractPathFromSources("SolidityContract", sources);
+    expect(result).to.equal("path/file.sol");
+  });
+
+  it("should return undefined when the contract path is not found in the provided sources", () => {
+    const sources = {
+      "path/file.sol": { content: "contract SolidityContract {}" },
+    } as any;
+    const result = getContractPathFromSources(
+      "AnotherSolidityContract",
+      sources,
+    );
+    expect(result).to.be.undefined;
+  });
+});
