@openzeppelin/adapter-stellar 1.0.0

package/src/transform/parsers/index.ts

@@ -0,0 +1,86 @@
+import { isEnumValue } from '@openzeppelin/ui-types';
+import { isPlainObject, logger } from '@openzeppelin/ui-utils';
+
+import { isLikelyEnumType } from '../../utils/type-detection';
+import { isGenericType, parseGeneric } from './generic-parser';
+import { isPrimitiveType, parsePrimitive } from './primitive-parser';
+
+// Re-export types for backward compatibility
+export type {
+  SorobanArgumentValue,
+  SorobanEnumValue,
+  SorobanMapEntry,
+  SorobanComplexValue,
+} from './types';
+
+// Re-export specific functions for backward compatibility
+export { getScValsFromArgs } from './complex-parser';
+export { valueToScVal } from './scval-converter';
+
+const SYSTEM_LOG_TAG = 'StellarInputParser';
+
+/**
+ * Parses form input values for Stellar/Soroban contracts.
+ * Handles both simple UI form inputs and complex structures.
+ *
+ * @param value - The input value from the form
+ * @param parameterType - The Stellar parameter type (e.g., 'Address', 'U128', 'Vec<U32>')
+ * @returns The parsed value suitable for nativeToScVal conversion
+ */
+export function parseStellarInput(value: unknown, parameterType: string): unknown {
+  try {
+    // Handle null/undefined values
+    if (value === null || value === undefined) {
+      return null;
+    }
+
+    // Try primitive types first (most common)
+    if (isPrimitiveType(parameterType)) {
+      const result = parsePrimitive(value, parameterType);
+      if (result !== null) {
+        return result;
+      }
+    }
+
+    // Try generic types (Vec, Map, Option, Result)
+    if (isGenericType(parameterType)) {
+      const result = parseGeneric(value, parameterType, parseStellarInput);
+      // For generic types, we always return the result (including null for Option<T> with empty/null values)
+      return result;
+    }
+
+    // Handle remaining custom types and special cases
+    // Check if this is an enum type and transform from chain-agnostic to Soroban format
+    if (isEnumValue(value) && isLikelyEnumType(parameterType)) {
+      // Chain-agnostic enum format: { tag: "VariantName", values?: [...] }
+      // Return the chain-agnostic enum value as-is
+      // The Stellar-specific transformation will happen in valueToScVal
+      return value;
+    }
+
+    // Check if this is a struct type (object with primitive fields)
+    if (isPlainObject(value)) {
+      // For structs, we need to recursively process each field
+      // But since we don't have field type information here, we'll pass it through
+      // and handle the conversion in valueToScVal where we have access to contract schema
+      return value;
+    }
+
+    // Accept array-shaped values for struct-like types (e.g., tuple structs with numeric keys).
+    // RHF treats numeric path segments as arrays, so a struct with fields "0", "1" can arrive as an array.
+    // Pass through; valueToScVal/convertStructToScVal will serialize correctly using the schema.
+    if (Array.isArray(value)) {
+      return value;
+    }
+
+    // For other types, try to return raw value with validation
+    if (typeof value === 'string' || typeof value === 'number') {
+      return value;
+    }
+
+    throw new Error(`Unsupported parameter type: ${parameterType} with value type ${typeof value}`);
+  } catch (error) {
+    logger.error(SYSTEM_LOG_TAG, 'Failed to parse Stellar input:', error);
+    throw error;
+  }
+}

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

