@openzeppelin/adapter-stellar 1.0.0

package/src/wallet/stellar-wallets-kit/__mocks__/@creit.tech/stellar-wallets-kit.ts

@@ -0,0 +1,48 @@
+// Mock for @creit.tech/stellar-wallets-kit to avoid CommonJS issues in tests
+
+export const WalletNetwork = {
+  TESTNET: 'TESTNET',
+  PUBLIC: 'PUBLIC',
+};
+
+export class StellarWalletsKit {
+  constructor(_options: Record<string, unknown>) {
+    // Mock constructor
+  }
+
+  async getAddress() {
+    return { address: 'GBTEST123456789' };
+  }
+
+  async setWallet(_walletId: string) {
+    // Mock implementation
+  }
+
+  async getSupportedWallets() {
+    return [
+      {
+        id: 'freighter',
+        name: 'Freighter',
+        icon: 'https://example.com/freighter.png',
+        isAvailable: true,
+        type: 'browser',
+      },
+    ];
+  }
+
+  async signTransaction(_xdr: string, _options: Record<string, unknown>) {
+    return { signedTxXdr: 'mock-signed-xdr' };
+  }
+}
+
+export function allowAllModules() {
+  return [];
+}
+
+export interface ISupportedWallet {
+  id: string;
+  name: string;
+  icon: string;
+  isAvailable: boolean;
+  type: string;
+}

package/src/wallet/stellar-wallets-kit/__tests__/export-service.test.ts

@@ -0,0 +1,93 @@
+import { describe, expect, it } from 'vitest';
+
+import type { UiKitConfiguration } from '@openzeppelin/ui-types';
+
+import { generateStellarWalletsKitExportables } from '../export-service';
+
+describe('generateStellarWalletsKitExportables', () => {
+  it('should generate default config when no customCode is provided', () => {
+    const uiKitConfig: UiKitConfiguration = {
+      kitName: 'stellar-wallets-kit',
+      kitConfig: {
+        appName: 'My Stellar DApp',
+        allowTestnet: true,
+      },
+    };
+
+    const result = generateStellarWalletsKitExportables(uiKitConfig);
+
+    expect(Object.keys(result)).toEqual(['src/config/wallet/stellar-wallets-kit.config.ts']);
+
+    const content = result['src/config/wallet/stellar-wallets-kit.config.ts'];
+    expect(content).toContain('// Stellar Wallets Kit configuration for your exported application');
+    expect(content).toContain("appName: 'My Stellar DApp'");
+    expect(content).toContain('network: WalletNetwork.TESTNET');
+  });
+
+  it('should use customCode when provided', () => {
+    const customCode = `// Custom Stellar Wallets Kit config
+import { StellarWalletsKit } from '@creit.tech/stellar-wallets-kit';
+
+const config = {
+  custom: true,
+  appName: 'Custom App',
+};
+
+export default config;`;
+
+    const uiKitConfig: UiKitConfiguration = {
+      kitName: 'stellar-wallets-kit',
+      kitConfig: {
+        appName: 'My Stellar DApp',
+      },
+      customCode,
+    };
+
+    const result = generateStellarWalletsKitExportables(uiKitConfig);
+
+    expect(Object.keys(result)).toEqual(['src/config/wallet/stellar-wallets-kit.config.ts']);
+    expect(result['src/config/wallet/stellar-wallets-kit.config.ts']).toBe(customCode);
+  });
+
+  it('should handle empty kitConfig', () => {
+    const uiKitConfig: UiKitConfiguration = {
+      kitName: 'stellar-wallets-kit',
+      kitConfig: {},
+    };
+
+    const result = generateStellarWalletsKitExportables(uiKitConfig);
+
+    const content = result['src/config/wallet/stellar-wallets-kit.config.ts'];
+    expect(content).toContain("appName: 'My Stellar App'"); // default value
+    expect(content).toContain('network: WalletNetwork.TESTNET'); // default value
+  });
+
+  it('should handle WalletConnect project ID when provided', () => {
+    const uiKitConfig: UiKitConfiguration = {
+      kitName: 'stellar-wallets-kit',
+      kitConfig: {
+        walletConnectProjectId: 'my-project-id-123',
+      },
+    };
+
+    const result = generateStellarWalletsKitExportables(uiKitConfig);
+
+    const content = result['src/config/wallet/stellar-wallets-kit.config.ts'];
+    expect(content).toContain("walletConnectProjectId: 'my-project-id-123'");
+    expect(content).not.toContain('// walletConnectProjectId:');
+  });
+
+  it('should respect network mainnet', () => {
+    const uiKitConfig: UiKitConfiguration = {
+      kitName: 'stellar-wallets-kit',
+      kitConfig: {
+        network: 'MAINNET',
+      },
+    };
+
+    const result = generateStellarWalletsKitExportables(uiKitConfig);
+
+    const content = result['src/config/wallet/stellar-wallets-kit.config.ts'];
+    expect(content).toContain('network: WalletNetwork.PUBLIC');
+  });
+});

