@openzeppelin/adapter-stellar 1.0.0

package/src/mapping/enum-metadata.ts

@@ -0,0 +1,237 @@
+import { xdr } from '@stellar/stellar-sdk';
+
+import type { FunctionParameter } from '@openzeppelin/ui-types';
+import { logger } from '@openzeppelin/ui-utils';
+
+// Import the type extraction utility from the shared utils module
+import { extractSorobanTypeFromScSpec } from '../utils/type-detection';
+import { extractStructFields, isStructType } from './struct-fields';
+import { buildTupleComponents } from './tuple-components';
+
+/**
+ * Represents a single enum variant with its type and optional payload information
+ */
+export interface EnumVariant {
+  /** Name of the variant (e.g., 'One', 'Two', 'Three') */
+  name: string;
+  /** Type of variant: 'void' for unit variants, 'tuple' for variants with payload, 'integer' for numeric enums */
+  type: 'void' | 'tuple' | 'integer';
+  /** For tuple variants: array of payload type names (e.g., ['U32', 'ScString']) */
+  payloadTypes?: string[];
+  /** Optional detailed component metadata for payload types */
+  payloadComponents?: (FunctionParameter[] | undefined)[];
+  /** For integer variants: the numeric value */
+  value?: number;
+  /** Flag indicating if this variant has a single Tuple payload that needs wrapping during serialization */
+  isSingleTuplePayload?: boolean;
+}
+
+/**
+ * Metadata about an enum extracted from Stellar contract spec
+ */
+export interface EnumMetadata {
+  /** Name of the enum type */
+  name: string;
+  /** Array of variants in the enum */
+  variants: EnumVariant[];
+  /** True if all variants are unit variants (no payloads), suitable for simple select/radio */
+  isUnitOnly: boolean;
+}
+
+/**
+ * Helper function to flatten a single payload type.
+ * Handles tuples, structs, and primitive types differently.
+ *
+ * @param payloadType - The type to flatten
+ * @param entries - Spec entries for struct/enum resolution
+ * @param flattenedTypes - Array to accumulate flattened type names
+ * @param flattenedComponents - Array to accumulate component metadata
+ */
+function flattenPayloadType(
+  payloadType: string,
+  entries: xdr.ScSpecEntry[],
+  flattenedTypes: string[],
+  flattenedComponents: (FunctionParameter[] | undefined)[]
+): void {
+  if (payloadType.startsWith('Tuple<')) {
+    // Extract tuple components and add them individually for UI rendering
+    const tupleComponents = buildTupleComponents(payloadType, entries);
+    if (tupleComponents && tupleComponents.length > 0) {
+      tupleComponents.forEach((component) => {
+        flattenedTypes.push(component.type);
+        if (isStructType(entries, component.type)) {
+          flattenedComponents.push(extractStructFields(entries, component.type) ?? undefined);
+        } else {
+          flattenedComponents.push(component.components);
+        }
+      });
+    } else {
+      flattenedTypes.push(payloadType);
+      flattenedComponents.push(undefined);
+    }
+  } else if (isStructType(entries, payloadType)) {
+    flattenedTypes.push(payloadType);
+    flattenedComponents.push(extractStructFields(entries, payloadType) ?? undefined);
+  } else {
+    flattenedTypes.push(payloadType);
+    flattenedComponents.push(undefined);
+  }
+}
+
+/**
+ * Extracts enum variant metadata from Stellar contract spec entries
+ *
+ * @param entries Array of ScSpecEntry from contract spec
+ * @param enumName Name of the enum type to extract variants for
+ * @returns EnumMetadata if found, null if not found or not an enum
+ */
+export function extractEnumVariants(
+  entries: xdr.ScSpecEntry[],
+  enumName: string
+): EnumMetadata | null {
+  try {
+    // Find the entry for the requested enum name
+    const entry = entries.find((e) => {
+      try {
+        return e.value().name().toString() === enumName;
+      } catch {
+        return false;
+      }
+    });
+
+    if (!entry) {
+      return null;
+    }
+
+    const entryKind = entry.switch();
+
+    // Handle UDT Union (tagged union enum like DemoEnum { One, Two(u32), Three(String) })
+    if (entryKind.value === xdr.ScSpecEntryKind.scSpecEntryUdtUnionV0().value) {
+      const unionUdt = entry.udtUnionV0();
+      const cases = unionUdt.cases();
+      const variants: EnumVariant[] = [];
+      let isUnitOnly = true;
+
+      for (const caseEntry of cases) {
+        const caseKind = caseEntry.switch();
+
+        if (caseKind.value === xdr.ScSpecUdtUnionCaseV0Kind.scSpecUdtUnionCaseVoidV0().value) {
+          // Void case (unit variant)
+          const voidCase = caseEntry.voidCase();
+          variants.push({
+            name: voidCase.name().toString(),
+            type: 'void',
+          });
+        } else if (
+          caseKind.value === xdr.ScSpecUdtUnionCaseV0Kind.scSpecUdtUnionCaseTupleV0().value
+        ) {
+          // Tuple case (variant with payload)
+          const tupleCase = caseEntry.tupleCase();
+          const rawPayloadTypes = tupleCase
+            .type()
+            .map((typeDef) => extractSorobanTypeFromScSpec(typeDef));
+
+          // Track if we have a single Tuple payload that needs special handling
+          const isSingleTuplePayload =
+            rawPayloadTypes.length === 1 && rawPayloadTypes[0].startsWith('Tuple<');
+
+          // Flatten tuple payloads for UI rendering
+          // Example: Some((Address, i128)) → payloadTypes: ['Address', 'I128'] for UI
+          // But we keep the original structure info for serialization
+          const flattenedPayloadTypes: string[] = [];
+          const flattenedPayloadComponents: (FunctionParameter[] | undefined)[] = [];
+
+          for (const payloadType of rawPayloadTypes) {
+            flattenPayloadType(
+              payloadType,
+              entries,
+              flattenedPayloadTypes,
+              flattenedPayloadComponents
+            );
+          }
+
+          variants.push({
+            name: tupleCase.name().toString(),
+            type: 'tuple',
+            payloadTypes: flattenedPayloadTypes,
+            ...(flattenedPayloadComponents.some(
+              (components) => components && components.length > 0
+            ) && {
+              payloadComponents: flattenedPayloadComponents,
+            }),
+            // Store metadata about whether this needs tuple wrapping during serialization
+            ...(isSingleTuplePayload && { isSingleTuplePayload: true }),
+          });
+          isUnitOnly = false;
+        }
+      }
+
+      return {
+        name: enumName,
+        variants,
+        isUnitOnly,
+      };
+    }
+
+    // Handle UDT Enum (integer enum like Priority { Low = 0, Medium = 1, High = 2 })
+    if (entryKind.value === xdr.ScSpecEntryKind.scSpecEntryUdtEnumV0().value) {
+      const enumUdt = entry.udtEnumV0();
+      const cases = enumUdt.cases();
+      const variants: EnumVariant[] = [];
+
+      for (const caseEntry of cases) {
+        variants.push({
+          name: caseEntry.name().toString(),
+          type: 'integer',
+          value: caseEntry.value(),
+        });
+      }
+
+      return {
+        name: enumName,
+        variants,
+        isUnitOnly: true, // Integer enums are considered unit-only for UI purposes
+      };
+    }
+
+    return null;
+  } catch (error) {
+    logger.error('extractEnumVariants', `Failed to extract enum variants for ${enumName}:`, error);
+    return null;
+  }
+}
+
+/**
+ * Checks if a parameter type name refers to a user-defined enum/union type
+ * by looking for it in the contract spec entries
+ *
+ * @param entries Array of ScSpecEntry from contract spec
+ * @param typeName Name of the type to check
+ * @returns true if the type is a UDT enum or union
+ */
+export function isEnumType(entries: xdr.ScSpecEntry[], typeName: string): boolean {
+  try {
+    const entry = entries.find((e) => {
+      try {
+        const entryName = e.value().name().toString();
+        return entryName === typeName;
+      } catch {
+        return false;
+      }
+    });
+
+    if (!entry) {
+      return false;
+    }
+
+    const entryKind = entry.switch();
+    const isEnum =
+      entryKind.value === xdr.ScSpecEntryKind.scSpecEntryUdtUnionV0().value ||
+      entryKind.value === xdr.ScSpecEntryKind.scSpecEntryUdtEnumV0().value;
+
+    return isEnum;
+  } catch (error) {
+    logger.error('isEnumType', `Failed to check if ${typeName} is enum:`, error);
+    return false;
+  }
+}

