Merge pull request #3 from sourcifyeth/staging

Release: Add Hardhat/Foundry build-info file support

Author: kuzdogan

CLAUDE.md

@@ -0,0 +1,69 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Development Commands
+
+- `npm run dev` - Start development server with hot reload (runs on http://localhost:5173)
+- `npm run build` - Build for production (outputs to `build/` directory)
+- `npm start` - Start production server
+- `npm run typecheck` - Run TypeScript type checking
+
+## Architecture Overview
+
+This is a React Router v7 SPA application for smart contract verification using the Sourcify service. The app operates in SPA mode (SSR disabled in react-router.config.ts).
+
+### Key Directories
+
+- `app/` - Main application code
+  - `components/` - Reusable UI components, with verification-specific components in `verification/`
+  - `contexts/` - React contexts for global state (ServerConfig, CompilerVersions, Chains)
+  - `hooks/` - Custom React hooks for form validation and verification state
+  - `routes/` - Route components (home page, job status)
+  - `types/` - TypeScript type definitions
+  - `utils/` - Utility functions for API calls, storage, and business logic
+
+### Core Architecture
+
+**Verification Flow**: The app supports multiple verification methods (single-file, multiple-files, std-json, metadata-json, build-info) for both Solidity and Vyper contracts. Framework helpers (hardhat, foundry) provide setup instructions and can optionally use build-info file uploads. All methods eventually convert to standard JSON format before submission to Sourcify's v2 API.
+
+**API Integration**: 
+- `sourcifyApi.ts` - Main Sourcify API client with custom headers for client identification
+- `etherscanApi.ts` - Etherscan integration for importing contract data
+- All API calls use custom `sourcifyFetch()` with client identification headers
+
+**State Management**: Uses React Context for global state:
+- `ServerConfigContext` - Manages Sourcify server URLs (default, custom, localStorage sync)
+- `CompilerVersionsContext` - Fetches and caches compiler versions
+- `ChainsContext` - Manages blockchain network data
+
+**Job Tracking**: Verification jobs are tracked via localStorage and polling the `/v2/verify/{verificationId}` endpoint.
+
+### Environment Variables
+
+- `VITE_SOURCIFY_SERVER_URL` - Default Sourcify server URL
+- `VITE_SOURCIFY_REPO_URL` - Sourcify repository URL
+- `VITE_GIT_COMMIT` - Git commit hash for client version tracking
+- `VITE_ENV` - Environment (development/production)
+
+### Build Configuration
+
+- React Router v7 with Vite
+- TailwindCSS v4 for styling
+- TypeScript with strict mode
+- Path alias: `~/*` maps to `./app/*`
+- Web Workers used for bytecode diff calculations (`public/diffWorker.js`)
+
+### Key Features Implemented
+
+**Build-Info File Support**: Framework helpers (Hardhat/Foundry) can toggle between showing setup commands or uploading build-info files. The build-info feature:
+- Parses Hardhat and Foundry build-info JSON files
+- Extracts standard JSON compilation input from the "input" field
+- Auto-populates compiler version from build-info metadata
+- Validates build-info structure and provides helpful error messages
+- Integrates seamlessly with existing std-json submission flow
+
+**Type Safety**: Strong TypeScript typing throughout:
+- `SelectedMethod` union type combines verification methods and framework methods
+- Proper typing for all form validation and state management
+- Type-safe API interfaces and response handling

app/components/verification/CompilerSelector.tsx

@@ -1,18 +1,18 @@
 import React, { useState } from "react";
 import { useCompilerVersions } from "../../contexts/CompilerVersionsContext";
 import type { SolidityVersion, VyperVersion } from "../../contexts/CompilerVersionsContext";
-import type { Language, VerificationMethodObject, FrameworkMethodObject } from "../../types/verification";
+import type { Language, SelectedMethod } from "../../types/verification";
 
 interface CompilerSelectorProps {
   language: Language | null;
-  verificationMethod: VerificationMethodObject | FrameworkMethodObject | null;
+  selectedMethod: SelectedMethod | "";
   selectedVersion?: string;
   onVersionSelect: (version: string) => void;
 }
 
 export default function CompilerSelector({
   language,
-  verificationMethod,
+  selectedMethod,
   selectedVersion,
   onVersionSelect,
 }: CompilerSelectorProps) {
@@ -31,14 +31,14 @@ export default function CompilerSelector({
   const [showPrereleases, setShowPrereleases] = useState(false);
 
   // Don't show if language is null or if using metadata/framework methods
-  if (!language || !verificationMethod) {
+  if (!language || !selectedMethod) {
     return null;
   }
 
   if (
-    verificationMethod.id === "metadata-json" ||
-    verificationMethod.id === "hardhat" ||
-    verificationMethod.id === "foundry"
+    selectedMethod === "metadata-json" ||
+    selectedMethod === "hardhat" ||
+    selectedMethod === "foundry"
   ) {
     return null;
   }

app/components/verification/ContractIdentifier.tsx

@@ -68,7 +68,7 @@ export default function ContractIdentifier({
       try {
         const contracts: ParsedContract[] = [];
 
-        if (selectedMethod === "std-json") {
+        if (selectedMethod === "std-json" || selectedMethod === "build-info") {
           // For std-json, use the first uploaded file
           const jsonFile = uploadedFiles[0];
           if (jsonFile) {

app/components/verification/FileUpload.tsx

@@ -57,6 +57,12 @@ const getFileRequirements = (method: VerificationMethod, language: Language | nu
         maxFiles: 1,
         description: `Solidity Metadata JSON file`,
       };
+    case "build-info":
+      return {
+        allowedExtensions: [".json"],
+        maxFiles: 1,
+        description: "Build-info JSON file from Hardhat/Foundry artifacts directory",
+      };
     default:
       return {
         allowedExtensions: [".sol"],

app/components/verification/VerificationMethodSelector.tsx

@@ -1,22 +1,40 @@
 import { Tooltip as ReactTooltip } from "react-tooltip";
+import { useState, useEffect } from "react";
+import { MdInfo } from "react-icons/md";
 import { verificationMethods, frameworkMethods, frameworkMessages } from "../../data/verificationMethods";
-import type { Language } from "../../types/verification";
+import type { Language, SelectedMethod } from "../../types/verification";
 import VerificationWarning from "./VerificationWarning";
 
 interface VerificationMethodSelectorProps {
   selectedLanguage: Language | null;
-  selectedMethod: string;
-  onMethodSelect: (method: string) => void;
+  selectedMethod: SelectedMethod | "";
+  onMethodSelect: (method: SelectedMethod) => void;
 }
 
 export default function VerificationMethodSelector({
   selectedLanguage,
   selectedMethod,
   onMethodSelect,
 }: VerificationMethodSelectorProps) {
+  // Keep track of the last selected framework method so we can return to it
+  const [lastFrameworkMethod, setLastFrameworkMethod] = useState<"hardhat" | "foundry">("hardhat");
+  
   if (!selectedLanguage) return null;
 
   const methods = verificationMethods[selectedLanguage as keyof typeof verificationMethods];
+  
+  // Update lastFrameworkMethod when a framework method is selected
+  useEffect(() => {
+    if (frameworkMethods.some(method => method.id === selectedMethod)) {
+      setLastFrameworkMethod(selectedMethod as "hardhat" | "foundry");
+    }
+  }, [selectedMethod]);
+
+  // Check if selected method is a framework method
+  const isFrameworkMethod = frameworkMethods.some((method) => method.id === selectedMethod);
+  
+  // Check if we're in build-info mode (selected method is build-info)
+  const isBuildInfoMode = selectedMethod === "build-info";
 
   // Get the warning for the selected method
   const selectedMethodWarning =
@@ -25,8 +43,12 @@ export default function VerificationMethodSelector({
           ?.warning
       : null;
 
-  // Get the framework message for the selected framework
-  const selectedFrameworkMessage = selectedMethod && frameworkMessages[selectedMethod];
+  // Get the framework message for the selected framework (or the active framework in build-info mode)
+  const selectedFrameworkMessage = (isFrameworkMethod && frameworkMessages[selectedMethod]) || 
+                                   (isBuildInfoMode && frameworkMessages[lastFrameworkMethod]);
+  
+  // Get the currently active framework method for visual selection purposes
+  const activeFrameworkMethod = isBuildInfoMode ? lastFrameworkMethod : (isFrameworkMethod ? selectedMethod : null);
 
   return (
     <div>
@@ -85,15 +107,15 @@ export default function VerificationMethodSelector({
             type="button"
             onClick={() => onMethodSelect(method.id)}
             className={`relative flex items-center justify-center gap-2 p-3 border-2 rounded-lg text-center transition-all duration-200 w-36 ${
-              selectedMethod === method.id
+              activeFrameworkMethod === method.id
                 ? "border-cerulean-blue-500 bg-cerulean-blue-50"
                 : "border-gray-300 hover:border-cerulean-blue-300 hover:bg-gray-50"
             }`}
           >
             <img src={method.icon} alt={method.title} className="w-6 h-6" />
             <h3
               className={`text-base font-medium ${
-                selectedMethod === method.id ? "text-cerulean-blue-600" : "text-gray-700"
+                activeFrameworkMethod === method.id ? "text-cerulean-blue-600" : "text-gray-700"
               }`}
             >
               {method.title}
@@ -102,16 +124,57 @@ export default function VerificationMethodSelector({
         ))}
       </div>
 
+      {/* Framework Build-Info Toggle */}
+      {(isFrameworkMethod || isBuildInfoMode) && (
+        <div className="mt-4 mb-4 flex items-center gap-2">
+          <span className="text-sm text-gray-700">Show Commands</span>
+          <label className="relative inline-flex items-center">
+            <input
+              type="checkbox"
+              checked={isBuildInfoMode}
+              onChange={(e) => {
+                if (e.target.checked) {
+                  onMethodSelect("build-info");
+                } else {
+                  onMethodSelect(lastFrameworkMethod);
+                }
+              }}
+              className="sr-only"
+            />
+            <div className={`w-11 h-6 rounded-full relative transition-colors ${
+              isBuildInfoMode ? "bg-cerulean-blue-600" : "bg-gray-200"
+            }`}>
+              <div className={`absolute top-[2px] left-[2px] bg-white border border-gray-300 rounded-full h-5 w-5 transition-transform ${
+                isBuildInfoMode ? "translate-x-full" : ""
+              }`}></div>
+            </div>
+          </label>
+          <span className="text-sm text-gray-700 flex items-center gap-1">
+            Upload build-info file
+            <button
+              type="button"
+              data-tooltip-id="build-info-tooltip"
+              data-tooltip-content="Build-info files are saved compilation outputs from Hardhat and Foundry. While it's recommended to use the framework commands directly for verification, you can also upload these files. Find them in artifacts/build-info (Hardhat) or out/build-info (Foundry)."
+              className="text-gray-500 hover:text-gray-700 transition-colors duration-200"
+            >
+              <MdInfo size={16} />
+            </button>
+            <ReactTooltip id="build-info-tooltip" place="top" style={{ maxWidth: '300px' }} />
+          </span>
+        </div>
+      )}
+
+
       {/* Verification Warnings */}
       {selectedMethodWarning && (
         <div className="mt-4">
           <VerificationWarning type="warning">{selectedMethodWarning}</VerificationWarning>
         </div>
       )}
 
-      {selectedFrameworkMessage && (
+      {selectedFrameworkMessage && !isBuildInfoMode && (
         <div className="mt-4">
-          <VerificationWarning type="info">{selectedFrameworkMessage}</VerificationWarning>
+          <VerificationWarning type="info">{selectedFrameworkMessage()}</VerificationWarning>
         </div>
       )}
     </div>

app/data/verificationMethods.tsx

@@ -70,68 +70,72 @@ export const frameworkMethods: FrameworkMethodObject[] = [
   },
 ];
 
-export const frameworkMessages: FrameworkMessages = {
-  hardhat: (
+export const createFrameworkMessage = (framework: 'hardhat' | 'foundry') => () => {
+  const isHardhat = framework === 'hardhat';
+  
+  return (
     <div>
       <p className="mb-3 text-sm">
         <a
-          href="https://hardhat.org/hardhat-runner/plugins/nomicfoundation-hardhat-verify#verifying-on-sourcify"
+          href={isHardhat 
+            ? "https://hardhat.org/hardhat-runner/plugins/nomicfoundation-hardhat-verify#verifying-on-sourcify"
+            : "https://book.getfoundry.sh/reference/forge/forge-verify-contract"
+          }
           target="_blank"
           rel="noopener noreferrer"
           className="text-cerulean-blue-600 hover:text-cerulean-blue-700 underline"
         >
-          Hardhat Documentation →
+          {isHardhat ? 'Hardhat' : 'Foundry'} Documentation →
         </a>
       </p>
-      <p className="mb-3">Enable Sourcify in your hardhat.config.js:</p>
-      <div className="bg-gray-900 text-gray-100 p-4 rounded-lg mb-3 overflow-x-auto">
-        <pre className="text-sm">
-          {`module.exports = {
+      
+      {isHardhat ? (
+        <>
+          <p className="mb-3">Enable Sourcify in your hardhat.config.js:</p>
+          <div className="bg-gray-900 text-gray-100 p-4 rounded-lg mb-3 overflow-x-auto">
+            <pre className="text-sm">
+              {`module.exports = {
   sourcify: {
     // Doesn't need an API key
     enabled: true
   }
 };`}
-        </pre>
-      </div>
-      <p className="mb-2">Then verify a contract:</p>
-      <div className="bg-gray-900 text-gray-100 p-4 rounded-lg overflow-x-auto">
-        <pre className="text-sm">
-          {`npx hardhat verify --network mainnet 0x1F98431c8aD98523631AE4a59f267346ea31F984`}
-        </pre>
-      </div>
-    </div>
-  ),
-  foundry: (
-    <div>
-      <p className="mb-3 text-sm">
-        <a
-          href="https://book.getfoundry.sh/reference/forge/forge-verify-contract"
-          target="_blank"
-          rel="noopener noreferrer"
-          className="text-cerulean-blue-600 hover:text-cerulean-blue-700 underline"
-        >
-          Foundry Documentation →
-        </a>
-      </p>
-      <p className="mb-2">Deploy and verify with Foundry:</p>
-      <div className="bg-gray-900 text-gray-100 p-4 rounded-lg mb-3 overflow-x-auto">
-        <pre className="text-sm">
-          {`forge create --rpc-url <rpc-url> --private-key <private-key> src/MyContract.sol:MyContract --verify --verifier sourcify`}
-        </pre>
-      </div>
-      <p className="mb-2">Or verify an already deployed contract:</p>
-      <div className="bg-gray-900 text-gray-100 p-4 rounded-lg mb-3 overflow-x-auto">
-        <pre className="text-sm">
-          {`forge verify-contract --verifier sourcify --chain <chain-id> 0xB4239c86440d6C39d518D6457038cB404451529b MyContract`}
-        </pre>
-      </div>
-      <p className="mb-2">Check if a contract is verified:</p>
-      <div className="bg-gray-900 text-gray-100 p-4 rounded-lg overflow-x-auto">
-        <pre className="text-sm">
-          {`forge verify-check 0x1F98431c8aD98523631AE4a59f267346ea31F984 --verifier sourcify`}
-        </pre>
-      </div>
+            </pre>
+          </div>
+          <p className="mb-2">Then verify a contract:</p>
+          <div className="bg-gray-900 text-gray-100 p-4 rounded-lg overflow-x-auto">
+            <pre className="text-sm">
+              {`npx hardhat verify --network mainnet 0x1F98431c8aD98523631AE4a59f267346ea31F984`}
+            </pre>
+          </div>
+        </>
+      ) : (
+        <>
+          <p className="mb-2">Deploy and verify with Foundry:</p>
+          <div className="bg-gray-900 text-gray-100 p-4 rounded-lg mb-3 overflow-x-auto">
+            <pre className="text-sm">
+              {`forge create --rpc-url <rpc-url> --private-key <private-key> src/MyContract.sol:MyContract --verify --verifier sourcify`}
+            </pre>
+          </div>
+          <p className="mb-2">Or verify an already deployed contract:</p>
+          <div className="bg-gray-900 text-gray-100 p-4 rounded-lg mb-3 overflow-x-auto">
+            <pre className="text-sm">
+              {`forge verify-contract --verifier sourcify --chain <chain-id> 0xB4239c86440d6C39d518D6457038cB404451529b MyContract`}
+            </pre>
+          </div>
+          <p className="mb-2">Check if a contract is verified:</p>
+          <div className="bg-gray-900 text-gray-100 p-4 rounded-lg overflow-x-auto">
+            <pre className="text-sm">
+              {`forge verify-check 0x1F98431c8aD98523631AE4a59f267346ea31F984 --verifier sourcify`}
+            </pre>
+          </div>
+        </>
+      )}
     </div>
-  ),
+  );
+};
+
+export const frameworkMessages: FrameworkMessages = {
+  hardhat: createFrameworkMessage('hardhat'),
+  foundry: createFrameworkMessage('foundry'),
 };