package/src/wallet/stellar-wallets-kit/config-generator.ts

@@ -0,0 +1,75 @@
+import type { UiKitConfiguration } from '@openzeppelin/ui-types';
+
+/**
+ * Generates the content for a `stellar-wallets-kit.config.ts` file for an exported project.
+ * This creates a configuration wrapper that can be used to initialize the Stellar Wallets Kit.
+ *
+ * @param userConfig - The user-provided configuration from the builder app.
+ * @returns A string containing the formatted TypeScript code for the config file.
+ */
+export function generateStellarWalletsKitConfigFile(
+  userConfig: UiKitConfiguration['kitConfig']
+): string {
+  const config = (userConfig || {}) as Record<string, unknown>;
+
+  // Extract user-provided configuration options
+  const appName = (config.appName as string) || 'My Stellar App';
+  const network = (config.network as string) || 'TESTNET';
+  const walletConnectProjectId = (config.walletConnectProjectId as string) || '';
+  const modalTitle = (config.modalTitle as string) || `Connect to ${appName}`;
+  const buttonText = (config.buttonText as string) || 'Connect Wallet';
+
+  const fileContent = `// Stellar Wallets Kit configuration for your exported application
+// This file is used ONLY in the exported app, not in the builder app preview
+
+import { 
+  StellarWalletsKit, 
+  WalletNetwork, 
+  allowAllModules
+} from '@creit.tech/stellar-wallets-kit';
+
+/**
+ * Stellar Wallets Kit configuration wrapper
+ * 
+ * The kit supports multiple wallets including:
+ * - Freighter
+ * - xBull  
+ * - Ledger
+ * - Trezor
+ * - WalletConnect
+ * - And more...
+ */
+export const stellarWalletsKitConfig = {
+  // App information
+  appName: '${appName}',
+  
+  // Network configuration (TESTNET or PUBLIC/MAINNET)
+  network: WalletNetwork.${network === 'MAINNET' || network === 'PUBLIC' ? 'PUBLIC' : 'TESTNET'},
+  
+  // UI customization
+  buttonText: '${buttonText}',
+  modalTitle: '${modalTitle}',
+  
+  // WalletConnect configuration
+  ${walletConnectProjectId ? `walletConnectProjectId: '${walletConnectProjectId}',` : "// walletConnectProjectId: 'YOUR_PROJECT_ID', // Get yours at https://cloud.walletconnect.com"}
+};
+
+/**
+ * Creates and configures a StellarWalletsKit instance
+ * @returns Configured StellarWalletsKit instance
+ */
+export function createStellarWalletsKit(): StellarWalletsKit {
+  const modules = [
+    ...allowAllModules()
+  ];
+
+  return new StellarWalletsKit({
+    network: stellarWalletsKitConfig.network,
+    modules,
+  });
+}
+
+export default stellarWalletsKitConfig;`;
+
+  return fileContent;
+}

package/src/wallet/stellar-wallets-kit/export-service.ts

@@ -0,0 +1,19 @@
+import type { UiKitConfiguration } from '@openzeppelin/ui-types';
+
+import { generateStellarWalletsKitConfigFile } from './config-generator';
+
+/**
+ * Generates the specific configuration file for Stellar Wallets Kit during project export.
+ *
+ * @param uiKitConfig The full UI kit configuration object from the builder.
+ * @returns A record containing the file path and its generated content.
+ */
+export function generateStellarWalletsKitExportables(
+  uiKitConfig: UiKitConfiguration
+): Record<string, string> {
+  const filePath = 'src/config/wallet/stellar-wallets-kit.config.ts';
+  const content =
+    uiKitConfig.customCode || generateStellarWalletsKitConfigFile(uiKitConfig.kitConfig);
+
+  return { [filePath]: content };
+}

package/src/wallet/stellar-wallets-kit/index.ts

@@ -0,0 +1,3 @@
+export * from './stellarUiKitManager';
+export * from './export-service';
+export { StellarWalletsKitConnectButton } from './StellarWalletsKitConnectButton';

