@openzeppelin/adapter-stellar 1.0.0

package/src/wallet/connection.ts

@@ -0,0 +1,151 @@
+import type { Connector } from '@openzeppelin/ui-types';
+import { logger } from '@openzeppelin/ui-utils';
+
+import {
+  getInitializedStellarWalletImplementation,
+  getStellarWalletImplementation,
+} from './utils/stellarWalletImplementationManager';
+
+import { stellarUiKitManager } from './stellar-wallets-kit';
+import { StellarConnectionStatusListener } from './types';
+
+/**
+ * Indicates if this adapter supports wallet connection
+ * @returns Whether wallet connection is supported by this adapter
+ */
+export function supportsStellarWalletConnection(): boolean {
+  return true;
+}
+
+/**
+ * Get available Stellar wallet connectors
+ */
+export async function getStellarAvailableConnectors(): Promise<Connector[]> {
+  const impl = await getStellarWalletImplementation();
+  return impl.getAvailableConnectors();
+}
+
+/**
+ * Connect to a Stellar wallet
+ * @param connectorId - The ID of the wallet to connect to
+ */
+export async function connectStellarWallet(
+  connectorId: string
+): Promise<{ connected: boolean; address?: string; error?: string }> {
+  const impl = await getStellarWalletImplementation();
+  return impl.connect(connectorId);
+}
+
+/**
+ * Disconnect from the current Stellar wallet
+ */
+export async function disconnectStellarWallet(): Promise<{
+  disconnected: boolean;
+  error?: string;
+}> {
+  const impl = await getStellarWalletImplementation();
+  return impl.disconnect();
+}
+
+/**
+ * Get the current wallet connection status
+ * @inheritdoc
+ */
+export function getStellarWalletConnectionStatus(): {
+  isConnected: boolean;
+  address?: string;
+  chainId?: string;
+  walletId?: string;
+} {
+  const impl = getInitializedStellarWalletImplementation();
+  if (!impl) {
+    logger.warn(
+      'getStellarWalletConnectionStatus',
+      'Wallet implementation not ready. Returning default disconnected state.'
+    );
+    return {
+      isConnected: false,
+      address: undefined,
+      chainId: stellarUiKitManager.getState().networkConfig?.id || 'stellar-testnet',
+      walletId: undefined,
+    };
+  }
+
+  const status = impl.getWalletConnectionStatus();
+  return {
+    isConnected: status.isConnected,
+    address: status.address,
+    chainId: typeof status.chainId === 'number' ? status.chainId.toString() : status.chainId,
+    walletId: status.walletId,
+  };
+}
+
+/**
+ * Update the cached Stellar wallet connection state.
+ * Used by provider code that derives the address directly from the kit.
+ */
+export function setStellarConnectedAddress(address: string | null, walletId?: string | null): void {
+  const impl = getInitializedStellarWalletImplementation();
+  if (impl) {
+    impl.updateConnectionStatus(address, walletId);
+  } else {
+    logger.warn(
+      'setStellarConnectedAddress',
+      'Wallet implementation not ready. Cannot update connection status.'
+    );
+  }
+}
+
+// StellarConnectionStatusListener is now imported from the implementation file
+
+/**
+ * Subscribe to Stellar wallet connection status changes
+ * @param callback Function to call when connection status changes
+ * @returns Unsubscribe function
+ */
+export function onStellarWalletConnectionChange(
+  callback: StellarConnectionStatusListener
+): () => void {
+  const impl = getInitializedStellarWalletImplementation();
+  if (!impl) {
+    logger.warn(
+      'onStellarWalletConnectionChange',
+      'Wallet implementation not ready. Returning no-op.'
+    );
+    return () => {};
+  }
+
+  // Convert from implementation status format to connection format
+  return impl.onWalletConnectionChange((currentImplStatus, prevImplStatus) => {
+    const currentStatus = {
+      isConnected: currentImplStatus.isConnected,
+      address: currentImplStatus.address,
+      chainId: currentImplStatus.chainId,
+      walletId: currentImplStatus.walletId,
+    };
+    const previousStatus = {
+      isConnected: prevImplStatus.isConnected,
+      address: prevImplStatus.address,
+      chainId: prevImplStatus.chainId,
+      walletId: prevImplStatus.walletId,
+    };
+
+    try {
+      callback(currentStatus, previousStatus);
+    } catch (error) {
+      logger.error('Error in Stellar connection status listener:', String(error));
+    }
+  });
+}
+
+/**
+ * Sign a transaction using the connected wallet
+ * @internal
+ */
+export async function signTransaction(
+  xdr: string,
+  address: string
+): Promise<{ signedTxXdr: string }> {
+  const impl = await getStellarWalletImplementation();
+  return impl.signTransaction(xdr, address);
+}

