@openzeppelin/adapter-stellar 1.0.0

package/src/transaction/components/FeeConfiguration.tsx

@@ -0,0 +1,41 @@
+import React from 'react';
+import { Control } from 'react-hook-form';
+
+import { BooleanField, NumberField } from '@openzeppelin/ui-components';
+
+import type { StellarRelayerFormData } from './useStellarRelayerOptions';
+
+interface FeeConfigurationProps {
+  control: Control<StellarRelayerFormData>;
+  showBasicFeeOnly: boolean;
+}
+
+export const FeeConfiguration: React.FC<FeeConfigurationProps> = ({
+  control,
+  showBasicFeeOnly,
+}) => {
+  return (
+    <div className="space-y-4">
+      <NumberField
+        id="maxFee"
+        label="Maximum Fee (stroops)"
+        name="transactionOptions.maxFee"
+        control={control}
+        placeholder="e.g., 1000000 (0.1 XLM)"
+        helperText="Maximum fee you're willing to pay in stroops (1 XLM = 10,000,000 stroops). Leave empty to use network defaults."
+        min={0}
+        step={1}
+      />
+
+      {!showBasicFeeOnly && (
+        <BooleanField
+          id="feeBump"
+          label="Enable Fee Bump"
+          name="transactionOptions.feeBump"
+          control={control}
+          helperText="Automatically increase fee if transaction gets stuck in the network."
+        />
+      )}
+    </div>
+  );
+};

package/src/transaction/components/StellarRelayerOptions.tsx

@@ -0,0 +1,60 @@
+import React from 'react';
+
+import { Tabs, TabsContent, TabsList, TabsTrigger } from '@openzeppelin/ui-components';
+
+import { AdvancedInfo } from './AdvancedInfo';
+import { FeeConfiguration } from './FeeConfiguration';
+import { TransactionTiming } from './TransactionTiming';
+import { useStellarRelayerOptions } from './useStellarRelayerOptions';
+
+/**
+ * Stellar-specific relayer transaction options component.
+ *
+ * Provides configuration for Stellar transaction parameters:
+ * - Basic: Simple max fee configuration with reasonable defaults
+ * - Advanced: Full control over maxFee, validUntil, and feeBump options
+ *
+ * Stellar transactions have different parameters compared to EVM:
+ * - maxFee: Maximum fee willing to pay (in stroops)
+ * - validUntil: Transaction expiration time
+ * - feeBump: Enable fee bump for stuck transactions
+ */
+export const StellarRelayerOptions: React.FC<{
+  options: Record<string, unknown>;
+  onChange: (options: Record<string, unknown>) => void;
+}> = ({ options, onChange }) => {
+  const [showAdvancedInfo, setShowAdvancedInfo] = React.useState(false);
+
+  const { control, configMode, handleModeChange } = useStellarRelayerOptions({
+    options,
+    onChange,
+  });
+
+  return (
+    <div className="space-y-4">
+      <AdvancedInfo
+        showAdvancedInfo={showAdvancedInfo}
+        onToggle={() => setShowAdvancedInfo(!showAdvancedInfo)}
+      />
+
+      <Tabs value={configMode} onValueChange={handleModeChange}>
+        <TabsList className="grid w-full grid-cols-2">
+          <TabsTrigger value="basic">Basic</TabsTrigger>
+          <TabsTrigger value="advanced">Advanced</TabsTrigger>
+        </TabsList>
+
+        <TabsContent value="basic" className="space-y-4">
+          <FeeConfiguration control={control} showBasicFeeOnly={true} />
+        </TabsContent>
+
+        <TabsContent value="advanced" className="space-y-4">
+          <div className="space-y-6">
+            <FeeConfiguration control={control} showBasicFeeOnly={false} />
+
+            <TransactionTiming control={control} />
+          </div>
+        </TabsContent>
+      </Tabs>
+    </div>
+  );
+};

package/src/transaction/components/TransactionTiming.tsx

