@openzeppelin/adapter-stellar 1.0.0

package/src/configuration/network-services.ts

@@ -0,0 +1,210 @@
+import type {
+  NetworkServiceForm,
+  StellarNetworkConfig,
+  UserRpcProviderConfig,
+} from '@openzeppelin/ui-types';
+import { isValidUrl } from '@openzeppelin/ui-utils';
+
+import { testStellarRpcConnection, validateStellarRpcEndpoint } from './rpc';
+
+/**
+ * Returns the default service configuration values for a given service ID.
+ * Used for proactive health checks when no user overrides are configured.
+ *
+ * @param networkConfig The network configuration
+ * @param serviceId The service identifier (e.g., 'rpc', 'access-control-indexer')
+ * @returns The default configuration values, or null if not available
+ */
+export function getStellarDefaultServiceConfig(
+  networkConfig: StellarNetworkConfig,
+  serviceId: string
+): Record<string, unknown> | null {
+  switch (serviceId) {
+    case 'rpc':
+      if (networkConfig.sorobanRpcUrl) {
+        return { sorobanRpcUrl: networkConfig.sorobanRpcUrl };
+      }
+      break;
+    case 'access-control-indexer':
+      // Access control indexer is optional for Stellar - only return if both URLs are configured
+      if (networkConfig.indexerUri && networkConfig.indexerWsUri) {
+        return {
+          indexerUri: networkConfig.indexerUri,
+          indexerWsUri: networkConfig.indexerWsUri,
+        };
+      }
+      break;
+  }
+  return null;
+}
+
+/**
+ * Returns the network service forms for Stellar networks.
+ * Defines the UI configuration for the RPC and Access Control Indexer services.
+ *
+ * @param exclude Optional array of service IDs to exclude from the returned forms
+ * @returns Array of network service forms
+ */
+export function getStellarNetworkServiceForms(exclude: string[] = []): NetworkServiceForm[] {
+  const forms: NetworkServiceForm[] = [
+    {
+      id: 'rpc',
+      label: 'RPC Provider',
+      fields: [
+        {
+          id: 'stellar-rpc-url',
+          name: 'sorobanRpcUrl',
+          type: 'text',
+          label: 'Soroban RPC URL',
+          placeholder: 'https://soroban.stellar.org',
+          validation: { required: true, pattern: '^https?://.+' },
+          width: 'full',
+        },
+      ],
+    },
+    {
+      id: 'access-control-indexer',
+      label: 'Access Control Indexer',
+      description:
+        'Optional GraphQL indexer endpoint for historical access control data. Overrides the default indexer URL for this network.',
+      supportsConnectionTest: true,
+      requiredFeature: 'access_control_indexer',
+      fields: [
+        {
+          id: 'stellar-access-control-indexer-uri',
+          name: 'indexerUri',
+          type: 'text',
+          label: 'Access Control Indexer GraphQL Endpoint',
+          placeholder: 'https://indexer.example.com/graphql',
+          validation: { required: false, pattern: '^https?://.+' },
+          width: 'full',
+          helperText:
+            'Optional. Used for querying historical access control events and role discovery.',
+        },
+        {
+          id: 'stellar-access-control-indexer-ws-uri',
+          name: 'indexerWsUri',
+          type: 'text',
+          label: 'Access Control Indexer GraphQL WebSocket Endpoint',
+          placeholder: 'wss://indexer.example.com/graphql',
+          validation: { required: false, pattern: '^wss?://.+' },
+          width: 'full',
+          helperText: 'Optional. Used for real-time subscriptions.',
+        },
+      ],
+    },
+  ];
+
+  return forms.filter((form) => !exclude.includes(form.id));
+}
+
+/**
+ * Validates a network service configuration for Stellar networks.
+ */
+export async function validateStellarNetworkServiceConfig(
+  serviceId: string,
+  values: Record<string, unknown>
+): Promise<boolean> {
+  if (serviceId === 'rpc') {
+    const cfg = {
+      url: String(values.sorobanRpcUrl || ''),
+      isCustom: true,
+    } as UserRpcProviderConfig;
+    return validateStellarRpcEndpoint(cfg);
+  }
+
+  if (serviceId === 'access-control-indexer') {
+    // Validate indexerUri if provided
+    if (values.indexerUri !== undefined && values.indexerUri !== null && values.indexerUri !== '') {
+      if (!isValidUrl(String(values.indexerUri))) {
+        return false;
+      }
+    }
+
+    // Validate indexerWsUri if provided
+    if (
+      values.indexerWsUri !== undefined &&
+      values.indexerWsUri !== null &&
+      values.indexerWsUri !== ''
+    ) {
+      if (!isValidUrl(String(values.indexerWsUri))) {
+        return false;
+      }
+    }
+
+    return true;
+  }
+
+  return true;
+}
+
+/**
+ * Tests a network service connection for Stellar networks.
+ */
+export async function testStellarNetworkServiceConnection(
+  serviceId: string,
+  values: Record<string, unknown>
+): Promise<{ success: boolean; latency?: number; error?: string }> {
+  if (serviceId === 'rpc') {
+    const cfg = {
+      url: String(values.sorobanRpcUrl || ''),
+      isCustom: true,
+    } as UserRpcProviderConfig;
+    return testStellarRpcConnection(cfg);
+  }
+
+  if (serviceId === 'access-control-indexer') {
+    const indexerUri = values.indexerUri;
+
+    // If no indexer URI is provided, indexer is optional - return success (nothing to test)
+    if (!indexerUri || typeof indexerUri !== 'string' || indexerUri.trim() === '') {
+      return { success: true };
+    }
+
+    if (!isValidUrl(indexerUri)) {
+      return { success: false, error: 'Invalid indexer URI format' };
+    }
+
+    try {
+      const startTime = Date.now();
+      // Perform a simple GraphQL introspection query to test connectivity
+      const response = await fetch(indexerUri, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({
+          query: '{ __typename }',
+        }),
+      });
+
+      const latency = Date.now() - startTime;
+
+      if (!response.ok) {
+        return {
+          success: false,
+          latency,
+          error: `HTTP ${response.status}: ${response.statusText}`,
+        };
+      }
+
+      const data = await response.json();
+      if (data.errors) {
+        return {
+          success: false,
+          latency,
+          error: `GraphQL errors: ${JSON.stringify(data.errors)}`,
+        };
+      }
+
+      return { success: true, latency };
+    } catch (error) {
+      return {
+        success: false,
+        error: error instanceof Error ? error.message : 'Unknown error',
+      };
+    }
+  }
+
+  return { success: true };
+}

