@openzeppelin/adapter-stellar 1.0.0

package/src/vite-config.ts

@@ -0,0 +1,67 @@
+/**
+ * Stellar Adapter: Vite Configuration Export
+ *
+ * This module exports Vite configuration fragments for the Stellar adapter.
+ * Currently minimal, but provides a consistent interface for adapter-specific
+ * build requirements.
+ *
+ * USAGE:
+ * 1. In the main builder app: Import and merge into packages/builder/vite.config.ts
+ * 2. In exported apps: The export system injects these configs when Stellar is used
+ *
+ * See: docs/ADAPTER_ARCHITECTURE.md § "Build-Time Requirements"
+ */
+
+import type { UserConfig } from 'vite';
+
+/**
+ * Returns the Vite configuration required for Stellar adapter compatibility
+ *
+ * @returns Vite configuration object to be merged with your main vite.config
+ *
+ * @example
+ * ```typescript
+ * // vite.config.ts
+ * import { getStellarViteConfig } from '@openzeppelin/adapter-stellar/vite-config';
+ *
+ * export default defineConfig(({ mode }) => {
+ *   const stellarConfig = getStellarViteConfig();
+ *
+ *   return {
+ *     plugins: [
+ *       react(),
+ *       ...stellarConfig.plugins,
+ *     ],
+ *     resolve: {
+ *       dedupe: [
+ *         ...stellarConfig.resolve.dedupe,
+ *       ],
+ *     },
+ *   };
+ * });
+ * ```
+ */
+export function getStellarViteConfig(): UserConfig {
+  return {
+    // Currently no Stellar-specific plugins required
+    plugins: [],
+
+    resolve: {
+      // Module Deduplication
+      // Ensure singleton instances of shared dependencies
+      dedupe: [
+        // Stellar-specific dependencies that may need deduplication
+        '@stellar/stellar-sdk',
+        '@creit.tech/stellar-wallets-kit',
+      ],
+    },
+
+    optimizeDeps: {
+      // Force Pre-Bundling (CommonJS → ESM conversion)
+      // Stellar dependencies are typically already ESM, but we include them here
+      // for consistency and to ensure proper module resolution
+      include: [],
+      exclude: [],
+    },
+  };
+}

package/src/wallet/README.md

