@openzeppelin/adapter-stellar 1.0.0

package/src/utils/index.ts

@@ -0,0 +1,6 @@
+// Barrel file
+
+export * from './artifacts';
+export * from './formatting';
+export * from './input-parsing';
+export * from './type-detection';

package/src/utils/input-parsing.ts

@@ -0,0 +1,336 @@
+import { nativeToScVal, xdr } from '@stellar/stellar-sdk';
+
+import { detectBytesEncoding, logger, stringToBytes } from '@openzeppelin/ui-utils';
+
+// Import types for internal use
+import type {
+  SorobanArgumentValue,
+  SorobanComplexValue,
+  SorobanEnumValue,
+  SorobanMapEntry,
+} from '../transform/input-parser';
+import { convertStellarTypeToScValType } from './formatting';
+import { compareScValsByXdr } from './xdr-ordering';
+
+const SYSTEM_LOG_TAG = 'StellarInputParsingUtils';
+
+// Re-export types for convenience
+export type {
+  SorobanArgumentValue,
+  SorobanEnumValue,
+  SorobanMapEntry,
+  SorobanComplexValue,
+} from '../transform/input-parser';
+
+// ================================
+// TYPE GUARDS AND UTILITIES
+// ================================
+
+export function isPrimitiveArgumentSet(args: Record<string, SorobanComplexValue>): boolean {
+  return Object.values(args).every(
+    (v) => typeof v === 'object' && v !== null && 'type' in v && 'value' in v
+  );
+}
+
+export function isEnumArgumentSet(args: Record<string, SorobanComplexValue>): boolean {
+  return Object.values(args).some(
+    (v) => typeof v === 'object' && v !== null && ('tag' in v || 'enum' in v)
+  );
+}
+
+export function isMapArray(argValue: unknown[]): boolean {
+  try {
+    return (
+      Array.isArray(argValue) &&
+      argValue.every((obj: unknown) => {
+        if (typeof obj !== 'object' || obj === null) return false;
+
+        const keys = Object.keys(obj);
+        if (keys.length !== 2 || !keys.includes('0') || !keys.includes('1')) {
+          return false;
+        }
+
+        const keyEntry = (obj as Record<string, unknown>)['0'];
+        return (
+          typeof keyEntry === 'object' &&
+          keyEntry !== null &&
+          'value' in keyEntry &&
+          'type' in keyEntry
+        );
+      })
+    );
+  } catch {
+    return false;
+  }
+}
+
+export function isComplexObjectArray(argValue: unknown[]): boolean {
+  return argValue.some(
+    (v) =>
+      typeof v === 'object' &&
+      v !== null &&
+      typeof Object.values(v as Record<string, unknown>)[0] === 'object'
+  );
+}
+
+export function isPrimitiveArray(argValue: unknown[]): argValue is SorobanArgumentValue[] {
+  if (argValue.length === 0) return false;
+
+  // Check if all items are SorobanArgumentValue (not SorobanMapEntry)
+  const allArePrimitives = argValue.every(
+    (v) =>
+      typeof v === 'object' &&
+      v !== null &&
+      'value' in v &&
+      'type' in v &&
+      !('0' in v) && // Not a map entry
+      !('1' in v) // Not a map entry
+  );
+
+  if (!allArePrimitives) return false;
+
+  const firstItem = argValue[0] as SorobanArgumentValue;
+  return argValue.every((v) => {
+    const item = v as SorobanArgumentValue;
+    return item.type === firstItem.type;
+  });
+}
+
+export function isTupleArray(argValue: unknown[]): argValue is SorobanArgumentValue[] {
+  return argValue.every(
+    (v: unknown) =>
+      typeof v === 'object' &&
+      v !== null &&
+      'type' in v &&
+      'value' in v &&
+      !('0' in v) && // Not a map entry
+      !('1' in v) // Not a map entry
+  );
+}
+
+export function isObjectWithTypedValues(argValue: SorobanComplexValue): boolean {
+  return (
+    typeof argValue === 'object' &&
+    argValue !== null &&
+    !Array.isArray(argValue) &&
+    Object.values(argValue).every(
+      (v: unknown) => typeof v === 'object' && v !== null && 'type' in v && 'value' in v
+    )
+  );
+}
+
+export function isPrimitiveValue(argValue: SorobanComplexValue): boolean {
+  return (
+    typeof argValue === 'object' && argValue !== null && 'type' in argValue && 'value' in argValue
+  );
+}
+
+// ================================
+// SCVAL CONVERSION UTILITIES
+// ================================
+
+export function getScValFromPrimitive(v: SorobanArgumentValue): xdr.ScVal {
+  try {
+    if (v.type === 'bool') {
+      const boolValue = typeof v.value === 'boolean' ? v.value : v.value === 'true';
+      return nativeToScVal(boolValue);
+    }
+
+    if (v.type === 'bytes') {
+      const stringValue = v.value as string;
+      const encoding = detectBytesEncoding(stringValue);
+      return nativeToScVal(stringToBytes(stringValue, encoding));
+    }
+
+    // Use our improved type conversion utility
+    const typeHint = convertStellarTypeToScValType(v.type);
+    return nativeToScVal(v.value, { type: typeHint });
+  } catch (error) {
+    logger.error(SYSTEM_LOG_TAG, `Failed to convert primitive ${v.type}:`, error);
+    throw new Error(`Failed to convert primitive value of type ${v.type}: ${error}`);
+  }
+}
+
+export function getScValFromArg(arg: SorobanComplexValue, scVals: xdr.ScVal[]): xdr.ScVal {
+  // Handle array of arrays with numeric objects (nested structures)
+  if (Array.isArray(arg) && arg.length > 0) {
+    const arrayScVals = arg.map((subArray) => {
+      if (Array.isArray(subArray) && isMapArray(subArray)) {
+        const { mapVal, mapType } = convertObjectToMap(subArray as SorobanMapEntry[]);
+
+        // Better map key-value pair handling
+        const items = Object.keys(mapVal);
+        if (items.length > 1) {
+          items.forEach((item) => {
+            const mapScVal = nativeToScVal(mapVal[item], {
+              type: mapType[item],
+            });
+            scVals.push(mapScVal);
+          });
+        }
+
+        return nativeToScVal(mapVal, { type: mapType });
+      }
+      return getScValFromArg(subArray as SorobanComplexValue, scVals);
+    });
+
+    return xdr.ScVal.scvVec(arrayScVals);
+  }
+
+  // For single values, handle based on type
+  if (typeof arg === 'object' && arg !== null && 'type' in arg && 'value' in arg) {
+    return getScValFromPrimitive(arg as SorobanArgumentValue);
+  }
+
+  // Fallback to nativeToScVal for simple values
+  return nativeToScVal(arg);
+}
+
+export function convertEnumToScVal(obj: SorobanEnumValue, scVals?: xdr.ScVal[]): xdr.ScVal {
+  try {
+    // Integer variant - has enum property (keep as-is for integer enums)
+    if (obj.enum !== undefined) {
+      const enumScVal = nativeToScVal(obj.enum, { type: 'u32' });
+      return enumScVal;
+    }
+
+    if (!obj.tag) {
+      throw new Error('Enum object must have either "tag" or "enum" property');
+    }
+
+    // Use Vector format with Symbol for variant names (as per Soroban documentation)
+    // Unit variants: ScVec containing single ScSymbol
+    // Tuple variants: ScVec with ScSymbol + payload elements
+    const tagSymbol = nativeToScVal(obj.tag, { type: 'symbol' });
+
+    if (!obj.values || obj.values.length === 0) {
+      // Unit variant - ScVec containing single ScSymbol
+      const unitVec = xdr.ScVal.scvVec([tagSymbol]);
+      return unitVec;
+    }
+
+    // Tuple variant - ScVec with ScSymbol + payload elements
+    const valuesVal = obj.values.map((v) => getScValFromArg(v, scVals || []));
+    const tupleVec = xdr.ScVal.scvVec([tagSymbol, ...valuesVal]);
+    return tupleVec;
+  } catch (error) {
+    logger.error(SYSTEM_LOG_TAG, 'Failed to convert enum:', error);
+    throw new Error(`Failed to convert enum: ${error}`);
+  }
+}
+
+export function convertValuesToScVals(
+  values: SorobanArgumentValue[],
+  scVals: xdr.ScVal[]
+): xdr.ScVal[] {
+  return values.map((v) => getScValFromArg(v, scVals));
+}
+
+export function convertObjectToScVal(obj: Record<string, SorobanArgumentValue>): xdr.ScVal {
+  try {
+    const convertedValue: Record<string, unknown> = {};
+    const typeHints: Record<string, string | string[]> = {};
+
+    // Process each field in the object
+    for (const key in obj) {
+      const field = obj[key];
+
+      if (field.type === 'bool') {
+        convertedValue[key] =
+          typeof field.value === 'boolean' ? field.value : field.value === 'true';
+        typeHints[key] = ['symbol']; // Key is always symbol, value type varies
+      } else {
+        convertedValue[key] = field.value;
+        const fieldTypeHint = convertStellarTypeToScValType(field.type);
+        typeHints[key] = [
+          'symbol',
+          ...(Array.isArray(fieldTypeHint) ? fieldTypeHint : [fieldTypeHint]),
+        ];
+      }
+    }
+
+    return nativeToScVal(convertedValue, { type: typeHints });
+  } catch (error) {
+    logger.error(SYSTEM_LOG_TAG, 'Failed to convert object:', error);
+    throw new Error(`Failed to convert object to ScVal: ${error}`);
+  }
+}
+
+export function convertObjectToMap(mapArray: SorobanMapEntry[]): {
+  mapVal: Record<string, unknown>;
+  mapType: Record<string, string | string[]>;
+} {
+  try {
+    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
+        const valueScVal = getScValFromArg(pair['1'], []);
+        acc[key] = valueScVal;
+      } else {
+        // Handle primitive values
+        const value = pair['1'].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 = 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] = [
+        ...(Array.isArray(keyTypeHint) ? keyTypeHint : [keyTypeHint]),
+        ...(Array.isArray(valueTypeHint) ? valueTypeHint : [valueTypeHint]),
+      ];
+      return acc;
+    }, {});
+
+    return { mapVal, mapType };
+  } catch (error) {
+    logger.error(SYSTEM_LOG_TAG, 'Failed to convert map:', error);
+    throw new Error(`Failed to convert map: ${error}`);
+  }
+}
+
+export function convertTupleToScVal(tupleArray: SorobanArgumentValue[]): xdr.ScVal {
+  try {
+    const tupleScVals = tupleArray.map((v) => {
+      if (v.type === 'bool') {
+        const boolValue = typeof v.value === 'boolean' ? v.value : v.value === 'true';
+        return nativeToScVal(boolValue);
+      }
+
+      if (v.type === 'bytes') {
+        const encoding = detectBytesEncoding(v.value as string);
+        return nativeToScVal(stringToBytes(v.value as string, encoding));
+      }
+
+      const typeHint = convertStellarTypeToScValType(v.type);
+      return nativeToScVal(v.value, { type: typeHint });
+    });
+
+    // JS SDK's nativeToScVal doesn't support mixed-type arrays, so use xdr.ScVal.scvVec
+    return xdr.ScVal.scvVec(tupleScVals);
+  } catch (error) {
+    logger.error(SYSTEM_LOG_TAG, 'Failed to convert tuple:', error);
+    throw new Error(`Failed to convert tuple: ${error}`);
+  }
+}

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