@@ -0,0 +1,123 @@
+import { Address } from '@stellar/stellar-sdk';
+
+import { detectBytesEncoding, logger, stringToBytes } from '@openzeppelin/ui-utils';
+
+const SYSTEM_LOG_TAG = 'PrimitiveParser';
+
+/**
+ * Parses primitive Stellar/Soroban types from form inputs.
+ * Handles: Bool, Bytes, Address, ScString, ScSymbol, and numeric types (U32, U64, U128, U256, I32, I64, I128, I256).
+ *
+ * @param value - The input value from the form
+ * @param parameterType - The Stellar parameter type
+ * @returns The parsed primitive value
+ */
+export function parsePrimitive(value: unknown, parameterType: string): unknown {
+  try {
+    // Handle null/undefined values
+    if (value === null || value === undefined) {
+      return null;
+    }
+
+    switch (parameterType) {
+      // Boolean: convert string "true"/"false" to actual boolean
+      case 'Bool':
+        if (typeof value === 'boolean') {
+          return value;
+        }
+        if (typeof value === 'string') {
+          return value.toLowerCase() === 'true';
+        }
+        throw new Error(`Boolean parameter expected, got ${typeof value}`);
+
+      // Bytes: handle encoding detection
+      case 'Bytes':
+        if (typeof value === 'string') {
+          // Remove 0x prefix if present
+          const cleanValue = value.startsWith('0x') ? value.slice(2) : value;
+          const encoding = detectBytesEncoding(cleanValue);
+          return stringToBytes(cleanValue, encoding);
+        }
+        throw new Error(`Bytes parameter must be a string, got ${typeof value}`);
+
+      // DataUrl: handle base64 encoded data (similar to Bytes)
+      case 'DataUrl':
+        if (typeof value === 'string') {
+          // DataUrl is typically base64 encoded
+          const encoding = detectBytesEncoding(value);
+          return stringToBytes(value, encoding);
+        }
+        throw new Error(`DataUrl parameter must be a string, got ${typeof value}`);
+
+      // Address: validate format
+      case 'Address':
+        if (typeof value === 'string') {
+          try {
+            Address.fromString(value); // Validate format
+            return value; // Return raw string - nativeToScVal will handle conversion
+          } catch {
+            throw new Error(`Invalid Stellar address format: ${value}`);
+          }
+        }
+        throw new Error(`Address parameter must be a string, got ${typeof value}`);
+
+      // String types: return as-is
+      case 'ScString':
+      case 'ScSymbol':
+        if (typeof value === 'string') {
+          return value;
+        }
+        throw new Error(`String parameter expected, got ${typeof value}`);
+
+      default:
+        // Handle BytesN<size> patterns
+        if (/^BytesN<\d+>$/.test(parameterType)) {
+          if (typeof value === 'string') {
+            const cleanValue = value.startsWith('0x') ? value.slice(2) : value;
+            const encoding = detectBytesEncoding(cleanValue);
+            return stringToBytes(cleanValue, encoding);
+          }
+          throw new Error(`Bytes parameter must be a string, got ${typeof value}`);
+        }
+
+        // Handle numeric types: U32, U64, U128, U256, I32, I64, I128, I256
+        if (/^[UI](32|64|128|256)$/.test(parameterType)) {
+          if (typeof value === 'string') {
+            // Validate it's a valid integer (no decimals, letters)
+            if (!/^-?\d+$/.test(value.trim())) {
+              throw new Error(`Invalid number format for ${parameterType}: ${value}`);
+            }
+            return value; // Return raw string - let nativeToScVal handle conversion with type hints
+          }
+          if (typeof value === 'number') {
+            return value.toString(); // Convert to string for consistency
+          }
+          throw new Error(`Numeric parameter expected for ${parameterType}, got ${typeof value}`);
+        }
+
+        return null; // Not a primitive type - let other parsers handle it
+    }
+  } catch (error) {
+    logger.error(SYSTEM_LOG_TAG, `Failed to parse primitive ${parameterType}:`, error);
+    throw error;
+  }
+}
+
+/**
+ * Checks if the given parameter type is a primitive type that can be handled by this parser.
+ *
+ * @param parameterType - The Stellar parameter type
+ * @returns True if this is a primitive type
+ */
+export function isPrimitiveType(parameterType: string): boolean {
+  return (
+    parameterType === 'Bool' ||
+    parameterType === 'Bytes' ||
+    parameterType === 'DataUrl' ||
+    parameterType === 'Address' ||
+    parameterType === 'ScString' ||
+    parameterType === 'ScSymbol' ||
+    /^BytesN<\d+>$/.test(parameterType) ||
+    /^[UI](32|64|128|256)$/.test(parameterType)
+  );
+}

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

