@openzeppelin/adapter-stellar 1.0.0

package/src/wallet/implementation/wallets-kit-implementation.ts

@@ -0,0 +1,379 @@
+/**
+ * Private Stellar wallet implementation for Stellar wallet connection
+ *
+ * This file contains the internal implementation of StellarWalletsKit for wallet connection.
+ * It's encapsulated within the Stellar adapter and not exposed to the rest of the application.
+ */
+import {
+  allowAllModules,
+  ISupportedWallet,
+  StellarWalletsKit,
+  WalletNetwork,
+} from '@creit.tech/stellar-wallets-kit';
+
+import type { Connector, StellarNetworkConfig, UiKitConfiguration } from '@openzeppelin/ui-types';
+import { logger } from '@openzeppelin/ui-utils';
+
+import type { StellarConnectionStatusListener, StellarWalletConnectionStatus } from '../types';
+
+const LOG_SYSTEM = 'StellarWalletImplementation';
+
+/**
+ * Class responsible for encapsulating StellarWalletsKit logic for wallet interactions.
+ * This class should not be used directly by UI components. The StellarAdapter
+ * exposes a standardized interface for wallet operations.
+ * It manages StellarWalletsKit instances and provides methods for wallet actions.
+ */
+export class WalletsKitImplementation {
+  private defaultInstanceKit: StellarWalletsKit | null = null;
+  private activeStellarKit: StellarWalletsKit | null = null; // To be set by StellarUiKitManager
+  private unsubscribeFromStatusChanges?: () => void;
+  private initialized: boolean = false;
+  private networkConfig: StellarNetworkConfig | null = null;
+
+  // Internal state tracking for connection status
+  private currentAddress: string | null = null;
+  private currentWalletId: string | null = null;
+  private connectionStatusListeners = new Set<StellarConnectionStatusListener>();
+
+  /**
+   * Constructs the StellarWalletImplementation.
+   * Configuration for StellarWalletsKit is deferred until actually needed or set externally.
+   * @param networkConfig - Stellar network configuration
+   * @param initialUiKitConfig - Optional initial UI kit configuration, primarily for logging the anticipated kit.
+   */
+  constructor(networkConfig?: StellarNetworkConfig, initialUiKitConfig?: UiKitConfiguration) {
+    this.networkConfig = networkConfig || null;
+    logger.info(
+      LOG_SYSTEM,
+      'Constructor called. Initial anticipated kitName:',
+      initialUiKitConfig?.kitName,
+      'Network:',
+      networkConfig?.name
+    );
+    this.initialized = true;
+    logger.info(
+      LOG_SYSTEM,
+      'StellarWalletImplementation instance initialized (StellarWalletsKit config creation deferred).'
+    );
+    // No kit created here by default anymore.
+  }
+
+  /**
+   * Sets the network configuration for the wallet implementation
+   * @param config - The Stellar network configuration
+   */
+  public setNetworkConfig(config: StellarNetworkConfig): void {
+    logger.info(LOG_SYSTEM, 'Network config updated:', config.name);
+    this.networkConfig = config;
+
+    // If we have active kits, they might need to be recreated with new network
+    // For now, just log - the kit manager will handle reconfiguration
+    if (this.activeStellarKit || this.defaultInstanceKit) {
+      logger.info(LOG_SYSTEM, 'Active kits detected - may need reconfiguration for new network');
+    }
+  }
+
+  /**
+   * Sets the externally determined, currently active StellarWalletsKit instance.
+   * This is typically called by StellarUiKitManager after it has resolved the appropriate
+   * kit for the selected UI kit mode.
+   * @param kit - The StellarWalletsKit object to set as active, or null to clear it.
+   */
+  public setActiveStellarKit(kit: StellarWalletsKit | null): void {
+    logger.info(
+      LOG_SYSTEM,
+      'setActiveStellarKit called with kit:',
+      kit ? 'Valid StellarWalletsKit' : 'Null'
+    );
+    this.activeStellarKit = kit;
+
+    // If there was an existing direct subscription, it might need to be updated
+    if (this.unsubscribeFromStatusChanges) {
+      logger.info(LOG_SYSTEM, 'Re-establishing connection status monitoring with new kit');
+      // The connection status will be managed internally
+    }
+  }
+
+  /**
+   * Creates a default StellarWalletsKit instance when no active kit is available.
+   * This ensures wallet functionality works even without explicit UI kit configuration.
+   * @returns A default StellarWalletsKit instance
+   */
+  private createDefaultKit(): StellarWalletsKit {
+    logger.info(LOG_SYSTEM, 'Creating default StellarWalletsKit instance');
+
+    const network = this.getWalletNetwork();
+    const kit = new StellarWalletsKit({
+      network,
+      selectedWalletId: undefined,
+      modules: allowAllModules(),
+    });
+
+    logger.info(LOG_SYSTEM, 'Default StellarWalletsKit instance created');
+    return kit;
+  }
+
+  /**
+   * Gets the appropriate WalletNetwork enum value based on network configuration
+   */
+  private getWalletNetwork(): WalletNetwork {
+    if (!this.networkConfig) {
+      logger.warn(LOG_SYSTEM, 'No network config available, defaulting to TESTNET');
+      return WalletNetwork.TESTNET;
+    }
+    return this.networkConfig.type === 'mainnet' ? WalletNetwork.PUBLIC : WalletNetwork.TESTNET;
+  }
+
+  /**
+   * Gets the kit to use for operations (active or default)
+   */
+  private getKitToUse(): StellarWalletsKit {
+    const kit =
+      this.activeStellarKit ||
+      this.defaultInstanceKit ||
+      (this.defaultInstanceKit = this.createDefaultKit());
+    return kit;
+  }
+
+  /**
+   * Gets available wallet connectors from StellarWalletsKit
+   * @returns Promise resolving to array of available connectors
+   */
+  public async getAvailableConnectors(): Promise<Connector[]> {
+    if (!this.initialized) {
+      logger.warn(LOG_SYSTEM, 'getAvailableConnectors called before initialization');
+      return [];
+    }
+
+    try {
+      const kit = this.getKitToUse();
+      const wallets = await kit.getSupportedWallets();
+
+      const connectors: Connector[] = wallets.map((wallet: ISupportedWallet) => ({
+        id: wallet.id,
+        name: wallet.name,
+        icon: wallet.icon,
+        installed: wallet.isAvailable,
+        type: (wallet.type as string) || 'browser',
+      }));
+
+      logger.info(LOG_SYSTEM, `Found ${connectors.length} available wallet connectors`);
+      return connectors;
+    } catch (error) {
+      logger.error(LOG_SYSTEM, 'Failed to get available connectors:', error);
+      return [];
+    }
+  }
+
+  /**
+   * Connects to a wallet using the specified connector ID
+   * @param connectorId - The ID of the wallet connector to use
+   * @returns Promise resolving to connection result
+   */
+  public async connect(connectorId: string): Promise<{
+    connected: boolean;
+    address?: string;
+    chainId?: string;
+    error?: string;
+  }> {
+    if (!this.initialized) {
+      return { connected: false, error: 'Wallet implementation not initialized' };
+    }
+
+    try {
+      const prevStatus = this.getWalletConnectionStatus();
+      const kit = this.getKitToUse();
+
+      logger.info(LOG_SYSTEM, `Attempting to connect to wallet: ${connectorId}`);
+
+      // Set the selected wallet
+      kit.setWallet(connectorId);
+
+      // Get the address from the wallet
+      const result = await kit.getAddress();
+
+      if (result.address) {
+        this.currentAddress = result.address;
+        this.currentWalletId = connectorId;
+
+        // Notify listeners of the connection change
+        const newStatus = this.getWalletConnectionStatus();
+        this.notifyConnectionListeners(newStatus, prevStatus);
+
+        logger.info(
+          LOG_SYSTEM,
+          `Successfully connected to wallet: ${connectorId}, address: ${result.address}`
+        );
+
+        return {
+          connected: true,
+          address: result.address,
+          chainId: this.networkConfig?.id,
+        };
+      } else {
+        return {
+          connected: false,
+          error: 'Failed to get address from wallet',
+        };
+      }
+    } catch (error) {
+      logger.error(LOG_SYSTEM, `Failed to connect to wallet ${connectorId}:`, error);
+      return {
+        connected: false,
+        error: error instanceof Error ? error.message : 'Unknown error occurred',
+      };
+    }
+  }
+
+  /**
+   * Disconnects from the currently connected wallet
+   * @returns Promise resolving to disconnection result
+   */
+  public async disconnect(): Promise<{ disconnected: boolean; error?: string }> {
+    if (!this.initialized) {
+      return { disconnected: false, error: 'Wallet implementation not initialized' };
+    }
+
+    try {
+      const prevStatus = this.getWalletConnectionStatus();
+
+      logger.info(LOG_SYSTEM, 'Disconnecting wallet');
+
+      // Clear the current connection state
+      this.currentAddress = null;
+      this.currentWalletId = null;
+
+      // Notify listeners of the disconnection
+      const newStatus = this.getWalletConnectionStatus();
+      this.notifyConnectionListeners(newStatus, prevStatus);
+
+      // For Stellar Wallets Kit, we just clear our internal state
+      // The kit doesn't have a specific disconnect method
+
+      logger.info(LOG_SYSTEM, 'Successfully disconnected wallet');
+      return { disconnected: true };
+    } catch (error) {
+      logger.error(LOG_SYSTEM, 'Failed to disconnect wallet:', error);
+      return {
+        disconnected: false,
+        error: error instanceof Error ? error.message : 'Unknown error occurred',
+      };
+    }
+  }
+
+  /**
+   * Gets the current wallet connection status
+   * @returns The current connection status
+   */
+  public getWalletConnectionStatus(): StellarWalletConnectionStatus {
+    const isConnected = this.currentAddress !== null;
+    const chainId = this.networkConfig?.id || 'stellar-testnet';
+
+    return {
+      isConnected,
+      isConnecting: false, // We don't track intermediate connecting state yet
+      isDisconnected: !isConnected,
+      isReconnecting: false,
+      status: isConnected ? 'connected' : 'disconnected',
+      address: this.currentAddress || undefined,
+      walletId: this.currentWalletId || undefined,
+      chainId,
+    };
+  }
+
+  /**
+   * Subscribes to wallet connection status changes
+   * @param callback - Function to call when connection status changes
+   * @returns A function to unsubscribe from the changes
+   */
+  public onWalletConnectionChange(callback: StellarConnectionStatusListener): () => void {
+    if (!this.initialized) {
+      logger.warn(LOG_SYSTEM, 'onWalletConnectionChange called before initialization. No-op.');
+      return () => {};
+    }
+
+    this.connectionStatusListeners.add(callback);
+    logger.info(LOG_SYSTEM, 'Connection status listener added');
+
+    // Return unsubscribe function
+    return () => {
+      this.connectionStatusListeners.delete(callback);
+      logger.debug(LOG_SYSTEM, 'Connection status listener removed');
+    };
+  }
+
+  /**
+   * Manually updates the cached connection address and wallet ID
+   * This is used when the connection status is determined externally
+   * @param address - The wallet address or null
+   * @param walletId - The wallet ID or null
+   */
+  public updateConnectionStatus(address: string | null, walletId?: string | null): void {
+    const prevStatus = this.getWalletConnectionStatus();
+
+    this.currentAddress = address;
+    this.currentWalletId = walletId ?? null;
+
+    const newStatus = this.getWalletConnectionStatus();
+    this.notifyConnectionListeners(newStatus, prevStatus);
+  }
+
+  /**
+   * Gets the active StellarWalletsKit instance for advanced operations
+   * @returns The active kit or null if not available
+   */
+  public getActiveKit(): StellarWalletsKit | null {
+    return this.activeStellarKit || this.defaultInstanceKit;
+  }
+
+  /**
+   * Signs a transaction using the connected wallet
+   * @param xdr - The transaction XDR to sign
+   * @param address - The account address
+   * @returns Promise resolving to signed transaction
+   */
+  public async signTransaction(xdr: string, address: string): Promise<{ signedTxXdr: string }> {
+    if (!this.initialized) {
+      throw new Error('Wallet implementation not initialized');
+    }
+
+    const kit = this.getKitToUse();
+    const networkPassphrase = this.getWalletNetwork();
+
+    logger.info(LOG_SYSTEM, 'Signing transaction with wallet');
+
+    return await kit.signTransaction(xdr, {
+      address,
+      networkPassphrase,
+    });
+  }
+
+  /**
+   * Notifies all connection listeners of status changes
+   */
+  private notifyConnectionListeners(
+    currentStatus: StellarWalletConnectionStatus,
+    previousStatus: StellarWalletConnectionStatus
+  ): void {
+    this.connectionStatusListeners.forEach((listener) => {
+      try {
+        listener(currentStatus, previousStatus);
+      } catch (error) {
+        logger.error(LOG_SYSTEM, 'Error in connection status listener:', String(error));
+      }
+    });
+  }
+
+  /**
+   * Cleanup resources when implementation is no longer needed
+   */
+  public cleanup(): void {
+    if (this.unsubscribeFromStatusChanges) {
+      this.unsubscribeFromStatusChanges();
+      this.unsubscribeFromStatusChanges = undefined;
+    }
+    this.connectionStatusListeners.clear();
+    logger.info(LOG_SYSTEM, 'Cleanup completed');
+  }
+}

