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

package/src/transaction/eoa.ts

@@ -1,98 +0,0 @@
-import { GetAccountReturnType } from '@wagmi/core';
-import { WalletClient } from 'viem';
-
-import {
-  EoaExecutionConfig,
-  ExecutionConfig,
-  TransactionStatusUpdate,
-  TxStatus,
-} from '@openzeppelin/ui-types';
-import { logger } from '@openzeppelin/ui-utils';
-
-import { WriteContractParameters } from '../types';
-import { validateEoaConfig } from '../validation';
-import { WagmiWalletImplementation } from '../wallet/implementation/wagmi-implementation';
-import { ExecutionStrategy } from './execution-strategy';
-
-const SYSTEM_LOG_TAG = 'EoaExecutionStrategy';
-
-/**
- * Implements the ExecutionStrategy for a standard Externally Owned Account (EOA).
- * This strategy involves signing and broadcasting a transaction directly from the user's
- * connected wallet, which is the most common way of interacting with a blockchain.
- */
-export class EoaExecutionStrategy implements ExecutionStrategy {
-  public async execute(
-    transactionData: WriteContractParameters,
-    executionConfig: ExecutionConfig,
-    walletImplementation: WagmiWalletImplementation,
-    onStatusChange: (status: TxStatus, details: TransactionStatusUpdate) => void,
-    // runtimeApiKey is unused in EOA strategy but required by the interface
-    _runtimeApiKey?: string
-  ): Promise<{ txHash: string }> {
-    const { walletClient, accountStatus } =
-      await this.getAuthenticatedWalletClient(walletImplementation);
-
-    // Final validation at the point of execution
-    const eoaConfig = executionConfig as EoaExecutionConfig;
-    const validationResult = await validateEoaConfig(eoaConfig, {
-      ...accountStatus,
-      chainId: accountStatus.chainId?.toString(),
-    });
-    if (validationResult !== true) {
-      throw new Error(validationResult);
-    }
-
-    logger.info(SYSTEM_LOG_TAG, 'Using EOA execution strategy.');
-    try {
-      logger.debug(SYSTEM_LOG_TAG, 'Calling walletClient.writeContract with:', {
-        account: accountStatus.address,
-        address: transactionData.address,
-        abi: transactionData.abi,
-        functionName: transactionData.functionName,
-        args: transactionData.args,
-        value: transactionData.value,
-        chain: walletClient.chain,
-      });
-
-      onStatusChange('pendingSignature', {});
-
-      const hash = await walletClient.writeContract({
-        account: accountStatus.address!,
-        address: transactionData.address,
-        abi: transactionData.abi,
-        functionName: transactionData.functionName,
-        args: transactionData.args,
-        value: transactionData.value,
-        chain: walletClient.chain,
-      });
-
-      logger.info(SYSTEM_LOG_TAG, 'EOA Transaction initiated. Hash:', hash);
-      return { txHash: hash };
-    } catch (error: unknown) {
-      logger.error(SYSTEM_LOG_TAG, 'Error during EOA writeContract call:', error);
-      const errorMessage = error instanceof Error ? error.message : 'Unknown EOA transaction error';
-      throw new Error(`Transaction failed (EOA): ${errorMessage}`);
-    }
-  }
-
-  private async getAuthenticatedWalletClient(
-    walletImplementation: WagmiWalletImplementation
-  ): Promise<{
-    walletClient: WalletClient;
-    accountStatus: GetAccountReturnType;
-  }> {
-    const walletClient = await walletImplementation.getWalletClient();
-    if (!walletClient) {
-      logger.error(SYSTEM_LOG_TAG, 'Wallet client not available. Is wallet connected?');
-      throw new Error('Wallet is not connected or client is unavailable.');
-    }
-
-    const accountStatus = walletImplementation.getWalletConnectionStatus();
-    if (!accountStatus.isConnected || !accountStatus.address) {
-      logger.error(SYSTEM_LOG_TAG, 'Account not available. Is wallet connected?');
-      throw new Error('Wallet is not connected or account address is unavailable.');
-    }
-    return { walletClient, accountStatus };
-  }
-}

