@openzeppelin/adapter-stellar 1.0.0

package/src/wallet/utils/__tests__/uiKitService.test.ts

@@ -0,0 +1,189 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import type { UiKitConfiguration, UiKitName } from '@openzeppelin/ui-types';
+
+import { CustomAccountDisplay, CustomConnectButton } from '../../components';
+import { getResolvedWalletComponents } from '../uiKitService';
+
+// Mock the stellar-wallets-kit before any imports that might use it
+vi.mock('@creit.tech/stellar-wallets-kit', () => ({
+  StellarWalletsKit: vi.fn(),
+  WalletNetwork: {
+    PUBLIC: 'PUBLIC',
+    TESTNET: 'TESTNET',
+  },
+  allowAllModules: vi.fn(() => ({})),
+}));
+
+// Mock the filterWalletComponents module
+vi.mock('../filterWalletComponents', () => ({
+  filterWalletComponents: vi.fn((components, exclusions) => {
+    // Simple mock implementation
+    if (!components || Object.keys(components).length === 0) return undefined;
+    if (exclusions.length === 0) return components;
+
+    const filtered: Record<string, unknown> = {};
+    for (const key in components) {
+      if (!exclusions.includes(key)) {
+        filtered[key] = components[key];
+      }
+    }
+    return Object.keys(filtered).length > 0 ? filtered : undefined;
+  }),
+  getComponentExclusionsFromConfig: vi.fn((config) => {
+    return config?.components?.exclude || [];
+  }),
+}));
+
+describe('uiKitService', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe('getResolvedWalletComponents', () => {
+    it('should return undefined for "none" kit', () => {
+      const config: UiKitConfiguration = {
+        kitName: 'none',
+        kitConfig: {},
+      };
+
+      const result = getResolvedWalletComponents(config);
+      expect(result).toBeUndefined();
+    });
+
+    it('should return custom components for "custom" kit', () => {
+      const config: UiKitConfiguration = {
+        kitName: 'custom',
+        kitConfig: {},
+      };
+
+      const result = getResolvedWalletComponents(config);
+
+      expect(result).toBeDefined();
+      expect(result?.ConnectButton).toBe(CustomConnectButton);
+      expect(result?.AccountDisplay).toBe(CustomAccountDisplay);
+      expect(result?.NetworkSwitcher).toBeUndefined(); // Stellar doesn't have NetworkSwitcher
+    });
+
+    it('should return built-in UI components for "stellar-wallets-kit" kit', () => {
+      const config: UiKitConfiguration = {
+        kitName: 'stellar-wallets-kit',
+        kitConfig: {},
+      };
+
+      const result = getResolvedWalletComponents(config);
+
+      expect(result).toBeDefined();
+      expect(result?.ConnectButton).toBeDefined();
+      expect(result?.ConnectButton?.name).toBe('StellarWalletsKitConnectButton');
+      expect(result?.AccountDisplay).toBeUndefined(); // Kit handles account display internally
+      expect(result?.NetworkSwitcher).toBeUndefined();
+    });
+
+    it('should apply component exclusions', () => {
+      const config: UiKitConfiguration = {
+        kitName: 'custom',
+        kitConfig: {
+          components: {
+            exclude: ['AccountDisplay'],
+          },
+        },
+      };
+
+      const result = getResolvedWalletComponents(config);
+
+      expect(result).toBeDefined();
+      expect(result?.ConnectButton).toBe(CustomConnectButton);
+      expect(result?.AccountDisplay).toBeUndefined();
+    });
+
+    it('should handle all components being excluded', () => {
+      const config: UiKitConfiguration = {
+        kitName: 'custom',
+        kitConfig: {
+          components: {
+            exclude: ['ConnectButton', 'AccountDisplay'],
+          },
+        },
+      };
+
+      const result = getResolvedWalletComponents(config);
+      expect(result).toBeUndefined();
+    });
+
+    it('should return undefined for unsupported kit name', () => {
+      const config: UiKitConfiguration = {
+        kitName: 'unsupported-kit' as UiKitName,
+        kitConfig: {},
+      };
+
+      const result = getResolvedWalletComponents(config);
+      expect(result).toBeUndefined();
+    });
+
+    it('should default to "custom" when kit name is not provided', () => {
+      const config: UiKitConfiguration = {
+        kitName: undefined as unknown as UiKitName,
+        kitConfig: {},
+      };
+
+      const result = getResolvedWalletComponents(config);
+
+      expect(result).toBeDefined();
+      expect(result?.ConnectButton).toBe(CustomConnectButton);
+      expect(result?.AccountDisplay).toBe(CustomAccountDisplay);
+    });
+
+    it('should handle empty kit config for stellar-wallets-kit', () => {
+      const config: UiKitConfiguration = {
+        kitName: 'stellar-wallets-kit',
+        kitConfig: undefined as Record<string, unknown> | undefined,
+      };
+
+      const result = getResolvedWalletComponents(config);
+
+      expect(result).toBeDefined();
+      expect(result?.ConnectButton).toBeDefined();
+      expect(result?.ConnectButton?.name).toBe('StellarWalletsKitConnectButton');
+      expect(result?.AccountDisplay).toBeUndefined();
+    });
+
+    it('should handle complex kit config with exclusions for custom kit', () => {
+      const config: UiKitConfiguration = {
+        kitName: 'custom',
+        kitConfig: {
+          showInjectedConnector: true,
+          appName: 'Test App',
+          components: {
+            exclude: ['ConnectButton'],
+            // Other potential component config
+          },
+        },
+      };
+
+      const result = getResolvedWalletComponents(config);
+
+      expect(result).toBeDefined();
+      expect(result?.ConnectButton).toBeUndefined();
+      expect(result?.AccountDisplay).toBe(CustomAccountDisplay);
+    });
+
+    it('should not apply exclusions to stellar-wallets-kit built-in components', () => {
+      const config: UiKitConfiguration = {
+        kitName: 'stellar-wallets-kit',
+        kitConfig: {
+          components: {
+            exclude: ['ConnectButton'], // Should be ignored
+          },
+        },
+      };
+
+      const result = getResolvedWalletComponents(config);
+
+      expect(result).toBeDefined();
+      // Built-in components are not affected by exclusions
+      expect(result?.ConnectButton).toBeDefined();
+      expect(result?.ConnectButton?.name).toBe('StellarWalletsKitConnectButton');
+    });
+  });
+});