package/src/wallet/index.ts

@@ -0,0 +1,11 @@
+// Barrel file
+
+export * from './connection';
+export * from './stellar-wallets-kit';
+export * from './context';
+export * from './hooks';
+export * from './components';
+export * from './types';
+export * from './utils';
+export * from './implementation/wallets-kit-implementation';
+export { resolveFullUiKitConfiguration } from './services/configResolutionService';

package/src/wallet/services/__tests__/configResolutionService.test.ts

@@ -0,0 +1,163 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import type { UiKitConfiguration, UiKitName } from '@openzeppelin/ui-types';
+
+import { resolveFullUiKitConfiguration } from '../configResolutionService';
+
+describe('configResolutionService', () => {
+  describe('resolveFullUiKitConfiguration', () => {
+    it('should use programmatic overrides as highest priority', async () => {
+      const programmaticOverrides: Partial<UiKitConfiguration> = {
+        kitName: 'stellar-wallets-kit',
+        kitConfig: {
+          showInjectedConnector: true,
+          components: {
+            exclude: ['NetworkSwitcher'],
+          },
+        },
+      };
+
+      const initialAppServiceKitName = 'custom';
+      const currentAppServiceConfig: UiKitConfiguration = {
+        kitName: 'none',
+        kitConfig: {
+          showInjectedConnector: false,
+        },
+      };
+
+      const result = await resolveFullUiKitConfiguration(
+        programmaticOverrides,
+        initialAppServiceKitName,
+        currentAppServiceConfig
+      );
+
+      expect(result).toEqual({
+        kitName: 'stellar-wallets-kit',
+        kitConfig: {
+          showInjectedConnector: true,
+          components: {
+            exclude: ['NetworkSwitcher'],
+          },
+        },
+      });
+    });
+
+    it('should use current app service config when no programmatic overrides', async () => {
+      const initialAppServiceKitName = 'custom';
+      const currentAppServiceConfig: UiKitConfiguration = {
+        kitName: 'stellar-wallets-kit',
+        kitConfig: {
+          showInjectedConnector: true,
+        },
+      };
+
+      const result = await resolveFullUiKitConfiguration(
+        {},
+        initialAppServiceKitName,
+        currentAppServiceConfig
+      );
+
+      expect(result).toEqual(currentAppServiceConfig);
+    });
+
+    it('should use initial app service kit name as fallback', async () => {
+      const initialAppServiceKitName = 'stellar-wallets-kit';
+      const currentAppServiceConfig: UiKitConfiguration = {
+        kitName: undefined as unknown as UiKitName,
+        kitConfig: {},
+      };
+
+      const result = await resolveFullUiKitConfiguration(
+        {},
+        initialAppServiceKitName,
+        currentAppServiceConfig
+      );
+
+      expect(result).toEqual({
+        kitName: 'stellar-wallets-kit',
+        kitConfig: {},
+      });
+    });
+
+    it('should default to custom when no kit name is available', async () => {
+      const result = await resolveFullUiKitConfiguration({}, undefined, {
+        kitName: undefined as unknown as UiKitName,
+        kitConfig: {},
+      });
+
+      expect(result).toEqual({
+        kitName: 'custom',
+        kitConfig: {},
+      });
+    });
+
+    it('should merge kit configs with programmatic overrides taking precedence', async () => {
+      const programmaticOverrides: Partial<UiKitConfiguration> = {
+        kitConfig: {
+          showInjectedConnector: true,
+          components: {
+            exclude: ['AccountDisplay'],
+          },
+        },
+      };
+
+      const currentAppServiceConfig: UiKitConfiguration = {
+        kitName: 'custom',
+        kitConfig: {
+          showInjectedConnector: false,
+          components: {
+            exclude: ['NetworkSwitcher'],
+          },
+          appName: 'Test App',
+        },
+      };
+
+      const result = await resolveFullUiKitConfiguration(
+        programmaticOverrides,
+        'custom',
+        currentAppServiceConfig
+      );
+
+      expect(result).toEqual({
+        kitName: 'custom',
+        kitConfig: {
+          showInjectedConnector: true,
+          components: {
+            exclude: ['AccountDisplay'],
+          },
+          appName: 'Test App',
+        },
+      });
+    });
+
+    it('should log debug message when native config loader is provided', async () => {
+      const mockNativeConfigLoader = vi.fn();
+      const debugSpy = vi.spyOn(console, 'debug').mockImplementation(() => {});
+
+      await resolveFullUiKitConfiguration(
+        {},
+        'custom',
+        { kitName: 'custom', kitConfig: {} },
+        { loadUiKitNativeConfig: mockNativeConfigLoader }
+      );
+
+      // Verify the native config loader is acknowledged but not called
+      expect(mockNativeConfigLoader).not.toHaveBeenCalled();
+
+      debugSpy.mockRestore();
+    });
+
+    it('should handle empty kit configs gracefully', async () => {
+      const result = await resolveFullUiKitConfiguration(
+        { kitName: 'stellar-wallets-kit' },
+        'custom',
+        { kitName: 'custom', kitConfig: undefined as Record<string, unknown> | undefined }
+      );
+
+      expect(result).toEqual({
+        kitName: 'stellar-wallets-kit',
+        kitConfig: {},
+      });
+    });
+  });
+});

