@hsuite/native-connect-angular 1.0.0

package/src/lib/services/unified-wallet.service.ts

@@ -0,0 +1,852 @@
+/**
+ * HSuite Native Connect
+ * Copyright 2024-2025 HSuite (https://hsuite.finance)
+ *
+ * SPDX-License-Identifier: PolyForm-Noncommercial-1.0.0
+ *
+ * This file is part of HSuite Native Connect. For commercial licensing,
+ * visit https://hsuite.finance/licensing
+ */
+
+/**
+ * @file Central service for managing multiple wallet providers in Angular applications.
+ * @module services/unified-wallet
+ *
+ * @description
+ * UnifiedWalletService is the primary entry point for dApp developers to interact with
+ * blockchain wallets. It provides a unified API that abstracts the differences between
+ * various wallet connection protocols (HSuite Native, WalletConnect, P2P).
+ *
+ * Key Capabilities:
+ * - **Multi-Provider Management**: Register and manage multiple wallet providers
+ * - **Unified Account Access**: Aggregate accounts from all connected providers
+ * - **Active Account Tracking**: Maintain and switch the currently active account
+ * - **Transaction Operations**: Sign and submit transactions through any connected wallet
+ * - **Session Management**: Handle wallet sessions with automatic reconnection
+ *
+ * Architecture:
+ * ```
+ * +-------------------------------------------------------------------+
+ * |                    UnifiedWalletService                          |
+ * +-------------------------------------------------------------------+
+ * |                                                                   |
+ * |  +-------------------+  +-------------------+  +----------------+ |
+ * |  | HsuiteNative      |  | WalletConnect     |  | P2PNative      | |
+ * |  | Provider          |  | V2Provider        |  | Provider       | |
+ * |  +-------------------+  +-------------------+  +----------------+ |
+ * |         |                      |                      |          |
+ * |         +----------------------+----------------------+          |
+ * |                                |                                 |
+ * |                    BaseWalletProvider                            |
+ * |                    (common interface)                            |
+ * +-------------------------------------------------------------------+
+ * ```
+ */
+
+import { Injectable, signal, computed, inject, effect } from '@angular/core';
+import { getLogger } from '@hsuite/native-connect-sdk';
+
+import type { ConnectionConfig } from '../models/connection-config.model';
+import type { ProviderType, ConnectionStatus } from '../models/provider-types';
+import type { UnifiedAccount } from '../models/unified-account.model';
+import { BaseWalletProvider } from '../providers/base-wallet-provider';
+import { HsuiteNativeProvider } from '../providers/hsuite-native-provider';
+import { P2PNativeProvider } from '../providers/p2p-native/p2p-native.provider';
+import { WalletConnectV2Provider } from '../providers/walletconnect/core/walletconnect-provider';
+
+import { WalletEventBus } from './wallet-event-bus.service';
+
+
+const logger = getLogger().scoped?.('UnifiedWalletService') ?? getLogger();
+
+interface ProviderSummary {
+  id: string;
+  name: string;
+  providerType: string;
+  status: ConnectionStatus;
+  accounts: UnifiedAccount[];
+  supportsReconnect: boolean;
+}
+
+/**
+ * Central service for managing wallet connections across multiple protocols.
+ *
+ * @description
+ * UnifiedWalletService provides a unified interface for interacting with blockchain wallets
+ * regardless of the underlying connection protocol. It manages multiple provider instances,
+ * aggregates accounts, and provides transaction signing/submission capabilities.
+ *
+ * The service automatically registers built-in providers (HSuite Native, WalletConnect, P2P)
+ * and supports session restoration across page reloads.
+ *
+ * @Component({
+ *   template: `
+ *     <div *ngIf="wallet.activeAccount() as account">
+ *       Connected: {{ account.address }}
+ *     </div>
+ *     <button (click)="connectWallet()">Connect</button>
+ *   `
+ * })
+ * export class MyComponent {
+ *   wallet = inject(UnifiedWalletService);
+ *
+ *   async connectWallet() {
+ *     await this.wallet.connect('hsuite-native', {
+ *       type: 'hsuite-native',
+ *       appId: 'my-dapp',
+ *       appName: 'My dApp',
+ *       ledgerId: 'hedera',
+ *       networkId: 'testnet',
+ *     });
+ *   }
+ * }
+ * ```
+ *
+ * @publicApi
+ */
+@Injectable({ providedIn: 'root' })
+export class UnifiedWalletService {
+  /**
+   * Map of registered providers
+   */
+  private readonly providers = new Map<string, BaseWalletProvider>();
+
+  /**
+   * Signal tracking all registered provider IDs
+   */
+  private readonly _providerIds = signal<string[]>([]);
+
+  /**
+   * Signal for the active account (across all providers)
+   */
+  private readonly _activeAccount = signal<UnifiedAccount | null>(null);
+
+  /**
+   * Event bus for emitting wallet events
+   */
+  private readonly eventBus = inject(WalletEventBus);
+
+  /**
+   *
+   * @param hsuiteProvider
+   * @param walletConnectProvider
+   * @param p2pNativeProvider
+   */
+  constructor(
+    hsuiteProvider: HsuiteNativeProvider,
+    walletConnectProvider: WalletConnectV2Provider,
+    p2pNativeProvider: P2PNativeProvider,
+  ) {
+    // Auto-register built-in providers (injected as constructor params)
+    this.registerProvider(hsuiteProvider);
+    this.registerProvider(walletConnectProvider);
+    this.registerProvider(p2pNativeProvider);
+
+    // Auto-select first account from unknown restored session (after a delay to let providers restore)
+    setTimeout(() => {
+      const allAccounts = this.allAccounts();
+      if (!this._activeAccount() && allAccounts.length > 0) {
+        this.setActiveAccount(allAccounts[0]);
+
+        // Emit session restored event
+        this.eventBus.sessionRestored.emit({
+          providerId: allAccounts[0].providerId,
+          sessionKey: allAccounts[0].id,
+          accounts: allAccounts,
+          metadata: { autoRestored: true },
+          timestamp: Date.now(),
+        });
+      }
+    }, 100);
+
+    effect(() => {
+      const accounts = this.allAccounts();
+      const active = this._activeAccount();
+
+      if (accounts.length === 0) {
+        if (active) {
+          this.setActiveAccount(null);
+        }
+        return;
+      }
+
+      const activeStillPresent = active ? accounts.some((acct) => acct.id === active.id) : false;
+      if (!activeStillPresent) {
+        this.setActiveAccount(accounts[0]);
+      }
+    });
+  }
+
+  /**
+   * Gets summaries of all registered providers including status and accounts.
+   *
+   * @description
+   * Returns metadata about each registered provider, useful for building
+   * wallet selection UI or debugging connection states.
+   *
+   * @returns Array of provider summaries with status and account information
+   */
+  getProviderSummaries(): ProviderSummary[] {
+    return Array.from(this.providers.values()).map((provider) => ({
+      id: provider.id,
+      name: provider.metadata.name,
+      providerType: provider.metadata.type,
+      status: provider.status(),
+      accounts: provider.accounts(),
+      supportsReconnect: typeof (provider as any).attemptReconnect === 'function',
+    }));
+  }
+
+  /**
+   * Attempts to reconnect a provider using stored session data.
+   *
+   * @description
+   * Some providers (like HSuite Native) support session persistence and can
+   * automatically reconnect after page reload without user interaction.
+   * This method triggers the reconnection attempt.
+   *
+   * @param providerId - The provider ID to reconnect (e.g., 'hsuite-native')
+   *
+   * @returns Promise resolving to true if reconnection succeeded, false otherwise
+   */
+  async reconnectProvider(providerId: string): Promise<boolean> {
+    const provider = this.providers.get(providerId);
+    if (!provider) {
+      return false;
+    }
+    const reconnect = (provider as unknown as { attemptReconnect?: () => Promise<boolean> })
+      .attemptReconnect;
+    if (typeof reconnect === 'function') {
+      try {
+        return await reconnect.call(provider);
+      } catch (error) {
+        logger.warn('Provider reconnect failed', { providerId, error });
+        return false;
+      }
+    }
+    return false;
+  }
+
+  /**
+   * All accounts from all connected providers (reactive)
+   */
+  readonly allAccounts = computed<UnifiedAccount[]>(() => {
+    const providers = Array.from(this.providers.values());
+    return providers.flatMap((p) => p.accounts());
+  });
+
+  /**
+   * Currently active account (reactive)
+   */
+  readonly activeAccount = computed(() => this._activeAccount());
+
+  /**
+   * List of connected providers (reactive)
+   */
+  readonly connectedProviders = computed<BaseWalletProvider[]>(() => {
+    return Array.from(this.providers.values()).filter((p) => p.isConnected());
+  });
+
+  /**
+   * Transport state for HSuite Native and P2P Native connections.
+   * Values: 'idle' | 'nostr-only' | 'upgrading' | 'p2p-connected' | 'p2p-failed'
+   *
+   * Checks both HSuite Native and P2P Native providers.
+   * Returns 'idle' for non-HSuite connections (WalletConnect, etc.)
+   */
+  readonly transportState = computed<string>(() => {
+    // Check HSuite Native provider first
+    const hsuiteProvider = this.providers.get('hsuite-native') as HsuiteNativeProvider | undefined;
+    if (hsuiteProvider) {
+      const status = hsuiteProvider.status();
+      if (status === 'connecting' || status === 'connected') {
+        return hsuiteProvider.transportState();
+      }
+    }
+
+    // Check P2P Native provider (mobile-native)
+    const p2pProvider = this.providers.get('mobile-native') as P2PNativeProvider | undefined;
+    if (p2pProvider) {
+      const status = p2pProvider.status();
+      if (status === 'connecting' || status === 'connected') {
+        return p2pProvider.transportState();
+      }
+    }
+
+    return 'idle';
+  });
+
+  /**
+   * Registers a wallet provider instance.
+   *
+   * @description
+   * Adds a provider to the service's internal registry. Once registered,
+   * the provider's accounts will be included in {@link allAccounts} and
+   * can be used for wallet operations.
+   *
+   * Built-in providers (HSuite Native, WalletConnect, P2P) are auto-registered.
+   * Use this method only for custom provider implementations.
+   *
+   * @param provider - The provider instance to register
+   */
+  registerProvider(provider: BaseWalletProvider): void {
+    if (this.providers.has(provider.id)) {
+      logger.warn('Provider already registered', { providerId: provider.id });
+      return;
+    }
+
+    this.providers.set(provider.id, provider);
+    this._providerIds.set(Array.from(this.providers.keys()));
+  }
+
+  /**
+   * Unregisters a wallet provider.
+   *
+   * @description
+   * Removes a provider from the service's registry. The provider's accounts
+   * will no longer be included in {@link allAccounts}.
+   *
+   * @param providerId - The provider ID to unregister
+   */
+  unregisterProvider(providerId: string): void {
+    this.providers.delete(providerId);
+    this._providerIds.set(Array.from(this.providers.keys()));
+  }
+
+  /**
+   * Gets a specific provider by ID.
+   *
+   * @description
+   * Retrieves a registered provider instance for direct interaction.
+   * Useful for accessing provider-specific features not exposed through
+   * the unified interface.
+   *
+   * @param providerId - The provider ID (e.g., 'hsuite-native', 'walletconnect-v2')
+   *
+   * @returns The provider instance or undefined if not found
+   */
+  getProvider(providerId: string): BaseWalletProvider | undefined {
+    return this.providers.get(providerId);
+  }
+
+  /**
+   * Gets all providers of a specific type.
+   *
+   * @description
+   * Filters providers by their type, useful when you need to work with
+   * a specific category of wallets.
+   *
+   * @param type - Provider type to filter by (e.g., 'hsuite-native', 'walletconnect-v2')
+   *
+   * @returns Array of providers matching the specified type
+   */
+  getProvidersByType(type: ProviderType): BaseWalletProvider[] {
+    return Array.from(this.providers.values()).filter((p) => p.metadata.type === type);
+  }
+
+  /**
+   * Connects to a wallet using a specific provider.
+   *
+   * @description
+   * Initiates a wallet connection through the specified provider. The connection
+   * flow varies by provider type:
+   * - **HSuite Native**: Opens wallet window/tab or uses Nostr discovery
+   * - **WalletConnect**: Displays QR code for mobile wallet scanning
+   * - **P2P Native**: Displays QR code for direct P2P connection
+   *
+   * Upon successful connection, emits 'connected' and 'accountsUpdated' events
+   * via WalletEventBus.
+   *
+   * @param providerId - The provider ID to use for connection
+   * @param config - Connection configuration (varies by provider type)
+   *
+   * @throws {Error} If provider is not found
+   * @throws {Error} If connection fails or times out
+   */
+  async connect(providerId: string, config: ConnectionConfig): Promise<void> {
+    const provider = this.providers.get(providerId);
+    if (!provider) {
+      throw new Error(`Provider ${providerId} not found`);
+    }
+
+    await provider.connect(config);
+
+    const accounts = provider.accounts();
+
+    // Emit connection event
+    this.eventBus.connected.emit({
+      providerId,
+      providerType: provider.metadata.type as 'hsuite-native' | 'walletconnect-v2',
+      accounts,
+      timestamp: Date.now(),
+    });
+
+    // Emit accounts updated
+    this.eventBus.accountsUpdated.emit({
+      providerId,
+      accounts,
+      totalAccounts: this.allAccounts().length,
+      timestamp: Date.now(),
+    });
+
+    // Auto-select first account if none is active
+    if (!this._activeAccount() && provider.accounts().length > 0) {
+      this.setActiveAccount(provider.accounts()[0]);
+    }
+  }
+
+  /**
+   * Disconnects a specific provider.
+   *
+   * @description
+   * Terminates the wallet connection for the specified provider. If the active
+   * account belonged to this provider, automatically selects another available
+   * account or clears the active account.
+   *
+   * @param providerId - The provider ID to disconnect
+   *
+   * @throws {Error} If provider is not found
+   */
+  async disconnect(providerId: string): Promise<void> {
+    const provider = this.providers.get(providerId);
+    if (!provider) {
+      throw new Error(`Provider ${providerId} not found`);
+    }
+
+    await provider.disconnect();
+
+    // If the active account belonged to this provider, clear it
+    const active = this._activeAccount();
+    if (active && active.providerId === providerId) {
+      // Try to select another account from a different provider
+      const accounts = this.allAccounts();
+      const nextAccount = accounts.find((a) => a.providerId !== providerId);
+      this.setActiveAccount(nextAccount || null);
+    }
+  }
+
+  /**
+   * Disconnects all connected providers.
+   *
+   * @description
+   * Terminates all wallet connections and clears the active account.
+   * Useful for logout flows or cleanup operations.
+   */
+  async disconnectAll(): Promise<void> {
+    const disconnectPromises = Array.from(this.providers.values())
+      .filter((p) => p.isConnected())
+      .map((p) => p.disconnect());
+
+    await Promise.all(disconnectPromises);
+    this.setActiveAccount(null);
+  }
+
+  /**
+   * Sets the active account for wallet operations.
+   *
+   * @description
+   * Changes the currently active account. All subsequent signing and transaction
+   * operations will use this account. Emits an 'accountChanged' event via
+   * WalletEventBus.
+   *
+   * @param account - The account to set as active, or null to clear
+   */
+  setActiveAccount(account: UnifiedAccount | null): void {
+    const previous = this._activeAccount();
+    this._activeAccount.set(account);
+
+    // Emit account change event
+    this.eventBus.accountChanged.emit({
+      previousAccount: previous,
+      newAccount: account,
+      timestamp: Date.now(),
+    });
+  }
+
+  /**
+   * Signs a transaction using the active account.
+   *
+   * @description
+   * Requests the wallet to sign the provided transaction payload using the
+   * active account's private key. The transaction is not submitted to the
+   * network.
+   *
+   * @param payload - Serialized transaction payload to sign (format depends on ledger)
+   *
+   * @returns Promise resolving to sign result with signed payload and signature
+   *
+   * @throws {Error} If no active account is set
+   * @throws {Error} If provider is not found
+   * @throws {Error} If user rejects the signing request
+   */
+  async signTransaction(payload: string): Promise<unknown> {
+    const account = this._activeAccount();
+    if (!account) {
+      throw new Error('No active account');
+    }
+
+    const provider = this.providers.get(account.providerId);
+    if (!provider) {
+      throw new Error(`Provider ${account.providerId} not found`);
+    }
+
+    return await provider.signTransaction({
+      accountAddress: account.address,
+      payload,
+      ledgerId: account.ledgerId,
+      networkId: account.networkId,
+    });
+  }
+
+  /**
+   * Submits a transaction using the active account.
+   *
+   * @description
+   * Signs and submits a transaction to the blockchain network. This is a two-step
+   * operation: sign then submit. For a single-prompt flow, use
+   * {@link signAndExecuteTransaction} instead.
+   *
+   * Supports batch transactions when isBatch is true.
+   *
+   * @param payload - Serialized transaction payload to submit
+   * @param options - Optional submission options
+   * @param options.isBatch - Whether this is a batch transaction
+   * @param options.batchKey - Unique key for batch grouping
+   * @param options.innerTransactions - Individual transactions within the batch
+   *
+   * @returns Promise resolving to submit result with transaction ID and hash
+   *
+   * @throws {Error} If no active account is set
+   * @throws {Error} If provider is not found
+   * @throws {Error} If user rejects or transaction fails
+   */
+  async submitTransaction(
+    payload: string,
+    options?: {
+      isBatch?: boolean;
+      batchKey?: string;
+      innerTransactions?: Array<{ payload: string; description?: string }>;
+    },
+  ): Promise<unknown> {
+    const account = this._activeAccount();
+    if (!account) {
+      throw new Error('No active account');
+    }
+
+    const provider = this.providers.get(account.providerId);
+    if (!provider) {
+      throw new Error(`Provider ${account.providerId} not found`);
+    }
+
+    return await provider.submitTransaction({
+      accountAddress: account.address,
+      payload,
+      ledgerId: account.ledgerId,
+      networkId: account.networkId,
+      ...options,
+    });
+  }
+
+  /**
+   * Signs an arbitrary message using the active account.
+   *
+   * @description
+   * Requests the wallet to sign a message for authentication or verification
+   * purposes (e.g., DAO votes, login challenges). The message is not a
+   * blockchain transaction.
+   *
+   * @param message - The message to sign (plain text or base64 encoded)
+   * @param encoding - Message encoding: 'utf-8' (default) or 'base64'
+   *
+   * @returns Promise resolving to sign result with signature and public key
+   *
+   * @throws {Error} If no active account is set
+   * @throws {Error} If provider is not found
+   * @throws {Error} If user rejects the signing request
+   */
+  async signMessage(message: string, encoding?: 'utf-8' | 'base64'): Promise<unknown> {
+    const account = this._activeAccount();
+    if (!account) {
+      throw new Error('No active account');
+    }
+
+    const provider = this.providers.get(account.providerId);
+    if (!provider) {
+      throw new Error(`Provider ${account.providerId} not found`);
+    }
+
+    return await provider.signMessage({
+      accountAddress: account.address,
+      message,
+      encoding,
+      ledgerId: account.ledgerId,
+      networkId: account.networkId,
+    });
+  }
+
+  /**
+   * Signs and executes a transaction in a single prompt.
+   *
+   * @description
+   * Performs atomic sign-and-submit in a single wallet prompt. This is the
+   * **recommended method** for most transaction submissions as it:
+   * - Only requires one user approval (better UX)
+   * - Matches WalletConnect's `hedera_signAndExecuteTransaction` behavior
+   * - Provides atomic operation (sign+submit happen together)
+   *
+   * For providers that don't support native signAndExecute, this method
+   * falls back to separate sign and submit calls.
+   *
+   * @param payload - Serialized transaction payload
+   * @param options - Optional provider-specific options
+   *
+   * @returns Promise resolving to execution result with transaction ID and hash
+   *
+   * @throws {Error} If no active account is set
+   * @throws {Error} If provider is not found
+   * @throws {Error} If user rejects or transaction fails
+   */
+  async signAndExecuteTransaction(
+    payload: string,
+    options?: Record<string, unknown>,
+  ): Promise<unknown> {
+    const account = this._activeAccount();
+    if (!account) {
+      throw new Error('No active account');
+    }
+
+    const provider = this.providers.get(account.providerId);
+    if (!provider) {
+      throw new Error(`Provider ${account.providerId} not found`);
+    }
+
+    // Check if provider has native signAndExecute support
+    if (
+      typeof (provider as any as { signAndExecuteTransaction: (payload: any) => Promise<any> })
+        .signAndExecuteTransaction === 'function'
+    ) {
+      return await (
+        provider as any as { signAndExecuteTransaction: (payload: any) => Promise<any> }
+      ).signAndExecuteTransaction({
+        accountAddress: account.address,
+        payload,
+        ledgerId: account.ledgerId,
+        networkId: account.networkId,
+        ...options,
+      });
+    }
+
+    // Fallback: sign then submit
+    const signResult = await provider.signTransaction({
+      accountAddress: account.address,
+      payload,
+      ledgerId: account.ledgerId,
+      networkId: account.networkId,
+      ...options,
+    });
+
+    return await provider.submitTransaction({
+      accountAddress: account.address,
+      payload: signResult.signedPayload || payload,
+      ledgerId: account.ledgerId,
+      networkId: account.networkId,
+      ...options,
+    });
+  }
+
+  /**
+   * Gets all active sessions across all providers.
+   *
+   * @description
+   * Returns detailed session information for all connected providers. For
+   * WalletConnect, each session is returned separately. For other providers,
+   * a single session entry represents the connection.
+   *
+   * @returns Array of session objects with provider and account information
+   */
+  getActiveSessions(): Array<{
+    providerId: string;
+    providerType: string;
+    providerName: string;
+    accounts: import('../models/unified-account.model').UnifiedAccount[];
+    metadata: any;
+  }> {
+    const sessions: Array<{
+      providerId: string;
+      providerType: string;
+      providerName: string;
+      accounts: import('../models/unified-account.model').UnifiedAccount[];
+      metadata: any;
+    }> = [];
+
+    for (const provider of this.providers.values()) {
+      const accounts = provider.accounts();
+
+      if (accounts.length > 0) {
+        // For WalletConnect, get detailed session info
+        if (provider.id === 'walletconnect-v2' && 'getActiveSessions' in provider) {
+          const wcProvider = provider as any;
+          const wcSessions = (
+            wcProvider as { getActiveSessions: () => unknown[] }
+          ).getActiveSessions();
+
+          for (const wcSession of wcSessions) {
+            sessions.push({
+              providerId: provider.id,
+              providerType: provider.metadata.type,
+              providerName: provider.metadata.name,
+              accounts: (wcSession as { accounts?: any[] }).accounts || [],
+              metadata: {
+                sessionKey: (wcSession as { sessionKey?: string }).sessionKey,
+                ledgerId: (wcSession as { ledgerId?: string }).ledgerId,
+                networkId: (wcSession as { networkId?: string }).networkId,
+                topic: (wcSession as { topic?: string }).topic,
+              },
+            });
+          }
+        } else {
+          // For HSuite Native and other providers, create a single session entry
+          sessions.push({
+            providerId: provider.id,
+            providerType: provider.metadata.type,
+            providerName: provider.metadata.name,
+            accounts,
+            metadata: {
+              type: provider.metadata.type,
+            },
+          });
+        }
+      }
+    }
+
+    return sessions;
+  }
+
+  /**
+   * Disconnects a specific session from a provider.
+   *
+   * @description
+   * For WalletConnect which supports multiple concurrent sessions, this allows
+   * disconnecting a specific session without affecting others. For other
+   * providers, this is equivalent to calling {@link disconnect}.
+   *
+   * @param providerId - The provider ID
+   * @param sessionKey - Optional session key (required for WalletConnect multi-session)
+   *
+   * @throws {Error} If provider is not found
+   */
+  async disconnectSession(providerId: string, sessionKey?: string): Promise<void> {
+    const provider = this.providers.get(providerId);
+    if (!provider) {
+      throw new Error(`Provider ${providerId} not found`);
+    }
+
+    // If provider supports session-level disconnect (WalletConnect), use it
+    if ('disconnectSession' in provider && sessionKey) {
+      const wcProvider = provider as any;
+      await (wcProvider as { disconnectSession: (key: string) => Promise<void> }).disconnectSession(
+        sessionKey,
+      );
+    } else {
+      // Otherwise, disconnect the entire provider
+      await provider.disconnect();
+    }
+
+    // Emit disconnection event
+    this.eventBus.disconnected.emit({
+      providerId,
+      providerType: provider.metadata.type,
+      sessionKey,
+      reason: 'user_initiated',
+      timestamp: Date.now(),
+    });
+
+    // Update active account if needed
+    const active = this._activeAccount();
+    if (active && active.providerId === providerId) {
+      const accounts = this.allAccounts();
+      const nextAccount = accounts.find(
+        (a) =>
+          a.providerId !== providerId ||
+          (sessionKey && (a.metadata as { sessionKey?: string })?.sessionKey !== sessionKey),
+      );
+      this.setActiveAccount(nextAccount || null);
+    }
+  }
+
+  /**
+   * Check if any provider is connected
+   */
+  isAnyConnected(): boolean {
+    return this.connectedProviders().length > 0;
+  }
+
+  /**
+   * Alias for isAnyConnected() - convenience method
+   */
+  isConnected(): boolean {
+    return this.isAnyConnected();
+  }
+
+  /**
+   * Get account by ID
+   * @param accountId
+   */
+  getAccountById(accountId: string): UnifiedAccount | undefined {
+    return this.allAccounts().find((a) => a.id === accountId);
+  }
+
+  /**
+   * Get list of unique ledger IDs from connected accounts
+   * @returns Array of ledger IDs (e.g., ['hedera', 'xrpl'])
+   */
+  getConnectedLedgers(): string[] {
+    const accounts = this.allAccounts();
+    const ledgerIds = new Set(accounts.map((a) => a.ledgerId).filter(Boolean));
+    return Array.from(ledgerIds);
+  }
+
+  /**
+   * Get accounts filtered by ledger ID
+   * @param ledgerId - Ledger identifier (e.g., 'hedera', 'xrpl')
+   * @returns Array of accounts for the specified ledger
+   */
+  getAccountsByLedger(ledgerId: string): UnifiedAccount[] {
+    return this.allAccounts().filter((a) => a.ledgerId === ledgerId);
+  }
+
+  /**
+   * Switch to an account by its ID
+   * @param accountId - The account ID to switch to
+   * @returns true if account was found and switched, false otherwise
+   */
+  switchAccount(accountId: string): boolean {
+    const account = this.getAccountById(accountId);
+    if (!account) {
+      logger.warn('Account not found', { accountId });
+      return false;
+    }
+
+    this.setActiveAccount(account);
+    return true;
+  }
+
+  /**
+   * Get the primary account for a specific ledger
+   * Returns the first account found for the specified ledger
+   * @param ledgerId - Ledger identifier (e.g., 'hedera', 'xrpl')
+   * @returns The first account for the ledger, or undefined
+   */
+  getPrimaryAccountForLedger(ledgerId: string): UnifiedAccount | undefined {
+    return this.allAccounts().find((a) => a.ledgerId === ledgerId);
+  }
+
+  /**
+   * Check if a specific ledger has connected accounts
+   * @param ledgerId - Ledger identifier (e.g., 'hedera', 'xrpl')
+   * @returns true if at least one account exists for the ledger
+   */
+  hasAccountsForLedger(ledgerId: string): boolean {
+    return this.getAccountsByLedger(ledgerId).length > 0;
+  }
+}