@@ -0,0 +1,93 @@
+# Stellar Adapter Wallet Module
+
+This directory contains the wallet integration layer for the Stellar adapter, providing all wallet‑related UI, hooks, context, and utilities using `@creit.tech/stellar-wallets-kit`.
+
+## Architectural Approach: Dual UI Support
+
+The Stellar adapter supports two UI modes:
+
+1. Native UI Mode (`stellar-wallets-kit`): Uses the Stellar Wallets Kit’s native button and modal with address display and account management.
+2. Custom UI Mode (`custom`): Uses custom React components that match the Builder’s design system.
+
+## Purpose
+
+- UI Environment Provision: `StellarWalletUiRoot` provides a stable provider root for wallet state.
+- Facade Hooks: `stellarFacadeHooks` expose standardized hooks for connection and account status.
+- UI Components: Custom‑styled wallet components (`ConnectButton`, `AccountDisplay`).
+- Configuration: Layered config via `AppConfigService` and programmatic overrides.
+
+## Directory Structure
+
+```text
+wallet/
+├── components/         # Wallet UI components & root
+│   ├── StellarWalletUiRoot.tsx
+│   ├── account/
+│   ├── connect/
+│   └── network/        # (Not used: no network switching in Stellar)
+├── context/
+├── hooks/
+├── implementation/     # Stellar Wallets Kit implementation
+├── services/           # Wallet UI config resolution
+├── stellar-wallets-kit/
+├── utils/
+└── connection.ts
+```
+
+## Key Components & Concepts
+
+- Adapter UI methods:
+  - `getEcosystemReactUiContextProvider()` → `StellarWalletUiRoot`
+  - `getEcosystemReactHooks()` → `stellarFacadeHooks`
+  - `getEcosystemWalletComponents()` → components for active kit
+- `stellarUiKitManager`: Singleton controller for kit state and network config
+- `StellarWalletUiRoot`: Stable provider that wires the kit and context
+- Facade hooks: `useStellarAccount`, `useStellarConnect`, `useStellarDisconnect`, `useUiKitConfig`
+
+## Differences from EVM Wallet Module
+
+- No network switching component (Stellar wallets do not switch networks dynamically)
+- Single primary wallet kit (Stellar Wallets Kit) vs multiple kits on EVM
+- No native TypeScript config files are loaded for kit setup (can be added later)
+
+## Configuration
+
+1. Global App Config (`app.config.json`):
+
+   Ecosystem‑namespaced configuration under `globalServiceConfigs.walletui.stellar`.
+
+   Custom UI components:
+
+   ```json
+   {
+     "globalServiceConfigs": {
+       "walletui": {
+         "stellar": {
+           "kitName": "custom",
+           "kitConfig": {
+             "showInjectedConnector": false,
+             "components": { "exclude": ["NetworkSwitcher"] }
+           }
+         }
+       }
+     }
+   }
+   ```
+
+   Native kit button:
+
+   ```json
+   {
+     "globalServiceConfigs": {
+       "walletui": {
+         "stellar": { "kitName": "stellar-wallets-kit", "kitConfig": {} }
+       }
+     }
+   }
+   ```
+
+2. Programmatic overrides: pass to `adapter.configureUiKit(overrides)`
+
+## Usage in Application
+
+`StellarWalletUiRoot` is returned by the adapter and used by the Builder’s `WalletStateProvider`. Use `useWalletState()` and facade hooks from `@openzeppelin/ui-react` to render the wallet UI components from `getEcosystemWalletComponents()`.

package/src/wallet/__tests__/connection.test.ts

@@ -0,0 +1,72 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import {
+  disconnectStellarWallet,
+  getStellarWalletConnectionStatus,
+  supportsStellarWalletConnection,
+} from '../connection';
+
+// Mock the stellar-wallets-kit to avoid CommonJS import issues
+vi.mock('@creit.tech/stellar-wallets-kit', () => ({
+  StellarWalletsKit: vi.fn(() => ({
+    getSupportedWallets: vi.fn().mockResolvedValue([]),
+    setWallet: vi.fn(),
+    getAddress: vi.fn(),
+    signTransaction: vi.fn(),
+  })),
+  WalletNetwork: {
+    PUBLIC: 'PUBLIC',
+    TESTNET: 'TESTNET',
+  },
+  allowAllModules: vi.fn(() => ({})),
+}));
+
+// Mock the stellarUiKitManager
+vi.mock('../stellar-wallets-kit', () => ({
+  stellarUiKitManager: {
+    getState: vi.fn(() => ({
+      isConfigured: true,
+      currentFullUiKitConfig: {
+        kitName: 'custom',
+        kitConfig: {},
+      },
+      stellarKitProvider: null,
+      networkConfig: {
+        type: 'testnet',
+        horizon: 'https://horizon-testnet.stellar.org',
+        passphrase: 'Test SDF Network ; September 2015',
+      },
+      hasConfigError: false,
+      lastConfigError: null,
+    })),
+  },
+}));
+
+describe('Stellar Wallet Connection', () => {
+  describe('supportsStellarWalletConnection', () => {
+    it('should return true', () => {
+      expect(supportsStellarWalletConnection()).toBe(true);
+    });
+  });
+
+  describe('disconnectStellarWallet', () => {
+    it('should disconnect wallet successfully', async () => {
+      await disconnectStellarWallet();
+
+      // Since disconnectStellarWallet only clears internal state and doesn't
+      // call any methods on the kit, we just verify it doesn't throw
+      expect(true).toBe(true);
+    });
+  });
+
+  describe('getStellarWalletConnectionStatus', () => {
+    it('should return disconnected status when no address', () => {
+      const status = getStellarWalletConnectionStatus();
+
+      expect(status).toHaveProperty('isConnected', false);
+      expect(status).toHaveProperty('address');
+      expect(status).toHaveProperty('walletId');
+      expect(status).toHaveProperty('chainId');
+    });
+  });
+});