@@ -0,0 +1,77 @@
+import React from 'react';
+import { Control, Controller } from 'react-hook-form';
+
+import { Button, DateTimeField } from '@openzeppelin/ui-components';
+
+import type { StellarRelayerFormData } from './useStellarRelayerOptions';
+
+interface TransactionTimingProps {
+  control: Control<StellarRelayerFormData>;
+}
+
+export const TransactionTiming: React.FC<TransactionTimingProps> = ({ control }) => {
+  // Helper function to generate a datetime-local value for 1 hour from now
+  const getOneHourFromNow = () => {
+    const now = new Date();
+    now.setHours(now.getHours() + 1);
+    // Format for datetime-local input (YYYY-MM-DDTHH:mm)
+    return now.toISOString().slice(0, 16);
+  };
+
+  // Helper function to generate a datetime-local value for 24 hours from now
+  const getTwentyFourHoursFromNow = () => {
+    const now = new Date();
+    now.setHours(now.getHours() + 24);
+    return now.toISOString().slice(0, 16);
+  };
+
+  return (
+    <div className="space-y-4">
+      <DateTimeField
+        id="validUntil"
+        label="Transaction Expiration"
+        name="transactionOptions.validUntil"
+        control={control}
+        placeholder="YYYY-MM-DDTHH:mm"
+        helperText="Set when this transaction should expire. Leave empty for no expiration limit."
+      />
+      <div className="flex gap-2 pt-1">
+        <Controller
+          name="transactionOptions.validUntil"
+          control={control}
+          render={({ field }) => (
+            <>
+              <Button
+                type="button"
+                variant="outline"
+                size="sm"
+                onClick={() => field.onChange(new Date(getOneHourFromNow()).toISOString())}
+                className="text-xs"
+              >
+                +1 Hour
+              </Button>
+              <Button
+                type="button"
+                variant="outline"
+                size="sm"
+                onClick={() => field.onChange(new Date(getTwentyFourHoursFromNow()).toISOString())}
+                className="text-xs"
+              >
+                +24 Hours
+              </Button>
+              <Button
+                type="button"
+                variant="outline"
+                size="sm"
+                onClick={() => field.onChange('')}
+                className="text-xs"
+              >
+                Clear
+              </Button>
+            </>
+          )}
+        />
+      </div>
+    </div>
+  );
+};

package/src/transaction/components/index.ts

@@ -0,0 +1,5 @@
+export { StellarRelayerOptions } from './StellarRelayerOptions';
+export { useStellarRelayerOptions } from './useStellarRelayerOptions';
+export { AdvancedInfo } from './AdvancedInfo';
+export { FeeConfiguration } from './FeeConfiguration';
+export { TransactionTiming } from './TransactionTiming';

package/src/transaction/components/useStellarRelayerOptions.ts