package/src/wallet/utils/filterWalletComponents.ts

@@ -0,0 +1,89 @@
+import type { EcosystemWalletComponents, UiKitConfiguration } from '@openzeppelin/ui-types';
+import { ECOSYSTEM_WALLET_COMPONENT_KEYS } from '@openzeppelin/ui-types';
+import { logger } from '@openzeppelin/ui-utils';
+
+/**
+ * Filters a set of wallet components based on an exclusion list.
+ *
+ * @param allPossibleComponents - An object containing all potential components for a kit.
+ * @param exclusions - An array of component keys to exclude.
+ * @param kitName - The name of the kit being filtered (for logging purposes).
+ * @returns The filtered EcosystemWalletComponents object, or undefined if all components are excluded.
+ */
+export function filterWalletComponents(
+  allPossibleComponents: EcosystemWalletComponents,
+  exclusions: Array<keyof EcosystemWalletComponents>,
+  kitName: string = 'custom' // Default to custom for logging context
+): EcosystemWalletComponents | undefined {
+  logger.debug(
+    'filterWalletComponents',
+    `Filtering components for kit: ${kitName}. Exclusions: ${exclusions.join(', ')}.`
+  );
+  if (!allPossibleComponents || Object.keys(allPossibleComponents).length === 0) {
+    logger.debug('filterWalletComponents', `No components provided to filter for kit: ${kitName}.`);
+    return undefined;
+  }
+
+  if (exclusions.length === 0) {
+    logger.debug(
+      'filterWalletComponents',
+      `Providing all components for kit: ${kitName}.`,
+      allPossibleComponents
+    );
+    return allPossibleComponents;
+  }
+
+  const filteredComponents: Partial<EcosystemWalletComponents> = {};
+  let componentCount = 0;
+  for (const key in allPossibleComponents) {
+    const componentKey = key as keyof EcosystemWalletComponents;
+    if (!exclusions.includes(componentKey)) {
+      if (allPossibleComponents[componentKey]) {
+        // Ensure the component actually exists before adding
+        filteredComponents[componentKey] = allPossibleComponents[componentKey];
+        componentCount++;
+      }
+    }
+  }
+
+  if (componentCount > 0) {
+    logger.debug(
+      'filterWalletComponents',
+      `Providing filtered components for kit: ${kitName} after exclusions (${exclusions.join(', ')}).`,
+      filteredComponents
+    );
+    return filteredComponents as EcosystemWalletComponents;
+  }
+
+  logger.debug('filterWalletComponents', `All components were excluded for kit: ${kitName}.`);
+  return undefined;
+}
+
+/**
+ * Extracts the component exclusion list from a UI kit configuration object.
+ *
+ * @param kitConfig - The `kitConfig` object from `UiKitConfiguration`.
+ * @returns An array of component keys to exclude, or an empty array if none are specified or config is invalid.
+ */
+export function getComponentExclusionsFromConfig(
+  kitConfig: UiKitConfiguration['kitConfig']
+): Array<keyof EcosystemWalletComponents> {
+  if (kitConfig && typeof kitConfig === 'object' && 'components' in kitConfig) {
+    const componentsCfg = kitConfig.components;
+    if (
+      componentsCfg &&
+      typeof componentsCfg === 'object' &&
+      'exclude' in componentsCfg &&
+      Array.isArray(componentsCfg.exclude)
+    ) {
+      // Ensure all elements are valid keys of EcosystemWalletComponents
+      // This provides a bit more type safety at runtime if the config comes from an untyped source
+      return componentsCfg.exclude.filter(
+        (key): key is keyof EcosystemWalletComponents =>
+          typeof key === 'string' &&
+          (ECOSYSTEM_WALLET_COMPONENT_KEYS as readonly string[]).includes(key)
+      ) as Array<keyof EcosystemWalletComponents>;
+    }
+  }
+  return [];
+}