package/src/wallet/components/StellarWalletUiRoot.tsx

@@ -0,0 +1,161 @@
+import type { ISupportedWallet } from '@creit.tech/stellar-wallets-kit';
+import { ReactNode, useCallback, useEffect, useState } from 'react';
+
+import type { UiKitConfiguration } from '@openzeppelin/ui-types';
+import { logger } from '@openzeppelin/ui-utils';
+
+import {
+  connectStellarWallet,
+  disconnectStellarWallet,
+  getStellarAvailableConnectors,
+  getStellarWalletConnectionStatus,
+  onStellarWalletConnectionChange,
+} from '../connection';
+import {
+  StellarWalletContext,
+  type StellarWalletContextType,
+} from '../context/StellarWalletContext';
+import { stellarUiKitManager, type StellarUiKitManagerState } from '../stellar-wallets-kit';
+
+/**
+ * Props for the StellarWalletUiRoot provider
+ */
+interface StellarWalletUiRootProps {
+  children: ReactNode;
+  /** UI kit configuration */
+  uiKitConfig?: UiKitConfiguration;
+}
+
+/**
+ * Stellar wallet UI root provider component
+ * This component manages the wallet connection state and provides it to child components
+ */
+export function StellarWalletUiRoot({ children, uiKitConfig }: StellarWalletUiRootProps) {
+  // UI Kit manager state
+  const [uiKitManagerState, setUiKitManagerState] = useState<StellarUiKitManagerState>(
+    stellarUiKitManager.getState()
+  );
+
+  // Connection state
+  const [address, setAddress] = useState<string | null>(null);
+  const [isConnecting, setIsConnecting] = useState(false);
+  const [availableWallets, setAvailableWallets] = useState<ISupportedWallet[]>([]);
+
+  // Initialize UI kit on mount
+  useEffect(() => {
+    // Only configure if a specific UI kit config is provided or if not already configured
+    const currentState = stellarUiKitManager.getState();
+
+    if (uiKitConfig || !currentState.currentFullUiKitConfig) {
+      const configToUse = uiKitConfig || { kitName: 'custom' as const, kitConfig: {} };
+
+      logger.debug('StellarWalletUiRoot', 'Configuring UI kit with:', configToUse);
+
+      stellarUiKitManager.configure(configToUse).catch((error) => {
+        logger.error('Failed to configure Stellar UI kit:', error);
+      });
+    }
+  }, [uiKitConfig]);
+
+  // Subscribe to UI kit state changes
+  useEffect(() => {
+    const unsubscribe = stellarUiKitManager.subscribe(() => {
+      setUiKitManagerState(stellarUiKitManager.getState());
+    });
+
+    return unsubscribe;
+  }, []);
+
+  // Event-driven connection status updates
+  useEffect(() => {
+    const unsubscribeFromConnectionChanges = onStellarWalletConnectionChange(
+      (currentStatus, _previousStatus) => {
+        setAddress(currentStatus.address || null);
+        logger.debug(
+          'StellarWalletUiRoot',
+          `Connection status changed: ${currentStatus.isConnected ? 'connected' : 'disconnected'}`,
+          currentStatus.address
+        );
+      }
+    );
+
+    // Initial update to sync current state
+    const initialStatus = getStellarWalletConnectionStatus();
+    setAddress(initialStatus.address || null);
+
+    return () => {
+      unsubscribeFromConnectionChanges();
+    };
+  }, [address]);
+
+  // Load available wallets
+  useEffect(() => {
+    const loadWallets = async () => {
+      try {
+        const connectors = await getStellarAvailableConnectors();
+        setAvailableWallets(connectors as unknown as ISupportedWallet[]);
+      } catch (error) {
+        logger.error('Failed to load available wallets:', String(error));
+      }
+    };
+
+    if (!uiKitManagerState.isInitializing && uiKitManagerState.stellarKitProvider) {
+      loadWallets();
+    }
+  }, [uiKitManagerState.isInitializing, uiKitManagerState.stellarKitProvider]);
+
+  /**
+   * Connect to a wallet
+   */
+  const connect = useCallback(async (walletId: string) => {
+    setIsConnecting(true);
+
+    try {
+      const result = await connectStellarWallet(walletId);
+
+      if (result.connected && result.address) {
+        setAddress(result.address);
+      } else {
+        throw new Error(result.error || 'Failed to connect wallet');
+      }
+    } catch (error) {
+      logger.error('Failed to connect:', String(error));
+      throw error;
+    } finally {
+      setIsConnecting(false);
+    }
+  }, []);
+
+  /**
+   * Disconnect from the current wallet
+   */
+  const disconnect = useCallback(async () => {
+    try {
+      const result = await disconnectStellarWallet();
+
+      if (result.disconnected) {
+        setAddress(null);
+      } else {
+        throw new Error(result.error || 'Failed to disconnect wallet');
+      }
+    } catch (error) {
+      logger.error('Failed to disconnect:', String(error));
+      throw error;
+    }
+  }, []);
+
+  const contextValue: StellarWalletContextType = {
+    address,
+    isConnected: address !== null,
+    isConnecting,
+    availableWallets,
+    connect,
+    disconnect,
+    uiKitManagerState,
+    kit: uiKitManagerState.stellarKitProvider,
+  };
+
+  return (
+    <StellarWalletContext.Provider value={contextValue}>{children}</StellarWalletContext.Provider>
+  );
+}