@@ -0,0 +1,114 @@
+import { useEffect, useRef, useState } from 'react';
+import { useForm } from 'react-hook-form';
+
+import type { StellarRelayerTransactionOptions } from '../relayer';
+
+export interface StellarRelayerFormData {
+  transactionOptions: StellarRelayerTransactionOptions;
+}
+
+interface UseStellarRelayerOptionsProps {
+  options: Record<string, unknown>;
+  onChange: (options: Record<string, unknown>) => void;
+}
+
+export const useStellarRelayerOptions = ({ options, onChange }: UseStellarRelayerOptionsProps) => {
+  // Store the latest onChange callback in a ref to avoid dependency issues
+  const onChangeRef = useRef(onChange);
+  onChangeRef.current = onChange;
+
+  // Initialize form with options from parent (only on mount to prevent loops)
+  const initialOptions: StellarRelayerTransactionOptions = {
+    maxFee: options.maxFee as number | undefined,
+    validUntil: options.validUntil as string | undefined,
+    feeBump: options.feeBump as boolean | undefined,
+  };
+
+  const { control, setValue, watch } = useForm<StellarRelayerFormData>({
+    defaultValues: {
+      transactionOptions: initialOptions,
+    },
+  });
+
+  const formValues = watch('transactionOptions');
+  const isInitialMount = useRef(true);
+
+  // Track user's intended mode (separate from auto-detection)
+  const [userMode, setUserMode] = useState<'basic' | 'advanced'>(() => {
+    // Determine initial mode based on existing settings
+    const hasAdvancedSettings = Boolean(formValues.validUntil || formValues.feeBump);
+    return hasAdvancedSettings ? 'advanced' : 'basic';
+  });
+
+  const configMode = userMode;
+
+  // Handle initial mount - ensure any default values are communicated to parent
+  useEffect(() => {
+    if (isInitialMount.current) {
+      isInitialMount.current = false;
+      // No default values to set for Stellar (unlike EVM's Speed.FAST)
+      return;
+    }
+  }, []);
+
+  // Notify parent of changes after initial mount - watch specific fields
+  useEffect(() => {
+    if (isInitialMount.current) {
+      return;
+    }
+
+    const timeoutId = setTimeout(() => {
+      const newOptions: StellarRelayerTransactionOptions = {};
+
+      // Set maxFee if provided
+      if (formValues.maxFee !== undefined && formValues.maxFee !== null) {
+        newOptions.maxFee = formValues.maxFee;
+      }
+
+      // Set validUntil if provided (check for actual date string, not just truthy)
+      if (formValues.validUntil && formValues.validUntil.trim() !== '') {
+        newOptions.validUntil = formValues.validUntil;
+      }
+
+      // Set feeBump if enabled
+      if (formValues.feeBump !== undefined) {
+        newOptions.feeBump = formValues.feeBump;
+      }
+
+      // Soroban transactions do not support memos; do not propagate any
+
+      onChangeRef.current(newOptions as Record<string, unknown>);
+    }, 100);
+
+    return () => clearTimeout(timeoutId);
+  }, [formValues.maxFee, formValues.validUntil, formValues.feeBump]);
+
+  // Event handlers
+  const handleModeChange = (mode: string) => {
+    const newMode = mode as 'basic' | 'advanced';
+    setUserMode(newMode);
+
+    if (newMode === 'basic') {
+      // Reset advanced options when switching to basic mode
+      setValue('transactionOptions', {
+        ...formValues,
+        validUntil: undefined,
+        feeBump: undefined,
+      });
+    } else {
+      // When switching to advanced mode, keep existing values or set reasonable defaults
+      setValue('transactionOptions', {
+        ...formValues,
+        validUntil: formValues.validUntil || undefined,
+        feeBump: formValues.feeBump || false,
+      });
+    }
+  };
+
+  return {
+    control,
+    formValues,
+    configMode,
+    handleModeChange,
+  };
+};

package/src/transaction/eoa.ts