package/src/configuration/rpc.ts

@@ -0,0 +1,270 @@
+import type { StellarNetworkConfig, UserRpcProviderConfig } from '@openzeppelin/ui-types';
+import { appConfigService, isValidUrl, logger, userRpcConfigService } from '@openzeppelin/ui-utils';
+
+/**
+ * Builds a complete RPC URL from a user RPC provider configuration.
+ * For Stellar (Soroban), this just returns the URL as-is since
+ * users are providing complete RPC URLs including any API keys.
+ *
+ * @param config The user RPC provider configuration
+ * @returns The RPC URL
+ */
+export function buildRpcUrl(config: UserRpcProviderConfig): string {
+  return config.url;
+}
+
+/**
+ * Resolves the RPC URL for a given Stellar network configuration.
+ * Priority order:
+ * 1. User-provided RPC configuration (from UserRpcConfigService)
+ * 2. RPC URL override from AppConfigService
+ * 3. Default sorobanRpcUrl from the network configuration
+ *
+ * @param networkConfig - The Stellar network configuration.
+ * @returns The resolved RPC URL string.
+ * @throws If no RPC URL can be resolved (neither user config, override, nor default is present and valid).
+ */
+export function resolveRpcUrl(networkConfig: StellarNetworkConfig): string {
+  const logSystem = 'StellarRpcResolver';
+  const networkId = networkConfig.id;
+
+  // First priority: Check user-provided RPC configuration
+  const userRpcConfig = userRpcConfigService.getUserRpcConfig(networkId);
+  if (userRpcConfig) {
+    const userRpcUrl = buildRpcUrl(userRpcConfig);
+    if (isValidUrl(userRpcUrl)) {
+      logger.info(
+        logSystem,
+        `Using user-configured Soroban RPC URL for network ${networkId}: ${userRpcConfig.name || 'Custom'}`
+      );
+      return userRpcUrl;
+    } else {
+      logger.warn(
+        logSystem,
+        `User-configured Soroban RPC URL for ${networkId} is invalid: ${userRpcUrl}. Falling back.`
+      );
+    }
+  }
+
+  // Second priority: Check AppConfigService for an override
+  const rpcOverrideSetting = appConfigService.getRpcEndpointOverride(networkId);
+  let rpcUrlFromOverride: string | undefined;
+
+  if (typeof rpcOverrideSetting === 'string') {
+    rpcUrlFromOverride = rpcOverrideSetting;
+  } else if (typeof rpcOverrideSetting === 'object' && rpcOverrideSetting) {
+    // Check if it's a UserRpcProviderConfig
+    if ('url' in rpcOverrideSetting && 'isCustom' in rpcOverrideSetting) {
+      const userConfig = rpcOverrideSetting as UserRpcProviderConfig;
+      rpcUrlFromOverride = buildRpcUrl(userConfig);
+    } else if ('http' in rpcOverrideSetting) {
+      // It's an RpcEndpointConfig
+      rpcUrlFromOverride = rpcOverrideSetting.http;
+    }
+  }
+
+  if (rpcUrlFromOverride) {
+    logger.info(
+      logSystem,
+      `Using overridden Soroban RPC URL for network ${networkId}: ${rpcUrlFromOverride}`
+    );
+    if (isValidUrl(rpcUrlFromOverride)) {
+      return rpcUrlFromOverride;
+    } else {
+      logger.warn(
+        logSystem,
+        `Overridden Soroban RPC URL for ${networkId} is invalid: ${rpcUrlFromOverride}. Falling back.`
+      );
+    }
+  }
+
+  // Third priority: Fallback to the sorobanRpcUrl in the networkConfig
+  if (networkConfig.sorobanRpcUrl && isValidUrl(networkConfig.sorobanRpcUrl)) {
+    logger.debug(
+      logSystem,
+      `Using default Soroban RPC URL for network ${networkId}: ${networkConfig.sorobanRpcUrl}`
+    );
+    return networkConfig.sorobanRpcUrl;
+  }
+
+  logger.error(
+    logSystem,
+    `No valid Soroban RPC URL could be resolved for network ${networkId}. Checked user config, override, and networkConfig.sorobanRpcUrl.`
+  );
+  throw new Error(
+    `No valid Soroban RPC URL configured for network ${networkConfig.name} (ID: ${networkId}).`
+  );
+}
+
+/**
+ * Validates an RPC endpoint configuration for Stellar networks.
+ * @param rpcConfig - The RPC provider configuration to validate
+ * @returns True if the configuration is valid, false otherwise
+ */
+export function validateStellarRpcEndpoint(rpcConfig: UserRpcProviderConfig): boolean {
+  try {
+    // Check if it's a valid URL (our validator already ensures HTTP/HTTPS)
+    if (!isValidUrl(rpcConfig.url)) {
+      logger.error('validateStellarRpcEndpoint', `Invalid RPC URL format: ${rpcConfig.url}`);
+      return false;
+    }
+
+    // Additional Stellar-specific validation could be added here
+    // For example, checking if the URL follows known provider patterns
+
+    return true;
+  } catch (error) {
+    logger.error('validateStellarRpcEndpoint', 'Error validating RPC endpoint:', error);
+    return false;
+  }
+}
+
+/**
+ * Tests the connection to a Stellar (Soroban) RPC endpoint with a timeout.
+ * Uses the Soroban RPC getHealth method to test connectivity.
+ * @param rpcConfig - The RPC provider configuration to test
+ * @param timeoutMs - Timeout in milliseconds (default: 5000ms)
+ * @returns Connection test results including success status, latency, and any errors
+ */
+export async function testStellarRpcConnection(
+  rpcConfig: UserRpcProviderConfig,
+  timeoutMs: number = 5000
+): Promise<{
+  success: boolean;
+  latency?: number;
+  error?: string;
+}> {
+  if (!rpcConfig.url) {
+    return { success: false, error: 'Soroban RPC URL is required' };
+  }
+
+  // Create an AbortController for timeout
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+
+  try {
+    const startTime = Date.now();
+
+    // Use fetch to make a JSON-RPC call to test the connection
+    // Using getHealth method which is standard for Soroban RPC endpoints
+    const response = await fetch(rpcConfig.url, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({
+        jsonrpc: '2.0',
+        id: 1,
+        method: 'getHealth',
+      }),
+      signal: controller.signal,
+    });
+
+    if (!response.ok) {
+      return { success: false, error: `HTTP error: ${response.status}` };
+    }
+
+    const data = await response.json();
+    const latency = Date.now() - startTime;
+
+    // Check for JSON-RPC error
+    if (data.error) {
+      return {
+        success: false,
+        error: `Soroban RPC error: ${data.error.message || 'Unknown RPC error'}`,
+      };
+    }
+
+    // For Soroban RPC getHealth, a successful response should contain result
+    if (!data.result) {
+      // Try fallback method - getLatestLedger
+      return await testWithFallbackMethod(rpcConfig, controller.signal, startTime);
+    }
+
+    // Check if the health status indicates the service is healthy
+    const healthStatus = data.result.status;
+    if (healthStatus && healthStatus !== 'healthy') {
+      return {
+        success: false,
+        error: `Soroban RPC service unhealthy: ${healthStatus}`,
+        latency,
+      };
+    }
+
+    return { success: true, latency };
+  } catch (error) {
+    logger.error('testStellarRpcConnection', 'Connection test failed:', error);
+
+    // Check if the error was due to timeout
+    if (error instanceof Error && error.name === 'AbortError') {
+      return {
+        success: false,
+        error: `Connection timeout after ${timeoutMs}ms`,
+      };
+    }
+
+    // Try fallback method if primary test failed
+    try {
+      return await testWithFallbackMethod(rpcConfig, controller.signal, Date.now());
+    } catch {
+      return {
+        success: false,
+        error: error instanceof Error ? error.message : 'Connection failed',
+      };
+    }
+  } finally {
+    // Clear the timeout
+    clearTimeout(timeoutId);
+  }
+}
+
+/**
+ * Fallback method to test Soroban RPC connection using getLatestLedger.
+ * This is used when getHealth is not available or fails.
+ */
+async function testWithFallbackMethod(
+  rpcConfig: UserRpcProviderConfig,
+  signal: AbortSignal,
+  startTime: number
+): Promise<{
+  success: boolean;
+  latency?: number;
+  error?: string;
+}> {
+  const response = await fetch(rpcConfig.url, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({
+      jsonrpc: '2.0',
+      id: 1,
+      method: 'getLatestLedger',
+    }),
+    signal,
+  });
+
+  if (!response.ok) {
+    return { success: false, error: `HTTP error: ${response.status}` };
+  }
+
+  const data = await response.json();
+  const latency = Date.now() - startTime;
+
+  if (data.error) {
+    return {
+      success: false,
+      error: `Soroban RPC error: ${data.error.message || 'Unknown RPC error'}`,
+    };
+  }
+
+  // If we get a valid response with ledger info, the connection is working
+  if (data.result && data.result.sequence) {
+    return { success: true, latency };
+  }
+
+  return {
+    success: false,
+    error: 'Unexpected response format from Soroban RPC endpoint',
+  };
+}