package/src/wallet/components/account/AccountDisplay.tsx

@@ -0,0 +1,50 @@
+import { LogOut } from 'lucide-react';
+import React from 'react';
+
+import { Button } from '@openzeppelin/ui-components';
+import type { BaseComponentProps } from '@openzeppelin/ui-types';
+import { cn, getWalletAccountDisplaySizeProps, truncateMiddle } from '@openzeppelin/ui-utils';
+
+import { useStellarAccount, useStellarDisconnect } from '../../hooks';
+
+/**
+ * A component that displays the connected account address.
+ * Also includes a disconnect button.
+ */
+export const CustomAccountDisplay: React.FC<BaseComponentProps> = ({
+  className,
+  size,
+  variant,
+  fullWidth,
+}) => {
+  const { isConnected, address } = useStellarAccount();
+  const { disconnect } = useStellarDisconnect();
+
+  const sizeProps = getWalletAccountDisplaySizeProps(size);
+
+  if (!isConnected || !address || !disconnect) {
+    return null;
+  }
+
+  return (
+    <div className={cn('flex items-center gap-2', fullWidth && 'w-full', className)}>
+      <div className={cn('flex flex-col', fullWidth && 'flex-1')}>
+        <span className={cn(sizeProps.textSize, 'font-medium')}>
+          {truncateMiddle(address, 4, 4)}
+        </span>
+        <span className={cn(sizeProps.subTextSize, 'text-muted-foreground -mt-0.5')}>
+          Stellar Account
+        </span>
+      </div>
+      <Button
+        onClick={() => disconnect()}
+        variant={variant || 'ghost'}
+        size="icon"
+        className={cn(sizeProps.iconButtonSize, 'p-0')}
+        title="Disconnect wallet"
+      >
+        <LogOut className={sizeProps.iconSize} />
+      </Button>
+    </div>
+  );
+};

package/src/wallet/components/connect/ConnectButton.tsx

