@openzeppelin/ui-builder-adapter-evm 1.2.0 → 1.4.0

package/src/abi/etherscan.ts

@@ -1,158 +0,0 @@
-import type { ContractSchema } from '@openzeppelin/ui-types';
-import { logger } from '@openzeppelin/ui-utils';
-
-import { resolveExplorerConfig } from '../configuration/explorer';
-import type { AbiItem, TypedEvmNetworkConfig } from '../types';
-import { loadAbiFromEtherscanV2, shouldUseV2Api } from './etherscan-v2';
-import { transformAbiToSchema } from './transformer';
-
-/**
- * Result type for Etherscan ABI loading that includes the original ABI string
- */
-export interface EtherscanAbiResult {
-  schema: ContractSchema;
-  originalAbi: string;
-}
-
-/**
- * IMPORTANT: Etherscan V1 API Deprecation Notice
- *
- * Etherscan has announced the deprecation of their V1 API endpoints in favor of the new V2 unified API.
- * The V2 API provides a single endpoint that works across all EVM chains, making it more scalable and
- * easier to maintain.
- *
- * Key differences:
- * - V1: Each chain has its own API endpoint (e.g., api.etherscan.io, api.bscscan.com, etc.)
- * - V2: Single unified endpoint (api.etherscan.io/v2/api) with chainId parameter
- *
- * Migration strategy:
- * - Networks with `supportsEtherscanV2: true` will automatically use V2 API
- * - Legacy networks without V2 support will continue using V1 until they're updated
- * - New networks should always be configured with V2 support
- *
- * The V1 API functions are maintained for backward compatibility but should be considered
- * deprecated and will be removed in a future release.
- */
-
-/**
- * Fetches and parses an ABI from Etherscan-compatible explorers using a contract address and network config.
- * Automatically selects V1 or V2 API based on network support and user configuration.
- */
-export async function loadAbiFromEtherscan(
-  address: string,
-  networkConfig: TypedEvmNetworkConfig
-): Promise<EtherscanAbiResult> {
-  if (shouldUseV2Api(networkConfig)) {
-    logger.info('loadAbiFromEtherscan', 'Using V2 API for fetching ABI');
-    return loadAbiFromEtherscanV2(address, networkConfig);
-  }
-
-  // Use V1 API (legacy)
-  logger.info('loadAbiFromEtherscan', 'Using V1 API for fetching ABI');
-  return loadAbiFromEtherscanV1(address, networkConfig);
-}
-
-/**
- * Fetches and parses an ABI from Etherscan V1 API using a contract address and network config.
- */
-export async function loadAbiFromEtherscanV1(
-  address: string,
-  networkConfig: TypedEvmNetworkConfig
-): Promise<EtherscanAbiResult> {
-  const explorerConfig = resolveExplorerConfig(networkConfig);
-
-  if (!explorerConfig.apiUrl) {
-    logger.error(
-      'loadAbiFromEtherscanV1',
-      `API URL is missing for ${networkConfig.name} explorer.`
-    );
-    throw new Error(`Explorer API URL for ${networkConfig.name} is not configured.`);
-  }
-
-  const url = new URL(explorerConfig.apiUrl);
-  url.searchParams.append('module', 'contract');
-  url.searchParams.append('action', 'getabi');
-  url.searchParams.append('address', address);
-
-  // Only append API key if provided
-  if (explorerConfig.apiKey) {
-    url.searchParams.append('apikey', explorerConfig.apiKey);
-  }
-
-  let response: Response;
-  try {
-    logger.info(
-      'loadAbiFromEtherscanV1',
-      `Fetching ABI from ${explorerConfig.apiUrl} for address: ${address}`
-    );
-    response = await fetch(url);
-  } catch (networkError) {
-    logger.error(
-      'loadAbiFromEtherscanV1',
-      `Network error fetching ABI from Explorer API: ${networkError}`
-    );
-    throw new Error(`Network error fetching ABI: ${(networkError as Error).message}`);
-  }
-
-  if (!response.ok) {
-    logger.error(
-      'loadAbiFromEtherscanV1',
-      `Explorer API request failed with status: ${response.status}`
-    );
-    throw new Error(`Explorer API request failed: ${response.status} ${response.statusText}`);
-  }
-
-  let apiResult: { status: string; message: string; result: string };
-  try {
-    apiResult = await response.json();
-  } catch (jsonError) {
-    logger.error(
-      'loadAbiFromEtherscanV1',
-      `Failed to parse Explorer API response as JSON: ${jsonError}`
-    );
-    throw new Error('Invalid JSON response received from Explorer API.');
-  }
-
-  if (apiResult.status !== '1') {
-    logger.warn(
-      'loadAbiFromEtherscanV1',
-      `Explorer API error: Status ${apiResult.status}, Message: ${apiResult.message}, Result: ${apiResult.result}`
-    );
-    if (apiResult.result?.includes('Contract source code not verified')) {
-      throw new Error(
-        `Contract not verified on ${networkConfig.name} explorer (address: ${address}). ABI not available. You can provide the contract's ABI manually.`
-      );
-    }
-    throw new Error(`Explorer API Error: ${apiResult.result || apiResult.message}`);
-  }
-
-  // Store the original raw ABI string before parsing
-  const originalAbiString = apiResult.result;
-
-  let abi: AbiItem[];
-  try {
-    abi = JSON.parse(originalAbiString);
-    if (!Array.isArray(abi)) {
-      throw new Error('Parsed ABI from Explorer API is not an array.');
-    }
-  } catch (error) {
-    logger.error(
-      'loadAbiFromEtherscanV1',
-      `Failed to parse ABI JSON string from Explorer API result: ${error}`
-    );
-    throw new Error(`Invalid ABI JSON received from Explorer API: ${(error as Error).message}`);
-  }
-
-  logger.info(
-    'loadAbiFromEtherscanV1',
-    `Successfully parsed ABI for ${networkConfig.name} with ${abi.length} items.`
-  );
-  // TODO: Fetch contract name?
-  const contractName = `Contract_${address.substring(0, 6)}`;
-  const schema = transformAbiToSchema(abi, contractName, address);
-
-  return {
-    schema,
-    originalAbi: originalAbiString,
-  };
-}