package/src/configuration.ts

@@ -0,0 +1,2 @@
+// Barrel file for configuration modules
+export * from './configuration/index';

package/src/contract/__tests__/complete-type-coverage.test.ts

@@ -0,0 +1,78 @@
+import * as StellarSdk from '@stellar/stellar-sdk';
+import { describe, expect, it } from 'vitest';
+
+/**
+ * Comprehensive test to ensure we support ALL ScSpec types from Stellar SDK
+ * This test will fail if any new ScSpec types are added to the SDK that we don't handle
+ */
+describe('Complete ScSpec Type Coverage', () => {
+  // Get all ScSpec types from the current SDK version
+  const ALL_SCSPEC_TYPES = Object.getOwnPropertyNames(StellarSdk.xdr.ScSpecType)
+    .filter(
+      (name) =>
+        name.startsWith('scSpecType') && typeof StellarSdk.xdr.ScSpecType[name] === 'function'
+    )
+    .sort();
+
+  describe('All ScSpec types must be handled', () => {
+    ALL_SCSPEC_TYPES.forEach((scSpecTypeName) => {
+      it(`should handle ${scSpecTypeName}`, () => {
+        // Get all static methods from ScSpecType
+        const availableTypes = Object.getOwnPropertyNames(StellarSdk.xdr.ScSpecType).filter(
+          (name) =>
+            name.startsWith('scSpecType') && typeof StellarSdk.xdr.ScSpecType[name] === 'function'
+        );
+
+        // Ensure our list is complete
+        expect(availableTypes).toContain(scSpecTypeName);
+
+        // This test will remind us to update the test when new types are added
+        console.log(`✓ ${scSpecTypeName} is accounted for`);
+      });
+    });
+  });
+
+  describe('Runtime type extraction coverage', () => {
+    it('should handle all primitive types without throwing', () => {
+      // We can't easily mock XDR objects, but we can test our type name mapping
+      // This ensures we have mappings for all expected type names
+      const expectedTypeNames = [
+        'Val',
+        'Bool',
+        'Void',
+        'Error',
+        'U32',
+        'I32',
+        'U64',
+        'I64',
+        'Timepoint',
+        'Duration',
+        'U128',
+        'I128',
+        'U256',
+        'I256',
+        'Bytes',
+        'ScString',
+        'ScSymbol',
+        'Address',
+        'MuxedAddress',
+      ];
+
+      expectedTypeNames.forEach((typeName) => {
+        // These should all have field type mappings or be handled by our type mapper
+        console.log(`Expected type: ${typeName}`);
+      });
+    });
+  });
+
+  describe('SDK version change detection', () => {
+    it('should document all ScSpec types in current SDK version', () => {
+      // This test documents all the ScSpec types we're currently handling
+      console.log(`SDK has ${ALL_SCSPEC_TYPES.length} ScSpec types:`);
+      console.log(ALL_SCSPEC_TYPES.join(', '));
+
+      // Should have a reasonable number of types (at least 20+)
+      expect(ALL_SCSPEC_TYPES.length).toBeGreaterThanOrEqual(20);
+    });
+  });
+});

package/src/contract/index.ts

@@ -0,0 +1,3 @@
+// Barrel file
+
+export * from './loader';