@@ -0,0 +1,100 @@
+import { Loader2, Wallet } from 'lucide-react';
+import React, { useEffect, useState } from 'react';
+
+import { Button } from '@openzeppelin/ui-components';
+import type { BaseComponentProps } from '@openzeppelin/ui-types';
+import { cn, getWalletButtonSizeProps } from '@openzeppelin/ui-utils';
+
+import { useStellarAccount } from '../../hooks';
+import { ConnectorDialog } from './ConnectorDialog';
+
+/**
+ * A button that allows users to connect their wallet.
+ * Opens a dialog to select from available connectors.
+ * @param hideWhenConnected - Whether to hide the button when wallet is connected (default: true)
+ */
+export interface ConnectButtonProps extends BaseComponentProps {
+  hideWhenConnected?: boolean;
+}
+
+export const CustomConnectButton: React.FC<ConnectButtonProps> = ({
+  className,
+  size,
+  variant,
+  fullWidth,
+  hideWhenConnected = true,
+}) => {
+  const [dialogOpen, setDialogOpen] = useState(false);
+  const { isConnected, isConnecting } = useStellarAccount();
+
+  // Local state to indicate the button has been clicked and dialog is open, awaiting user selection
+  const [isManuallyInitiated, setIsManuallyInitiated] = useState(false);
+
+  const sizeProps = getWalletButtonSizeProps(size);
+
+  useEffect(() => {
+    if (isConnected && hideWhenConnected) {
+      setDialogOpen(false);
+      setIsManuallyInitiated(false); // Reset if dialog closes due to connection
+    }
+  }, [isConnected, hideWhenConnected]);
+
+  // If dialog is closed, reset manual initiation state
+  useEffect(() => {
+    if (!dialogOpen) {
+      setIsManuallyInitiated(false);
+    }
+  }, [dialogOpen]);
+
+  // If wallet reports it's connecting, we no longer need our manual pending state
+  useEffect(() => {
+    if (isConnecting) {
+      setIsManuallyInitiated(false);
+    }
+  }, [isConnecting]);
+
+  const handleConnectClick = () => {
+    if (!isConnected) {
+      setIsManuallyInitiated(true); // User clicked, show pending on button
+      setDialogOpen(true);
+    }
+  };
+
+  if (isConnected && hideWhenConnected) {
+    return null;
+  }
+
+  // Button shows loading if either hook reports connecting OR if user just clicked to open dialog
+  const showButtonLoading = isConnecting || isManuallyInitiated;
+
+  return (
+    <div className={cn('flex items-center', fullWidth && 'w-full', className)}>
+      <Button
+        onClick={handleConnectClick}
+        disabled={showButtonLoading || isConnected}
+        variant={variant || 'outline'}
+        size={sizeProps.size}
+        className={cn(sizeProps.className, fullWidth && 'w-full')}
+        title={isConnected ? 'Connected' : 'Connect Wallet'}
+      >
+        {showButtonLoading ? (
+          <Loader2 className={cn(sizeProps.iconSize, 'animate-spin mr-1')} />
+        ) : (
+          <Wallet className={cn(sizeProps.iconSize, 'mr-1')} />
+        )}
+        {showButtonLoading ? 'Connecting...' : 'Connect Wallet'}
+      </Button>
+
+      <ConnectorDialog
+        open={dialogOpen}
+        onOpenChange={(open) => {
+          setDialogOpen(open);
+          // If dialog is closed manually by user before selection, reset manual initiation
+          if (!open) {
+            setIsManuallyInitiated(false);
+          }
+        }}
+      />
+    </div>
+  );
+};

package/src/wallet/components/connect/ConnectorDialog.tsx

