@openzeppelin/adapter-stellar 1.0.0

package/src/transaction/sender.ts

@@ -0,0 +1,156 @@
+import { rpc as StellarRpc } from '@stellar/stellar-sdk';
+
+import type {
+  ExecutionConfig,
+  StellarNetworkConfig,
+  TransactionStatusUpdate,
+  TxStatus,
+} from '@openzeppelin/ui-types';
+import { logger, userRpcConfigService } from '@openzeppelin/ui-utils';
+
+import { EoaExecutionStrategy } from './eoa';
+import { ExecutionStrategy } from './execution-strategy';
+import type { StellarTransactionData } from './formatter';
+import { RelayerExecutionStrategy } from './relayer';
+
+const SYSTEM_LOG_TAG = 'adapter-stellar';
+
+// --- Helper Functions ---
+
+/**
+ * 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,
+  });
+}
+
+/**
+ * Sign and broadcast a Stellar transaction using the strategy pattern.
+ * This follows the same architecture as the EVM adapter.
+ *
+ * @param transactionData - The formatted transaction data from formatStellarTransactionData
+ * @param executionConfig - Execution configuration specifying method (eoa, relayer, etc.)
+ * @param networkConfig - Stellar network configuration
+ * @param onStatusChange - Callback for status updates
+ * @param runtimeApiKey - Optional session-only API key for methods like Relayer
+ * @returns Promise resolving to the transaction hash
+ */
+export async function signAndBroadcastStellarTransaction(
+  transactionData: unknown,
+  executionConfig: ExecutionConfig,
+  networkConfig: StellarNetworkConfig,
+  onStatusChange?: (status: TxStatus, details: TransactionStatusUpdate) => void,
+  runtimeApiKey?: string
+): Promise<{ txHash: string }> {
+  logger.info(
+    SYSTEM_LOG_TAG,
+    'Stellar signAndBroadcast called with executionConfig:',
+    executionConfig
+  );
+
+  // Validate network config
+  if (!networkConfig || networkConfig.ecosystem !== 'stellar') {
+    throw new Error('Invalid Stellar network configuration provided.');
+  }
+
+  const txData = transactionData as StellarTransactionData;
+  let strategy: ExecutionStrategy;
+
+  // Select execution strategy based on method
+  switch (executionConfig.method) {
+    case 'eoa':
+      strategy = new EoaExecutionStrategy();
+      break;
+    case 'relayer':
+      strategy = new RelayerExecutionStrategy();
+      break;
+    case 'multisig':
+      // TODO: Implement MultisigExecutionStrategy when Stellar multisig support is added
+      throw new Error('Multisig execution method not yet implemented for Stellar.');
+    default: {
+      const exhaustiveCheck: never = executionConfig;
+      logger.error(SYSTEM_LOG_TAG, `Unsupported execution method encountered: ${exhaustiveCheck}`);
+      throw new Error(`Unsupported execution method: ${exhaustiveCheck}`);
+    }
+  }
+
+  return strategy.execute(
+    txData,
+    executionConfig,
+    networkConfig,
+    onStatusChange || (() => {}),
+    runtimeApiKey
+  );
+}
+
+/**
+ * Waits for a transaction to be confirmed on the blockchain.
+ *
+ * @param txHash - The hash of the transaction to wait for.
+ * @param networkConfig - The network configuration.
+ * @returns A promise resolving to the final status and receipt/error.
+ */
+export async function waitForStellarTransactionConfirmation(
+  txHash: string,
+  networkConfig: StellarNetworkConfig
+): Promise<{
+  status: 'success' | 'error';
+  receipt?: unknown;
+  error?: Error;
+}> {
+  try {
+    const rpcServer = getSorobanRpcServer(networkConfig);
+    const MAX_ATTEMPTS = 20; // More attempts for confirmation
+    let attempts = 0;
+
+    while (attempts++ < MAX_ATTEMPTS) {
+      try {
+        const txResponse = await rpcServer.getTransaction(txHash);
+
+        switch (txResponse.status) {
+          case 'SUCCESS':
+            return {
+              status: 'success',
+              receipt: txResponse,
+            };
+          case 'FAILED':
+            return {
+              status: 'error',
+              error: new Error(`Transaction failed: ${JSON.stringify(txResponse.resultXdr)}`),
+            };
+          case 'NOT_FOUND':
+            // Continue waiting
+            break;
+          default:
+          // Continue waiting for other statuses
+        }
+
+        await new Promise((resolve) => setTimeout(resolve, 1000));
+      } catch (error) {
+        logger.error('waitForStellarTransactionConfirmation', `Attempt ${attempts} failed:`, error);
+      }
+    }
+
+    return {
+      status: 'error',
+      error: new Error('Transaction confirmation timeout'),
+    };
+  } catch (error) {
+    return {
+      status: 'error',
+      error: error as Error,
+    };
+  }
+}