@@ -0,0 +1,405 @@
+import { nativeToScVal, xdr } from '@stellar/stellar-sdk';
+
+import { isEnumValue, type FunctionParameter } from '@openzeppelin/ui-types';
+
+import { convertStellarTypeToScValType } from '../../utils/formatting';
+import { convertEnumToScVal } from '../../utils/input-parsing';
+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-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.
+ *
+ * @param value - The parsed value from parseStellarInput
+ * @param parameterType - The Stellar parameter type
+ * @param paramSchema - Optional parameter schema with struct field definitions
+ * @param parseInnerValue - Function to recursively parse inner values (defaults to parseStellarInput)
+ * @returns ScVal ready for contract calls
+ */
+export function valueToScVal(
+  value: unknown,
+  parameterType: string,
+  paramSchema?: FunctionParameter,
+  parseInnerValue?: (val: unknown, type: string) => unknown
+): xdr.ScVal {
+  // Default parseInnerValue to a basic pass-through function if not provided
+  // This handles the common case where callers don't need recursive parsing
+  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(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 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,
+        (innerValue, innerType, innerSchema) =>
+          valueToScVal(innerValue, innerType, innerSchema, parseInnerValue)
+      );
+    }
+
+    // Non-generic types - use existing logic
+    if (parameterType === 'Bool' || parameterType === 'Bytes') {
+      return nativeToScVal(value);
+    }
+    if (isBytesNType(parameterType)) {
+      const match = parameterType.match(/^BytesN<(\d+)>$/);
+      if (!match) {
+        throw new Error(`Invalid BytesN parameterType format: ${parameterType}`);
+      }
+      const expectedBytes = Number.parseInt(match[1], 10);
+      const decoded = parsePrimitive(value, 'Bytes');
+      const bytesValue = decoded instanceof Uint8Array ? decoded : (decoded ?? value);
+
+      if (
+        Number.isFinite(expectedBytes) &&
+        bytesValue instanceof Uint8Array &&
+        bytesValue.length !== expectedBytes
+      ) {
+        throw new Error(
+          `BytesN value must be exactly ${expectedBytes} bytes, received ${bytesValue.length}`
+        );
+      }
+
+      return nativeToScVal(bytesValue);
+    }
+    const scValType = convertStellarTypeToScValType(parameterType);
+    const typeHint = Array.isArray(scValType) ? scValType[0] : scValType;
+    return nativeToScVal(value, { type: typeHint });
+  }
+
+  const { baseType, parameters } = genericInfo;
+
+  switch (baseType) {
+    case 'Vec': {
+      // Handle Vec<T> types
+      const innerType = parameters[0];
+      if (Array.isArray(value)) {
+        // 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);
+    }
+
+    case 'Map': {
+      // Handle Map<K,V> types in Stellar SDK format
+      if (Array.isArray(value)) {
+        // Expect Stellar SDK format: [{ 0: {value, type}, 1: {value, type} }, ...]
+        const mapEntries: xdr.ScMapEntry[] = [];
+
+        value.forEach(
+          (entry: { 0: { value: string; type: string }; 1: { value: string; type: string } }) => {
+            if (
+              typeof entry !== 'object' ||
+              entry === null ||
+              !entry[0] ||
+              !entry[1] ||
+              typeof entry[0].value === 'undefined' ||
+              typeof entry[1].value === 'undefined'
+            ) {
+              throw new Error('Invalid Stellar SDK map format in valueToScVal');
+            }
+
+            // Process key and value through parsePrimitive for bytes conversion
+            let processedKey: unknown = entry[0].value;
+            let processedValue: unknown = entry[1].value;
+
+            // Handle bytes conversion for keys
+            const keyPrimitive = parsePrimitive(entry[0].value, entry[0].type);
+            if (keyPrimitive !== null) {
+              processedKey = keyPrimitive;
+            }
+
+            // Handle bytes conversion for values
+            const valuePrimitive = parsePrimitive(entry[1].value, entry[1].type);
+            if (valuePrimitive !== null) {
+              processedValue = valuePrimitive;
+            }
+
+            // 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);
+            const valueTypeHint = Array.isArray(valueScValType)
+              ? valueScValType[0]
+              : valueScValType;
+            const valueScVal = nativeToScVal(processedValue, { type: valueTypeHint });
+
+            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()));
+        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];
+
+      if (value === null || value === undefined) {
+        return nativeToScVal(null); // None variant
+      } else {
+        // Some variant - convert the inner value
+        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);
+      }
+    }
+
+    case 'Result': {
+      // Handle Result<T,E> types
+      const okType = parameters[0];
+      const errType = parameters[1];
+
+      // 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) {
+          const okScVal = valueToScVal(resultObj.ok, okType);
+          return nativeToScVal({ ok: okScVal });
+        } else if ('err' in resultObj) {
+          const errScVal = valueToScVal(resultObj.err, errType);
+          return nativeToScVal({ err: errScVal });
+        }
+      }
+      return nativeToScVal(value);
+    }
+
+    default: {
+      // Unknown generic type - fallback to basic conversion
+      const scValType = convertStellarTypeToScValType(parameterType);
+      const typeHint = Array.isArray(scValType) ? scValType[0] : scValType;
+      return nativeToScVal(value, { type: typeHint });
+    }
+  }
+}