@@ -0,0 +1,229 @@
+import {
+  Account,
+  BASE_FEE,
+  Contract,
+  rpc as StellarRpc,
+  TransactionBuilder,
+} from '@stellar/stellar-sdk';
+
+import type {
+  ExecutionConfig,
+  StellarNetworkConfig,
+  TransactionStatusUpdate,
+  TxStatus,
+} from '@openzeppelin/ui-types';
+import { logger, userRpcConfigService } from '@openzeppelin/ui-utils';
+
+import { CALLER_PLACEHOLDER } from '../access-control/actions';
+import { valueToScVal } from '../transform/input-parser';
+import { getStellarWalletConnectionStatus, signTransaction } from '../wallet/connection';
+import { ExecutionStrategy } from './execution-strategy';
+import type { StellarTransactionData } from './formatter';
+
+const SYSTEM_LOG_TAG = 'EoaExecutionStrategy';
+
+/**
+ * Get Soroban RPC Server instance with proper configuration
+ */
+function getSorobanRpcServer(networkConfig: StellarNetworkConfig): StellarRpc.Server {
+  const customRpcConfig = userRpcConfigService.getUserRpcConfig(networkConfig.id);
+  const rpcUrl = customRpcConfig?.url || networkConfig.sorobanRpcUrl;
+
+  if (!rpcUrl) {
+    throw new Error(`No Soroban RPC URL available for network ${networkConfig.name}`);
+  }
+
+  // Allow HTTP for localhost development
+  const allowHttp = new URL(rpcUrl).hostname === 'localhost';
+
+  return new StellarRpc.Server(rpcUrl, {
+    allowHttp,
+  });
+}
+
+/**
+ * Implements the ExecutionStrategy for a standard Externally Owned Account (EOA).
+ * This strategy involves signing and broadcasting a transaction directly from the user's
+ * connected Stellar wallet, which is the most common way of interacting with Stellar/Soroban contracts.
+ */
+export class EoaExecutionStrategy implements ExecutionStrategy {
+  public async execute(
+    transactionData: StellarTransactionData,
+    executionConfig: ExecutionConfig,
+    networkConfig: StellarNetworkConfig,
+    onStatusChange: (status: TxStatus, details: TransactionStatusUpdate) => void,
+    // runtimeApiKey is unused in EOA strategy but required by the interface
+    _runtimeApiKey?: string
+  ): Promise<{ txHash: string }> {
+    logger.info(SYSTEM_LOG_TAG, 'Using Stellar EOA execution strategy');
+
+    // Validate execution config is for EOA
+    if (executionConfig.method !== 'eoa') {
+      throw new Error(`Expected EOA execution config, got: ${executionConfig.method}`);
+    }
+
+    return this.executeEoaTransaction(transactionData, networkConfig, onStatusChange);
+  }
+
+  private async executeEoaTransaction(
+    txData: StellarTransactionData,
+    stellarConfig: StellarNetworkConfig,
+    onStatusChange: (status: TxStatus, details: TransactionStatusUpdate) => void
+  ): Promise<{ txHash: string }> {
+    try {
+      // --- Step 1: Get RPC Server and Connected Wallet Address --- //
+      const rpcServer = getSorobanRpcServer(stellarConfig);
+      const connectedAddress = this.getConnectedWalletAddress();
+
+      logger.info(SYSTEM_LOG_TAG, `Connected address: ${connectedAddress}`);
+
+      // --- Step 2: Get Account Details --- //
+      let sourceAccount: Account;
+      try {
+        const accountResponse = await rpcServer.getAccount(connectedAddress);
+        sourceAccount = new Account(connectedAddress, accountResponse.sequenceNumber());
+      } catch (error) {
+        throw new Error(`Failed to load account details: ${(error as Error).message}`);
+      }
+
+      // --- Step 3: Build Transaction --- //
+      const contract = new Contract(txData.contractAddress);
+
+      const transactionBuilder = new TransactionBuilder(sourceAccount, {
+        fee: BASE_FEE,
+        networkPassphrase: stellarConfig.networkPassphrase,
+      });
+
+      // Replace CALLER_PLACEHOLDER with the connected wallet address
+      // This supports OpenZeppelin Stellar access control functions that require a caller parameter
+      const resolvedArgs = txData.args.map((arg) =>
+        arg === CALLER_PLACEHOLDER ? connectedAddress : arg
+      );
+
+      // Add the contract call operation (convert args to ScVal with comprehensive type support)
+      const scValArgs = resolvedArgs.map((arg, index) => {
+        const argType = txData.argTypes[index];
+        const argSchema = txData.argSchema?.[index]; // Pass schema for struct field type resolution
+
+        return valueToScVal(arg, argType, argSchema);
+      });
+
+      transactionBuilder.addOperation(contract.call(txData.functionName, ...scValArgs));
+
+      // Set timeout (default 30 seconds)
+      transactionBuilder.setTimeout(30);
+
+      let transaction = transactionBuilder.build();
+
+      // --- Step 4: Simulate Transaction First --- //
+      try {
+        const simulation = await rpcServer.simulateTransaction(transaction);
+
+        if (StellarRpc.Api.isSimulationError(simulation)) {
+          throw new Error(`Transaction simulation failed: ${simulation.error}`);
+        }
+
+        // Prepare the transaction with simulation results
+        transaction = await rpcServer.prepareTransaction(transaction);
+      } catch (error) {
+        throw new Error(`Transaction simulation/preparation failed: ${(error as Error).message}`);
+      }
+
+      onStatusChange('pendingSignature', {});
+
+      // --- Step 5: Sign Transaction --- //
+      try {
+        const signResult = await signTransaction(transaction.toXDR(), connectedAddress);
+        const signedTx = TransactionBuilder.fromXDR(
+          signResult.signedTxXdr,
+          stellarConfig.networkPassphrase
+        );
+
+        // Type guard to ensure we have a regular Transaction, not a FeeBumpTransaction
+        if ('memo' in signedTx && 'sequence' in signedTx) {
+          transaction = signedTx;
+        } else {
+          throw new Error('Unexpected transaction type returned from signing');
+        }
+      } catch (error) {
+        if ((error as Error).message.includes('User declined')) {
+          throw new Error('Transaction was rejected by user');
+        }
+        throw new Error(`Failed to sign transaction: ${(error as Error).message}`);
+      }
+
+      onStatusChange('pendingConfirmation', {});
+
+      // --- Step 6: Send Transaction --- //
+      let sendResult: StellarRpc.Api.SendTransactionResponse;
+      try {
+        sendResult = await rpcServer.sendTransaction(transaction);
+      } catch (error) {
+        throw new Error(`Failed to broadcast transaction: ${(error as Error).message}`);
+      }
+
+      if (sendResult.status !== 'PENDING') {
+        throw new Error(`Transaction failed to submit: ${sendResult.status}`);
+      }
+
+      const txHash = sendResult.hash;
+      logger.info(SYSTEM_LOG_TAG, `Transaction submitted successfully: ${txHash}`);
+
+      // Status remains 'pendingConfirmation' during confirmation wait
+
+      // --- Step 7: Wait for Confirmation --- //
+      try {
+        let txResponse;
+        const MAX_ATTEMPTS = 10;
+        let attempts = 0;
+
+        while (attempts++ < MAX_ATTEMPTS && txResponse?.status !== 'SUCCESS') {
+          await new Promise((resolve) => setTimeout(resolve, 1000));
+          txResponse = await rpcServer.getTransaction(txHash);
+
+          switch (txResponse.status) {
+            case 'FAILED':
+              throw new Error(`Transaction failed: ${JSON.stringify(txResponse.resultXdr)}`);
+            case 'NOT_FOUND':
+              continue;
+            case 'SUCCESS':
+              break;
+            default:
+            // Continue waiting
+          }
+        }
+
+        if (attempts >= MAX_ATTEMPTS || txResponse?.status !== 'SUCCESS') {
+          logger.warn(SYSTEM_LOG_TAG, `Transaction confirmation timeout for ${txHash}`);
+          // Don't throw error, just return the hash - transaction might still succeed
+        }
+      } catch (confirmError) {
+        // Log the error but don't fail the transaction - it was already submitted
+        logger.error(SYSTEM_LOG_TAG, 'Error waiting for confirmation:', confirmError);
+      }
+
+      onStatusChange('success', {
+        txHash,
+      });
+
+      return { txHash };
+    } catch (error) {
+      const errorMessage = `Failed to execute Stellar EOA transaction: ${(error as Error).message}`;
+      logger.error(SYSTEM_LOG_TAG, errorMessage, error);
+
+      onStatusChange('error', {});
+
+      throw new Error(errorMessage);
+    }
+  }
+
+  private getConnectedWalletAddress(): string {
+    const connectionStatus = getStellarWalletConnectionStatus();
+
+    if (!connectionStatus.isConnected || !connectionStatus.address) {
+      throw new Error('No connected wallet found. Please connect your Stellar wallet first.');
+    }
+
+    return connectionStatus.address;
+  }
+}

package/src/transaction/execution-strategy.ts

@@ -0,0 +1,33 @@
+import {
+  ExecutionConfig,
+  StellarNetworkConfig,
+  TransactionStatusUpdate,
+  TxStatus,
+} from '@openzeppelin/ui-types';
+
+import type { StellarTransactionData } from './formatter';
+
+/**
+ * Defines a common interface for different transaction execution strategies.
+ * 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 call parameters, including contract address, function name, and args.
+   * @param executionConfig The configuration for the selected execution method.
+   * @param networkConfig The Stellar network configuration to use for the transaction.
+   * @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: StellarTransactionData,
+    executionConfig: ExecutionConfig,
+    networkConfig: StellarNetworkConfig,
+    onStatusChange: (status: TxStatus, details: TransactionStatusUpdate) => void,
+    runtimeApiKey?: string
+  ): Promise<{ txHash: string }>;
+}