package/src/transform/index.ts

@@ -0,0 +1,4 @@
+// Barrel file
+
+export * from './input-parser';
+export * from './output-formatter';

package/src/transform/input-parser.ts

@@ -0,0 +1,9 @@
+// Re-export all types and functions for backward compatibility
+export type {
+  SorobanArgumentValue,
+  SorobanEnumValue,
+  SorobanMapEntry,
+  SorobanComplexValue,
+} from './parsers';
+
+export { parseStellarInput, getScValsFromArgs, valueToScVal } from './parsers';

package/src/transform/output-formatter.ts

@@ -0,0 +1,133 @@
+import { scValToNative, xdr } from '@stellar/stellar-sdk';
+
+import type { ContractFunction } from '@openzeppelin/ui-types';
+import { bytesToHex, logger } from '@openzeppelin/ui-utils';
+
+import { isSerializableObject, stringifyWithBigInt } from '../utils';
+
+/**
+ * Formats the result of a Stellar view function call into a user-friendly string.
+ *
+ * @param result The result value (can be ScVal, native JS value, or other types).
+ * @param functionDetails The contract function details.
+ * @returns A string representation suitable for display.
+ */
+export function formatStellarFunctionResult(
+  result: unknown,
+  functionDetails: ContractFunction
+): string {
+  if (!functionDetails.outputs || !Array.isArray(functionDetails.outputs)) {
+    logger.warn(
+      'formatStellarFunctionResult',
+      `Output definition missing or invalid for function ${functionDetails.name}.`
+    );
+    return '[Error: Output definition missing]';
+  }
+
+  try {
+    let valueToFormat: unknown;
+
+    // Handle null/undefined values
+    if (result === null || result === undefined) {
+      return '(null)';
+    }
+
+    // Check if result is an ScVal and convert to native JS value
+    if (isScVal(result)) {
+      try {
+        // Special handling for void ScVal
+        const scVal = result as xdr.ScVal;
+        if (scVal.switch().name === 'scvVoid') {
+          return '(void)';
+        }
+        valueToFormat = scValToNative(scVal);
+
+        // Convert Buffer to Uint8Array for cross-platform compatibility
+        // scValToNative may return Buffer objects in some environments
+        if (
+          valueToFormat &&
+          typeof valueToFormat === 'object' &&
+          'constructor' in valueToFormat &&
+          valueToFormat.constructor?.name === 'Buffer'
+        ) {
+          valueToFormat = new Uint8Array(valueToFormat as ArrayLike<number>);
+        }
+      } catch (error) {
+        logger.error('formatStellarFunctionResult', 'Failed to convert ScVal to native', {
+          functionName: functionDetails.name,
+          error,
+        });
+        return '[Error: Failed to decode ScVal]';
+      }
+    } else {
+      valueToFormat = result;
+    }
+
+    // Format based on type
+    if (typeof valueToFormat === 'bigint') {
+      return valueToFormat.toString();
+    } else if (typeof valueToFormat === 'string') {
+      return valueToFormat;
+    } else if (typeof valueToFormat === 'number') {
+      return valueToFormat.toString();
+    } else if (typeof valueToFormat === 'boolean') {
+      return String(valueToFormat);
+    } else if (valueToFormat instanceof Uint8Array) {
+      // Handle byte arrays - convert to hex string
+      return bytesToHex(valueToFormat, true);
+    } else if (Array.isArray(valueToFormat)) {
+      // Handle arrays/vectors
+      if (valueToFormat.length === 0) {
+        return '[]';
+      }
+      // Use compact formatting for simple arrays, pretty formatting for complex ones
+      if (
+        valueToFormat.every(
+          (item) =>
+            typeof item === 'string' ||
+            typeof item === 'number' ||
+            typeof item === 'boolean' ||
+            typeof item === 'bigint'
+        )
+      ) {
+        return stringifyWithBigInt(valueToFormat); // No spacing for simple arrays
+      }
+      return stringifyWithBigInt(valueToFormat, 2);
+    } else if (isSerializableObject(valueToFormat)) {
+      // Handle objects/maps/structs
+      if (Object.keys(valueToFormat as object).length === 0) {
+        return '{}';
+      }
+      return stringifyWithBigInt(valueToFormat, 2);
+    } else if (valueToFormat === null || valueToFormat === undefined) {
+      return '(null)';
+    } else {
+      // Handle any other type by stringifying
+      return stringifyWithBigInt(valueToFormat, 2);
+    }
+  } catch (error) {
+    const errorMessage = `Error formatting result for ${functionDetails.name}: ${(error as Error).message}`;
+    logger.error('formatStellarFunctionResult', errorMessage, {
+      functionName: functionDetails.name,
+      result,
+      error,
+    });
+    return `[${errorMessage}]`;
+  }
+}
+
+/**
+ * Type guard to check if a value is an ScVal
+ */
+function isScVal(value: unknown): boolean {
+  if (!value || typeof value !== 'object') {
+    return false;
+  }
+
+  try {
+    // Use instanceof check for robust type detection
+    return typeof xdr !== 'undefined' && xdr.ScVal && value instanceof xdr.ScVal;
+  } catch {
+    return false;
+  }
+}

