@openzeppelin/ui-builder-adapter-stellar 0.15.0 → 1.0.0

package/src/transform/parsers/scval-converter.ts

@@ -4,12 +4,18 @@ import { isEnumValue, type FunctionParameter } from '@openzeppelin/ui-builder-ty
 
 import { convertStellarTypeToScValType } from '../../utils/formatting';
 import { convertEnumToScVal } from '../../utils/input-parsing';
-import { isBytesNType } from '../../utils/type-detection';
+import { isPrimitiveParamType } from '../../utils/stellar-types';
+import { isBytesNType, isLikelyEnumType } from '../../utils/type-detection';
+import { compareScValsByXdr } from '../../utils/xdr-ordering';
 import { parseGenericType } from './generic-parser';
 import { parsePrimitive } from './primitive-parser';
 import { convertStructToScVal, isStructType } from './struct-parser';
 import type { SorobanEnumValue } from './types';
 
+// FunctionParameter already includes enumMetadata in its type definition (from @openzeppelin/ui-builder-types)
+// No need for a separate type wrapper
+type EnumAwareFunctionParameter = FunctionParameter;
+
 /**
  * Converts a value to ScVal with comprehensive generic type support.
  * This should be used in the transaction execution instead of calling nativeToScVal directly.
@@ -31,19 +37,152 @@ export function valueToScVal(
   const parseValue = parseInnerValue || ((val: unknown) => val);
   const genericInfo = parseGenericType(parameterType);
 
+  // Helper: detect SorobanArgumentValue wrapper { type, value }
+  const isTypedWrapper = (v: unknown): v is { type: string; value: unknown } =>
+    !!v &&
+    typeof v === 'object' &&
+    'type' in (v as Record<string, unknown>) &&
+    'value' in (v as Record<string, unknown>);
+
+  const enumMetadata = (paramSchema as EnumAwareFunctionParameter | undefined)?.enumMetadata;
+  const possibleEnumValue =
+    typeof value === 'string' && (enumMetadata || isLikelyEnumType(parameterType))
+      ? { tag: value }
+      : value;
+
   if (!genericInfo) {
+    // Integer-only enums (discriminant enums) → encode as u32 (matches Lab behavior)
+    if (enumMetadata && enumMetadata.variants.every((v) => v.type === 'integer')) {
+      // Derive numeric discriminant from name, tag, or numeric input
+      let numericValue: number | undefined;
+      if (typeof value === 'string') {
+        const byName = enumMetadata.variants.find((v) => v.name === value);
+        numericValue = byName?.value ?? Number(value);
+      } else if (typeof value === 'number') {
+        numericValue = value;
+      } else if (isEnumValue(value)) {
+        const byTag = enumMetadata.variants.find((v) => v.name === value.tag);
+        numericValue = byTag?.value;
+      }
+      if (numericValue === undefined || Number.isNaN(numericValue)) {
+        const validNames = enumMetadata.variants.map((v) => v.name).join(', ');
+        throw new Error(
+          `Invalid integer enum value for ${parameterType}: ${String(value)}. Expected one of: ${validNames}`
+        );
+      }
+      return nativeToScVal(numericValue, { type: 'u32' });
+    }
+    // If a typed wrapper is provided, convert directly using the wrapped type/value
+    if (isTypedWrapper(possibleEnumValue)) {
+      const wrapped = possibleEnumValue;
+      const parsed = parsePrimitive(wrapped.value, wrapped.type);
+      const finalVal = parsed !== null ? parsed : wrapped.value;
+      const scValType = convertStellarTypeToScValType(wrapped.type);
+      const typeHint = Array.isArray(scValType) ? scValType[0] : scValType;
+      return nativeToScVal(finalVal, { type: typeHint });
+    }
+
     // Check if this is an enum object (has 'tag' or 'enum' property)
-    if (isEnumValue(value) || (typeof value === 'object' && value !== null && 'enum' in value)) {
-      return convertEnumToScVal(value as SorobanEnumValue);
+    if (
+      isEnumValue(possibleEnumValue) ||
+      (typeof possibleEnumValue === 'object' &&
+        possibleEnumValue !== null &&
+        'enum' in possibleEnumValue)
+    ) {
+      const enumValue = possibleEnumValue as { tag: string; values?: unknown[]; enum?: number };
+
+      // Handle integer enums
+      if ('enum' in enumValue && typeof enumValue.enum === 'number') {
+        return nativeToScVal(enumValue.enum, { type: 'u32' });
+      }
+
+      // Handle tagged enums with metadata for proper type conversion
+      const tagSymbol = nativeToScVal(enumValue.tag, { type: 'symbol' });
+
+      if (!enumValue.values || enumValue.values.length === 0) {
+        // Unit variant - ScVec containing single ScSymbol
+        return xdr.ScVal.scvVec([tagSymbol]);
+      }
+
+      const payloadValues = enumValue.values as unknown[];
+
+      // Tuple variant - convert each payload value with proper types
+      let payloadScVals: xdr.ScVal[];
+      // Use the variant type from EnumAwareFunctionParameter's enumMetadata
+      type EnumVariant = NonNullable<
+        EnumAwareFunctionParameter['enumMetadata']
+      >['variants'][number];
+      let variant: EnumVariant | undefined;
+
+      if (enumMetadata) {
+        variant = enumMetadata.variants.find((variantEntry) => variantEntry.name === enumValue.tag);
+        if (!variant || !variant.payloadTypes) {
+          // No variant metadata or payloadTypes - use convertEnumToScVal fallback
+          return convertEnumToScVal(enumValue as SorobanEnumValue);
+        }
+        // Convert each payload value with its corresponding type
+        // variant is guaranteed to be defined here due to the check above
+        const payloadTypes = variant.payloadTypes;
+        const payloadComponents = variant.payloadComponents;
+        payloadScVals = payloadTypes.map((payloadType, index) => {
+          const payloadSchema = payloadComponents?.[index]
+            ? {
+                name: `payload_${index}`,
+                type: payloadType,
+                components: payloadComponents[index],
+              }
+            : { name: `payload_${index}`, type: payloadType };
+
+          const val = payloadValues[index];
+          return valueToScVal(val, payloadType, payloadSchema, parseValue);
+        });
+      } else {
+        // No enum metadata - use convertEnumToScVal fallback
+        return convertEnumToScVal(enumValue as SorobanEnumValue);
+      }
+
+      // For single Tuple payload, wrap all payload ScVals in another ScVec
+      // Example: Some((Address, i128)) → ScVec([Symbol("Some"), ScVec([Address, I128])])
+      if (variant?.isSingleTuplePayload) {
+        const tuplePayloadVec = xdr.ScVal.scvVec(payloadScVals);
+        return xdr.ScVal.scvVec([tagSymbol, tuplePayloadVec]);
+      }
+
+      // Return ScVec with tag symbol followed by payload values
+      return xdr.ScVal.scvVec([tagSymbol, ...payloadScVals]);
     }
 
-    // Check if this is a struct type
-    if (isStructType(value, parameterType)) {
+    // Check if this is a struct or tuple type
+    // Accept array-shaped values for tuple-structs when schema components are provided
+    if (
+      Array.isArray(possibleEnumValue) &&
+      paramSchema?.components &&
+      paramSchema.components.length
+    ) {
+      // Runtime validation: ensure array length matches schema components
+      if (possibleEnumValue.length !== paramSchema.components.length) {
+        throw new Error(
+          `Tuple-struct value length (${possibleEnumValue.length}) does not match schema components (${paramSchema.components.length}) for type ${parameterType}`
+        );
+      }
+      return convertStructToScVal(
+        possibleEnumValue as unknown as Record<string, unknown>,
+        parameterType,
+        paramSchema,
+        parseValue,
+        (innerValue, innerType, innerSchema) =>
+          valueToScVal(innerValue, innerType, innerSchema, parseInnerValue)
+      );
+    }
+
+    if (!isPrimitiveParamType(parameterType) && isStructType(value, parameterType)) {
       return convertStructToScVal(
         value as Record<string, unknown>,
         parameterType,
         paramSchema,
-        parseValue
+        parseValue,
+        (innerValue, innerType, innerSchema) =>
+          valueToScVal(innerValue, innerType, innerSchema, parseInnerValue)
       );
     }
 
@@ -84,7 +223,28 @@ export function valueToScVal(
       // Handle Vec<T> types
       const innerType = parameters[0];
       if (Array.isArray(value)) {
-        const convertedElements = value.map((element) => valueToScVal(element, innerType));
+        // For enum element types, we need to pass enum metadata
+        // Check if paramSchema has enumMetadata or components that should be used for elements
+        let elementSchema: FunctionParameter | undefined;
+        if (enumMetadata) {
+          // This Vec is of enum type - pass the enum metadata to each element
+          elementSchema = {
+            name: 'element',
+            type: innerType,
+            enumMetadata,
+          } as EnumAwareFunctionParameter;
+        } else if (paramSchema?.components) {
+          // This Vec is of struct type - pass the components to each element
+          elementSchema = {
+            name: 'element',
+            type: innerType,
+            components: paramSchema.components,
+          };
+        }
+
+        const convertedElements = value.map((element) =>
+          valueToScVal(element, innerType, elementSchema, parseValue)
+        );
         return nativeToScVal(convertedElements);
       }
       return nativeToScVal(value);
@@ -94,8 +254,7 @@ export function valueToScVal(
       // Handle Map<K,V> types in Stellar SDK format
       if (Array.isArray(value)) {
         // Expect Stellar SDK format: [{ 0: {value, type}, 1: {value, type} }, ...]
-        const convertedValue: Record<string, unknown> = {};
-        const typeHints: Record<string, string[]> = {};
+        const mapEntries: xdr.ScMapEntry[] = [];
 
         value.forEach(
           (entry: { 0: { value: string; type: string }; 1: { value: string; type: string } }) => {
@@ -111,7 +270,6 @@ export function valueToScVal(
             }
 
             // Process key and value through parsePrimitive for bytes conversion
-            // This ensures bytes strings are converted to Uint8Array before nativeToScVal
             let processedKey: unknown = entry[0].value;
             let processedValue: unknown = entry[1].value;
 
@@ -127,26 +285,71 @@ export function valueToScVal(
               processedValue = valuePrimitive;
             }
 
-            // Use the processed key as the object key (convert to string if needed)
-            const keyString =
-              typeof processedKey === 'string' ? processedKey : String(processedKey);
-            convertedValue[keyString] = processedValue;
-
+            // Create ScVals for key and value
             const keyScValType = convertStellarTypeToScValType(entry[0].type);
+            const keyTypeHint = Array.isArray(keyScValType) ? keyScValType[0] : keyScValType;
+            const keyScVal = nativeToScVal(processedKey, { type: keyTypeHint });
+
             const valueScValType = convertStellarTypeToScValType(entry[1].type);
-            typeHints[keyString] = [
-              Array.isArray(keyScValType) ? keyScValType[0] : keyScValType,
-              Array.isArray(valueScValType) ? valueScValType[0] : valueScValType,
-            ];
+            const valueTypeHint = Array.isArray(valueScValType)
+              ? valueScValType[0]
+              : valueScValType;
+            const valueScVal = nativeToScVal(processedValue, { type: valueTypeHint });
+
+            mapEntries.push(
+              new xdr.ScMapEntry({
+                key: keyScVal,
+                val: valueScVal,
+              })
+            );
           }
         );
 
-        return nativeToScVal(convertedValue, { type: typeHints });
+        // Sort map entries by XDR-encoded keys (required by Soroban)
+        const sortedMapEntries = mapEntries.sort((a, b) => compareScValsByXdr(a.key(), b.key()));
+        return xdr.ScVal.scvMap(sortedMapEntries);
       }
 
       return nativeToScVal(value);
     }
 
+    case 'Tuple': {
+      if (!paramSchema?.components || paramSchema.components.length === 0) {
+        throw new Error(
+          `Tuple parameter "${paramSchema?.name ?? 'unknown'}" is missing component metadata`
+        );
+      }
+
+      const tupleComponents = paramSchema.components;
+      const tupleValues: xdr.ScVal[] = [];
+
+      tupleComponents.forEach((component, index) => {
+        const key = component.name ?? `item_${index}`;
+        let elementValue: unknown;
+
+        if (Array.isArray(value)) {
+          elementValue = value[index];
+        } else if (value && typeof value === 'object') {
+          elementValue = (value as Record<string, unknown>)[key];
+        }
+
+        if (typeof elementValue === 'undefined') {
+          const expectedTypes = tupleComponents.map((c) => c.type).join(', ');
+          throw new Error(
+            `Missing tuple value for "${key}" in parameter "${paramSchema.name ?? 'unknown'}". Expected ${tupleComponents.length} values of types [${expectedTypes}] but received: ${JSON.stringify(value)}`
+          );
+        }
+
+        if (typeof elementValue === 'string' && isLikelyEnumType(component.type)) {
+          elementValue = { tag: elementValue };
+        }
+
+        tupleValues.push(valueToScVal(elementValue, component.type, component, parseInnerValue));
+      });
+
+      return xdr.ScVal.scvVec(tupleValues);
+    }
+
     case 'Option': {
       // Handle Option<T> types
       const innerType = parameters[0];
@@ -155,7 +358,21 @@ export function valueToScVal(
         return nativeToScVal(null); // None variant
       } else {
         // Some variant - convert the inner value
-        return valueToScVal(value, innerType);
+        let innerSchema: FunctionParameter | undefined;
+        if (enumMetadata) {
+          innerSchema = {
+            name: 'inner',
+            type: innerType,
+            ...({ enumMetadata } as unknown as Record<string, unknown>),
+          } as unknown as FunctionParameter;
+        } else if (paramSchema?.components) {
+          innerSchema = {
+            name: 'inner',
+            type: innerType,
+            components: paramSchema.components,
+          };
+        }
+        return valueToScVal(value, innerType, innerSchema, parseInnerValue);
       }
     }
 

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

@@ -1,13 +1,23 @@
 import { nativeToScVal, xdr } from '@stellar/stellar-sdk';
 
-import type { FunctionParameter } from '@openzeppelin/ui-builder-types';
+import { isEnumValue, type FunctionParameter } from '@openzeppelin/ui-builder-types';
 import { isPlainObject, logger } from '@openzeppelin/ui-builder-utils';
 
 import { convertStellarTypeToScValType } from '../../utils/formatting';
+import { isLikelyEnumType } from '../../utils/type-detection';
+import { compareScValsByXdr } from '../../utils/xdr-ordering';
 import { parseGenericType } from './generic-parser';
 
 const SYSTEM_LOG_TAG = 'StructParser';
 
+function isTupleStructSchema(schema: FunctionParameter | undefined): boolean {
+  if (!schema?.components || schema.components.length === 0) {
+    return false;
+  }
+
+  return schema.components.every((component, index) => component.name === index.toString());
+}
+
 /**
  * Determines if a field value needs parsing through parseStellarInput.
  * Returns false for already-processed values (like Uint8Array for bytes).
@@ -59,6 +69,7 @@ function needsParsing(value: unknown, fieldType: string): boolean {
  * @param parameterType - The Stellar parameter type (for error messages)
  * @param paramSchema - Parameter schema with struct field definitions (required)
  * @param parseInnerValue - Function to recursively parse inner values
+ * @param convertToScVal - Optional function to recursively convert values to ScVal (for tuple structs)
  * @returns ScVal ready for contract calls
  * @throws Error if schema information is missing for any field
  */