package/src/mapping/field-generator.ts

@@ -0,0 +1,296 @@
+import { xdr } from '@stellar/stellar-sdk';
+import { startCase } from 'lodash';
+
+import type {
+  ContractSchema,
+  FieldType,
+  FieldValidation,
+  FieldValue,
+  FormFieldType,
+  FunctionParameter,
+} from '@openzeppelin/ui-types';
+import {
+  enhanceNumericValidation,
+  getDefaultValueForType,
+  logger,
+  type NumericBoundsMap,
+} from '@openzeppelin/ui-utils';
+
+import { extractMapTypes, extractVecElementType } from '../utils/safe-type-parser';
+import { isBytesNType, isLikelyEnumType } from '../utils/type-detection';
+import { extractEnumVariants, isEnumType, type EnumMetadata } from './enum-metadata';
+import { extractStructFields, isStructType } from './struct-fields';
+import { buildTupleComponents } from './tuple-components';
+import { mapStellarParameterTypeToFieldType } from './type-mapper';
+
+/**
+ * Get default validation rules for a parameter type.
+ * Only includes serializable validation rules - no custom functions.
+ */
+function getDefaultValidationForType(): FieldValidation {
+  return { required: true };
+}
+
+/**
+ * Stellar/Soroban numeric type bounds.
+ * Maps Stellar type names to their min/max value constraints.
+ *
+ * Note: U64, U128, U256, I64, I128, and I256 are not included here because they exceed
+ * JavaScript's Number.MAX_SAFE_INTEGER (2^53 - 1). These types are mapped to 'bigint' field type
+ * and handle validation through BigIntField component's internal validation mechanism.
+ */
+const STELLAR_NUMERIC_BOUNDS: NumericBoundsMap = {
+  U8: { min: 0, max: 255 },
+  U16: { min: 0, max: 65_535 },
+  U32: { min: 0, max: 4_294_967_295 },
+  I8: { min: -128, max: 127 },
+  I16: { min: -32_768, max: 32_767 },
+  I32: { min: -2_147_483_648, max: 2_147_483_647 },
+};
+
+/**
+ * Generate default form configuration for a Stellar function parameter. Supports:
+ * - WASM artifacts: parameters arrive with baked-in enum metadata and struct components.
+ * - SAC runtime specs: metadata is fetched on demand, so we reconstruct the same shape from
+ *   `metadata.specEntries` to keep the UI identical across contract types.
+ */
+export function generateStellarDefaultField<T extends FieldType = FieldType>(
+  parameter: FunctionParameter,
+  contractSchema?: ContractSchema
+): FormFieldType<T> {
+  // Extract spec entries from contract schema metadata if available
+  const specEntries = contractSchema?.metadata?.specEntries as xdr.ScSpecEntry[] | undefined;
+  const fieldType = mapStellarParameterTypeToFieldType(parameter.type) as T;
+
+  // Debug logging for unmapped types
+  if (parameter.type === 'unknown') {
+    logger.warn(
+      'adapter-stellar',
+      `[generateStellarDefaultField] Parameter "${parameter.name}" has type "unknown"`
+    );
+  }
+
+  let enumMetadata: EnumMetadata | null = null;
+  // WASM artifacts still include `components` on struct inputs because we bake them during
+  // the build step. SAC contracts fetch their spec at runtime, so struct parameters show up
+  // without that data. Cache whatever the SAC spec gives us so the final field mirrors the
+  // WASM experience.
+  let structComponents: FunctionParameter[] | null = null;
+  let finalFieldType = fieldType;
+  let options: { label: string; value: string }[] | undefined;
+
+  // Check if this parameter is an enum type (by spec or heuristic) and extract metadata
+  const enumDetectedBySpec = !!(specEntries && isEnumType(specEntries, parameter.type));
+  const enumDetectedHeuristic = isLikelyEnumType(parameter.type);
+  if (enumDetectedBySpec || enumDetectedHeuristic) {
+    if (enumDetectedBySpec) {
+      // We have spec entries, extract full metadata
+      enumMetadata = extractEnumVariants(specEntries!, parameter.type);
+      if (enumMetadata) {
+        if (enumMetadata.isUnitOnly) {
+          // Unit-only enums can use select/radio with options
+          finalFieldType = 'select' as T;
+          options = enumMetadata.variants.map((variant) => ({
+            label: variant.name,
+            value: variant.type === 'integer' ? variant.value!.toString() : variant.name,
+          }));
+        } else {
+          // Tagged enums with payloads use the composite enum field
+          finalFieldType = 'enum' as T;
+        }
+      }
+    } else {
+      // No spec entries available, but type looks like enum - use enum field as fallback
+      finalFieldType = 'enum' as T;
+      // Create minimal enum metadata for fallback
+      enumMetadata = {
+        name: parameter.type,
+        variants: [], // Empty variants will trigger fallback UI
+        isUnitOnly: false,
+      };
+    }
+  }
+
+  // Same story here: WASM schemas already embed struct components, but SAC schemas only
+  // expose them inside the downloaded spec. Pull them out up front so the UI sees the
+  // same shape regardless of how the metadata was sourced.
+  if (specEntries && isStructType(specEntries, parameter.type)) {
+    const structFields = extractStructFields(specEntries, parameter.type);
+    if (structFields && structFields.length > 0) {
+      structComponents = structFields;
+    }
+  }
+
+  if (!structComponents) {
+    const tupleComponents = buildTupleComponents(parameter.type, specEntries);
+    if (tupleComponents && tupleComponents.length > 0) {
+      structComponents = tupleComponents;
+    }
+  }
+
+  const baseField: FormFieldType<T> = {
+    id: `field-${Math.random().toString(36).substring(2, 9)}`,
+    name: parameter.name || parameter.type, // Use type if name missing
+    label: startCase(parameter.displayName || parameter.name || parameter.type),
+    type: finalFieldType,
+    placeholder: enumMetadata
+      ? `Select ${parameter.displayName || parameter.name || parameter.type}`
+      : `Enter ${parameter.displayName || parameter.name || parameter.type}`,
+    helperText: parameter.description || '',
+    defaultValue: getDefaultValueForType(finalFieldType) as FieldValue<T>,
+    validation: getDefaultValidationForType(),
+    width: 'full',
+    options,
+  };
+
+  baseField.validation = enhanceNumericValidation(
+    baseField.validation,
+    parameter.type,
+    STELLAR_NUMERIC_BOUNDS
+  );
+
+  // Propagate max byte length for BytesN types so the UI can enforce it
+  if (isBytesNType(parameter.type)) {
+    const sizeMatch = parameter.type.match(/^BytesN<(\d+)>$/);
+    const maxBytes = sizeMatch ? Number.parseInt(sizeMatch[1], 10) : undefined;
+
+    if (!Number.isNaN(maxBytes) && Number.isFinite(maxBytes)) {
+      baseField.metadata = {
+        ...(baseField.metadata ?? {}),
+        maxBytes,
+      };
+    }
+  }
+
+  // For array types (including arrays of complex types), provide element type information
+  if (fieldType === 'array' || fieldType === 'array-object') {
+    const elementType = extractVecElementType(parameter.type);
+    if (elementType) {
+      const elementFieldType = mapStellarParameterTypeToFieldType(elementType);
+
+      // Check if the element type is an enum or struct and needs additional metadata
+      let elementEnumMetadata: EnumMetadata | undefined;
+      let elementComponents: FunctionParameter[] | undefined;
+      let finalElementFieldType = elementFieldType;
+
+      // Extract enum metadata for array elements
+      if (isLikelyEnumType(elementType)) {
+        if (specEntries && isEnumType(specEntries, elementType)) {
+          elementEnumMetadata = extractEnumVariants(specEntries, elementType) ?? undefined;
+          if (elementEnumMetadata) {
+            // Override field type based on enum characteristics
+            finalElementFieldType = elementEnumMetadata.isUnitOnly ? 'select' : 'enum';
+          }
+        }
+      }
+
+      // Extract struct components for array elements
+      if (specEntries && isStructType(specEntries, elementType)) {
+        const structFields = extractStructFields(specEntries, elementType);
+        if (structFields && structFields.length > 0) {
+          elementComponents = structFields;
+          finalElementFieldType = 'object';
+        }
+      }
+
+      // For array-object, if we have components from the parameter, use them
+      if (fieldType === 'array-object' && parameter.components) {
+        elementComponents = parameter.components;
+        finalElementFieldType = 'object';
+      }
+
+      // Build element validation with bounds
+      let elementValidation: FieldValidation = { required: true };
+      elementValidation = enhanceNumericValidation(
+        elementValidation,
+        elementType,
+        STELLAR_NUMERIC_BOUNDS
+      );
+
+      // Add array-specific properties with full element metadata
+      const arrayField = {
+        ...baseField,
+        type: 'array' as FieldType, // Always use 'array' as the field type
+        elementType: finalElementFieldType,
+        elementFieldConfig: {
+          type: finalElementFieldType,
+          validation: elementValidation,
+          placeholder: `Enter ${elementType}`,
+          originalParameterType: elementType,
+          ...(elementEnumMetadata && { enumMetadata: elementEnumMetadata }),
+          ...(elementComponents && { components: elementComponents }),
+        },
+      };
+      return arrayField as unknown as FormFieldType<T>;
+    }
+  }
+
+  // For map types, provide key and value type information
+  if (fieldType === ('map' as FieldType)) {
+    const mapTypes = extractMapTypes(parameter.type);
+    if (mapTypes) {
+      const keyFieldType = mapStellarParameterTypeToFieldType(mapTypes.keyType);
+      const valueFieldType = mapStellarParameterTypeToFieldType(mapTypes.valueType);
+
+      // Add map-specific properties
+      const mapField = {
+        ...baseField,
+        mapMetadata: {
+          keyType: keyFieldType,
+          valueType: valueFieldType,
+          keyFieldConfig: {
+            type: keyFieldType,
+            validation: enhanceNumericValidation(
+              { required: true },
+              mapTypes.keyType,
+              STELLAR_NUMERIC_BOUNDS
+            ),
+            placeholder: `Enter ${mapTypes.keyType}`,
+            originalParameterType: mapTypes.keyType,
+          },
+          valueFieldConfig: {
+            type: valueFieldType,
+            validation: enhanceNumericValidation(
+              { required: true },
+              mapTypes.valueType,
+              STELLAR_NUMERIC_BOUNDS
+            ),
+            placeholder: `Enter ${mapTypes.valueType}`,
+            originalParameterType: mapTypes.valueType,
+          },
+        },
+        validation: {
+          ...getDefaultValidationForType(),
+          min: 0,
+          // No max limit - users can add as many map entries as needed
+        },
+      };
+      return mapField;
+    }
+  }
+
+  // Preserve components for object and array-object types
+  if (fieldType === 'object' || fieldType === 'array-object') {
+    const componentsToUse = parameter.components || structComponents;
+    if (componentsToUse) {
+      // Prefer the baked-in WASM components, otherwise fall back to the SAC-derived
+      // components we cached above.
+      const result = {
+        ...baseField,
+        components: componentsToUse,
+      };
+      return result;
+    }
+  }
+
+  // Add enum metadata if available
+  if (enumMetadata) {
+    const result = {
+      ...baseField,
+      enumMetadata,
+    };
+    return result;
+  }
+
+  return baseField;
+}