package/src/abi/index.ts

@@ -1,7 +0,0 @@
-// Barrel file for abi module
-export * from './transformer';
-export { loadAbiFromEtherscan } from './etherscan';
-export { loadAbiFromEtherscanV2, shouldUseV2Api } from './etherscan-v2';
-export { loadEvmContract } from './loader';
-export * from './types';
-export { AbiComparisonService, abiComparisonService } from './comparison';

package/src/abi/loader.ts

@@ -1,415 +0,0 @@
-import { isAddress } from 'viem';
-
-import type {
-  ContractDefinitionMetadata,
-  ContractSchema,
-  EvmNetworkConfig,
-  ProxyInfo,
-} from '@openzeppelin/ui-types';
-import {
-  appConfigService,
-  logger,
-  simpleHash,
-  userNetworkServiceConfigService,
-  withTimeout,
-} from '@openzeppelin/ui-utils';
-
-import { getEvmExplorerAddressUrl } from '../configuration/explorer';
-import { detectProxyFromAbi, getAdminAddress, getImplementationAddress } from '../proxy/detection';
-import type { AbiItem, TypedEvmNetworkConfig } from '../types';
-import type { EvmContractArtifacts } from '../types/artifacts';
-import {
-  EvmProviderKeys,
-  isEvmProviderKey,
-  type EvmContractDefinitionProviderKey,
-} from '../types/providers';
-import { loadAbiFromEtherscan } from './etherscan';
-import { getSourcifyContractAppUrl, loadAbiFromSourcify } from './sourcify';
-import { transformAbiToSchema } from './transformer';
-
-/**
- * Loads and parses an ABI directly from a JSON string.
- */
-async function loadAbiFromJson(abiJsonString: string): Promise<ContractSchema> {
-  let abi: AbiItem[];
-  try {
-    abi = JSON.parse(abiJsonString);
-    if (!Array.isArray(abi)) {
-      throw new Error('Parsed JSON is not an array.');
-    }
-  } catch (error) {
-    logger.error('loadAbiFromJson', 'Failed to parse source string as JSON ABI:', error);
-    throw new Error(`Invalid JSON ABI provided: ${(error as Error).message}`);
-  }
-
-  logger.info('loadAbiFromJson', `Successfully parsed JSON ABI with ${abi.length} items.`);
-  const contractName = 'ContractFromABI'; // Default name for direct ABI
-  return transformAbiToSchema(abi, contractName, undefined);
-}
-
-/**
- * Enhanced result type for ABI loading with metadata and proxy information
- */
-export interface EvmContractLoadResult {
-  schema: ContractSchema;
-  source: 'fetched' | 'manual';
-  contractDefinitionOriginal?: string;
-  metadata?: ContractDefinitionMetadata;
-  proxyInfo?: ProxyInfo;
-}
-
-/**
- * Options for contract loading behavior
- */
-export interface ContractLoadOptions {
-  /** Skip proxy detection and load the contract ABI as-is */
-  skipProxyDetection?: boolean;
-  /** Force treating the address as an implementation contract */
-  treatAsImplementation?: boolean;
-}
-
-const PER_PROVIDER_TIMEOUT_MS = 4000;
-const OVERALL_BUDGET_MS = 10000;
-
-/**
- * Loads contract schema from artifacts provided by the UI, prioritizing manual ABI input.
- * Returns enhanced result with schema source information and automatic proxy detection.
- */
-export async function loadEvmContract(
-  artifacts: EvmContractArtifacts,
-  networkConfig: EvmNetworkConfig,
-  options: ContractLoadOptions = {}
-): Promise<EvmContractLoadResult> {
-  const { contractAddress, contractDefinition, __proxyDetectionOptions } = artifacts;
-
-  // Extract proxy detection options from form data if present
-  const proxyOptions = __proxyDetectionOptions as { skipProxyDetection?: boolean } | undefined;
-  if (proxyOptions?.skipProxyDetection) {
-    options.skipProxyDetection = true;
-  }
-
-  if (!contractAddress || typeof contractAddress !== 'string' || !isAddress(contractAddress)) {
-    throw new Error('A valid contract address is required.');
-  }
-
-  // 1. Prioritize manual contract definition input if provided.
-  if (
-    contractDefinition &&
-    typeof contractDefinition === 'string' &&
-    contractDefinition.trim().length > 0
-  ) {
-    // Try to detect if this looks like JSON
-    const trimmed = contractDefinition.trim();
-    const hasJsonContent = trimmed.includes('[') && trimmed.includes(']') && trimmed.includes('{');
-
-    if (hasJsonContent) {
-      logger.info('loadEvmContract', 'Manual contract definition provided. Attempting to parse...');
-      try {
-        const schema = await loadAbiFromJson(contractDefinition);
-        // Attach the address to the schema from the separate address field.
-        return {
-          schema: { ...schema, address: contractAddress },
-          source: 'manual' as const,
-          contractDefinitionOriginal: contractDefinition,
-          metadata: {
-            contractName: schema.name,
-            fetchTimestamp: new Date(),
-            verificationStatus: 'unknown', // Manual ABI - verification status unknown
-          },
-          // Note: No proxy detection for manual ABIs - user provides what they want
-        };
-      } catch (error) {
-        logger.error('loadEvmContract', 'Failed to parse manually provided ABI:', error);
-        // If manual ABI is provided but invalid, it's a hard error.
-        throw new Error(`The provided ABI JSON is invalid: ${(error as Error).message}`);
-      }
-    }
-  }
-
-  // Extract optional forced provider (from adapter-specific field or generic 'service')
-  const forcedRaw =
-    (artifacts as unknown as { __forcedProvider?: string }).__forcedProvider ||
-    (artifacts as unknown as { service?: string }).service;
-  const forcedProvider: EvmContractDefinitionProviderKey | null = isEvmProviderKey(forcedRaw)
-    ? (forcedRaw as EvmContractDefinitionProviderKey)
-    : null;
-
-  // 2. If no manual ABI, fall back to fetching from provider(s) with proxy detection.
-  logger.info(
-    'loadEvmContract',
-    `No manual ABI detected. Attempting Etherscan fetch for address: ${contractAddress}...`
-  );
-
-  return await loadContractWithProxyDetection(
-    contractAddress,
-    networkConfig as TypedEvmNetworkConfig,
-    options,
-    forcedProvider
-  );
-}
-
-/**
- * Builds a standard contract result with metadata
- */
-function buildContractResult(
-  contractAddress: string,
-  abiResult: { schema: ContractSchema; originalAbi: string },
-  networkConfig: TypedEvmNetworkConfig,
-  sourceProvider: EvmContractDefinitionProviderKey | null,
-  proxyInfo?: ProxyInfo
-): EvmContractLoadResult {
-  // Determine provenance URL based on the provider that supplied the ABI
-  let fetchedFrom: string | undefined = undefined;
-  if (sourceProvider === EvmProviderKeys.Etherscan) {
-    fetchedFrom = getEvmExplorerAddressUrl(contractAddress, networkConfig) || undefined;
-  } else if (sourceProvider === EvmProviderKeys.Sourcify) {
-    fetchedFrom = getSourcifyContractAppUrl(networkConfig.chainId, contractAddress);
-  } else {
-    // Fallback to resolved explorer URL when provider is unknown
-    fetchedFrom = getEvmExplorerAddressUrl(contractAddress, networkConfig) || undefined;
-  }
-
-  return {
-    schema: { ...abiResult.schema, address: contractAddress },
-    source: 'fetched',
-    contractDefinitionOriginal: abiResult.originalAbi,
-    metadata: {
-      fetchedFrom,
-      contractName: abiResult.schema.name,
-      verificationStatus: 'verified',
-      fetchTimestamp: new Date(),
-      definitionHash: simpleHash(abiResult.originalAbi),
-    },
-    proxyInfo,
-  };
-}
-
-/**
- * Attempts to load implementation ABI for a detected proxy
- */
-async function loadImplementationAbi(
-  _contractAddress: string,
-  implementationAddress: string,
-  networkConfig: TypedEvmNetworkConfig,
-  _proxyType: string
-): Promise<{ schema: ContractSchema; originalAbi: string } | null> {
-  try {
-    const implementationResult = await loadAbiFromEtherscan(implementationAddress, networkConfig);
-
-    logger.info(
-      'loadImplementationAbi',
-      `Successfully fetched implementation ABI with ${implementationResult.schema.functions.length} functions`
-    );
-
-    return implementationResult;
-  } catch (implementationError) {
-    logger.warn(
-      'loadImplementationAbi',
-      `Failed to load implementation ABI: ${implementationError}`
-    );
-    return null;
-  }
-}
-
-/**
- * Handles the proxy detection flow and returns appropriate result
- */
-async function handleProxyDetection(
-  contractAddress: string,
-  initialResult: { schema: ContractSchema; originalAbi: string },
-  networkConfig: TypedEvmNetworkConfig,
-  initialProvider: EvmContractDefinitionProviderKey | null
-): Promise<EvmContractLoadResult | null> {
-  // Parse the ABI to check for proxy patterns
-  const abi: AbiItem[] = JSON.parse(initialResult.originalAbi);
-  const proxyDetection = detectProxyFromAbi(abi);
-
-  if (!proxyDetection.isProxy) {
-    return null; // Not a proxy, let caller handle normal flow
-  }
-
-  logger.info(
-    'handleProxyDetection',
-    `Proxy detected: ${proxyDetection.proxyType} (confidence: ${proxyDetection.confidence})`
-  );
-
-  const proxyType = proxyDetection.proxyType || 'unknown';
-  const implementationAddress = await getImplementationAddress(
-    contractAddress,
-    networkConfig,
-    proxyType
-  );
-
-  // Attempt to resolve admin address as well for display purposes
-  const adminAddress = await getAdminAddress(contractAddress, networkConfig);
-
-  if (!implementationAddress) {
-    logger.info('handleProxyDetection', 'Proxy detected but implementation address not found');
-
-    // Return proxy ABI with proxy info indicating detection failure
-    return buildContractResult(contractAddress, initialResult, networkConfig, initialProvider, {
-      isProxy: true,
-      proxyType,
-      proxyAddress: contractAddress,
-      detectionMethod: 'automatic',
-    });
-  }
-
-  logger.info('handleProxyDetection', `Found implementation at: ${implementationAddress}`);
-
-  // Try to load implementation ABI
-  const implementationResult = await loadImplementationAbi(
-    contractAddress,
-    implementationAddress,
-    networkConfig,
-    proxyType
-  );
-
-  const baseProxyInfo = {
-    isProxy: true,
-    proxyType,
-    implementationAddress,
-    proxyAddress: contractAddress,
-    detectionMethod: 'automatic',
-    ...(adminAddress ? { adminAddress } : {}),
-  };
-
-  if (implementationResult) {
-    // Use implementation ABI with proxy metadata
-    // Implementation ABI was fetched from Etherscan
-    return buildContractResult(
-      contractAddress,
-      implementationResult,
-      networkConfig,
-      EvmProviderKeys.Etherscan,
-      baseProxyInfo
-    );
-  } else {
-    // Fall back to proxy ABI with proxy info (provenance from initial provider)
-    return buildContractResult(
-      contractAddress,
-      initialResult,
-      networkConfig,
-      initialProvider,
-      baseProxyInfo
-    );
-  }
-}
-
-/**
- * Loads contract with automatic proxy detection and implementation resolution
- */
-async function loadContractWithProxyDetection(
-  contractAddress: string,
-  networkConfig: TypedEvmNetworkConfig,
-  options: ContractLoadOptions = {},
-  forcedProvider: EvmContractDefinitionProviderKey | null = null
-): Promise<EvmContractLoadResult> {
-  try {
-    // Determine provider precedence based on forced provider and user config
-    let uiDefault: EvmContractDefinitionProviderKey | null = null;
-    // 1) New generic per-service config
-    const svcCfg = userNetworkServiceConfigService.get(networkConfig.id, 'contract-definitions');
-    if (svcCfg && typeof svcCfg === 'object' && 'defaultProvider' in svcCfg) {
-      const raw = (svcCfg as Record<string, unknown>).defaultProvider;
-      if (isEvmProviderKey(raw)) uiDefault = raw as EvmContractDefinitionProviderKey;
-    }
-    // App-config default provider (optional)
-    const appDefaultRaw = appConfigService.getGlobalServiceParam(
-      'contractdefinition',
-      'defaultProvider'
-    );
-    const appDefault: EvmContractDefinitionProviderKey | null =
-      typeof appDefaultRaw === 'string' && isEvmProviderKey(appDefaultRaw)
-        ? (appDefaultRaw as EvmContractDefinitionProviderKey)
-        : null;
-
-    // Helper function to build provider array from primary provider
-    const buildProviderArray = (
-      primary: EvmContractDefinitionProviderKey
-    ): Array<EvmContractDefinitionProviderKey> => [
-      primary,
-      primary === EvmProviderKeys.Etherscan ? EvmProviderKeys.Sourcify : EvmProviderKeys.Etherscan,
-    ];
-
-    const providers: Array<EvmContractDefinitionProviderKey> = forcedProvider
-      ? [forcedProvider]
-      : uiDefault
-        ? buildProviderArray(uiDefault)
-        : appDefault
-          ? buildProviderArray(appDefault)
-          : [EvmProviderKeys.Etherscan, EvmProviderKeys.Sourcify];
-
-    const overallDeadline = Date.now() + OVERALL_BUDGET_MS;
-    let initialResult: { schema: ContractSchema; originalAbi: string } | null = null;
-    let lastError: unknown = null;
-    let usedProvider: EvmContractDefinitionProviderKey | null = null;
-    for (const provider of providers) {
-      try {
-        const remainingOverall = Math.max(100, overallDeadline - Date.now());
-        const attemptTimeout = Math.min(PER_PROVIDER_TIMEOUT_MS, remainingOverall);
-
-        if (provider === EvmProviderKeys.Etherscan) {
-          initialResult = await withTimeout(
-            loadAbiFromEtherscan(contractAddress, networkConfig),
-            attemptTimeout,
-            'etherscan'
-          );
-        } else if (provider === EvmProviderKeys.Sourcify) {
-          initialResult = await withTimeout(
-            loadAbiFromSourcify(contractAddress, networkConfig, attemptTimeout),
-            attemptTimeout,
-            'sourcify'
-          );
-        }
-        if (initialResult) {
-          usedProvider = provider;
-          break;
-        }
-      } catch (err) {
-        lastError = err;
-        continue;
-      }
-    }
-    if (!initialResult) throw lastError ?? new Error('No provider succeeded');
-
-    logger.info(
-      'loadContractWithProxyDetection',
-      `Successfully fetched initial ABI for ${contractAddress} with ${initialResult.schema.functions.length} functions`
-    );
-
-    // Step 2: Handle proxy detection if enabled
-    if (!options.skipProxyDetection && !options.treatAsImplementation) {
-      const proxyResult = await handleProxyDetection(
-        contractAddress,
-        initialResult,
-        networkConfig,
-        usedProvider
-      );
-      if (proxyResult) {
-        return proxyResult;
-      }
-    }
-
-    // Step 3: Not a proxy or proxy detection skipped - return original ABI
-    return buildContractResult(contractAddress, initialResult, networkConfig, usedProvider);
-  } catch (error) {
-    logger.warn('loadContractWithProxyDetection', `Contract loading failed: ${error}`);
-
-    // If a forced provider was specified, honor it and do NOT fallback automatically
-    if (forcedProvider) {
-      throw error;
-    }
-
-    // Check if this is a "contract not verified" error
-    const errorMessage = (error as Error).message || '';
-    if (errorMessage.includes('Contract not verified')) {
-      throw new Error(
-        `Contract at ${contractAddress} is not verified on the block explorer. ` +
-          `Verification status: unverified. Please provide the contract ABI manually.`
-      );
-    }
-    // Otherwise, rethrow the last error from provider attempts
-    throw error;
-  }
-}