package/src/wallet/utils/index.ts

@@ -0,0 +1,3 @@
+export * from './filterWalletComponents';
+export * from './stellarWalletImplementationManager';
+export * from './uiKitService';

package/src/wallet/utils/stellarWalletImplementationManager.ts

@@ -0,0 +1,118 @@
+import type { StellarNetworkConfig, UiKitConfiguration } from '@openzeppelin/ui-types';
+import { appConfigService, logger } from '@openzeppelin/ui-utils';
+
+import { WalletsKitImplementation } from '../implementation/wallets-kit-implementation';
+
+let walletImplementationInstance: WalletsKitImplementation | undefined;
+let walletImplementationPromise: Promise<WalletsKitImplementation> | undefined;
+
+const LOG_SYSTEM = 'StellarWalletImplementationManager';
+
+/**
+ * Get or create the singleton instance of WalletsKitImplementation.
+ * This function ensures that the initialization logic runs only once.
+ *
+ * @param networkConfig - Optional network configuration to use for initialization
+ * @returns A Promise resolving to the WalletsKitImplementation singleton
+ */
+export async function getStellarWalletImplementation(
+  networkConfig?: StellarNetworkConfig
+): Promise<WalletsKitImplementation> {
+  if (walletImplementationInstance) {
+    // If network config is provided and different, update it
+    if (networkConfig) {
+      walletImplementationInstance.setNetworkConfig(networkConfig);
+    }
+    return walletImplementationInstance;
+  }
+
+  if (walletImplementationPromise) {
+    const instance = await walletImplementationPromise;
+    // If network config is provided and different, update it
+    if (networkConfig) {
+      instance.setNetworkConfig(networkConfig);
+    }
+    return instance;
+  }
+
+  walletImplementationPromise = (async () => {
+    try {
+      logger.info(LOG_SYSTEM, 'Initializing StellarWalletImplementation singleton (async)...');
+
+      // Get initial UI kit config from appConfigService
+      const initialUiKitConfig = appConfigService.getTypedNestedConfig<UiKitConfiguration>(
+        'walletui',
+        'config'
+      );
+
+      // Create instance with provided network config or undefined
+      const instance = new WalletsKitImplementation(networkConfig, initialUiKitConfig);
+
+      logger.info(LOG_SYSTEM, 'WalletsKitImplementation singleton created (async).');
+      walletImplementationInstance = instance;
+      return instance;
+    } catch (error) {
+      logger.error(LOG_SYSTEM, 'Failed to initialize WalletsKitImplementation (async):', error);
+
+      // Create fallback instance
+      const fallbackInstance = new WalletsKitImplementation(networkConfig);
+      walletImplementationInstance = fallbackInstance;
+      return fallbackInstance;
+    }
+  })();
+
+  return walletImplementationPromise;
+}
+
+/**
+ * A synchronous getter for cases where the instance is known to be initialized.
+ * Use with caution, prefer the async getter.
+ *
+ * This function is essential for cases where you need immediate access to the
+ * wallet implementation and know it has already been initialized.
+ *
+ * @returns The initialized WalletsKitImplementation instance or undefined
+ */
+export function getInitializedStellarWalletImplementation(): WalletsKitImplementation | undefined {
+  if (!walletImplementationInstance) {
+    logger.warn(
+      LOG_SYSTEM,
+      'getInitializedStellarWalletImplementation called before instance was ready.'
+    );
+  }
+  return walletImplementationInstance;
+}
+
+/**
+ * Updates the network configuration for the wallet implementation
+ * This is useful when the network changes but the implementation instance should remain the same
+ *
+ * @param networkConfig - The new network configuration
+ */
+export function updateWalletImplementationNetworkConfig(networkConfig: StellarNetworkConfig): void {
+  logger.info(LOG_SYSTEM, 'Updating wallet implementation network config:', networkConfig.name);
+
+  if (walletImplementationInstance) {
+    walletImplementationInstance.setNetworkConfig(networkConfig);
+  } else {
+    logger.warn(
+      LOG_SYSTEM,
+      'Cannot update network config - wallet implementation not initialized yet'
+    );
+  }
+}
+
+/**
+ * Resets the singleton instance (primarily for testing or cleanup)
+ * Use with extreme caution in production code
+ */
+export function resetWalletImplementationInstance(): void {
+  logger.warn(LOG_SYSTEM, 'Resetting wallet implementation singleton instance');
+
+  if (walletImplementationInstance) {
+    walletImplementationInstance.cleanup();
+  }
+
+  walletImplementationInstance = undefined;
+  walletImplementationPromise = undefined;
+}