package/src/wallet/context/StellarWalletContext.ts

@@ -0,0 +1,32 @@
+import type { ISupportedWallet, StellarWalletsKit } from '@creit.tech/stellar-wallets-kit';
+import { createContext } from 'react';
+
+import type { StellarUiKitManagerState } from '../stellar-wallets-kit';
+
+/**
+ * Stellar wallet context type
+ */
+export interface StellarWalletContextType {
+  // Connection state
+  address: string | null;
+  isConnected: boolean;
+  isConnecting: boolean;
+
+  // Available wallets
+  availableWallets: ISupportedWallet[];
+
+  // Connection methods
+  connect: (walletId: string) => Promise<void>;
+  disconnect: () => Promise<void>;
+
+  // UI Kit manager state
+  uiKitManagerState: StellarUiKitManagerState;
+
+  // Kit instance (for advanced usage)
+  kit: StellarWalletsKit | null;
+}
+
+/**
+ * Create the context with undefined default value
+ */
+export const StellarWalletContext = createContext<StellarWalletContextType | undefined>(undefined);

package/src/wallet/context/index.ts

@@ -0,0 +1,4 @@
+// Re-export from components directory to maintain backwards compatibility
+export { StellarWalletUiRoot } from '../components/StellarWalletUiRoot';
+export * from './StellarWalletContext';
+export * from './useStellarWalletContext';

package/src/wallet/context/useStellarWalletContext.ts

@@ -0,0 +1,17 @@
+import { useContext } from 'react';
+
+import { StellarWalletContext, type StellarWalletContextType } from './StellarWalletContext';
+
+/**
+ * Hook to use the Stellar wallet context
+ * @throws Error if used outside of StellarWalletUiRoot
+ */
+export function useStellarWalletContext(): StellarWalletContextType {
+  const context = useContext(StellarWalletContext);
+
+  if (context === undefined) {
+    throw new Error('useStellarWalletContext must be used within a StellarWalletUiRoot');
+  }
+
+  return context;
+}

package/src/wallet/hooks/facade-hooks.ts

@@ -0,0 +1,31 @@
+import type { EcosystemSpecificReactHooks } from '@openzeppelin/ui-types';
+
+import { useStellarAccount } from './useStellarAccount';
+import { useStellarConnect } from './useStellarConnect';
+import { useStellarDisconnect } from './useStellarDisconnect';
+
+/**
+ * Stellar-specific facade hooks following the EcosystemSpecificReactHooks interface
+ * These hooks provide a standardized interface for wallet operations in the Stellar ecosystem
+ */
+export const stellarFacadeHooks: EcosystemSpecificReactHooks = {
+  // Account management
+  useAccount: useStellarAccount,
+
+  // Connection management
+  useConnect: useStellarConnect,
+  useDisconnect: useStellarDisconnect,
+
+  // Stellar doesn't have the same network switching capabilities as EVM
+  // These are included for interface compatibility but may not be fully functional
+  useSwitchChain: () => ({ switchChain: undefined }),
+  useChainId: () => 'stellar',
+  useChains: () => [],
+
+  // Transaction and signing hooks - to be implemented as needed
+  useBalance: () => ({ data: undefined, isLoading: false }),
+  useSendTransaction: () => ({ sendTransaction: undefined }),
+  useWaitForTransactionReceipt: () => ({ data: undefined }),
+  useSignMessage: () => ({ signMessage: undefined }),
+  useSignTypedData: () => ({ signTypedData: undefined }),
+};

package/src/wallet/hooks/index.ts

@@ -0,0 +1,7 @@
+// Barrel file for Stellar wallet hooks
+
+export * from './facade-hooks';
+export * from './useStellarAccount';
+export * from './useStellarConnect';
+export * from './useStellarDisconnect';
+export * from './useUiKitConfig';

package/src/wallet/hooks/useStellarAccount.ts

@@ -0,0 +1,27 @@
+import { useStellarWalletContext } from '../context';
+
+/**
+ * Account information returned by the hook
+ */
+export interface StellarAccountInfo {
+  /** The connected wallet address */
+  address: string | null;
+  /** Whether a wallet is currently connected */
+  isConnected: boolean;
+  /** Whether a connection is in progress */
+  isConnecting: boolean;
+}
+
+/**
+ * Hook to get the current Stellar account information
+ * @returns Account information including address and connection status
+ */
+export function useStellarAccount(): StellarAccountInfo {
+  const { address, isConnected, isConnecting } = useStellarWalletContext();
+
+  return {
+    address,
+    isConnected,
+    isConnecting,
+  };
+}

package/src/wallet/hooks/useStellarConnect.ts