@@ -0,0 +1,303 @@
+/**
+ * Safe type parsing utilities for Stellar generic types.
+ *
+ * This module provides secure, performant alternatives to regex-based parsing
+ * to prevent ReDoS (Regular Expression Denial of Service) attacks when processing
+ * Stellar contract parameter types like Vec<T>, Map<K,V>, and Option<T>.
+ *
+ * Uses iterative parsing instead of vulnerable regex patterns with greedy quantifiers.
+ */
+
+/**
+ * Configuration constants for safe parsing
+ */
+const PARSING_LIMITS = {
+  /** Maximum depth for nested generic types to prevent stack overflow */
+  MAX_NESTING_DEPTH: 10,
+  /** Maximum string length for type parsing to prevent DoS */
+  MAX_TYPE_STRING_LENGTH: 1000,
+} as const;
+
+/**
+ * Result type for type extraction operations
+ */
+type ExtractionResult<T> = T | null;
+
+/**
+ * Safely extracts the inner type from a Stellar Vec type.
+ *
+ * @param parameterType - The parameter type (e.g., 'Vec<U32>', 'Vec<Vec<Address>>')
+ * @returns The inner type (e.g., 'U32', 'Vec<Address>') or null if not a Vec type
+ *
+ * @example
+ * ```typescript
+ * extractVecElementType('Vec<U32>') // → 'U32'
+ * extractVecElementType('Vec<Vec<Address>>') // → 'Vec<Address>'
+ * extractVecElementType('U32') // → null
+ * ```
+ */
+export function extractVecElementType(parameterType: string): ExtractionResult<string> {
+  if (!isValidTypeString(parameterType) || !parameterType.startsWith('Vec<')) {
+    return null;
+  }
+
+  return extractGenericInnerType(parameterType, 'Vec');
+}
+
+/**
+ * Safely extracts the key and value types from a Stellar Map type.
+ *
+ * @param parameterType - The parameter type (e.g., 'Map<Symbol, Bytes>', 'Map<U32, Vec<Address>>')
+ * @returns An object with keyType and valueType, or null if not a Map type
+ *
+ * @example
+ * ```typescript
+ * extractMapTypes('Map<U32, Address>') // → { keyType: 'U32', valueType: 'Address' }
+ * extractMapTypes('Map<Symbol, Vec<U32>>') // → { keyType: 'Symbol', valueType: 'Vec<U32>' }
+ * extractMapTypes('U32') // → null
+ * ```
+ */
+export function extractMapTypes(
+  parameterType: string
+): ExtractionResult<{ keyType: string; valueType: string }> {
+  if (!isValidTypeString(parameterType) || !parameterType.startsWith('Map<')) {
+    return null;
+  }
+
+  const innerContent = extractGenericInnerType(parameterType, 'Map');
+  if (!innerContent) {
+    return null;
+  }
+
+  // Find the top-level comma that separates key and value types
+  const commaIndex = findTopLevelComma(innerContent);
+  if (commaIndex === -1) {
+    return null;
+  }
+
+  const keyType = innerContent.slice(0, commaIndex).trim();
+  const valueType = innerContent.slice(commaIndex + 1).trim();
+
+  // Validate both types are non-empty and don't contain invalid characters
+  if (!keyType || !valueType || hasInvalidCharacters(keyType) || hasInvalidCharacters(valueType)) {
+    return null;
+  }
+
+  return { keyType, valueType };
+}
+
+/**
+ * Safely extracts the inner type from a Stellar Option type.
+ *
+ * @param parameterType - The parameter type (e.g., 'Option<U32>', 'Option<Vec<Address>>')
+ * @returns The inner type or null if not an Option type
+ *
+ * @example
+ * ```typescript
+ * extractOptionElementType('Option<U32>') // → 'U32'
+ * extractOptionElementType('Option<Vec<Address>>') // → 'Vec<Address>'
+ * extractOptionElementType('U32') // → null
+ * ```
+ */
+export function extractOptionElementType(parameterType: string): ExtractionResult<string> {
+  if (!isValidTypeString(parameterType) || !parameterType.startsWith('Option<')) {
+    return null;
+  }
+
+  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.
+ *
+ * @param parameterType - The full parameter type
+ * @param genericName - The generic type name (e.g., 'Vec', 'Map', 'Option')
+ * @returns The inner content or null if extraction fails
+ */
+function extractGenericInnerType(
+  parameterType: string,
+  genericName: string
+): ExtractionResult<string> {
+  const prefix = `${genericName}<`;
+
+  if (!parameterType.startsWith(prefix) || !parameterType.endsWith('>')) {
+    return null;
+  }
+
+  const innerContent = parameterType.slice(prefix.length, -1);
+
+  if (!innerContent || hasInvalidCharacters(innerContent)) {
+    return null;
+  }
+
+  // Validate that brackets are properly balanced
+  if (!isBalancedBrackets(innerContent)) {
+    return null;
+  }
+
+  return innerContent.trim();
+}
+
+/**
+ * Finds the first top-level comma in a type string, ignoring commas inside nested brackets.
+ *
+ * @param content - The content to search in
+ * @returns The index of the top-level comma, or -1 if not found
+ *
+ * @example
+ * ```typescript
+ * findTopLevelComma('U32, Address') // → 3
+ * findTopLevelComma('Vec<U32, U64>, Address') // → 13 (after the first >)
+ * ```
+ */
+function findTopLevelComma(content: string): number {
+  let angleLevel = 0;
+
+  for (let i = 0; i < content.length; i++) {
+    const char = content[i];
+
+    switch (char) {
+      case '<':
+        angleLevel++;
+        break;
+      case '>':
+        angleLevel--;
+        if (angleLevel < 0) return -1; // Malformed input
+        break;
+      case ',':
+        if (angleLevel === 0) {
+          return i;
+        }
+        break;
+    }
+  }
+
+  return -1;
+}
+
+/**
+ * Checks if brackets are properly balanced in a string and enforces nesting depth limits.
+ *
+ * @param content - The content to validate
+ * @returns True if brackets are balanced and within depth limits, false otherwise
+ */
+function isBalancedBrackets(content: string): boolean {
+  let angleLevel = 0;
+  let maxNesting = 0;
+
+  for (const char of content) {
+    switch (char) {
+      case '<':
+        angleLevel++;
+        maxNesting = Math.max(maxNesting, angleLevel);
+        // Enforce nesting depth limit
+        if (maxNesting > PARSING_LIMITS.MAX_NESTING_DEPTH) {
+          return false;
+        }
+        break;
+      case '>':
+        angleLevel--;
+        if (angleLevel < 0) return false;
+        break;
+    }
+  }
+
+  return angleLevel === 0;
+}
+
+/**
+ * Validates that a type string is safe to process.
+ *
+ * @param typeString - The type string to validate
+ * @returns True if the type string is safe to process
+ */
+export function isValidTypeString(typeString: string): boolean {
+  if (!typeString || typeof typeString !== 'string') {
+    return false;
+  }
+
+  // Length check to prevent DoS
+  if (typeString.length > PARSING_LIMITS.MAX_TYPE_STRING_LENGTH) {
+    return false;
+  }
+
+  // Check for invalid characters
+  if (hasInvalidCharacters(typeString)) {
+    return false;
+  }
+
+  // Validate bracket balance
+  return isBalancedBrackets(typeString);
+}
+
+/**
+ * Checks if a string contains invalid characters for type names.
+ *
+ * @param str - The string to check
+ * @returns True if the string contains invalid characters
+ */
+function hasInvalidCharacters(str: string): boolean {
+  // No control characters or line breaks
+  if (/[\x00-\x1F\x7F\r\n]/.test(str)) {
+    return true;
+  }
+
+  // Only allow alphanumeric, angle brackets, commas, underscores, and spaces
+  // 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);
+}