package/src/transform/parsers/complex-parser.ts

@@ -0,0 +1,157 @@
+import { nativeToScVal, xdr } from '@stellar/stellar-sdk';
+
+import { detectBytesEncoding, stringToBytes } from '@openzeppelin/ui-utils';
+
+import { convertStellarTypeToScValType } from '../../utils/formatting';
+import {
+  convertEnumToScVal,
+  convertObjectToMap,
+  convertObjectToScVal,
+  convertTupleToScVal,
+  getScValFromArg,
+  getScValFromPrimitive,
+  isComplexObjectArray,
+  isEnumArgumentSet,
+  isMapArray,
+  isObjectWithTypedValues,
+  isPrimitiveArgumentSet,
+  isPrimitiveArray,
+  isPrimitiveValue,
+  isTupleArray,
+} from '../../utils/input-parsing';
+import type {
+  SorobanArgumentValue,
+  SorobanComplexValue,
+  SorobanEnumValue,
+  SorobanMapEntry,
+} from './types';
+
+/**
+ * Advanced ScVal generation from complex Soroban arguments.
+ * Handles Maps, Enums, Tuples, and nested structures.
+ *
+ * @param args - Complex argument structure from advanced UI forms
+ * @param scVals - Accumulator for generated ScVals (used for recursion)
+ * @returns Array of ScVals ready for contract invocation
+ */
+export function getScValsFromArgs(
+  args: Record<string, SorobanComplexValue> | SorobanComplexValue[],
+  scVals: xdr.ScVal[] = []
+): xdr.ScVal[] {
+  // Handle array input (multiple arguments)
+  if (Array.isArray(args)) {
+    return args.map((arg) => {
+      if (typeof arg === 'object' && 'value' in arg && 'type' in arg) {
+        return getScValFromPrimitive(arg as SorobanArgumentValue);
+      }
+      return getScValFromArg(arg, []);
+    });
+  }
+
+  // Handle primitive case - all values have type and value
+  if (isPrimitiveArgumentSet(args)) {
+    const primitiveScVals = Object.values(args).map((v) => {
+      return getScValFromPrimitive(v as SorobanArgumentValue);
+    });
+
+    return primitiveScVals;
+  }
+
+  // Handle enum case - values have tag or enum properties
+  if (isEnumArgumentSet(args)) {
+    const enumScVals = Object.values(args).map((v) => {
+      return convertEnumToScVal(v as SorobanEnumValue, scVals);
+    });
+
+    return enumScVals;
+  }
+
+  // Handle complex cases (maps, objects, arrays)
+  for (const argKey in args) {
+    const argValue = args[argKey];
+
+    if (Array.isArray(argValue)) {
+      // Map case - array of key-value pair objects
+      if (isMapArray(argValue)) {
+        const { mapVal, mapType } = convertObjectToMap(argValue as SorobanMapEntry[]);
+        const mapScVal = nativeToScVal(mapVal, { type: mapType });
+        scVals.push(mapScVal);
+        continue;
+      }
+
+      // Vector case #1: array of complex objects or tuples
+      if (isComplexObjectArray(argValue)) {
+        const arrayScVals = argValue.map((v) => {
+          // Use proper type guards to ensure safe casting
+          if (typeof v === 'object' && v !== null && ('tag' in v || 'enum' in v)) {
+            return convertEnumToScVal(v as SorobanEnumValue, scVals);
+          }
+          if (
+            typeof v === 'object' &&
+            v !== null &&
+            !Array.isArray(v) &&
+            !('0' in v) &&
+            !('1' in v)
+          ) {
+            return convertObjectToScVal(v as Record<string, SorobanArgumentValue>);
+          }
+          // Fallback for other types
+          return nativeToScVal(v);
+        });
+
+        const tupleScValsVec = xdr.ScVal.scvVec(arrayScVals);
+        scVals.push(tupleScValsVec);
+        continue;
+      }
+
+      // Vector case #2: array of primitives (homogeneous type)
+      if (isPrimitiveArray(argValue)) {
+        // TypeScript now knows argValue is SorobanArgumentValue[] thanks to type predicate
+        const arrayScVals = argValue.reduce((acc: unknown[], v) => {
+          const primitive = v as unknown as SorobanArgumentValue;
+          if (primitive.type === 'bool') {
+            acc.push(primitive.value === 'true' ? true : false);
+          } else if (primitive.type === 'bytes') {
+            const encoding = detectBytesEncoding(primitive.value as string);
+            acc.push(stringToBytes(primitive.value as string, encoding));
+          } else {
+            acc.push(primitive.value);
+          }
+          return acc;
+        }, []);
+
+        const firstItem = argValue[0];
+        const scValType = convertStellarTypeToScValType(firstItem.type);
+        const typeHint = Array.isArray(scValType) ? scValType[0] : scValType;
+        const scVal = nativeToScVal(arrayScVals, {
+          type: typeHint,
+        });
+
+        scVals.push(scVal);
+        continue;
+      }
+
+      // Tuple case - mixed types in array
+      if (isTupleArray(argValue)) {
+        // TypeScript now knows argValue is SorobanArgumentValue[] thanks to type predicate
+        const tupleScValsVec = convertTupleToScVal(argValue);
+        scVals.push(tupleScValsVec);
+        continue;
+      }
+    }
+
+    // Object case - structured data
+    if (isObjectWithTypedValues(argValue)) {
+      const convertedObj = convertObjectToScVal(argValue as Record<string, SorobanArgumentValue>);
+      scVals.push(convertedObj);
+      continue;
+    }
+
+    // Single primitive value
+    if (isPrimitiveValue(argValue)) {
+      scVals.push(getScValFromPrimitive(argValue as SorobanArgumentValue));
+    }
+  }
+
+  return scVals;
+}