@@ -66,10 +77,40 @@ export function convertStructToScVal(
   structObj: Record<string, unknown>,
   parameterType: string,
   paramSchema: FunctionParameter | undefined,
-  parseInnerValue: (val: unknown, type: string) => unknown
+  parseInnerValue: (val: unknown, type: string) => unknown,
+  convertToScVal?: (
+    value: unknown,
+    type: string,
+    schema?: FunctionParameter,
+    parseValue?: (val: unknown, type: string) => unknown
+  ) => xdr.ScVal
 ): xdr.ScVal {
   // Laboratory-style struct conversion with proper type hint handling
 
+  // Check if this is a tuple struct (numeric field names like "0", "1", "2")
+  // Tuple structs in Soroban need to be serialized as vectors, not maps
+  if (isTupleStructSchema(paramSchema) && paramSchema && convertToScVal) {
+    const tupleValues = paramSchema.components!.map((component, index) => {
+      const key = component.name ?? index.toString();
+      let elementValue = structObj[key];
+
+      if (typeof elementValue === 'undefined') {
+        throw new Error(
+          `Missing tuple value for "${key}" in struct type "${parameterType}". Received: ${JSON.stringify(structObj)}`
+        );
+      }
+
+      // If the element is a string and its type is likely an enum, wrap it as { tag: value }
+      if (typeof elementValue === 'string' && isLikelyEnumType(component.type)) {
+        elementValue = { tag: elementValue };
+      }
+
+      return convertToScVal(elementValue, component.type, component, parseInnerValue);
+    });
+
+    return xdr.ScVal.scvVec(tupleValues);
+  }
+
   // Struct conversion using Laboratory pattern with schema-based type resolution
   // See: laboratory/src/helpers/sorobanUtils.ts convertObjectToScVal
   const convertedValue: Record<string, unknown> = {};
@@ -101,6 +142,10 @@ export function convertStructToScVal(
         parsedValue = fieldValue;
       }
 
+      if (typeof parsedValue === 'string' && isLikelyEnumType(fieldType)) {
+        parsedValue = { tag: parsedValue };
+      }
+
       // Handle Map fields specially - convert from SDK format to plain object with type hints
       if (fieldType.startsWith('Map<') && Array.isArray(parsedValue)) {
         // Extract key and value types
@@ -149,12 +194,25 @@ export function convertStructToScVal(
         // Provide nested type hints for Map field (Laboratory pattern)
         typeHints[fieldName] = ['symbol', mapTypeHints];
       } else {
-        convertedValue[fieldName] = parsedValue;
+        // Check if this is a Vec or other generic type that needs special handling
+        if (convertToScVal && (fieldType.startsWith('Vec<') || isEnumValue(parsedValue))) {
+          const fieldSchema = paramSchema?.components?.find((c) => c.name === fieldName);
+          // Use valueToScVal for Vec and enum fields to ensure proper conversion
+          convertedValue[fieldName] = convertToScVal(
+            parsedValue,
+            fieldType,
+            fieldSchema,
+            parseInnerValue
+          );
+          typeHints[fieldName] = ['symbol', 'scval'];
+        } else {
+          convertedValue[fieldName] = parsedValue;
 
-        // Use exact type from schema for non-Map fields
-        const scValType = convertStellarTypeToScValType(fieldType);
-        if (scValType !== 'map-special') {
-          typeHints[fieldName] = ['symbol', Array.isArray(scValType) ? scValType[0] : scValType];
+          // Use exact type from schema for non-Map fields
+          const scValType = convertStellarTypeToScValType(fieldType);
+          if (scValType !== 'map-special') {
+            typeHints[fieldName] = ['symbol', Array.isArray(scValType) ? scValType[0] : scValType];
+          }
         }
       }
     } else {
@@ -172,7 +230,55 @@ export function convertStructToScVal(
     typeHints,
   });
 
-  const scVal = nativeToScVal(convertedValue, { type: typeHints });
+  // Check if any fields are enums that need special conversion
+  const hasEnumFields = paramSchema?.components?.some((comp) => {
+    const fieldValue = convertedValue[comp.name];
+    return isEnumValue(fieldValue);
+  });
+
+  let scVal: xdr.ScVal;
+
+  if (hasEnumFields && convertToScVal && paramSchema?.components) {
+    // Manually build the ScMap with proper enum conversion
+    const mapEntries: xdr.ScMapEntry[] = [];
+
+    for (const fieldSchema of paramSchema.components) {
+      const fieldName = fieldSchema.name;
+      const fieldValue = convertedValue[fieldName];
+
+      // Create key
+      const keyScVal = nativeToScVal(fieldName, { type: 'symbol' });
+
+      // Create value - check if it's an enum
+      let valueScVal: xdr.ScVal;
+      if (isEnumValue(fieldValue)) {
+        valueScVal = convertToScVal(fieldValue, fieldSchema.type, fieldSchema, parseInnerValue);
+      } else {
+        // Use nativeToScVal for non-enum fields
+        const fieldTypeHint = typeHints[fieldName];
+        if (fieldTypeHint && Array.isArray(fieldTypeHint) && fieldTypeHint.length > 1) {
+          valueScVal = nativeToScVal(fieldValue, { type: fieldTypeHint[1] });
+        } else {
+          valueScVal = nativeToScVal(fieldValue);
+        }
+      }
+
+      mapEntries.push(
+        new xdr.ScMapEntry({
+          key: keyScVal,
+          val: valueScVal,
+        })
+      );
+    }
+
+    // Sort map entries by XDR-encoded keys (required by Soroban)
+    const sortedMapEntries = mapEntries.sort((a, b) => compareScValsByXdr(a.key(), b.key()));
+
+    scVal = xdr.ScVal.scvMap(sortedMapEntries);
+  } else {
+    scVal = nativeToScVal(convertedValue, { type: typeHints });
+  }
+
   logger.debug(SYSTEM_LOG_TAG, 'convertStructToScVal generated ScVal:', {
     parameterType,
     scValType: scVal.switch().name,

package/src/utils/input-parsing.ts

@@ -10,6 +10,7 @@ import type {
   SorobanMapEntry,
 } from '../transform/input-parser';
 import { convertStellarTypeToScValType } from './formatting';
+import { compareScValsByXdr } from './xdr-ordering';
 
 const SYSTEM_LOG_TAG = 'StellarInputParsingUtils';
 
@@ -260,8 +261,14 @@ export function convertObjectToMap(mapArray: SorobanMapEntry[]): {
   mapType: Record<string, string | string[]>;
 } {
   try {
-    const mapVal = mapArray.reduce((acc: Record<string, unknown>, pair) => {
-      const key = pair['0'].value as string;
+    const sortedEntries = [...mapArray].sort((a, b) => {
+      const aKey = getScValFromPrimitive(a['0'] as SorobanArgumentValue);
+      const bKey = getScValFromPrimitive(b['0'] as SorobanArgumentValue);
+      return compareScValsByXdr(aKey, bKey);
+    });
+
+    const mapVal = sortedEntries.reduce((acc: Record<string, unknown>, pair) => {
+      const key = String(pair['0'].value);
 
       if (Array.isArray(pair['1'])) {
         // Handle nested array values
@@ -270,13 +277,23 @@ export function convertObjectToMap(mapArray: SorobanMapEntry[]): {
       } else {
         // Handle primitive values
         const value = pair['1'].value;
-        acc[key] = pair['1'].type === 'bool' ? value === 'true' : value;
+        if (pair['1'].type === 'bool') {
+          if (typeof value === 'boolean') {
+            acc[key] = value;
+          } else if (typeof value === 'string') {
+            acc[key] = value === 'true';
+          } else {
+            acc[key] = Boolean(value);
+          }
+        } else {
+          acc[key] = value;
+        }
       }
       return acc;
     }, {});
 
-    const mapType = mapArray.reduce((acc: Record<string, string[]>, pair) => {
-      const key = pair['0'].value as string;
+    const mapType = sortedEntries.reduce((acc: Record<string, string[]>, pair) => {
+      const key = String(pair['0'].value);
       const keyTypeHint = convertStellarTypeToScValType(pair['0'].type);
       const valueTypeHint = convertStellarTypeToScValType(pair['1'].type);
       acc[key] = [

package/src/utils/safe-type-parser.ts

@@ -107,6 +107,30 @@ export function extractOptionElementType(parameterType: string): ExtractionResul
   return extractGenericInnerType(parameterType, 'Option');
 }
 
+/**
+ * Safely extracts the element types from a Stellar Tuple type.
+ *
+ * @param parameterType - The parameter type (e.g., 'Tuple<U32, Bool>')
+ * @returns Array of element types or null if not a Tuple type
+ */
+export function extractTupleTypes(parameterType: string): ExtractionResult<string[]> {
+  if (!isValidTypeString(parameterType) || !parameterType.startsWith('Tuple<')) {
+    return null;
+  }
+
+  const innerContent = extractGenericInnerType(parameterType, 'Tuple');
+  if (!innerContent) {
+    return null;
+  }
+
+  const parts = splitTopLevelTypes(innerContent);
+  if (parts.length === 0) {
+    return null;
+  }
+
+  return parts;
+}
+
 /**
  * Generic function to extract inner content from generic types.
  *
@@ -246,3 +270,34 @@ function hasInvalidCharacters(str: string): boolean {
   // Note: Parentheses are NOT allowed in Stellar type strings
   return !/^[A-Za-z0-9<>,\s_]+$/.test(str);
 }
+
+/**
+ * Splits a comma-separated list of types while respecting nested generics.
+ */
+function splitTopLevelTypes(content: string): string[] {
+  const types: string[] = [];
+  let start = 0;
+  let level = 0;
+
+  for (let i = 0; i < content.length; i += 1) {
+    const char = content[i];
+    if (char === '<') {
+      level += 1;
+    } else if (char === '>') {
+      level -= 1;
+    } else if (char === ',' && level === 0) {
+      const segment = content.slice(start, i).trim();
+      if (segment) {
+        types.push(segment);
+      }
+      start = i + 1;
+    }
+  }
+
+  const lastSegment = content.slice(start).trim();
+  if (lastSegment) {
+    types.push(lastSegment);
+  }
+
+  return types;
+}

package/src/utils/stellar-types.ts

@@ -0,0 +1,35 @@
+/**
+ * Set of primitive Stellar/Soroban parameter types.
+ * These types do not have nested components and can be directly serialized.
+ *
+ * Used to distinguish primitive types from complex types (structs, enums, tuples, maps, vecs)
+ * when processing parameters for serialization and validation.
+ */
+export const PRIMITIVE_STELLAR_TYPES = new Set([
+  'Bool',
+  'ScString',
+  'ScSymbol',
+  'Address',
+  'Bytes',
+  'U8',
+  'U16',
+  'U32',
+  'U64',
+  'U128',
+  'U256',
+  'I8',
+  'I16',
+  'I32',
+  'I64',
+  'I128',
+  'I256',
+]);
+
+/**
+ * Check if a Stellar type is a primitive type.
+ * @param type - The Stellar type to check
+ * @returns True if the type is primitive, false otherwise
+ */
+export function isPrimitiveParamType(type: string): boolean {
+  return PRIMITIVE_STELLAR_TYPES.has(type);
+}