package/src/wallet/stellar-wallets-kit/stellarUiKitManager.ts

@@ -0,0 +1,235 @@
+import { allowAllModules, StellarWalletsKit, WalletNetwork } from '@creit.tech/stellar-wallets-kit';
+
+import type { StellarNetworkConfig, UiKitConfiguration } from '@openzeppelin/ui-types';
+import { logger } from '@openzeppelin/ui-utils';
+
+import { getStellarWalletImplementation } from '../utils/stellarWalletImplementationManager';
+
+export interface StellarUiKitManagerState {
+  isConfigured: boolean;
+  isInitializing: boolean;
+  hasConfigError: boolean;
+  error: Error | null;
+  lastConfigError: Error | null;
+  currentFullUiKitConfig: UiKitConfiguration | null;
+  stellarKitProvider: StellarWalletsKit | null;
+  kitProviderComponent: React.ComponentType<{ children: React.ReactNode }> | null;
+  isKitAssetsLoaded: boolean;
+  networkConfig: StellarNetworkConfig | null;
+}
+
+const getInitialState = (): StellarUiKitManagerState => ({
+  isConfigured: false,
+  isInitializing: false,
+  hasConfigError: false,
+  error: null,
+  lastConfigError: null,
+  currentFullUiKitConfig: null,
+  stellarKitProvider: null,
+  kitProviderComponent: null,
+  isKitAssetsLoaded: false,
+  networkConfig: null,
+});
+
+let state: StellarUiKitManagerState = getInitialState();
+
+interface StellarUiKitManagerListener {
+  (state: StellarUiKitManagerState): void;
+}
+
+const listeners: Set<StellarUiKitManagerListener> = new Set();
+
+function notifyListeners() {
+  listeners.forEach((listener) => listener(state));
+}
+
+function subscribe(listener: StellarUiKitManagerListener): () => void {
+  listeners.add(listener);
+
+  // Call the listener immediately with the current state
+  listener(state);
+
+  // Return unsubscribe function
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+function getState(): StellarUiKitManagerState {
+  return state;
+}
+
+function setNetworkConfig(config: StellarNetworkConfig): void {
+  state = {
+    ...state,
+    networkConfig: config,
+  };
+  notifyListeners();
+}
+
+function getWalletNetwork(networkConfig: StellarNetworkConfig | null): WalletNetwork {
+  if (!networkConfig) {
+    logger.warn('StellarUiKitManager', 'No network config available, defaulting to TESTNET');
+    return WalletNetwork.TESTNET;
+  }
+
+  return networkConfig.type === 'mainnet' ? WalletNetwork.PUBLIC : WalletNetwork.TESTNET;
+}
+
+async function configure(newFullUiKitConfig: UiKitConfiguration): Promise<void> {
+  logger.info(
+    'StellarUiKitManager:configure',
+    'Configuring UI kit. New config:',
+    newFullUiKitConfig
+  );
+
+  const oldKitName = state.currentFullUiKitConfig?.kitName;
+  const newKitName = newFullUiKitConfig.kitName;
+  const kitChanged = oldKitName !== newKitName;
+
+  state = {
+    ...state,
+    isInitializing: true,
+    error: null,
+    currentFullUiKitConfig: newFullUiKitConfig,
+    kitProviderComponent: kitChanged ? null : state.kitProviderComponent,
+    isKitAssetsLoaded: kitChanged ? false : state.isKitAssetsLoaded,
+  };
+  notifyListeners();
+
+  try {
+    const walletNetwork = getWalletNetwork(state.networkConfig);
+
+    if (newKitName === 'stellar-wallets-kit') {
+      // Initialize the Stellar Wallets Kit with its built-in UI components
+      const kit = new StellarWalletsKit({
+        network: walletNetwork,
+        selectedWalletId: undefined,
+        modules: allowAllModules(), // Use all available wallet modules
+      });
+
+      state.stellarKitProvider = kit;
+      // Stellar Wallets Kit provides its own modal UI that can be opened with kit.openModal()
+      // We don't need to provide custom components when using the built-in UI
+      state.kitProviderComponent = null;
+      state.isKitAssetsLoaded = true;
+      state.error = null;
+
+      // Wire the active kit into the wallet implementation
+      // This ensures signing and other operations use the correct kit instance
+      if (state.networkConfig) {
+        try {
+          const impl = await getStellarWalletImplementation(state.networkConfig);
+          impl.setActiveStellarKit(kit);
+          logger.debug(
+            'StellarUiKitManager:configure',
+            'Active kit wired into wallet implementation for stellar-wallets-kit'
+          );
+        } catch (error) {
+          logger.warn(
+            'StellarUiKitManager:configure',
+            'Failed to attach active kit to wallet implementation:',
+            error
+          );
+        }
+      }
+
+      logger.info(
+        'StellarUiKitManager:configure',
+        'Stellar Wallets Kit configured with built-in UI and all wallet modules'
+      );
+    } else if (newKitName === 'custom' || !newKitName) {
+      // Initialize the Stellar Wallets Kit for custom UI mode
+      const kit = new StellarWalletsKit({
+        network: walletNetwork,
+        selectedWalletId: undefined,
+        modules: allowAllModules(),
+      });
+
+      state.stellarKitProvider = kit;
+      state.kitProviderComponent = null;
+      state.isKitAssetsLoaded = true;
+      state.error = null;
+
+      // Wire the active kit into the wallet implementation
+      // This ensures signing and other operations use the correct kit instance
+      if (state.networkConfig) {
+        try {
+          const impl = await getStellarWalletImplementation(state.networkConfig);
+          impl.setActiveStellarKit(kit);
+          logger.debug(
+            'StellarUiKitManager:configure',
+            'Active kit wired into wallet implementation for custom'
+          );
+        } catch (error) {
+          logger.warn(
+            'StellarUiKitManager:configure',
+            'Failed to attach active kit to wallet implementation:',
+            error
+          );
+        }
+      }
+
+      logger.info(
+        'StellarUiKitManager:configure',
+        'Stellar Wallets Kit configured for custom UI components'
+      );
+    } else if (newKitName === 'none') {
+      // No wallet UI kit
+      state.stellarKitProvider = null;
+      state.kitProviderComponent = null;
+      state.isKitAssetsLoaded = false;
+      state.error = null;
+
+      // Clear the active kit from the wallet implementation
+      if (state.networkConfig) {
+        try {
+          const impl = await getStellarWalletImplementation(state.networkConfig);
+          impl.setActiveStellarKit(null);
+          logger.debug(
+            'StellarUiKitManager:configure',
+            'Active kit cleared from wallet implementation for none'
+          );
+        } catch (error) {
+          logger.warn(
+            'StellarUiKitManager:configure',
+            'Failed to clear active kit from wallet implementation:',
+            error
+          );
+        }
+      }
+
+      logger.info('StellarUiKitManager:configure', 'UI kit set to "none", no wallet UI provided');
+    } else {
+      throw new Error(`Unknown UI kit name: ${newKitName}`);
+    }
+
+    state = {
+      ...state,
+      isConfigured: true,
+      isInitializing: false,
+      hasConfigError: false,
+      error: null,
+    };
+    notifyListeners();
+  } catch (error) {
+    logger.error('StellarUiKitManager:configure', 'Failed to configure UI kit:', error);
+    state = {
+      ...state,
+      isInitializing: false,
+      hasConfigError: true,
+      error: error instanceof Error ? error : new Error('Failed to configure UI kit'),
+      lastConfigError: error instanceof Error ? error : new Error('Failed to configure UI kit'),
+      isConfigured: false,
+    };
+    notifyListeners();
+    throw error;
+  }
+}
+
+export const stellarUiKitManager = {
+  configure,
+  getState,
+  subscribe,
+  setNetworkConfig,
+};

package/src/wallet/types.ts

@@ -0,0 +1,19 @@
+import type { WalletConnectionStatus } from '@openzeppelin/ui-types';
+
+/**
+ * Stellar-specific wallet connection status extending the base interface.
+ * Includes Stellar-specific fields like walletId.
+ * Note that stellar wallets don't work with multiple addresses, only a single active address.
+ */
+export interface StellarWalletConnectionStatus extends WalletConnectionStatus {
+  /** Stellar-specific wallet identifier (e.g., 'freighter', 'albedo') */
+  walletId?: string;
+}
+
+/**
+ * Type for wallet connection status listener callback
+ */
+export type StellarConnectionStatusListener = (
+  status: StellarWalletConnectionStatus,
+  prevStatus: StellarWalletConnectionStatus
+) => void;

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

@@ -0,0 +1,150 @@
+import { describe, expect, it } from 'vitest';
+
+import type { EcosystemWalletComponents } from '@openzeppelin/ui-types';
+
+import {
+  filterWalletComponents,
+  getComponentExclusionsFromConfig,
+} from '../filterWalletComponents';
+
+// Mock components
+const MockConnectButton = () => null;
+const MockAccountDisplay = () => null;
+const MockNetworkSwitcher = () => null;
+
+describe('filterWalletComponents', () => {
+  const allComponents: EcosystemWalletComponents = {
+    ConnectButton: MockConnectButton as React.FC,
+    AccountDisplay: MockAccountDisplay as React.FC,
+    NetworkSwitcher: MockNetworkSwitcher as React.FC,
+  };
+
+  it('should return all components when no exclusions', () => {
+    const result = filterWalletComponents(allComponents, [], 'test-kit');
+
+    expect(result).toEqual(allComponents);
+    expect(result).toHaveProperty('ConnectButton');
+    expect(result).toHaveProperty('AccountDisplay');
+    expect(result).toHaveProperty('NetworkSwitcher');
+  });
+
+  it('should exclude specified components', () => {
+    const result = filterWalletComponents(allComponents, ['NetworkSwitcher'], 'test-kit');
+
+    expect(result).toHaveProperty('ConnectButton');
+    expect(result).toHaveProperty('AccountDisplay');
+    expect(result).not.toHaveProperty('NetworkSwitcher');
+  });
+
+  it('should exclude multiple components', () => {
+    const result = filterWalletComponents(
+      allComponents,
+      ['NetworkSwitcher', 'AccountDisplay'],
+      'test-kit'
+    );
+
+    expect(result).toHaveProperty('ConnectButton');
+    expect(result).not.toHaveProperty('AccountDisplay');
+    expect(result).not.toHaveProperty('NetworkSwitcher');
+  });
+
+  it('should return undefined when all components are excluded', () => {
+    const result = filterWalletComponents(
+      allComponents,
+      ['ConnectButton', 'AccountDisplay', 'NetworkSwitcher'],
+      'test-kit'
+    );
+
+    expect(result).toBeUndefined();
+  });
+
+  it('should return undefined when no components provided', () => {
+    const result = filterWalletComponents({}, [], 'test-kit');
+
+    expect(result).toBeUndefined();
+  });
+
+  it('should return undefined when null components provided', () => {
+    const result = filterWalletComponents(
+      null as unknown as EcosystemWalletComponents,
+      [],
+      'test-kit'
+    );
+
+    expect(result).toBeUndefined();
+  });
+
+  it('should ignore invalid exclusion keys', () => {
+    const result = filterWalletComponents(
+      allComponents,
+      ['InvalidKey' as keyof EcosystemWalletComponents, 'NetworkSwitcher'],
+      'test-kit'
+    );
+
+    expect(result).toHaveProperty('ConnectButton');
+    expect(result).toHaveProperty('AccountDisplay');
+    expect(result).not.toHaveProperty('NetworkSwitcher');
+  });
+});
+
+describe('getComponentExclusionsFromConfig', () => {
+  it('should return empty array when no config', () => {
+    const result = getComponentExclusionsFromConfig(undefined);
+    expect(result).toEqual([]);
+  });
+
+  it('should return empty array when no components config', () => {
+    const result = getComponentExclusionsFromConfig({
+      showInjectedConnector: true,
+    });
+    expect(result).toEqual([]);
+  });
+
+  it('should return empty array when no exclude array', () => {
+    const result = getComponentExclusionsFromConfig({
+      components: {},
+    });
+    expect(result).toEqual([]);
+  });
+
+  it('should return exclude array when present', () => {
+    const result = getComponentExclusionsFromConfig({
+      components: {
+        exclude: ['NetworkSwitcher', 'AccountDisplay'],
+      },
+    });
+    expect(result).toEqual(['NetworkSwitcher', 'AccountDisplay']);
+  });
+
+  it('should handle non-array exclude value', () => {
+    const result = getComponentExclusionsFromConfig({
+      components: {
+        exclude: 'NetworkSwitcher' as unknown as string[],
+      },
+    });
+    expect(result).toEqual([]);
+  });
+
+  it('should filter out non-string values', () => {
+    const result = getComponentExclusionsFromConfig({
+      components: {
+        exclude: ['NetworkSwitcher', 123, null, 'AccountDisplay'] as unknown as string[],
+      },
+    });
+    expect(result).toEqual(['NetworkSwitcher', 'AccountDisplay']);
+  });
+
+  it('should handle nested config structure', () => {
+    const config = {
+      components: {
+        exclude: ['ConnectButton'],
+        otherProp: 'value',
+      },
+      showInjectedConnector: false,
+      appName: 'Test App',
+    };
+
+    const result = getComponentExclusionsFromConfig(config);
+    expect(result).toEqual(['ConnectButton']);
+  });
+});