@openzeppelin/adapter-stellar 1.0.0

package/src/utils/type-detection.ts

@@ -0,0 +1,163 @@
+import * as StellarSdk from '@stellar/stellar-sdk';
+
+import { isDevelopmentOrTestEnvironment, logger } from '@openzeppelin/ui-utils';
+
+/**
+ * Utility functions for detecting and analyzing Stellar/Soroban parameter types
+ */
+
+/**
+ * Extract human-readable Soroban type name from ScSpecTypeDef
+ * Based on the Stellar SDK type system
+ */
+export function extractSorobanTypeFromScSpec(scSpecType: StellarSdk.xdr.ScSpecTypeDef): string {
+  try {
+    const typeSwitch = scSpecType.switch();
+
+    switch (typeSwitch) {
+      case StellarSdk.xdr.ScSpecType.scSpecTypeVal():
+        return 'Val';
+      case StellarSdk.xdr.ScSpecType.scSpecTypeBool():
+        return 'Bool';
+      case StellarSdk.xdr.ScSpecType.scSpecTypeVoid():
+        return 'Void';
+      case StellarSdk.xdr.ScSpecType.scSpecTypeError():
+        return 'Error';
+      case StellarSdk.xdr.ScSpecType.scSpecTypeU32():
+        return 'U32';
+      case StellarSdk.xdr.ScSpecType.scSpecTypeI32():
+        return 'I32';
+      case StellarSdk.xdr.ScSpecType.scSpecTypeU64():
+        return 'U64';
+      case StellarSdk.xdr.ScSpecType.scSpecTypeI64():
+        return 'I64';
+      case StellarSdk.xdr.ScSpecType.scSpecTypeTimepoint():
+        return 'Timepoint';
+      case StellarSdk.xdr.ScSpecType.scSpecTypeDuration():
+        return 'Duration';
+      case StellarSdk.xdr.ScSpecType.scSpecTypeU128():
+        return 'U128';
+      case StellarSdk.xdr.ScSpecType.scSpecTypeI128():
+        return 'I128';
+      case StellarSdk.xdr.ScSpecType.scSpecTypeU256():
+        return 'U256';
+      case StellarSdk.xdr.ScSpecType.scSpecTypeI256():
+        return 'I256';
+      case StellarSdk.xdr.ScSpecType.scSpecTypeBytes():
+        return 'Bytes';
+      case StellarSdk.xdr.ScSpecType.scSpecTypeBytesN(): {
+        const bytesNType = scSpecType.bytesN();
+        const size = bytesNType.n();
+        return `BytesN<${size}>`;
+      }
+      case StellarSdk.xdr.ScSpecType.scSpecTypeString():
+        return 'ScString';
+      case StellarSdk.xdr.ScSpecType.scSpecTypeSymbol():
+        return 'ScSymbol';
+      case StellarSdk.xdr.ScSpecType.scSpecTypeVec(): {
+        const vecType = scSpecType.vec();
+        const elementType = extractSorobanTypeFromScSpec(vecType.elementType());
+        return `Vec<${elementType}>`;
+      }
+      case StellarSdk.xdr.ScSpecType.scSpecTypeMap(): {
+        const mapType = scSpecType.map();
+        const keyType = extractSorobanTypeFromScSpec(mapType.keyType());
+        const valueType = extractSorobanTypeFromScSpec(mapType.valueType());
+        return `Map<${keyType}, ${valueType}>`;
+      }
+      case StellarSdk.xdr.ScSpecType.scSpecTypeTuple(): {
+        const tupleType = scSpecType.tuple();
+        const valueTypes = tupleType.valueTypes();
+        const typeNames = valueTypes.map((t) => extractSorobanTypeFromScSpec(t));
+        return `Tuple<${typeNames.join(', ')}>`;
+      }
+      case StellarSdk.xdr.ScSpecType.scSpecTypeOption(): {
+        const optionType = scSpecType.option();
+        const valueType = extractSorobanTypeFromScSpec(optionType.valueType());
+        return `Option<${valueType}>`;
+      }
+      case StellarSdk.xdr.ScSpecType.scSpecTypeResult(): {
+        const resultType = scSpecType.result();
+        const okType = extractSorobanTypeFromScSpec(resultType.okType());
+        const errorType = extractSorobanTypeFromScSpec(resultType.errorType());
+        return `Result<${okType}, ${errorType}>`;
+      }
+      case StellarSdk.xdr.ScSpecType.scSpecTypeAddress():
+        return 'Address';
+      case StellarSdk.xdr.ScSpecType.scSpecTypeMuxedAddress():
+        return 'MuxedAddress';
+      case StellarSdk.xdr.ScSpecType.scSpecTypeUdt(): {
+        const udtType = scSpecType.udt();
+        return udtType.name().toString();
+      }
+      default:
+        // COMPREHENSIVE TYPE MISS DETECTION
+        logger.error('extractSorobanTypeFromScSpec', `🚨 MISSING SCSPEC TYPE HANDLER 🚨`, {
+          typeSwitchValue: typeSwitch.value,
+          typeSwitchName: typeSwitch.name,
+          rawScSpecType: scSpecType,
+          message: 'This indicates a missing case in extractSorobanTypeFromScSpec switch statement',
+          actionRequired: 'Add support for this ScSpec type immediately',
+          sdkVersion: process.env.npm_package_dependencies_stellar_sdk || 'unknown',
+        });
+
+        // Create detailed error report for unknown types
+        const errorReport = {
+          type: 'MISSING_SCSPEC_TYPE',
+          scSpecType: typeSwitch.name,
+          value: typeSwitch.value,
+          timestamp: new Date().toISOString(),
+        };
+
+        // In development, throw an error to fail fast
+        if (isDevelopmentOrTestEnvironment()) {
+          throw new Error(
+            `Missing ScSpec type handler: ${typeSwitch.name} (value: ${typeSwitch.value}). Please add support for this type.`
+          );
+        }
+
+        // In production, log extensively but don't break
+        logger.error('STELLAR_ADAPTER_MISSING_TYPE', 'Missing ScSpec type handler:', errorReport);
+        return 'unknown';
+    }
+  } catch (error) {
+    logger.error('extractSorobanTypeFromScSpec', 'Failed to extract type:', error);
+    return 'unknown';
+  }
+}
+
+/**
+ * Determines if a parameter type is likely an enum based on naming conventions
+ * and common patterns in Stellar/Soroban contracts.
+ *
+ * @param parameterType The parameter type string to analyze
+ * @returns true if the type appears to be an enum based on naming patterns
+ */
+export function isLikelyEnumType(parameterType: string): boolean {
+  // Direct enum name patterns
+  if (parameterType.includes('Enum') || parameterType.includes('enum')) {
+    return true;
+  }
+
+  // Common enum naming patterns in Stellar/Soroban
+  const enumPatterns = [
+    /^(Status|State|Type|Kind|Mode|Level|Priority|Category)$/i,
+    /^.*?(Status|State|Type|Kind|Mode|Level|Priority|Category)$/i,
+    /^(Token|Asset|Account|Contract|Network)Type$/i,
+  ];
+
+  // Only apply pattern matching if it's not a generic "UnknownType" or similar
+  if (
+    parameterType === 'UnknownType' ||
+    parameterType === 'CustomStruct' ||
+    parameterType === 'UserInfo'
+  ) {
+    return false;
+  }
+
+  return enumPatterns.some((pattern) => pattern.test(parameterType));
+}
+
+export function isBytesNType(parameterType: string): boolean {
+  return /^BytesN<\d+>$/.test(parameterType);
+}

