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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openzeppelin/ui-builder-adapter-evm",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "private": false,
   "description": "EVM Adapter for UI Builder",
   "keywords": [
@@ -37,16 +37,17 @@
   },
   "dependencies": {
     "@openzeppelin/relayer-sdk": "1.4.0",
-    "@openzeppelin/ui-components": "^1.0.2",
-    "@openzeppelin/ui-react": "^1.0.0",
-    "@openzeppelin/ui-types": "^1.1.0",
-    "@openzeppelin/ui-utils": "^1.0.0",
+    "@openzeppelin/ui-components": "^1.2.0",
+    "@openzeppelin/ui-react": "^1.1.0",
+    "@openzeppelin/ui-types": "^1.5.0",
+    "@openzeppelin/ui-utils": "^1.2.0",
     "@wagmi/connectors": "5.7.13",
     "@wagmi/core": "^2.20.3",
     "@web3icons/react": "^4.0.19",
     "lodash": "^4.17.21",
     "lucide-react": "^0.510.0",
-    "react-hook-form": "^7.62.0"
+    "react-hook-form": "^7.62.0",
+    "@openzeppelin/ui-builder-adapter-evm-core": "1.0.0"
   },
   "devDependencies": {
     "@rainbow-me/rainbowkit": "^2.2.8",

package/src/__tests__/adapter-parsing.test.ts

@@ -1,13 +1,14 @@
 import { beforeEach, describe, expect, it } from 'vitest';
 
-// Adjust path as needed
+import {
+  EVM_TYPE_TO_FIELD_TYPE,
+  parseEvmInput as parseEvmInputFunction,
+} from '@openzeppelin/ui-builder-adapter-evm-core';
 import type { ContractFunction, FunctionParameter } from '@openzeppelin/ui-types';
 
 import { mockEvmNetworkConfig } from './mocks/mock-network-configs';
 
 import { EvmAdapter } from '../adapter';
-import { EVM_TYPE_TO_FIELD_TYPE } from '../mapping';
-import { parseEvmInput as parseEvmInputFunction } from '../transform';
 
 // Mock FunctionParameter type helper
 const createParam = (

package/src/__tests__/getDefaultServiceConfig.test.ts

@@ -0,0 +1,185 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import type { TypedEvmNetworkConfig } from '@openzeppelin/ui-builder-adapter-evm-core';
+import type { EvmNetworkConfig } from '@openzeppelin/ui-types';
+import { appConfigService } from '@openzeppelin/ui-utils';
+
+import { getEvmDefaultServiceConfig } from '../configuration/network-services';
+
+describe('getEvmDefaultServiceConfig', () => {
+  const createMockNetworkConfig = (
+    overrides: Partial<TypedEvmNetworkConfig> = {}
+  ): EvmNetworkConfig => ({
+    id: 'ethereum',
+    exportConstName: 'ethereum',
+    name: 'Ethereum',
+    ecosystem: 'evm',
+    network: 'mainnet',
+    type: 'mainnet',
+    isTestnet: false,
+    chainId: 1,
+    rpcUrl: 'https://eth.llamarpc.com',
+    explorerUrl: 'https://etherscan.io',
+    apiUrl: 'https://api.etherscan.io/api',
+    nativeCurrency: {
+      name: 'Ether',
+      symbol: 'ETH',
+      decimals: 18,
+    },
+    ...overrides,
+  });
+
+  beforeEach(() => {
+    vi.spyOn(appConfigService, 'getGlobalServiceConfig').mockReturnValue(undefined);
+    vi.spyOn(appConfigService, 'getExplorerApiKey').mockReturnValue(undefined);
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  describe('rpc service', () => {
+    it('should return RPC config when rpcUrl is present', () => {
+      const networkConfig = createMockNetworkConfig();
+
+      const result = getEvmDefaultServiceConfig(networkConfig, 'rpc');
+
+      expect(result).toEqual({
+        rpcUrl: 'https://eth.llamarpc.com',
+      });
+    });
+
+    it('should return null when rpcUrl is missing', () => {
+      const networkConfig = createMockNetworkConfig({
+        rpcUrl: undefined,
+      });
+
+      const result = getEvmDefaultServiceConfig(networkConfig, 'rpc');
+
+      expect(result).toBeNull();
+    });
+  });
+
+  describe('explorer service', () => {
+    it('should return explorer config with explorerUrl and apiUrl when present', () => {
+      const networkConfig = createMockNetworkConfig();
+
+      const result = getEvmDefaultServiceConfig(networkConfig, 'explorer');
+
+      expect(result).toEqual({
+        explorerUrl: 'https://etherscan.io',
+        apiUrl: 'https://api.etherscan.io/api',
+      });
+    });
+
+    it('should include global V2 API key for V2-compatible networks', () => {
+      vi.spyOn(appConfigService, 'getGlobalServiceConfig').mockReturnValue({
+        apiKey: 'test-v2-api-key',
+      });
+
+      const networkConfig = createMockNetworkConfig({
+        supportsEtherscanV2: true,
+        primaryExplorerApiIdentifier: 'etherscan-v2',
+      });
+
+      const result = getEvmDefaultServiceConfig(networkConfig, 'explorer');
+
+      expect(result).toEqual({
+        explorerUrl: 'https://etherscan.io',
+        apiUrl: 'https://api.etherscan.io/api',
+        apiKey: 'test-v2-api-key',
+      });
+      expect(appConfigService.getGlobalServiceConfig).toHaveBeenCalledWith('etherscanv2');
+    });
+
+    it('should include app API key from globalServiceConfigs for non-V2 networks', () => {
+      vi.spyOn(appConfigService, 'getGlobalServiceConfig').mockReturnValue({
+        apiKey: 'test-routescan-key',
+      });
+
+      const networkConfig = createMockNetworkConfig({
+        supportsEtherscanV2: false,
+        primaryExplorerApiIdentifier: 'routescan',
+      });
+
+      const result = getEvmDefaultServiceConfig(networkConfig, 'explorer');
+
+      expect(result).toEqual({
+        explorerUrl: 'https://etherscan.io',
+        apiUrl: 'https://api.etherscan.io/api',
+        apiKey: 'test-routescan-key',
+      });
+      expect(appConfigService.getGlobalServiceConfig).toHaveBeenCalledWith('routescan');
+    });
+
+    it('should fallback to getExplorerApiKey when globalServiceConfig has no apiKey', () => {
+      vi.spyOn(appConfigService, 'getGlobalServiceConfig').mockReturnValue(undefined);
+      vi.spyOn(appConfigService, 'getExplorerApiKey').mockReturnValue('fallback-api-key');
+
+      const networkConfig = createMockNetworkConfig({
+        supportsEtherscanV2: false,
+        primaryExplorerApiIdentifier: 'blockscout',
+      });
+
+      const result = getEvmDefaultServiceConfig(networkConfig, 'explorer');
+
+      expect(result).toEqual({
+        explorerUrl: 'https://etherscan.io',
+        apiUrl: 'https://api.etherscan.io/api',
+        apiKey: 'fallback-api-key',
+      });
+      expect(appConfigService.getExplorerApiKey).toHaveBeenCalledWith('blockscout');
+    });
+
+    it('should return null when explorerUrl is missing and no API key configured', () => {
+      const networkConfig = createMockNetworkConfig({
+        explorerUrl: undefined,
+        apiUrl: undefined,
+      });
+
+      const result = getEvmDefaultServiceConfig(networkConfig, 'explorer');
+
+      expect(result).toBeNull();
+    });
+
+    it('should return config with API key when explorerUrl is missing but API key is available', () => {
+      vi.spyOn(appConfigService, 'getGlobalServiceConfig').mockReturnValue({
+        apiKey: 'test-api-key-only',
+      });
+
+      const networkConfig = createMockNetworkConfig({
+        explorerUrl: undefined,
+        apiUrl: undefined,
+        supportsEtherscanV2: true,
+        primaryExplorerApiIdentifier: 'etherscan-v2',
+      });
+
+      const result = getEvmDefaultServiceConfig(networkConfig, 'explorer');
+
+      expect(result).toEqual({
+        explorerUrl: undefined,
+        apiUrl: undefined,
+        apiKey: 'test-api-key-only',
+      });
+    });
+  });
+
+  describe('contract-definitions service', () => {
+    it('should return null for contract-definitions service', () => {
+      const networkConfig = createMockNetworkConfig();
+
+      const result = getEvmDefaultServiceConfig(networkConfig, 'contract-definitions');
+
+      expect(result).toBeNull();
+    });
+  });
+
+  describe('unknown service', () => {
+    it('should return null for unknown service IDs', () => {
+      const networkConfig = createMockNetworkConfig();
+
+      expect(getEvmDefaultServiceConfig(networkConfig, 'indexer')).toBeNull();
+      expect(getEvmDefaultServiceConfig(networkConfig, 'unknown')).toBeNull();
+    });
+  });
+});

package/src/__tests__/mocks/mock-network-configs.ts

@@ -1,4 +1,4 @@
-import type { TypedEvmNetworkConfig } from '../../types';
+import type { TypedEvmNetworkConfig } from '@openzeppelin/ui-builder-adapter-evm-core';
 
 /**
  * Mock EVM Network Configuration for testing purposes.

package/src/__tests__/provenanceLinks.test.ts

@@ -1,9 +1,11 @@
 import { describe, expect, it, vi } from 'vitest';
 
-import { loadEvmContract } from '../abi/loader';
-import { getEvmExplorerAddressUrl } from '../configuration/explorer';
-import type { TypedEvmNetworkConfig } from '../types';
-import type { EvmContractArtifacts } from '../types/artifacts';
+import {
+  getEvmExplorerAddressUrl,
+  loadEvmContract,
+  type EvmContractArtifacts,
+  type TypedEvmNetworkConfig,
+} from '@openzeppelin/ui-builder-adapter-evm-core';
 
 describe('EVM provenance links', () => {
   it('builds address URL from explorer config', () => {

package/src/__tests__/providerSelection.test.ts

@@ -1,11 +1,12 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
+import {
+  loadEvmContract,
+  type EvmContractArtifacts,
+  type TypedEvmNetworkConfig,
+} from '@openzeppelin/ui-builder-adapter-evm-core';
 import { appConfigService, userNetworkServiceConfigService } from '@openzeppelin/ui-utils';
 
-import { loadEvmContract } from '../abi/loader';
-import type { TypedEvmNetworkConfig } from '../types';
-import type { EvmContractArtifacts } from '../types/artifacts';
-
 describe('EVM provider selection (etherscan → sourcify, forced/app/ui precedence)', () => {
   const mockFetch = vi.fn();
 

package/src/__tests__/timeouts.test.ts

@@ -1,8 +1,10 @@
 import { describe, expect, it, vi } from 'vitest';
 
-import { loadEvmContract } from '../abi/loader';
-import type { TypedEvmNetworkConfig } from '../types';
-import type { EvmContractArtifacts } from '../types/artifacts';
+import {
+  loadEvmContract,
+  type EvmContractArtifacts,
+  type TypedEvmNetworkConfig,
+} from '@openzeppelin/ui-builder-adapter-evm-core';
 
 describe('EVM provider timeouts', () => {
   it('moves to next provider when the first provider exceeds per-provider timeout', async () => {

package/src/__tests__/wallet-connect.test.ts

@@ -8,7 +8,7 @@ import { mockEvmNetworkConfig } from './mocks/mock-network-configs';
 
 import { EvmAdapter } from '../adapter';
 
-// Mock the WagmiWalletImplementation to isolate EvmAdapter logic
+// Mock the createEvmWalletImplementation factory to isolate EvmAdapter logic
 vi.mock('../wallet/implementation/wagmi-implementation', () => {
   // --- Mock implementations for WagmiWalletImplementation methods ---
   const mockGetAvailableConnectors = vi.fn().mockResolvedValue([
@@ -50,7 +50,7 @@ vi.mock('../wallet/implementation/wagmi-implementation', () => {
   // --- End Mock Implementations ---
 
   return {
-    WagmiWalletImplementation: vi.fn().mockImplementation(() => ({
+    createEvmWalletImplementation: vi.fn().mockImplementation(() => ({
       // Expose mocks
       getAvailableConnectors: mockGetAvailableConnectors,
       connect: mockConnect,

package/src/adapter.ts

@@ -1,6 +1,42 @@
 import { type TransactionReceipt } from 'viem';
 import React from 'react';
 
+// Core module imports - reusable EVM logic
+import {
+  compareContractDefinitions as coreCompareContractDefinitions,
+  hashContractDefinition as coreHashContractDefinition,
+  validateContractDefinition as coreValidateContractDefinition,
+  EvmProviderKeys,
+  executeEvmTransaction,
+  formatEvmFunctionResult,
+  formatEvmTransactionData,
+  generateEvmDefaultField,
+  generateRainbowKitConfigFile,
+  generateRainbowKitExportables,
+  getEvmCompatibleFieldTypes,
+  getEvmCurrentBlock,
+  getEvmExplorerAddressUrl,
+  getEvmExplorerTxUrl,
+  getEvmTypeMappingInfo,
+  isEvmViewFunction,
+  isValidEvmAddress,
+  loadContractSchema,
+  loadContractWithFullMetadata,
+  mapEvmParamTypeToFieldType,
+  RelayerExecutionStrategy,
+  resolveFullUiKitConfiguration,
+  testEvmExplorerConnection,
+  testEvmNetworkServiceConnection,
+  testEvmRpcConnection,
+  validateEvmExecutionConfig,
+  validateEvmExplorerConfig,
+  validateEvmNetworkServiceConfig,
+  validateEvmRpcEndpoint,
+  waitForEvmTransactionConfirmation,
+  type EvmContractDefinitionProviderKey,
+  type TypedEvmNetworkConfig,
+  type WriteContractParameters,
+} from '@openzeppelin/ui-builder-adapter-evm-core';
 import type {
   AvailableUiKit,
   Connector,
@@ -31,52 +67,20 @@ import type {
 } from '@openzeppelin/ui-types';
 import { logger } from '@openzeppelin/ui-utils';
 
-import { abiComparisonService } from './abi/comparison';
-import {
-  getEvmNetworkServiceForms,
-  testEvmNetworkServiceConnection,
-  validateEvmNetworkServiceConfig,
-} from './configuration/network-services';
-import { EvmProviderKeys, type EvmContractDefinitionProviderKey } from './types/providers';
 import { EvmWalletUiRoot } from './wallet/components/EvmWalletUiRoot';
 import { evmUiKitManager } from './wallet/evmUiKitManager';
 import { evmFacadeHooks } from './wallet/hooks/facade-hooks';
 import { loadInitialConfigFromAppService } from './wallet/hooks/useUiKitConfig';
-import { generateRainbowKitConfigFile } from './wallet/rainbowkit/config-generator';
-import { generateRainbowKitExportables } from './wallet/rainbowkit/export-service';
-import { resolveFullUiKitConfiguration } from './wallet/services/configResolutionService';
 
-import { loadEvmContract } from './abi';
+// Adapter-specific imports - EVM adapter orchestration
 import {
-  getEvmCurrentBlock,
-  getEvmExplorerAddressUrl,
-  getEvmExplorerTxUrl,
+  getEvmDefaultServiceConfig,
+  getEvmNetworkServiceForms,
   getEvmSupportedExecutionMethods,
-  testEvmExplorerConnection,
-  testEvmRpcConnection,
-  validateEvmExecutionConfig,
-  validateEvmExplorerConfig,
-  validateEvmRpcEndpoint,
 } from './configuration';
-import {
-  generateEvmDefaultField,
-  getEvmCompatibleFieldTypes,
-  getEvmTypeMappingInfo,
-  mapEvmParamTypeToFieldType,
-} from './mapping';
-import { isEvmViewFunction, queryEvmViewFunction } from './query';
-import {
-  EoaExecutionStrategy,
-  EvmRelayerOptions,
-  ExecutionStrategy,
-  formatEvmTransactionData,
-  RelayerExecutionStrategy,
-  waitForEvmTransactionConfirmation,
-} from './transaction';
-import { formatEvmFunctionResult } from './transform';
-import { TypedEvmNetworkConfig } from './types';
-import type { WriteContractParameters } from './types';
-import { isValidEvmAddress, validateAndConvertEvmArtifacts } from './utils';
+// Adapter-specific query with RPC resolution
+import { queryEvmViewFunction } from './query';
+import { EvmRelayerOptions } from './transaction';
 import {
   connectAndEnsureCorrectNetwork,
   convertWagmiToEvmStatus,
@@ -160,14 +164,18 @@ export class EvmAdapter implements ContractAdapter {
     return testEvmNetworkServiceConnection(serviceId, values, this.networkConfig);
   }
 
+  /**
+   * @inheritdoc
+   */
+  public getDefaultServiceConfig(serviceId: string): Record<string, unknown> | null {
+    return getEvmDefaultServiceConfig(this.networkConfig, serviceId);
+  }
+
   /**
    * @inheritdoc
    */
   public async loadContract(source: string | Record<string, unknown>): Promise<ContractSchema> {
-    // Convert generic input to EVM-specific artifacts
-    const artifacts = validateAndConvertEvmArtifacts(source);
-    const result = await loadEvmContract(artifacts, this.networkConfig);
-    return result.schema;
+    return loadContractSchema(source, this.networkConfig);
   }
 
   /**
@@ -186,30 +194,9 @@ export class EvmAdapter implements ContractAdapter {
     };
     proxyInfo?: ProxyInfo;
   }> {
-    try {
-      // Convert generic input to EVM-specific artifacts
-      const artifacts = validateAndConvertEvmArtifacts(source);
-      const result = await loadEvmContract(artifacts, this.networkConfig);
-
-      return {
-        schema: result.schema,
-        source: result.source,
-        contractDefinitionOriginal: result.contractDefinitionOriginal,
-        metadata: result.metadata,
-        proxyInfo: result.proxyInfo,
-      };
-    } catch (error) {
-      // Check if this is an unverified contract error
-      const errorMessage = (error as Error).message || '';
-      if (errorMessage.includes('not verified on the block explorer')) {
-        // For unverified contracts, we still need to throw but include metadata
-        // The UI will handle this error and can extract verification status from the message
-        throw error;
-      }
-
-      // Re-throw other errors
-      throw error;
-    }
+    // Delegate to core convenience function
+    // Errors (including unverified contract errors) are handled by the core function
+    return loadContractWithFullMetadata(source, this.networkConfig);
   }
 
   /**
@@ -257,19 +244,7 @@ export class EvmAdapter implements ContractAdapter {
     runtimeApiKey?: string
   ): Promise<{ txHash: string }> {
     const walletImplementation = await getEvmWalletImplementation();
-    let strategy: ExecutionStrategy;
-
-    switch (executionConfig.method) {
-      case 'relayer':
-        strategy = new RelayerExecutionStrategy();
-        break;
-      case 'eoa':
-      default:
-        strategy = new EoaExecutionStrategy();
-        break;
-    }
-
-    return strategy.execute(
+    return executeEvmTransaction(
       transactionData as WriteContractParameters,
       executionConfig,
       walletImplementation,
@@ -388,7 +363,7 @@ export class EvmAdapter implements ContractAdapter {
       params,
       contractSchema,
       walletImplementation,
-      (src) => this.loadContract({ contractAddress: src })
+      (src: string) => this.loadContract({ contractAddress: src })
     );
   }
 
@@ -741,26 +716,8 @@ Get your WalletConnect projectId from <a href="https://cloud.walletconnect.com"
     severity: 'none' | 'minor' | 'major' | 'breaking';
     summary: string;
   }> {
-    try {
-      const result = abiComparisonService.compareAbis(storedSchema, freshSchema);
-      return {
-        identical: result.identical,
-        differences: result.differences.map((diff) => ({
-          type: diff.type,
-          section: diff.section,
-          name: diff.name,
-          details: diff.details,
-          impact: diff.impact,
-          oldSignature: diff.oldSignature,
-          newSignature: diff.newSignature,
-        })),
-        severity: result.severity,
-        summary: result.summary,
-      };
-    } catch (error) {
-      logger.error('EVM contract definition comparison failed:', (error as Error).message);
-      throw new Error(`Contract definition comparison failed: ${(error as Error).message}`);
-    }
+    // Delegate to core convenience function
+    return coreCompareContractDefinitions(storedSchema, freshSchema);
   }
 
   /**
@@ -771,19 +728,16 @@ Get your WalletConnect projectId from <a href="https://cloud.walletconnect.com"
     errors: string[];
     warnings: string[];
   } {
-    const result = abiComparisonService.validateAbi(definition);
-    return {
-      valid: result.valid,
-      errors: result.errors,
-      warnings: result.warnings,
-    };
+    // Delegate to core convenience function
+    return coreValidateContractDefinition(definition);
   }
 
   /**
    * @inheritdoc
    */
   public hashContractDefinition(definition: string): string {
-    return abiComparisonService.hashAbi(definition);
+    // Delegate to core convenience function
+    return coreHashContractDefinition(definition);
   }
 
   /**

package/src/configuration/execution.ts

@@ -1,17 +1,6 @@
-import type {
-  EoaExecutionConfig,
-  ExecutionConfig,
-  ExecutionMethodDetail,
-  MultisigExecutionConfig,
-  RelayerExecutionConfig,
-} from '@openzeppelin/ui-types';
+import type { ExecutionMethodDetail } from '@openzeppelin/ui-types';
 import { logger } from '@openzeppelin/ui-utils';
 
-import { validateEoaConfig, validateRelayerConfig } from '../validation';
-import { EvmWalletConnectionStatus } from '../wallet/types';
-
-const SYSTEM_LOG_TAG = 'adapter-evm-execution-config';
-
 /**
  * Returns details for execution methods supported by the EVM adapter.
  */
@@ -41,43 +30,3 @@ export async function getEvmSupportedExecutionMethods(): Promise<ExecutionMethod
     },
   ]);
 }