package/src/wallet/services/configResolutionService.ts

@@ -0,0 +1,65 @@
+import type { NativeConfigLoader, UiKitConfiguration } from '@openzeppelin/ui-types';
+import { logger } from '@openzeppelin/ui-utils';
+
+/**
+ * Resolves the final, complete UiKitConfiguration for Stellar by merging various sources.
+ *
+ * Note: Unlike the EVM adapter, Stellar has limited UI kit options, so this is simpler.
+ * We don't currently support loading native TypeScript config files for Stellar.
+ *
+ * @param programmaticOverrides - Overrides passed directly to the configureUiKit call.
+ * @param initialAppServiceKitName - The kitName noted from AppConfigService when the adapter instance was constructed.
+ * @param currentAppServiceConfig - The full UiKitConfiguration from AppConfigService, re-fetched at the time of the call.
+ * @param options - Options, including the callback to load user's native config file (currently unused for Stellar).
+ * @returns A Promise resolving to the final UiKitConfiguration.
+ */
+export async function resolveFullUiKitConfiguration(
+  programmaticOverrides: Partial<UiKitConfiguration>,
+  initialAppServiceKitName: UiKitConfiguration['kitName'],
+  currentAppServiceConfig: UiKitConfiguration,
+  options?: {
+    loadUiKitNativeConfig?: NativeConfigLoader;
+  }
+): Promise<UiKitConfiguration> {
+  logger.debug(
+    'stellar:configResolutionService:resolveFullUiKitConfiguration',
+    'Starting resolution with:',
+    {
+      programmaticOverrides,
+      initialAppServiceKitName,
+      currentAppServiceConfig,
+      hasLoadNativeCallback: !!options?.loadUiKitNativeConfig,
+    }
+  );
+
+  // Note: We currently don't support loading native TypeScript config files for Stellar
+  // This could be added in the future if needed
+  if (options?.loadUiKitNativeConfig) {
+    logger.debug(
+      'stellar:configResolutionService',
+      'Native config loader provided but not currently supported for Stellar adapter'
+    );
+  }
+
+  const effectiveKitName: UiKitConfiguration['kitName'] =
+    programmaticOverrides.kitName ||
+    currentAppServiceConfig.kitName ||
+    initialAppServiceKitName ||
+    'custom';
+
+  const finalFullConfig: UiKitConfiguration = {
+    kitName: effectiveKitName,
+    kitConfig: {
+      ...(currentAppServiceConfig.kitConfig || {}),
+      ...(programmaticOverrides.kitConfig || {}),
+    },
+  };
+
+  logger.debug(
+    'stellar:configResolutionService:resolveFullUiKitConfiguration',
+    'Resolved finalFullConfig:',
+    finalFullConfig
+  );
+
+  return finalFullConfig;
+}