package/src/transaction/execution-strategy.ts

@@ -1,33 +0,0 @@
-import { ExecutionConfig, TransactionStatusUpdate, TxStatus } from '@openzeppelin/ui-types';
-
-import { WriteContractParameters } from '../types';
-import { WagmiWalletImplementation } from '../wallet/implementation/wagmi-implementation';
-
-/**
- * Defines a common interface for different transaction execution strategies (e.g., EOA, Relayer).
- * This allows the adapter to remain a lean orchestrator that selects the appropriate strategy
- * at runtime based on the user's configuration.
- */
-export interface ExecutionStrategy {
-  /**
-   * Executes a transaction according to the specific strategy.
-   *
-   * @param transactionData The contract write parameters, including ABI, function name, and args.
-   * @param executionConfig The configuration for the selected execution method.
-   * @param walletImplementation The wallet implementation to use for signing. Even for strategies
-   * that do not require a direct wallet signature for gas (like some relayers), this is kept
-   * as a required parameter to support meta-transactions, which still need a user's signature
-   * on the transaction data itself. This ensures a consistent interface and future-proofs the
-   * architecture for more advanced relayer patterns.
-   * @param onStatusChange A callback to report real-time status updates to the UI.
-   * @param runtimeApiKey Optional session-only API key for methods like Relayer.
-   * @returns A promise that resolves to an object containing the final transaction hash.
-   */
-  execute(
-    transactionData: WriteContractParameters,
-    executionConfig: ExecutionConfig,
-    walletImplementation: WagmiWalletImplementation,
-    onStatusChange: (status: TxStatus, details: TransactionStatusUpdate) => void,
-    runtimeApiKey?: string
-  ): Promise<{ txHash: string }>;
-}

package/src/transaction/formatter.ts

@@ -1,101 +0,0 @@
-import { isAddress } from 'viem';
-
-import type { ContractSchema, FormFieldType } from '@openzeppelin/ui-types';
-import { logger } from '@openzeppelin/ui-utils';
-
-import { createAbiFunctionItem } from '../abi';
-import { parseEvmInput } from '../transform';
-import type { WriteContractParameters } from '../types';
-
-/**
- * Formats transaction data for EVM chains based on parsed inputs.
- *
- * @param contractSchema The contract schema.
- * @param functionId The ID of the function being called.
- * @param submittedInputs The raw data submitted from the form.
- * @param fields The fields of the form schema.
- * @returns The formatted data payload suitable for signAndBroadcast.
- */
-export function formatEvmTransactionData(
-  contractSchema: ContractSchema,
-  functionId: string,
-  submittedInputs: Record<string, unknown>,
-  fields: FormFieldType[]
-): WriteContractParameters {
-  logger.info(
-    'formatEvmTransactionData',
-    `Formatting EVM transaction data for function: ${functionId}`
-  );
-
-  // --- Step 1: Determine Argument Order --- //
-  const functionDetails = contractSchema.functions.find((fn) => fn.id === functionId);
-  if (!functionDetails) {
-    throw new Error(`Function definition for ${functionId} not found in provided contract schema.`);
-  }
-  const expectedArgs = functionDetails.inputs;
-
-  // --- Step 2: Iterate and Select Values --- //
-  const orderedRawValues: unknown[] = [];
-  for (const expectedArg of expectedArgs) {
-    const fieldConfig = fields.find((field: FormFieldType) => field.name === expectedArg.name);
-    if (!fieldConfig) {
-      throw new Error(`Configuration missing for argument: ${expectedArg.name} in provided fields`);
-    }
-    let value: unknown;
-    if (fieldConfig.isHardcoded) {
-      value = fieldConfig.hardcodedValue;
-    } else if (fieldConfig.isHidden) {
-      throw new Error(`Field '${fieldConfig.name}' cannot be hidden without being hardcoded.`);
-    } else {
-      if (!(fieldConfig.name in submittedInputs)) {
-        throw new Error(`Missing submitted input for required field: ${fieldConfig.name}`);
-      }
-      value = submittedInputs[fieldConfig.name];
-    }
-    orderedRawValues.push(value);
-  }
-
-  // --- Step 3: Parse/Transform Values using the imported parser --- //
-  const transformedArgs = expectedArgs.map((param, index) => {
-    let valueToParse = orderedRawValues[index];
-
-    // If the ABI parameter type is an array (e.g., 'tuple[]', 'address[]') and
-    // the raw value from the form/runtime is an array (not already a string),
-    // stringify it for parseEvmInput which expects JSON at the top-level.
-    if (
-      typeof param.type === 'string' &&
-      param.type.endsWith('[]') &&
-      Array.isArray(valueToParse)
-    ) {
-      valueToParse = JSON.stringify(valueToParse);
-    }
-
-    return parseEvmInput(param, valueToParse, false);
-  });
-
-  // --- Step 4 & 5: Prepare Return Object --- //
-  const isPayable = functionDetails.stateMutability === 'payable';
-  let transactionValue = 0n; // Use BigInt zero
-  if (isPayable) {
-    logger.warn(
-      'formatEvmTransactionData',
-      'Payable function detected, but sending 0 ETH. Implement value input.'
-    );
-    // TODO: Read value from submittedInputs or config when payable input is implemented
-  }
-
-  const functionAbiItem = createAbiFunctionItem(functionDetails);
-
-  if (!contractSchema.address || !isAddress(contractSchema.address)) {
-    throw new Error('Contract address is missing or invalid in the provided schema.');
-  }
-
-  const paramsForSignAndBroadcast: WriteContractParameters = {
-    address: contractSchema.address,
-    abi: [functionAbiItem],
-    functionName: functionDetails.name,
-    args: transformedArgs,
-    value: transactionValue, // Pass BigInt value
-  };
-  return paramsForSignAndBroadcast;
-}