package/src/transform/parsers/generic-parser.ts

@@ -0,0 +1,171 @@
+import { isMapEntryArray } from '@openzeppelin/ui-types';
+import { logger } from '@openzeppelin/ui-utils';
+
+const SYSTEM_LOG_TAG = 'GenericParser';
+
+/**
+ * Parses a generic type string and extracts the base type and parameters
+ * @param typeString - Type like "Vec<U32>", "Map<U32,Address>", "Option<Vec<U32>>"
+ * @returns Object with baseType and parameters, or null if not generic
+ */
+export function parseGenericType(typeString: string): {
+  baseType: string;
+  parameters: string[];
+} | null {
+  const match = typeString.match(/^(\w+)<(.*)>$/);
+  if (!match) return null;
+
+  const baseType = match[1];
+  const paramString = match[2];
+
+  // Handle nested generics by counting angle brackets
+  const parameters: string[] = [];
+  let current = '';
+  let depth = 0;
+  let i = 0;
+
+  while (i < paramString.length) {
+    const char = paramString[i];
+
+    if (char === '<') {
+      depth++;
+      current += char;
+    } else if (char === '>') {
+      depth--;
+      current += char;
+    } else if (char === ',' && depth === 0) {
+      parameters.push(current.trim());
+      current = '';
+    } else {
+      current += char;
+    }
+    i++;
+  }
+
+  if (current.trim()) {
+    parameters.push(current.trim());
+  }
+
+  return { baseType, parameters };
+}
+
+/**
+ * Parses generic types like Vec<T>, Map<K,V>, and Option<T>.
+ *
+ * @param value - The input value from the form
+ * @param parameterType - The generic parameter type (e.g., 'Vec<U32>', 'Map<Symbol,Bytes>')
+ * @param parseInnerValue - Function to recursively parse inner values
+ * @returns The parsed value suitable for further processing
+ */
+export function parseGeneric(
+  value: unknown,
+  parameterType: string,
+  parseInnerValue: (val: unknown, type: string) => unknown
+): unknown {
+  try {
+    const genericInfo = parseGenericType(parameterType);
+    if (!genericInfo) {
+      return null; // Not a generic type
+    }
+
+    const { baseType, parameters } = genericInfo;
+
+    switch (baseType) {
+      case 'Vec': {
+        // Handle Vec<T> types
+        if (!Array.isArray(value)) {
+          throw new Error(`Array expected for Vec type ${parameterType}, got ${typeof value}`);
+        }
+
+        const innerType = parameters[0];
+        if (!innerType) {
+          throw new Error(`Could not parse Vec inner type: ${parameterType}`);
+        }
+
+        return value.map((item) => parseInnerValue(item, innerType));
+      }
+
+      case 'Map': {
+        // Handle Map<K,V> types
+        if (!isMapEntryArray(value)) {
+          throw new Error(`Array of MapEntry objects expected for Map type, got ${typeof value}`);
+        }
+
+        if (parameters.length < 2) {
+          throw new Error(`Could not parse Map types: ${parameterType}`);
+        }
+
+        const mapKeyType = parameters[0];
+        const mapValueType = parameters[1];
+
+        // Convert MapEntry array to Stellar SDK expected format
+        return value.map((entry) => ({
+          0: {
+            value: entry.key,
+            type: mapKeyType,
+          },
+          1: {
+            value: entry.value,
+            type: mapValueType,
+          },
+        }));
+      }
+
+      case 'Option': {
+        // Handle Option<T> types - empty string should be treated as null
+        if (value === null || value === undefined || value === '') {
+          return null;
+        }
+
+        const innerType = parameters[0];
+        if (!innerType) {
+          throw new Error(`Could not parse Option inner type: ${parameterType}`);
+        }
+
+        return parseInnerValue(value, innerType);
+      }
+
+      case 'Result': {
+        // Handle Result<T,E> types (basic support)
+        if (parameters.length < 2) {
+          throw new Error(`Could not parse Result types: ${parameterType}`);
+        }
+
+        // Result types typically come as {ok: value} or {err: error}
+        if (typeof value === 'object' && value !== null) {
+          const resultObj = value as Record<string, unknown>;
+          if ('ok' in resultObj) {
+            return {
+              ok: parseInnerValue(resultObj.ok, parameters[0]),
+            };
+          } else if ('err' in resultObj) {
+            return {
+              err: parseInnerValue(resultObj.err, parameters[1]),
+            };
+          }
+        }
+
+        return value; // Pass through if not in expected format
+      }
+
+      default:
+        // Unknown generic type
+        logger.warn(SYSTEM_LOG_TAG, `Unknown generic type: ${baseType}`);
+        return null;
+    }
+  } catch (error) {
+    logger.error(SYSTEM_LOG_TAG, `Failed to parse generic type ${parameterType}:`, error);
+    throw error;
+  }
+}
+
+/**
+ * Checks if the given parameter type is a generic type that can be handled by this parser.
+ *
+ * @param parameterType - The Stellar parameter type
+ * @returns True if this is a generic type
+ */
+export function isGenericType(parameterType: string): boolean {
+  const genericInfo = parseGenericType(parameterType);
+  return genericInfo !== null && ['Vec', 'Map', 'Option', 'Result'].includes(genericInfo.baseType);
+}