package/src/abi/sourcify.ts

@@ -1,75 +0,0 @@
-import type { ContractSchema } from '@openzeppelin/ui-types';
-import { logger } from '@openzeppelin/ui-utils';
-
-import type { AbiItem, TypedEvmNetworkConfig } from '../types';
-import { transformAbiToSchema } from './transformer';
-
-export interface SourcifyAbiResult {
-  schema: ContractSchema;
-  originalAbi: string;
-}
-
-const SOURCIFY_APP_BASE = 'https://repo.sourcify.dev';
-
-export function getSourcifyContractAppUrl(chainId: number, address: string): string {
-  return `${SOURCIFY_APP_BASE}/${chainId}/${address}`;
-}
-
-const SOURCIFY_API_BASE = 'https://sourcify.dev/server/v2';
-
-interface SourcifyApiContractResponse {
-  abi?: AbiItem[];
-  metadata?: {
-    contractName?: string;
-    output?: {
-      abi?: AbiItem[];
-    };
-  };
-}
-
-function buildSourcifyApiUrl(chainId: number, address: string): string {
-  const normalizedAddress = address.toLowerCase();
-  const url = new URL(
-    `${SOURCIFY_API_BASE}/contract/${chainId}/${normalizedAddress}?fields=abi,metadata`
-  );
-  return url.toString();
-}
-
-export async function loadAbiFromSourcify(
-  address: string,
-  networkConfig: TypedEvmNetworkConfig,
-  timeoutMs = 4000
-): Promise<SourcifyAbiResult> {
-  const controller = new AbortController();
-  const timeout = setTimeout(() => controller.abort(), timeoutMs);
-
-  try {
-    const url = buildSourcifyApiUrl(networkConfig.chainId, address);
-    logger.info('loadAbiFromSourcify', `Fetching contract from ${url}`);
-
-    const response = await fetch(url, { signal: controller.signal });
-    if (!response.ok) {
-      throw new Error(`Sourcify request failed: ${response.status} ${response.statusText}`);
-    }
-
-    const payload = (await response.json()) as SourcifyApiContractResponse;
-    const abi = payload.abi ?? payload.metadata?.output?.abi;
-
-    if (!abi || !Array.isArray(abi)) {
-      throw new Error('Sourcify metadata did not include a valid ABI array');
-    }
-
-    const normalizedAddress = address.toLowerCase();
-    const contractName =
-      payload.metadata?.contractName ||
-      `Contract_${normalizedAddress.substring(0, 6).toUpperCase()}`;
-    const schema = transformAbiToSchema(abi, contractName, address);
-
-    return { schema, originalAbi: JSON.stringify(abi) };
-  } catch (error) {
-    logger.warn('loadAbiFromSourcify', `Failed to fetch ABI from Sourcify: ${String(error)}`);
-    throw error as Error;
-  } finally {
-    clearTimeout(timeout);
-  }
-}