package/src/transaction/relayer.ts

@@ -1,380 +0,0 @@
-// This file will contain the business logic for interacting with the Relayer SDK
-import { encodeFunctionData, formatEther } from 'viem';
-
-import {
-  Configuration,
-  RelayersApi,
-  Speed,
-  type ApiResponseRelayerResponseData,
-  type EvmTransactionRequest,
-  type EvmTransactionResponse,
-} from '@openzeppelin/relayer-sdk';
-import {
-  ExecutionConfig,
-  RelayerDetails,
-  RelayerDetailsRich,
-  RelayerExecutionConfig,
-  TransactionStatusUpdate,
-  TxStatus,
-} from '@openzeppelin/ui-types';
-import { logger } from '@openzeppelin/ui-utils';
-
-import { TypedEvmNetworkConfig, WriteContractParameters } from '../types';
-import { WagmiWalletImplementation } from '../wallet/implementation/wagmi-implementation';
-import { ExecutionStrategy } from './execution-strategy';
-
-/**
- * EVM-specific transaction options for the OpenZeppelin Relayer.
- * These options map directly to the EvmTransactionRequest parameters in the SDK.
- */
-export interface EvmRelayerTransactionOptions {
-  // Basic options that most users will want to configure
-  speed?: Speed;
-  gasLimit?: number;
-
-  // Advanced options for fine-grained control
-  gasPrice?: number;
-  maxFeePerGas?: number;
-  maxPriorityFeePerGas?: number;
-
-  // Transaction expiration
-  validUntil?: string; // ISO 8601 date string
-}
-
-/**
- * Implements the ExecutionStrategy for the OpenZeppelin Relayer.
- * This strategy sends the transaction to the relayer service, which then handles
- * gas payment, signing, and broadcasting. It includes a polling mechanism to wait
- * for the transaction to be mined and return the final hash.
- */
-export class RelayerExecutionStrategy implements ExecutionStrategy {
-  public async execute(
-    transactionData: WriteContractParameters,
-    executionConfig: ExecutionConfig,
-    _walletImplementation: WagmiWalletImplementation,
-    onStatusChange: (status: TxStatus, details: TransactionStatusUpdate) => void,
-    runtimeApiKey?: string
-  ): Promise<{ txHash: string }> {
-    const relayerConfig = executionConfig as RelayerExecutionConfig;
-
-    if (!runtimeApiKey) {
-      throw new Error('API Key is required for Relayer execution.');
-    }
-
-    const { transactionId } = await this.sendTransactionViaRelayer(
-      transactionData,
-      relayerConfig,
-      runtimeApiKey
-    );
-
-    onStatusChange('pendingRelayer', { transactionId });
-
-    const sdkConfig = new Configuration({
-      basePath: relayerConfig.serviceUrl,
-      accessToken: runtimeApiKey,
-    });
-
-    const txHash = await this.pollForTransactionHash(
-      relayerConfig.relayer.relayerId,
-      transactionId,
-      sdkConfig
-    );
-
-    return { txHash };
-  }
-
-  /**
-   * Fetches and filters relayers for a specific EVM network from the OpenZeppelin Relayer service.
-   * This function handles pagination to retrieve all available relayers.
-   *
-   * @param serviceUrl The base URL of the relayer service.
-   * @param accessToken The session-based API key for authentication.
-   * @param networkConfig The EVM network configuration to filter relayers by.
-   * @returns A promise that resolves to an array of compatible relayer details.
-   * @throws If the API call fails or returns an unsuccessful response.
-   */
-  public async getEvmRelayers(
-    serviceUrl: string,
-    accessToken: string,
-    networkConfig: TypedEvmNetworkConfig
-  ): Promise<RelayerDetails[]> {
-    logger.info(
-      '[Relayer] Getting relayers with access token',
-      accessToken.slice(0, 5).padEnd(accessToken.length, '*')
-    );
-    const sdkConfig = new Configuration({
-      basePath: serviceUrl,
-      accessToken,
-    });
-    const relayersApi = new RelayersApi(sdkConfig);
-
-    let allRelayers: ApiResponseRelayerResponseData[] = [];
-    let currentPage = 1;
-    let totalItems = 0;
-    let hasMore = true;
-
-    do {
-      const { data } = await relayersApi.listRelayers(currentPage, 100);
-
-      if (!data.success || !data.data) {
-        throw new Error(`Failed to fetch relayers on page ${currentPage}.`);
-      }
-
-      allRelayers = [...allRelayers, ...data.data];
-      totalItems = data.pagination?.total_items || 0;
-
-      if (allRelayers.length >= totalItems) {
-        hasMore = false;
-      } else {
-        currentPage++;
-      }
-    } while (hasMore);
-
-    return allRelayers
-      .filter(
-        (r: ApiResponseRelayerResponseData) =>
-          r.network_type === 'evm' && networkConfig.id.includes(r.network)
-      )
-      .map((r: ApiResponseRelayerResponseData) => ({
-        relayerId: r.id,
-        name: r.name,
-        address: r.address || '',
-        network: r.network,
-        paused: r.paused || false,
-      }));
-  }
-
-  /**
-   * Fetches comprehensive information about a specific relayer including balance and status.
-   * This function combines multiple SDK API calls to provide rich relayer details.
-   *
-   * @param serviceUrl The base URL of the relayer service.
-   * @param accessToken The session-based API key for authentication.
-   * @param relayerId The unique identifier of the relayer.
-   * @param networkConfig The EVM network configuration to get the native currency symbol.
-   * @returns A promise that resolves to enhanced relayer details including balance and status.
-   * @throws If any API call fails or returns an unsuccessful response.
-   */
-  public async getEvmRelayer(
-    serviceUrl: string,
-    accessToken: string,
-    relayerId: string,
-    networkConfig: TypedEvmNetworkConfig
-  ): Promise<RelayerDetailsRich> {
-    logger.info('[Relayer] Getting detailed relayer info', relayerId);
-
-    const sdkConfig = new Configuration({
-      basePath: serviceUrl,
-      accessToken,
-    });
-    const relayersApi = new RelayersApi(sdkConfig);
-
-    try {
-      // Fetch basic relayer details, balance, and status in parallel
-      const [relayerResponse, balanceResponse, statusResponse] = await Promise.all([
-        relayersApi.getRelayer(relayerId),
-        relayersApi.getRelayerBalance(relayerId).catch((err) => {
-          logger.warn('[Relayer] Failed to fetch balance', err);
-          return null;
-        }),
-        relayersApi.getRelayerStatus(relayerId).catch((err) => {
-          logger.warn('[Relayer] Failed to fetch status', err);
-          return null;
-        }),
-      ]);
-
-      if (!relayerResponse.data.success || !relayerResponse.data.data) {
-        throw new Error(`Failed to fetch relayer details for ID: ${relayerId}`);
-      }
-
-      const relayerData = relayerResponse.data.data;
-
-      // Build enhanced relayer details object
-      const enhancedDetails: RelayerDetailsRich = {
-        relayerId: relayerData.id,
-        name: relayerData.name,
-        address: relayerData.address || '',
-        network: relayerData.network,
-        paused: relayerData.paused || false,
-        systemDisabled: relayerData.system_disabled || false,
-      };
-
-      // Add balance if available
-      if (balanceResponse?.data?.success && balanceResponse.data.data?.balance) {
-        try {
-          // Format balance from wei to native currency
-          const balanceInWei = BigInt(balanceResponse.data.data.balance);
-          const balanceInEth = formatEther(balanceInWei);
-          const currencySymbol = networkConfig.nativeCurrency.symbol;
-          enhancedDetails.balance = `${balanceInEth} ${currencySymbol}`;
-        } catch (error) {
-          logger.warn('[Relayer] Failed to format balance, using raw value', String(error));
-          enhancedDetails.balance = String(balanceResponse.data.data.balance);
-        }
-      }
-
-      // Add status details if available
-      if (statusResponse?.data?.success && statusResponse.data.data) {
-        const statusData = statusResponse.data.data;
-        if (statusData.network_type === 'evm') {
-          if (statusData.nonce !== undefined && statusData.nonce !== null) {
-            enhancedDetails.nonce = String(statusData.nonce);
-          }
-          if (statusData.pending_transactions_count !== undefined) {
-            enhancedDetails.pendingTransactionsCount = statusData.pending_transactions_count;
-          }
-          if (statusData.last_confirmed_transaction_timestamp) {
-            enhancedDetails.lastConfirmedTransactionTimestamp =
-              statusData.last_confirmed_transaction_timestamp;
-          }
-        }
-      }
-
-      logger.info('[Relayer] Retrieved enhanced relayer details', JSON.stringify(enhancedDetails));
-      return enhancedDetails;
-    } catch (error) {
-      logger.error(
-        '[Relayer] Failed to get relayer details',
-        error instanceof Error ? error.message : String(error)
-      );
-      throw error;
-    }
-  }
-
-  /**
-   * Submits a transaction to the relayer service for asynchronous processing.
-   * @param transactionData The contract write parameters.
-   * @param executionConfig The relayer-specific execution configuration.
-   * @param runtimeApiKey The user's session-only API key.
-   * @returns A promise that resolves to an object containing the transaction ID assigned by the relayer.
-   */
-  private async sendTransactionViaRelayer(
-    transactionData: WriteContractParameters,
-    executionConfig: RelayerExecutionConfig,
-    runtimeApiKey: string
-  ): Promise<{ transactionId: string }> {
-    const data = encodeFunctionData({
-      abi: transactionData.abi,
-      functionName: transactionData.functionName,
-      args: transactionData.args,
-    });
-
-    // Type-safe extraction of EVM-specific options
-    const evmOptions = executionConfig.transactionOptions as
-      | EvmRelayerTransactionOptions
-      | undefined;
-
-    // Compute value for relayer request. The SDK type is number, but JS Number
-    // cannot safely represent large wei amounts. Prefer passing zero when undefined
-    // or warn when truncation would occur.
-    const valueBigint = transactionData.value ?? 0n;
-    let valueNumber: number = 0;
-    const MAX_SAFE = BigInt(Number.MAX_SAFE_INTEGER);
-    if (valueBigint > MAX_SAFE) {
-      logger.warn(
-        '[Relayer] Value exceeds JS safe integer. Truncating for request.',
-        valueBigint.toString()
-      );
-      valueNumber = Number(MAX_SAFE);
-    } else {
-      valueNumber = Number(valueBigint);
-    }
-
-    const relayerTxRequest: EvmTransactionRequest = {
-      to: transactionData.address,
-      data,
-      value: valueNumber,
-      // If no explicit gas limit is provided, keep a conservative default but warn.
-      gas_limit: (() => {
-        if (typeof evmOptions?.gasLimit === 'number') return evmOptions.gasLimit;
-        logger.warn(
-          '[Relayer]',
-          'No gasLimit provided; using default 210000. Consider setting explicitly.'
-        );
-        return 210000;
-      })(),
-      // Note: The OpenZeppelin Relayer API requires exactly one gas pricing strategy to be provided.
-      // Valid options are: speed, gas_price, or both max_fee_per_gas + max_priority_fee_per_gas.
-      // If none are provided, the API will return a 400 Bad Request error.
-      // Only include speed if explicitly set in options
-      ...(evmOptions?.speed !== undefined && { speed: evmOptions.speed }),
-      // Include optional parameters only if provided
-      ...(evmOptions?.gasPrice !== undefined && { gas_price: evmOptions.gasPrice }),
-      ...(evmOptions?.maxFeePerGas !== undefined && { max_fee_per_gas: evmOptions.maxFeePerGas }),
-      ...(evmOptions?.maxPriorityFeePerGas !== undefined && {
-        max_priority_fee_per_gas: evmOptions.maxPriorityFeePerGas,
-      }),
-      ...(evmOptions?.validUntil !== undefined && { valid_until: evmOptions.validUntil }),
-    };
-
-    const sdkConfig = new Configuration({
-      basePath: executionConfig.serviceUrl,
-      accessToken: runtimeApiKey,
-    });
-    const relayersApi = new RelayersApi(sdkConfig);
-
-    const result = await relayersApi.sendTransaction(
-      executionConfig.relayer.relayerId,
-      relayerTxRequest
-    );
-
-    if (!result.data.success || !result.data.data?.id) {
-      throw new Error(`Relayer API failed to return a transaction ID. Error: ${result.data.error}`);
-    }
-
-    return { transactionId: result.data.data.id };
-  }
-
-  /**
-   * Polls the relayer for a transaction's status until it is mined and has a hash, or fails.
-   * @param relayerId The ID of the relayer processing the transaction.
-   * @param transactionId The ID of the transaction to poll.
-   * @param sdkConfig The SDK configuration containing the necessary authentication.
-   * @returns A promise that resolves to the final transaction hash.
-   * @throws If the transaction fails or polling times out.
-   */
-  private async pollForTransactionHash(
-    relayerId: string,
-    transactionId: string,
-    sdkConfig: Configuration
-  ): Promise<string> {
-    const relayersApi = new RelayersApi(sdkConfig);
-    const POLLING_INTERVAL = 2000;
-    const POLLING_TIMEOUT = 300000; // 5 minutes in milliseconds
-    const startTime = Date.now();
-
-    while (Date.now() - startTime < POLLING_TIMEOUT) {
-      const { data } = await relayersApi.getTransactionById(relayerId, transactionId);
-
-      if (!data.success || !data.data) {
-        throw new Error(`Failed to get transaction status for ID: ${transactionId}`);
-      }
-
-      const txResponse = data.data as EvmTransactionResponse;
-
-      if (txResponse.status === 'mined' || txResponse.status === 'confirmed') {
-        if (!txResponse.hash) {
-          throw new Error(
-            `Transaction is confirmed but no hash was returned for ID: ${transactionId}`
-          );
-        }
-        return txResponse.hash;
-      }
-
-      if (
-        txResponse.status === 'failed' ||
-        txResponse.status === 'canceled' ||
-        txResponse.status === 'expired'
-      ) {
-        throw new Error(
-          `Transaction ${txResponse.status}: ${txResponse.status_reason || 'No reason provided.'}`
-        );
-      }
-
-      // Continue polling for 'pending' or 'sent' statuses
-      await new Promise((resolve) => setTimeout(resolve, POLLING_INTERVAL));
-    }
-
-    throw new Error(`Polling for transaction hash timed out for ID: ${transactionId}`);
-  }
-}