@@ -0,0 +1,125 @@
+import React, { useEffect, useState } from 'react';
+
+import {
+  Button,
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogHeader,
+  DialogTitle,
+} from '@openzeppelin/ui-components';
+import type { Connector } from '@openzeppelin/ui-types';
+import { logger } from '@openzeppelin/ui-utils';
+
+import { getStellarAvailableConnectors } from '../../connection';
+import { useStellarAccount, useStellarConnect } from '../../hooks';
+
+/**
+ * Dialog component for selecting a wallet connector
+ */
+interface ConnectorDialogProps {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+}
+
+export const ConnectorDialog: React.FC<ConnectorDialogProps> = ({ open, onOpenChange }) => {
+  const { connect } = useStellarConnect();
+  const { isConnected, isConnecting } = useStellarAccount();
+  const [connectingId, setConnectingId] = useState<string | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const [connectors, setConnectors] = useState<Connector[]>([]);
+  const [loadingConnectors, setLoadingConnectors] = useState(true);
+
+  // Load available connectors
+  useEffect(() => {
+    const loadConnectors = async () => {
+      try {
+        const availableConnectors = await getStellarAvailableConnectors();
+        setConnectors(availableConnectors);
+      } catch (err) {
+        logger.error('Failed to load Stellar connectors:', String(err));
+        setError('Failed to load available wallets');
+      } finally {
+        setLoadingConnectors(false);
+      }
+    };
+
+    if (open) {
+      loadConnectors();
+    }
+  }, [open]);
+
+  // Track connection attempts for dialog closure
+  useEffect(() => {
+    // If we're connected and there was a connection attempt, close the dialog
+    if (isConnected && connectingId) {
+      onOpenChange(false);
+      setConnectingId(null);
+      setError(null);
+    }
+  }, [isConnected, connectingId, onOpenChange]);
+
+  // If connect function itself is not available
+  if (!connect) {
+    return (
+      <Dialog open={open} onOpenChange={onOpenChange}>
+        <DialogContent className="sm:max-w-[425px]">
+          <DialogHeader>
+            <DialogTitle>Error</DialogTitle>
+          </DialogHeader>
+          <p>Wallet connection function is not available.</p>
+        </DialogContent>
+      </Dialog>
+    );
+  }
+
+  const handleConnectorSelect = async (selectedConnector: Connector) => {
+    setConnectingId(selectedConnector.id);
+    setError(null);
+
+    try {
+      await connect({ connector: selectedConnector });
+    } catch (err) {
+      setError(err instanceof Error ? err.message : 'Failed to connect');
+      setConnectingId(null);
+    }
+  };
+
+  return (
+    <Dialog open={open} onOpenChange={onOpenChange}>
+      <DialogContent className="sm:max-w-[425px]">
+        <DialogHeader>
+          <DialogTitle>Connect Wallet</DialogTitle>
+          <DialogDescription>
+            Select a wallet provider to connect with this application.
+          </DialogDescription>
+        </DialogHeader>
+
+        <div className="grid gap-4 py-4">
+          {loadingConnectors ? (
+            <p className="text-center text-muted-foreground">Loading available wallets...</p>
+          ) : connectors.length === 0 ? (
+            <p className="text-center text-muted-foreground">No wallet connectors available.</p>
+          ) : (
+            connectors.map((connector: Connector) => (
+              <Button
+                key={connector.id}
+                onClick={() => handleConnectorSelect(connector)}
+                disabled={isConnecting && connectingId === connector.id}
+                variant="outline"
+                className="flex justify-between items-center w-full py-6"
+              >
+                <span>{connector.name}</span>
+                {isConnecting && connectingId === connector.id && (
+                  <span className="ml-2 text-xs">Connecting...</span>
+                )}
+              </Button>
+            ))
+          )}
+        </div>
+
+        {error && <p className="text-sm text-red-500 mt-1">{error}</p>}
+      </DialogContent>
+    </Dialog>
+  );
+};

package/src/wallet/components/index.ts

@@ -0,0 +1,3 @@
+// Export all wallet UI components
+export { CustomConnectButton } from './connect/ConnectButton';
+export { CustomAccountDisplay } from './account/AccountDisplay';