package/src/utils/xdr-ordering.ts

@@ -0,0 +1,36 @@
+import { xdr } from '@stellar/stellar-sdk';
+
+/**
+ * Compare two ScVals based on their XDR encoding without relying on Node's Buffer.
+ */
+export function compareScValsByXdr(a: xdr.ScVal, b: xdr.ScVal): number {
+  const aBytes = getBytes(a);
+  const bBytes = getBytes(b);
+
+  const minLength = Math.min(aBytes.length, bBytes.length);
+  for (let index = 0; index < minLength; index += 1) {
+    const diff = aBytes[index] - bBytes[index];
+    if (diff !== 0) {
+      return diff;
+    }
+  }
+
+  return aBytes.length - bBytes.length;
+}
+
+function getBytes(scVal: xdr.ScVal): Uint8Array {
+  const xdrValue = scVal.toXDR();
+
+  // In browsers, toXDR may already return a Uint8Array (Buffer is a Uint8Array subclass in Node).
+  if (xdrValue instanceof Uint8Array) {
+    return xdrValue;
+  }
+
+  // Handle array-like objects (e.g., Buffer in Node.js)
+  const arrayLike = xdrValue as ArrayLike<number>;
+  const result = new Uint8Array(arrayLike.length);
+  for (let index = 0; index < arrayLike.length; index += 1) {
+    result[index] = arrayLike[index];
+  }
+  return result;
+}