-
-/**
- * Validates Multisig execution configuration (placeholder).
- */
-async function _validateMultisigConfig(
-  _config: MultisigExecutionConfig,
-  _walletStatus: EvmWalletConnectionStatus
-): Promise<true | string> {
-  logger.info(SYSTEM_LOG_TAG, 'Multisig execution config validation: Not yet fully implemented.');
-  // TODO: Add validation for Safe address, required signers, etc.
-  return true; // Placeholder
-}
-
-/**
- * Validates the complete execution configuration object against the
- * requirements and capabilities of the EVM adapter.
- */
-export async function validateEvmExecutionConfig(
-  config: ExecutionConfig,
-  walletStatus: EvmWalletConnectionStatus
-): Promise<true | string> {
-  logger.info(SYSTEM_LOG_TAG, 'Validating EVM execution config:', { config, walletStatus });
-
-  switch (config.method) {
-    case 'eoa':
-      return validateEoaConfig(config as EoaExecutionConfig, walletStatus);
-    case 'relayer':
-      return validateRelayerConfig(config as RelayerExecutionConfig);
-    case 'multisig':
-      return _validateMultisigConfig(config as MultisigExecutionConfig, walletStatus);
-    default: {
-      const unknownMethod = (config as ExecutionConfig).method;
-      logger.warn(
-        SYSTEM_LOG_TAG,
-        `Unsupported execution method type encountered: ${unknownMethod}`
-      );
-      return `Unsupported execution method type: ${unknownMethod}`;
-    }
-  }
-}

package/src/configuration/index.ts

@@ -1,5 +1,4 @@
-// Barrel file for config module
+// Barrel file for configuration module
+// Adapter-specific exports only - core configuration utilities available from @openzeppelin/ui-builder-adapter-evm-core
 export * from './execution';
-export * from './explorer';
 export * from './network-services';
-export * from './rpc';