package/src/wallet/stellar-wallets-kit/StellarWalletsKitConnectButton.tsx

@@ -0,0 +1,82 @@
+import { useEffect, useRef } from 'react';
+
+import { logger } from '@openzeppelin/ui-utils';
+
+import { setStellarConnectedAddress } from '../connection';
+import { stellarUiKitManager } from './stellarUiKitManager';
+
+/**
+ * Creates a Stellar Wallets Kit ConnectButton component.
+ * This renders the kit's native button UI which includes built-in connected state,
+ * copy address functionality, and disconnect options.
+ *
+ * @returns A React component that uses Stellar Wallets Kit's native button
+ */
+export function StellarWalletsKitConnectButton() {
+  const containerRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    const state = stellarUiKitManager.getState();
+    const kit = state.stellarKitProvider;
+
+    if (!kit || !containerRef.current) {
+      logger.error(
+        'StellarWalletsKitConnectButton',
+        'Kit not initialized or container not available'
+      );
+      return;
+    }
+
+    // Create the native button provided by Stellar Wallets Kit
+    kit.createButton({
+      container: containerRef.current,
+      onConnect: ({ address }) => {
+        logger.info('StellarWalletsKitConnectButton', `Connected to address: ${address}`);
+        // Inform the adapter's wallet implementation so the context updates
+        // This ensures the Execute Transaction button and other components
+        // recognize the wallet connection state
+        try {
+          setStellarConnectedAddress(address ?? null);
+        } catch (error) {
+          logger.warn(
+            'StellarWalletsKitConnectButton',
+            'Failed to set connected address in adapter implementation:',
+            error
+          );
+        }
+      },
+      onDisconnect: () => {
+        logger.info('StellarWalletsKitConnectButton', 'Disconnected');
+        // Inform the implementation we are no longer connected
+        try {
+          setStellarConnectedAddress(null);
+        } catch (error) {
+          logger.warn(
+            'StellarWalletsKitConnectButton',
+            'Failed to clear connected address in adapter implementation:',
+            error
+          );
+        }
+      },
+      buttonText: 'Connect Wallet',
+    });
+
+    // Cleanup: remove the button when component unmounts
+    return () => {
+      if (typeof kit.removeButton === 'function') {
+        try {
+          kit.removeButton();
+        } catch (error) {
+          logger.warn('StellarWalletsKitConnectButton', 'Error removing button:', error);
+        }
+      } else {
+        logger.warn(
+          'StellarWalletsKitConnectButton',
+          'removeButton method not available on kit instance'
+        );
+      }
+    };
+  }, []);
+
+  return <div ref={containerRef} className="stellar-native-button" />;
+}