package/src/validation/__tests__/address.test.ts

@@ -0,0 +1,267 @@
+// Import the mocked StrKey for use in tests
+import { StrKey } from '@stellar/stellar-sdk';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import {
+  isValidAccountAddress,
+  isValidAddress,
+  isValidContractAddress,
+  isValidMuxedAddress,
+  isValidSecretSeed,
+  isValidSignedPayloadAddress,
+  type StellarAddressType,
+} from '../address';
+
+// Mock StrKey from stellar-sdk
+vi.mock('@stellar/stellar-sdk', () => ({
+  StrKey: {
+    isValidEd25519PublicKey: vi.fn(),
+    isValidContract: vi.fn(),
+    isValidMed25519PublicKey: vi.fn(),
+    isValidEd25519SecretSeed: vi.fn(),
+    isValidSignedPayload: vi.fn(),
+    decodePreAuthTx: vi.fn(),
+    decodeSha256Hash: vi.fn(),
+  },
+}));
+
+const mockStrKey = StrKey as unknown as {
+  isValidEd25519PublicKey: ReturnType<typeof vi.fn>;
+  isValidContract: ReturnType<typeof vi.fn>;
+  isValidMed25519PublicKey: ReturnType<typeof vi.fn>;
+  isValidEd25519SecretSeed: ReturnType<typeof vi.fn>;
+  isValidSignedPayload: ReturnType<typeof vi.fn>;
+  decodePreAuthTx: ReturnType<typeof vi.fn>;
+  decodeSha256Hash: ReturnType<typeof vi.fn>;
+};
+
+describe('Specific validation functions', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe('isValidAccountAddress', () => {
+    it('should return true for valid account address (G...)', () => {
+      const accountAddress = 'GDQP2KPQGKIHYJGXNUIYOMHARUARCA7DJT5FO2FFOOKY3B2WSQHG4W37';
+      mockStrKey.isValidEd25519PublicKey.mockReturnValue(true);
+
+      const result = isValidAccountAddress(accountAddress);
+
+      expect(result).toBe(true);
+      expect(mockStrKey.isValidEd25519PublicKey).toHaveBeenCalledWith(accountAddress);
+    });
+
+    it('should return false for invalid account address', () => {
+      const invalidAddress = 'INVALID_ACCOUNT';
+      mockStrKey.isValidEd25519PublicKey.mockReturnValue(false);
+
+      const result = isValidAccountAddress(invalidAddress);
+
+      expect(result).toBe(false);
+    });
+  });
+
+  describe('isValidContractAddress', () => {
+    it('should return true for valid contract address (C...)', () => {
+      const contractAddress = 'CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQAUHKENIFEJ';
+      mockStrKey.isValidContract.mockReturnValue(true);
+
+      const result = isValidContractAddress(contractAddress);
+
+      expect(result).toBe(true);
+      expect(mockStrKey.isValidContract).toHaveBeenCalledWith(contractAddress);
+    });
+  });
+
+  describe('isValidMuxedAddress', () => {
+    it('should return true for valid muxed address (M...)', () => {
+      const muxedAddress = 'MDQP2KPQGKIHYJGXNUIYOMHARUARCA7DJT5FO2FFOOKY3B2WSQHG4W37AAAAAAAAAAAA';
+      mockStrKey.isValidMed25519PublicKey.mockReturnValue(true);
+
+      const result = isValidMuxedAddress(muxedAddress);
+
+      expect(result).toBe(true);
+      expect(mockStrKey.isValidMed25519PublicKey).toHaveBeenCalledWith(muxedAddress);
+    });
+  });
+
+  describe('isValidSecretSeed', () => {
+    it('should return true for valid secret seed (S...)', () => {
+      const secretSeed = 'SDQP2KPQGKIHYJGXNUIYOMHARUARCA7DJT5FO2FFOOKY3B2WSQHG4W37';
+      mockStrKey.isValidEd25519SecretSeed.mockReturnValue(true);
+
+      const result = isValidSecretSeed(secretSeed);
+
+      expect(result).toBe(true);
+      expect(mockStrKey.isValidEd25519SecretSeed).toHaveBeenCalledWith(secretSeed);
+    });
+  });
+
+  describe('isValidSignedPayloadAddress', () => {
+    it('should return true for valid signed payload address (P...)', () => {
+      const signedPayload = 'PDQP2KPQGKIHYJGXNUIYOMHARUARCA7DJT5FO2FFOOKY3B2WSQHG4W37';
+      mockStrKey.isValidSignedPayload.mockReturnValue(true);
+
+      const result = isValidSignedPayloadAddress(signedPayload);
+
+      expect(result).toBe(true);
+      expect(mockStrKey.isValidSignedPayload).toHaveBeenCalledWith(signedPayload);
+    });
+  });
+});
+
+describe('isValidAddress (main function)', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe('without specific type (validates common types)', () => {
+    it('should return true for valid account address (G...)', () => {
+      const accountAddress = 'GDQP2KPQGKIHYJGXNUIYOMHARUARCA7DJT5FO2FFOOKY3B2WSQHG4W37';
+      mockStrKey.isValidEd25519PublicKey.mockReturnValue(true);
+      mockStrKey.isValidContract.mockReturnValue(false);
+      mockStrKey.isValidMed25519PublicKey.mockReturnValue(false);
+
+      const result = isValidAddress(accountAddress);
+
+      expect(result).toBe(true);
+    });
+
+    it('should return true for valid contract address (C...)', () => {
+      const contractAddress = 'CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQAUHKENIFEJ';
+      mockStrKey.isValidEd25519PublicKey.mockReturnValue(false);
+      mockStrKey.isValidContract.mockReturnValue(true);
+      mockStrKey.isValidMed25519PublicKey.mockReturnValue(false);
+
+      const result = isValidAddress(contractAddress);
+
+      expect(result).toBe(true);
+    });
+
+    it('should return true for valid muxed address (M...)', () => {
+      const muxedAddress = 'MDQP2KPQGKIHYJGXNUIYOMHARUARCA7DJT5FO2FFOOKY3B2WSQHG4W37AAAAAAAAAAAA';
+      mockStrKey.isValidEd25519PublicKey.mockReturnValue(false);
+      mockStrKey.isValidContract.mockReturnValue(false);
+      mockStrKey.isValidMed25519PublicKey.mockReturnValue(true);
+
+      const result = isValidAddress(muxedAddress);
+
+      expect(result).toBe(true);
+    });
+
+    it('should return false for secret seeds (security)', () => {
+      const secretSeed = 'SDQP2KPQGKIHYJGXNUIYOMHARUARCA7DJT5FO2FFOOKY3B2WSQHG4W37';
+      mockStrKey.isValidEd25519PublicKey.mockReturnValue(false);
+      mockStrKey.isValidContract.mockReturnValue(false);
+      mockStrKey.isValidMed25519PublicKey.mockReturnValue(false);
+
+      const result = isValidAddress(secretSeed);
+
+      expect(result).toBe(false);
+      // Secret validation should NOT be called for security
+      expect(mockStrKey.isValidEd25519SecretSeed).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('with specific address type', () => {
+    it('should validate only account type when specified', () => {
+      const accountAddress = 'GDQP2KPQGKIHYJGXNUIYOMHARUARCA7DJT5FO2FFOOKY3B2WSQHG4W37';
+      mockStrKey.isValidEd25519PublicKey.mockReturnValue(true);
+
+      const result = isValidAddress(accountAddress, 'account');
+
+      expect(result).toBe(true);
+      expect(mockStrKey.isValidEd25519PublicKey).toHaveBeenCalledWith(accountAddress);
+      // Other validation methods should not be called
+      expect(mockStrKey.isValidContract).not.toHaveBeenCalled();
+    });
+
+    it('should validate only contract type when specified', () => {
+      const contractAddress = 'CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQAUHKENIFEJ';
+      mockStrKey.isValidContract.mockReturnValue(true);
+
+      const result = isValidAddress(contractAddress, 'contract');
+
+      expect(result).toBe(true);
+      expect(mockStrKey.isValidContract).toHaveBeenCalledWith(contractAddress);
+      // Other validation methods should not be called
+      expect(mockStrKey.isValidEd25519PublicKey).not.toHaveBeenCalled();
+    });
+
+    it('should validate only muxed type when specified', () => {
+      const muxedAddress = 'MDQP2KPQGKIHYJGXNUIYOMHARUARCA7DJT5FO2FFOOKY3B2WSQHG4W37AAAAAAAAAAAA';
+      mockStrKey.isValidMed25519PublicKey.mockReturnValue(true);
+
+      const result = isValidAddress(muxedAddress, 'muxed');
+
+      expect(result).toBe(true);
+      expect(mockStrKey.isValidMed25519PublicKey).toHaveBeenCalledWith(muxedAddress);
+    });
+
+    it('should validate secret seeds when specifically requested', () => {
+      const secretSeed = 'SDQP2KPQGKIHYJGXNUIYOMHARUARCA7DJT5FO2FFOOKY3B2WSQHG4W37';
+      mockStrKey.isValidEd25519SecretSeed.mockReturnValue(true);
+
+      const result = isValidAddress(secretSeed, 'secret');
+
+      expect(result).toBe(true);
+      expect(mockStrKey.isValidEd25519SecretSeed).toHaveBeenCalledWith(secretSeed);
+    });
+
+    it('should validate pre-auth-tx when specified', () => {
+      const preAuthTx = 'TDQP2KPQGKIHYJGXNUIYOMHARUARCA7DJT5FO2FFOOKY3B2WSQHG4W37';
+      mockStrKey.decodePreAuthTx.mockReturnValue(new Uint8Array([1, 2, 3, 4]));
+
+      const result = isValidAddress(preAuthTx, 'pre-auth-tx');
+
+      expect(result).toBe(true);
+      expect(mockStrKey.decodePreAuthTx).toHaveBeenCalledWith(preAuthTx);
+    });
+
+    it('should validate hash-x when specified', () => {
+      const hashX = 'XDQP2KPQGKIHYJGXNUIYOMHARUARCA7DJT5FO2FFOOKY3B2WSQHG4W37';
+      mockStrKey.decodeSha256Hash.mockReturnValue(new Uint8Array([1, 2, 3, 4]));
+
+      const result = isValidAddress(hashX, 'hash-x');
+
+      expect(result).toBe(true);
+      expect(mockStrKey.decodeSha256Hash).toHaveBeenCalledWith(hashX);
+    });
+
+    it('should return false for unknown address type', () => {
+      const address = 'GDQP2KPQGKIHYJGXNUIYOMHARUARCA7DJT5FO2FFOOKY3B2WSQHG4W37';
+
+      const result = isValidAddress(address, 'unknown' as StellarAddressType);
+
+      expect(result).toBe(false);
+    });
+  });
+
+  describe('edge cases', () => {
+    it('should return false for empty string', () => {
+      const result = isValidAddress('');
+      expect(result).toBe(false);
+    });
+
+    it('should return false for null/undefined input', () => {
+      // @ts-expect-error Testing invalid input
+      const resultNull = isValidAddress(null);
+      // @ts-expect-error Testing invalid input
+      const resultUndefined = isValidAddress(undefined);
+
+      expect(resultNull).toBe(false);
+      expect(resultUndefined).toBe(false);
+    });
+
+    it('should handle exceptions gracefully', () => {
+      const address = 'MALFORMED_ADDRESS';
+      mockStrKey.isValidEd25519PublicKey.mockImplementation(() => {
+        throw new Error('Invalid format');
+      });
+
+      const result = isValidAddress(address);
+
+      expect(result).toBe(false);
+    });
+  });
+});

package/src/validation/address.ts

@@ -0,0 +1,136 @@
+import { StrKey } from '@stellar/stellar-sdk';
+
+/**
+ * Stellar address types supported by the validation functions
+ */
+export type StellarAddressType =
+  | 'account' // G... - Ed25519 public keys (standard account addresses)
+  | 'contract' // C... - Contract addresses
+  | 'muxed' // M... - Muxed account addresses (for exchanges/sub-accounts)
+  | 'secret' // S... - Secret seeds (private keys)
+  | 'signed-payload' // P... - Signed payload addresses
+  | 'pre-auth-tx' // T... - Pre-authorized transaction hashes
+  | 'hash-x'; // X... - Hash-x condition addresses
+
+/**
+ * Validate a standard Stellar account address (Ed25519 public key starting with 'G')
+ * @param address The address to validate
+ * @returns Whether the address is a valid account address
+ */
+export function isValidAccountAddress(address: string): boolean {
+  try {
+    return StrKey.isValidEd25519PublicKey(address);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Validate a Stellar contract address (starting with 'C')
+ * @param address The address to validate
+ * @returns Whether the address is a valid contract address
+ */
+export function isValidContractAddress(address: string): boolean {
+  try {
+    return StrKey.isValidContract(address);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Validate a Stellar muxed account address (starting with 'M')
+ * @param address The address to validate
+ * @returns Whether the address is a valid muxed account address
+ */
+export function isValidMuxedAddress(address: string): boolean {
+  try {
+    return StrKey.isValidMed25519PublicKey(address);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Validate a Stellar secret seed (private key starting with 'S')
+ * @param seed The secret seed to validate
+ * @returns Whether the seed is a valid secret seed
+ */
+export function isValidSecretSeed(seed: string): boolean {
+  try {
+    return StrKey.isValidEd25519SecretSeed(seed);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Validate a signed payload address (starting with 'P')
+ * @param address The address to validate
+ * @returns Whether the address is a valid signed payload address
+ */
+export function isValidSignedPayloadAddress(address: string): boolean {
+  try {
+    return StrKey.isValidSignedPayload(address);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Main validation function that supports all Stellar address types
+ * @param address The address to validate
+ * @param addressType Optional specific address type to validate
+ * @returns Whether the address is valid for the specified or any supported type
+ */
+export function isValidAddress(address: string, addressType?: StellarAddressType): boolean {
+  if (!address || typeof address !== 'string') {
+    return false;
+  }
+
+  // If specific type is requested, validate only that type
+  if (addressType) {
+    switch (addressType) {
+      case 'account':
+        return isValidAccountAddress(address);
+      case 'contract':
+        return isValidContractAddress(address);
+      case 'muxed':
+        return isValidMuxedAddress(address);
+      case 'secret':
+        return isValidSecretSeed(address);
+      case 'signed-payload':
+        return isValidSignedPayloadAddress(address);
+      case 'pre-auth-tx':
+        try {
+          // Pre-auth transactions start with 'T' - validate by trying to decode
+          StrKey.decodePreAuthTx(address);
+          return true;
+        } catch {
+          return false;
+        }
+      case 'hash-x':
+        try {
+          // Hash-x conditions start with 'X' - validate by trying to decode
+          StrKey.decodeSha256Hash(address);
+          return true;
+        } catch {
+          return false;
+        }
+      default:
+        return false;
+    }
+  }
+
+  // If no specific type requested, validate against common address types
+  // (excluding secrets and special-purpose addresses for security)
+  try {
+    return (
+      StrKey.isValidEd25519PublicKey(address) || // G... - accounts (most common)
+      StrKey.isValidContract(address) || // C... - contracts
+      StrKey.isValidMed25519PublicKey(address) // M... - muxed accounts
+    );
+  } catch {
+    return false;
+  }
+}

package/src/validation/eoa.ts

@@ -0,0 +1,33 @@
+import { EoaExecutionConfig } from '@openzeppelin/ui-types';
+import { logger } from '@openzeppelin/ui-utils';
+
+import { StellarWalletConnectionStatus } from '../wallet/types';
+import { isValidAddress } from './address';
+
+const SYSTEM_LOG_TAG = 'StellarEoaValidator';
+
+export async function validateEoaConfig(
+  config: EoaExecutionConfig,
+  walletStatus: StellarWalletConnectionStatus
+): Promise<true | string> {
+  if (!config.allowAny) {
+    if (!config.specificAddress) {
+      return "EOA execution selected, but no specific address was provided when 'allowAny' is false.";
+    }
+    if (!isValidAddress(config.specificAddress)) {
+      return `Invalid specific Stellar address format: ${config.specificAddress}`;
+    }
+    if (walletStatus.isConnected && walletStatus.address) {
+      if (walletStatus.address !== config.specificAddress) {
+        return `Connected wallet address (${walletStatus.address}) does not match the required specific Stellar address (${config.specificAddress}). Please connect the correct wallet.`;
+      }
+    } else if (walletStatus.isConnected && !walletStatus.address) {
+      logger.warn(
+        SYSTEM_LOG_TAG,
+        'Wallet is connected but address is unavailable for Stellar EOA validation.'
+      );
+      return 'Connected wallet address is not available for validation against specific Stellar address.';
+    }
+  }
+  return true;
+}

package/src/validation/index.ts

@@ -0,0 +1,3 @@
+export * from './address';
+export * from './eoa';
+export * from './relayer';

package/src/validation/relayer.ts

@@ -0,0 +1,13 @@
+import { RelayerExecutionConfig } from '@openzeppelin/ui-types';
+
+export async function validateRelayerConfig(
+  config: RelayerExecutionConfig
+): Promise<true | string> {
+  if (!config.serviceUrl) {
+    return 'Relayer execution selected, but no service URL was provided.';
+  }
+  if (!config.relayer?.relayerId) {
+    return 'Relayer execution selected, but no relayer was chosen from the list.';
+  }
+  return true;
+}