package/src/mapping/index.ts

@@ -0,0 +1,5 @@
+// Barrel file
+
+export * from './constants';
+export * from './type-mapper';
+export * from './field-generator';

package/src/mapping/struct-fields.ts

@@ -0,0 +1,106 @@
+import { xdr } from '@stellar/stellar-sdk';
+
+import type { FunctionParameter } from '@openzeppelin/ui-types';
+import { logger } from '@openzeppelin/ui-utils';
+
+// Import the type extraction utility from the shared utils module
+import { extractSorobanTypeFromScSpec } from '../utils/type-detection';
+
+/**
+ * Extracts struct field definitions from Stellar contract spec entries
+ *
+ * @param entries Array of ScSpecEntry from contract spec
+ * @param structName Name of the struct type to extract fields for
+ * @returns Array of FunctionParameter representing struct fields, or null if not found
+ */
+export function extractStructFields(
+  entries: xdr.ScSpecEntry[],
+  structName: string
+): FunctionParameter[] | null {
+  try {
+    // Find the entry for the requested struct name
+    const entry = entries.find((e) => {
+      try {
+        return e.value().name().toString() === structName;
+      } catch {
+        return false;
+      }
+    });
+
+    if (!entry) {
+      return null;
+    }
+
+    const entryKind = entry.switch();
+
+    // Handle UDT Struct (like DemoStruct { id: u32, flag: bool, info: Symbol })
+    if (entryKind.value === xdr.ScSpecEntryKind.scSpecEntryUdtStructV0().value) {
+      const structUdt = entry.udtStructV0();
+      const fields = structUdt.fields();
+      const structFields: FunctionParameter[] = [];
+
+      for (const field of fields) {
+        const fieldName = field.name().toString();
+        const fieldType = extractSorobanTypeFromScSpec(field.type());
+
+        const fieldParam: FunctionParameter = {
+          name: fieldName,
+          type: fieldType,
+        };
+
+        // Recursively extract nested struct components
+        if (isStructType(entries, fieldType)) {
+          const nestedFields = extractStructFields(entries, fieldType);
+          if (nestedFields && nestedFields.length > 0) {
+            fieldParam.components = nestedFields;
+          }
+        }
+
+        structFields.push(fieldParam);
+      }
+
+      return structFields;
+    }
+
+    return null;
+  } catch (error) {
+    logger.error(
+      'extractStructFields',
+      `Failed to extract struct fields for ${structName}:`,
+      error
+    );
+    return null;
+  }
+}
+
+/**
+ * Determines if a given type name is a struct type in the contract spec
+ *
+ * @param entries Array of ScSpecEntry from contract spec
+ * @param typeName Name of the type to check
+ * @returns true if the type is a struct, false otherwise
+ */
+export function isStructType(entries: xdr.ScSpecEntry[], typeName: string): boolean {
+  try {
+    const entry = entries.find((e) => {
+      try {
+        const entryName = e.value().name().toString();
+        return entryName === typeName;
+      } catch {
+        return false;
+      }
+    });
+
+    if (!entry) {
+      return false;
+    }
+
+    const entryKind = entry.switch();
+    const isStruct = entryKind.value === xdr.ScSpecEntryKind.scSpecEntryUdtStructV0().value;
+
+    return isStruct;
+  } catch (error) {
+    logger.error('isStructType', `Failed to check if ${typeName} is struct:`, error);
+    return false;
+  }
+}