package/src/wallet/utils/uiKitService.ts

@@ -0,0 +1,74 @@
+import type { EcosystemWalletComponents, UiKitConfiguration } from '@openzeppelin/ui-types';
+import { logger } from '@openzeppelin/ui-utils';
+
+import { CustomAccountDisplay, CustomConnectButton } from '../components';
+import { StellarWalletsKitConnectButton } from '../stellar-wallets-kit';
+import { filterWalletComponents, getComponentExclusionsFromConfig } from './filterWalletComponents';
+
+/**
+ * Determines the final set of wallet components to be provided by the Stellar adapter
+ * based on the UI kit configuration.
+ *
+ * @param uiKitConfiguration - The UiKitConfiguration from the adapter instance.
+ * @returns The EcosystemWalletComponents object or undefined.
+ */
+export function getResolvedWalletComponents(
+  uiKitConfiguration: UiKitConfiguration
+): EcosystemWalletComponents | undefined {
+  logger.debug(
+    'stellar:uiKitService:getResolvedWalletComponents',
+    'Received uiKitConfiguration:',
+    JSON.stringify(uiKitConfiguration)
+  );
+
+  const currentKitName = uiKitConfiguration.kitName || 'custom';
+
+  if (currentKitName === 'none') {
+    logger.info(
+      'stellar:uiKitService',
+      'UI Kit set to "none" for getResolvedWalletComponents, not providing wallet components.'
+    );
+    return undefined;
+  }
+
+  const exclusions = getComponentExclusionsFromConfig(uiKitConfiguration.kitConfig);
+  logger.debug(
+    'stellar:uiKitService',
+    `Extracted component exclusions for ${currentKitName}: ${exclusions.join(', ') || 'none'}.`
+  );
+
+  // For 'custom' kit, we provide our custom components
+  if (currentKitName === 'custom') {
+    const allCustomComponents: EcosystemWalletComponents = {
+      ConnectButton: CustomConnectButton,
+      AccountDisplay: CustomAccountDisplay,
+      // NetworkSwitcher is not included as Stellar doesn't support network switching
+    };
+
+    logger.info(
+      'stellar:uiKitService',
+      `Providing custom Stellar wallet components for kit: ${currentKitName}`
+    );
+
+    return filterWalletComponents(allCustomComponents, exclusions, currentKitName);
+  }
+
+  // For 'stellar-wallets-kit', use the kit's native button with built-in UI
+  if (currentKitName === 'stellar-wallets-kit') {
+    const stellarKitComponents: EcosystemWalletComponents = {
+      ConnectButton: StellarWalletsKitConnectButton,
+      // The kit's native button handles account display internally
+      AccountDisplay: undefined,
+    };
+
+    logger.info('stellar:uiKitService', 'Using Stellar Wallets Kit native button');
+
+    return stellarKitComponents;
+  }
+
+  logger.warn(
+    'stellar:uiKitService',
+    `UI Kit "${currentKitName}" for getResolvedWalletComponents not explicitly supported. No components provided.`
+  );
+  return undefined;
+}