@@ -0,0 +1,60 @@
+import type { ISupportedWallet } from '@creit.tech/stellar-wallets-kit';
+import { useCallback, useState } from 'react';
+
+import type { Connector } from '@openzeppelin/ui-types';
+
+import { useStellarWalletContext } from '../context';
+
+/**
+ * Connect hook return type - matches what react-core expects
+ */
+export interface StellarConnectReturnType {
+  connect: (args: { connector: Connector }) => Promise<void>;
+  connectors: Connector[];
+  isLoading: boolean;
+  isPending: boolean;
+  error: Error | null;
+}
+
+/**
+ * Hook to get the wallet connect function and status
+ * @returns An object with connect function and connection status
+ */
+export function useStellarConnect(): StellarConnectReturnType {
+  const { connect, isConnecting, availableWallets } = useStellarWalletContext();
+  const [error, setError] = useState<Error | null>(null);
+
+  const connectFunction = useCallback(
+    async ({ connector }: { connector: Connector }) => {
+      try {
+        // Clear any previous errors
+        setError(null);
+        await connect(connector.id);
+      } catch (err) {
+        // Store the error for access by the consumer
+        const connectError = err instanceof Error ? err : new Error(String(err));
+        setError(connectError);
+        // Re-throw to maintain the same behavior for error handling in UI components
+        throw connectError;
+      }
+    },
+    [connect]
+  );
+
+  // Convert ISupportedWallet[] to Connector[]
+  const connectors: Connector[] = availableWallets.map((wallet: ISupportedWallet) => ({
+    id: wallet.id,
+    name: wallet.name,
+    icon: wallet.icon,
+    installed: wallet.isAvailable,
+    type: (wallet.type as string) || 'browser',
+  }));
+
+  return {
+    connect: connectFunction,
+    connectors,
+    isLoading: isConnecting,
+    isPending: isConnecting,
+    error,
+  };
+}

package/src/wallet/hooks/useStellarDisconnect.ts

@@ -0,0 +1,47 @@
+import { useCallback, useState } from 'react';
+
+import { useStellarWalletContext } from '../context';
+
+/**
+ * Disconnect hook return type - matches what react-core expects
+ */
+export interface StellarDisconnectReturnType {
+  disconnect: () => Promise<void>;
+  isLoading: boolean;
+  isPending: boolean;
+  error: Error | null;
+}
+
+/**
+ * Hook to get the wallet disconnect function and status
+ * @returns An object with disconnect function and disconnection status
+ */
+export function useStellarDisconnect(): StellarDisconnectReturnType {
+  const { disconnect } = useStellarWalletContext();
+  const [isDisconnecting, setIsDisconnecting] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const disconnectFunction = useCallback(async () => {
+    try {
+      // Clear any previous errors
+      setError(null);
+      setIsDisconnecting(true);
+      await disconnect();
+    } catch (err) {
+      // Store the error for access by the consumer
+      const disconnectError = err instanceof Error ? err : new Error(String(err));
+      setError(disconnectError);
+      // Re-throw to maintain the same behavior for error handling in UI components
+      throw disconnectError;
+    } finally {
+      setIsDisconnecting(false);
+    }
+  }, [disconnect]);
+
+  return {
+    disconnect: disconnectFunction,
+    isLoading: isDisconnecting,
+    isPending: isDisconnecting,
+    error,
+  };
+}

package/src/wallet/hooks/useUiKitConfig.ts

@@ -0,0 +1,40 @@
+import type { UiKitConfiguration } from '@openzeppelin/ui-types';
+import { appConfigService, logger } from '@openzeppelin/ui-utils';
+
+/**
+ * Default configuration when no specific configuration is provided
+ */
+const defaultConfig: UiKitConfiguration = {
+  kitName: 'custom', // Default to using our custom implementation for Stellar
+  kitConfig: {},
+};
+
+/**
+ * Loads the initial UI kit configuration from the AppConfigService
+ * @returns The UI kit configuration from app.config.local.json or defaults
+ */
+export function loadInitialConfigFromAppService(): UiKitConfiguration {
+  logger.debug(
+    'stellar:useUiKitConfig',
+    'Attempting to load initial config from AppConfigService...'
+  );
+  const configObj = appConfigService.getWalletUIConfig<UiKitConfiguration>('stellar');
+
+  if (configObj && configObj.kitName) {
+    logger.info(
+      'stellar:useUiKitConfig',
+      `Loaded initial config from AppConfigService: kitName=${configObj.kitName}`,
+      configObj.kitConfig
+    );
+    // Merge with defaults to ensure all base keys are present if AppConfigService only provides partial config
+    return {
+      kitName: configObj.kitName,
+      kitConfig: { ...defaultConfig.kitConfig, ...(configObj.kitConfig || {}) },
+    };
+  }
+  logger.debug(
+    'stellar:useUiKitConfig',
+    'No initial config found in AppConfigService, using module default.'
+  );
+  return { ...defaultConfig };
+}