package/src/mapping/tuple-components.ts

@@ -0,0 +1,43 @@
+import { xdr } from '@stellar/stellar-sdk';
+
+import type { FunctionParameter } from '@openzeppelin/ui-types';
+
+import { extractTupleTypes } from '../utils/safe-type-parser';
+import { extractStructFields, isStructType } from './struct-fields';
+
+/**
+ * Builds synthetic FunctionParameter definitions for tuple types so they can be rendered
+ * using the existing object field UI.
+ */
+export function buildTupleComponents(
+  parameterType: string,
+  specEntries?: xdr.ScSpecEntry[]
+): FunctionParameter[] | null {
+  const tupleElements = extractTupleTypes(parameterType);
+  if (!tupleElements || tupleElements.length === 0) {
+    return null;
+  }
+
+  return tupleElements.map((elementType, index) => {
+    let nestedComponents: FunctionParameter[] | undefined;
+
+    if (specEntries && isStructType(specEntries, elementType)) {
+      const structFields = extractStructFields(specEntries, elementType);
+      if (structFields && structFields.length > 0) {
+        nestedComponents = structFields;
+      }
+    } else if (elementType.startsWith('Tuple<')) {
+      const tupleStruct = buildTupleComponents(elementType, specEntries);
+      if (tupleStruct && tupleStruct.length > 0) {
+        nestedComponents = tupleStruct;
+      }
+    }
+
+    return {
+      name: `item_${index}`,
+      type: elementType,
+      displayName: `Value ${index + 1} (${elementType})`,
+      ...(nestedComponents && { components: nestedComponents }),
+    };
+  });
+}