@hsuite/native-connect-angular 1.0.0

package/src/lib/providers/walletconnect/core/walletconnect-client-manager.ts

@@ -0,0 +1,364 @@
+/**
+ * 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 walletconnect-client-manager.ts
+ * @description WalletConnect SignClient lifecycle management
+ *
+ * Handles:
+ * - SignClient initialization with projectId
+ * - Client reuse across multiple connections
+ * - Session restoration from IndexedDB
+ * - Event listener registration
+ *
+ * Extracted from WalletConnectV2Provider to reduce file size.
+ */
+
+import { getLogger } from '@hsuite/native-connect-sdk';
+import { WalletConnectModal } from '@walletconnect/modal';
+import SignClient from '@walletconnect/sign-client';
+
+import { SessionHealthManager } from './session-health';
+
+const logger = getLogger().scoped?.('WCClientManager') ?? getLogger();
+
+/**
+ * Storage key for persisted projectId
+ */
+const STORAGE_KEY_PROJECT_ID = 'hsuite.walletconnect.projectId';
+
+/**
+ * WalletConnect app metadata
+ */
+export interface WCAppMetadata {
+  name: string;
+  description: string;
+  url: string;
+  icons: string[];
+}
+
+/**
+ * WalletConnect Client Manager
+ *
+ * Manages the SignClient instance lifecycle.
+ * Handles initialization, session restoration, and cleanup.
+ */
+export class WalletConnectClientManager {
+  private client?: SignClient;
+  private modal?: WalletConnectModal;
+  private projectId?: string;
+  private sessionHealth?: SessionHealthManager;
+
+  /**
+   * Initialize or return existing SignClient.
+   *
+   * @param projectId - WalletConnect Cloud project ID
+   * @param metadata - App metadata for wallet display
+   * @returns Initialized SignClient instance
+   */
+  async initialize(projectId: string, metadata: WCAppMetadata): Promise<SignClient> {
+    if (this.client && this.projectId === projectId) {
+      return this.client;
+    }
+
+    logger.debug('Initializing SignClient', { projectId: projectId.substring(0, 8) });
+
+    // Store projectId for session restoration
+    this.projectId = projectId;
+    this.persistProjectId(projectId);
+
+    // Use 'fatal' logger to suppress pino noise from WalletConnect SDK
+    this.client = await SignClient.init({
+      projectId,
+      logger: 'fatal',
+      metadata,
+    });
+
+    // Initialize session health manager for relay subscription management
+    this.sessionHealth = new SessionHealthManager(this.client);
+
+    logger.info('SignClient initialized with session health manager');
+    return this.client;
+  }
+
+  /**
+   * Get the current client instance.
+   * @throws Error if not initialized
+   */
+  getClient(): SignClient {
+    if (!this.client) {
+      throw new Error('WalletConnect client not initialized');
+    }
+    return this.client;
+  }
+
+  /**
+   * Check if client is initialized.
+   */
+  isInitialized(): boolean {
+    return !!this.client;
+  }
+
+  /**
+   * Restore client from stored projectId.
+   * Used for session restoration on page reload.
+   *
+   * @param metadata - App metadata
+   * @returns Client if restoration succeeded, undefined otherwise
+   */
+  async restoreClient(metadata: WCAppMetadata): Promise<SignClient | undefined> {
+    const storedProjectId = this.getStoredProjectId();
+    if (!storedProjectId) {
+      logger.debug('No stored projectId, skipping client restoration');
+      return undefined;
+    }
+
+    try {
+      return await this.initialize(storedProjectId, metadata);
+    } catch (error) {
+      logger.error('Failed to restore client', {
+        error: error instanceof Error ? error.message : String(error),
+      });
+      return undefined;
+    }
+  }
+
+  /**
+   * Get all active sessions from the client.
+   */
+  getActiveSessions(): any[] {
+    if (!this.client) {
+      return [];
+    }
+    return this.client.session.getAll();
+  }
+
+  /**
+   * Get a specific session by topic.
+   * @param topic
+   */
+  getSession(topic: string): any | undefined {
+    if (!this.client) {
+      return undefined;
+    }
+    try {
+      return this.client.session.get(topic);
+    } catch {
+      return undefined;
+    }
+  }
+
+  /**
+   * Create and return a modal for QR code display.
+   * @param projectId
+   * @param chains
+   */
+  createModal(projectId: string, chains: string[]): WalletConnectModal {
+    this.modal = new WalletConnectModal({
+      projectId,
+      chains,
+    });
+    return this.modal;
+  }
+
+  /**
+   * Close the modal if open.
+   */
+  closeModal(): void {
+    if (this.modal) {
+      this.modal.closeModal();
+    }
+  }
+
+  /**
+   * Connect to wallet and get session.
+   *
+   * @param optionalNamespaces - Namespace configuration
+   * @param sessionProperties - Optional session properties (e.g., preferredNetwork)
+   * @returns URI and approval promise
+   */
+  async connect(
+    optionalNamespaces: Record<string, any>,
+    sessionProperties?: Record<string, string>,
+  ): Promise<{
+    uri?: string;
+    approval: () => Promise<any>;
+  }> {
+    if (!this.client) {
+      throw new Error('Client not initialized');
+    }
+
+    const connectParams: any = { optionalNamespaces };
+
+    // Add session properties if provided
+    // This allows passing metadata like preferredNetwork to the wallet
+    if (sessionProperties) {
+      connectParams.sessionProperties = sessionProperties;
+    }
+
+    logger.debug('Connecting with params', {
+      namespaces: Object.keys(optionalNamespaces),
+      hasSessionProperties: !!sessionProperties,
+    });
+
+    return this.client.connect(connectParams);
+  }
+
+  /**
+   * Disconnect a session.
+   * @param topic
+   * @param reason
+   * @param reason.code
+   * @param reason.message
+   */
+  async disconnect(topic: string, reason?: { code: number; message: string }): Promise<void> {
+    if (!this.client) {
+      return;
+    }
+    await this.client.disconnect({
+      topic,
+      reason: reason || { code: 6000, message: 'User disconnected' },
+    });
+  }
+
+  /**
+   * Register event listener on the client.
+   * @param event
+   * @param handler
+   */
+  on(event: string, handler: (event: any) => void): void {
+    if (!this.client) {
+      return;
+    }
+    (this.client as any).on(event, handler);
+  }
+
+  /**
+   * Send a request to a session.
+   *
+   * Features:
+   * - Automatically ensures session health by pinging before the request
+   * - Runs keep-alive pings during long-running requests (e.g., transaction approval)
+   * - Prevents stale relay subscription issues that cause empty error objects
+   *
+   * @param params - Request parameters including topic, chainId, and request data
+   * @param params.expiry - Optional expiry time in seconds (default: 300)
+   * @param params.topic
+   * @param params.chainId
+   * @param params.request
+   * @param params.request.method
+   * @param params.request.params
+   * @returns Promise resolving to the request result
+   */
+  async request<T = unknown>(params: {
+    topic: string;
+    chainId: string;
+    request: { method: string; params: unknown };
+    expiry?: number;
+  }): Promise<T> {
+    if (!this.client) {
+      throw new Error('Client not initialized');
+    }
+
+    // Ensure session health before request (transparent to caller)
+    // This pings the session if needed to refresh relay subscription
+    if (this.sessionHealth) {
+      await this.sessionHealth.ensureSessionHealth(params.topic);
+    }
+
+    // Keep-alive pings during long-running requests (e.g., transaction approval)
+    // WC relay has ~30s subscription timeout, so we ping every 20s to keep it alive
+    const KEEP_ALIVE_INTERVAL_MS = 20000;
+    let keepAliveInterval: ReturnType<typeof setInterval> | undefined;
+
+    const startKeepAlive = () => {
+      keepAliveInterval = setInterval(async () => {
+        try {
+          logger.debug('Keep-alive ping during request', {
+            topic: params.topic?.substring(0, 16) + '...',
+            method: params.request.method,
+          });
+          if (this.client) {
+            await Promise.race([
+              this.client.ping({ topic: params.topic }),
+              new Promise((_, reject) => setTimeout(() => reject(new Error('Ping timeout')), 5000)),
+            ]);
+          }
+        } catch (err) {
+          // Log but don't throw - ping failure during wait is not critical
+          logger.debug('Keep-alive ping failed (non-critical)', {
+            error: err instanceof Error ? err.message : String(err),
+          });
+        }
+      }, KEEP_ALIVE_INTERVAL_MS);
+    };
+
+    const stopKeepAlive = () => {
+      if (keepAliveInterval) {
+        clearInterval(keepAliveInterval);
+        keepAliveInterval = undefined;
+      }
+    };
+
+    // Start keep-alive pings
+    startKeepAlive();
+
+    try {
+      const result = await this.client.request<T>(params);
+      return result;
+    } finally {
+      // Always stop keep-alive, whether success or error
+      stopKeepAlive();
+    }
+  }
+
+  /**
+   * Get the session health manager for advanced operations.
+   *
+   * Use this if you need to:
+   * - Force refresh a subscription
+   * - Clear ping cache
+   * - Access health manager directly
+   *
+   * @returns SessionHealthManager instance or undefined if not initialized
+   */
+  getSessionHealthManager(): SessionHealthManager | undefined {
+    return this.sessionHealth;
+  }
+
+  // ========== STORAGE ==========
+
+  private persistProjectId(projectId: string): void {
+    try {
+      window.localStorage?.setItem(STORAGE_KEY_PROJECT_ID, projectId);
+    } catch {
+      logger.warn('Failed to persist projectId');
+    }
+  }
+
+  private getStoredProjectId(): string | null {
+    try {
+      return window.localStorage?.getItem(STORAGE_KEY_PROJECT_ID) ?? null;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Clear stored projectId.
+   */
+  clearStoredProjectId(): void {
+    try {
+      window.localStorage?.removeItem(STORAGE_KEY_PROJECT_ID);
+    } catch {
+      // Ignore
+    }
+  }
+}

package/src/lib/providers/walletconnect/core/walletconnect-provider.integration.spec.ts

@@ -0,0 +1,348 @@
+/**
+ * @file walletconnect-provider.integration.spec.ts
+ * @description Integration tests for WalletConnectV2Provider
+ * 
+ * @compodoc
+ * These tests verify the WalletConnect v2 provider integration.
+ * Some tests are skipped due to complex session state requirements.
+ */
+
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { TestBed } from '@angular/core/testing';
+import { WalletConnectV2Provider } from './walletconnect-provider';
+import { SignerFactory } from '../signers/signer-factory';
+import { HederaSigner } from '../signers/hedera-signer';
+import { XrplSigner } from '../signers/xrpl-signer';
+import type { WalletConnectV2Config } from './walletconnect-types';
+
+// Mock WalletConnect modules
+vi.mock('@walletconnect/sign-client', () => ({
+  default: {
+    init: vi.fn(),
+  },
+}));
+
+vi.mock('@walletconnect/modal', () => ({
+  WalletConnectModal: vi.fn(),
+}));
+
+describe('WalletConnectV2Provider Integration Tests', () => {
+  let provider: WalletConnectV2Provider;
+  // Note: SignerFactory uses static methods, no need to inject
+  let mockSignClient: any;
+  let mockModal: any;
+
+  beforeEach(async () => {
+    // Clear localStorage
+    localStorage.clear();
+    
+    // Mock SignClient
+    mockSignClient = {
+      connect: vi.fn().mockResolvedValue({
+        uri: 'wc:test-uri',
+        approval: vi.fn().mockResolvedValue({
+          topic: 'test-topic',
+          namespaces: {
+            hedera: {
+              accounts: ['hedera:testnet:0.0.12345'],
+              methods: ['hedera_signTransaction'],
+              chains: ['hedera:testnet']
+            }
+          }
+        })
+      }),
+      disconnect: vi.fn().mockResolvedValue(undefined),
+      request: vi.fn(),
+      session: {
+        getAll: vi.fn().mockReturnValue([])
+      },
+      on: vi.fn()
+    };
+    
+    // Mock Modal
+    mockModal = {
+      openModal: vi.fn().mockResolvedValue(undefined),
+      closeModal: vi.fn()
+    };
+    
+    const { default: SignClient } = await import('@walletconnect/sign-client');
+    const { WalletConnectModal } = await import('@walletconnect/modal');
+    
+    vi.mocked(SignClient.init).mockResolvedValue(mockSignClient);
+    vi.mocked(WalletConnectModal).mockImplementation(() => mockModal);
+    
+    TestBed.configureTestingModule({
+      providers: [
+        WalletConnectV2Provider,
+        HederaSigner,
+        XrplSigner
+      ]
+    });
+    
+    provider = TestBed.inject(WalletConnectV2Provider);
+  });
+
+  describe('Provider Metadata', () => {
+    it('should have correct metadata', () => {
+      expect(provider.id).toBe('walletconnect-v2');
+      expect(provider.metadata.type).toBe('walletconnect-v2');
+      expect(provider.metadata.name).toBe('WalletConnect');
+    });
+  });
+
+  describe('Connection Flow', () => {
+    const config: WalletConnectV2Config = {
+      type: 'walletconnect-v2',
+      projectId: 'test-project-id',
+      ledgerId: 'hedera',
+      networkId: 'hedera:testnet',
+      appName: 'Test dApp'
+    };
+
+    it('should connect successfully with Hedera', async () => {
+      await provider.connect(config);
+      
+      expect(provider.status()).toBe('connected');
+      expect(provider.accounts()).toHaveLength(1);
+      expect(provider.accounts()[0].address).toBe('0.0.12345');
+    });
+
+    it('should initialize SignClient with correct params', async () => {
+      const { default: SignClient } = await import('@walletconnect/sign-client');
+      
+      await provider.connect(config);
+      
+      expect(SignClient.init).toHaveBeenCalledWith(
+        expect.objectContaining({
+          projectId: 'test-project-id',
+          metadata: expect.objectContaining({
+            name: 'Test dApp'
+          })
+        })
+      );
+    });
+
+    it('should open modal with URI', async () => {
+      await provider.connect(config);
+      
+      expect(mockModal.openModal).toHaveBeenCalledWith({
+        uri: 'wc:test-uri'
+      });
+    });
+
+    it('should close modal after approval', async () => {
+      await provider.connect(config);
+      
+      expect(mockModal.closeModal).toHaveBeenCalled();
+    });
+
+    it('should store user network selection in localStorage', async () => {
+      await provider.connect(config);
+
+      // The provider stores user's network selection per session topic for restoration
+      // Check that the network selection was stored (using the test-topic from mock)
+      expect(localStorage.getItem('wc_user_network_selection_test-topic')).toBe('hedera:testnet');
+    });
+
+    it('should set error state if connection fails', async () => {
+      const { default: SignClient } = await import('@walletconnect/sign-client');
+      vi.mocked(SignClient.init).mockRejectedValue(new Error('Network error'));
+      
+      await expect(provider.connect(config)).rejects.toThrow();
+      
+      expect(provider.status()).toBe('error');
+      expect(provider.error()).toContain('Network error');
+    });
+  });
+
+  // Transaction signing tests - provider delegates to signers via the orchestrator
+  describe('Transaction Signing', () => {
+    beforeEach(async () => {
+      // Connect first
+      await provider.connect({
+        type: 'walletconnect-v2',
+        projectId: 'test-project-id',
+        ledgerId: 'hedera',
+        networkId: 'hedera:testnet'
+      });
+
+      mockSignClient.request.mockResolvedValue({
+        signatureMap: 'signed-result'
+      });
+    });
+
+    it('should throw error when signing with unknown account address', async () => {
+      // Attempt to sign with an account that doesn't exist in the session
+      await expect(provider.signTransaction({
+        ledgerId: 'hedera',
+        networkId: 'hedera:testnet',
+        accountAddress: '0.0.99999', // Not in session
+        payload: 'base64TransactionHere'
+      })).rejects.toThrow('No WalletConnect session found for account');
+    });
+
+    it('should throw error when no session exists for account', async () => {
+      // Disconnect first - this clears all sessions
+      await provider.disconnect();
+
+      // Create new provider that's not connected
+      const disconnectedProvider = TestBed.inject(WalletConnectV2Provider);
+
+      // The session lookup happens first, so we get "No WalletConnect session" error
+      await expect(disconnectedProvider.signTransaction({
+        ledgerId: 'hedera',
+        networkId: 'hedera:testnet',
+        accountAddress: '0.0.12345',
+        payload: 'base64'
+      })).rejects.toThrow('No WalletConnect session found for account');
+    });
+  });
+
+  // Transaction submission tests - provider delegates to signers via the orchestrator
+  describe('Transaction Submission', () => {
+    beforeEach(async () => {
+      await provider.connect({
+        type: 'walletconnect-v2',
+        projectId: 'test-project-id',
+        ledgerId: 'hedera',
+        networkId: 'hedera:testnet'
+      });
+
+      mockSignClient.request.mockResolvedValue({
+        transactionId: '0.0.12345@1699999999.123'
+      });
+    });
+
+    it('should throw error when submitting with unknown account address', async () => {
+      // Attempt to submit with an account that doesn't exist in the session
+      await expect(provider.submitTransaction({
+        ledgerId: 'hedera',
+        networkId: 'hedera:testnet',
+        accountAddress: '0.0.99999', // Not in session
+        payload: 'base64TransactionHere'
+      })).rejects.toThrow('No WalletConnect session found for account');
+    });
+
+    it('should throw error when no session exists for account', async () => {
+      // Disconnect first - this clears all sessions
+      await provider.disconnect();
+
+      // Create new provider that's not connected
+      const disconnectedProvider = TestBed.inject(WalletConnectV2Provider);
+
+      // The session lookup happens first, so we get "No WalletConnect session" error
+      await expect(disconnectedProvider.submitTransaction({
+        ledgerId: 'hedera',
+        networkId: 'hedera:testnet',
+        accountAddress: '0.0.12345',
+        payload: 'base64'
+      })).rejects.toThrow('No WalletConnect session found for account');
+    });
+  });
+
+  describe('Disconnection', () => {
+    it('should disconnect and clear state', async () => {
+      // Connect first
+      await provider.connect({
+        type: 'walletconnect-v2',
+        projectId: 'test-project-id',
+        ledgerId: 'hedera',
+        networkId: 'hedera:testnet'
+      });
+      
+      expect(provider.status()).toBe('connected');
+      
+      // Disconnect
+      await provider.disconnect();
+      
+      expect(provider.status()).toBe('disconnected');
+      expect(provider.accounts()).toHaveLength(0);
+      expect(mockSignClient.disconnect).toHaveBeenCalledWith({
+        topic: 'test-topic',
+        reason: expect.any(Object)
+      });
+    });
+
+    it('should close modal on disconnect', async () => {
+      await provider.connect({
+        type: 'walletconnect-v2',
+        projectId: 'test-project-id',
+        ledgerId: 'hedera',
+        networkId: 'hedera:testnet'
+      });
+      
+      await provider.disconnect();
+      
+      // Modal closed during disconnect cleanup
+      expect(mockModal.closeModal).toHaveBeenCalled();
+    });
+  });
+
+  describe('Session Restoration', () => {
+    it('should restore session from localStorage', async () => {
+      // Set up stored session
+      localStorage.setItem('hsuite.walletconnect.projectId', 'stored-project-id');
+      localStorage.setItem('hsuite.walletconnect.ledgerId', 'hedera');
+      localStorage.setItem('hsuite.walletconnect.networkId', 'hedera:testnet');
+      
+      mockSignClient.session.getAll.mockReturnValue([
+        {
+          topic: 'stored-topic',
+          namespaces: {
+            hedera: {
+              accounts: ['hedera:testnet:0.0.99999']
+            }
+          }
+        }
+      ]);
+      
+      // Create new provider instance (triggers restoration)
+      const newProvider = TestBed.inject(WalletConnectV2Provider);
+      
+      // Wait for restoration
+      await new Promise(resolve => setTimeout(resolve, 100));
+      
+      // Restoration happens in constructor, check if client was initialized
+      const { default: SignClient } = await import('@walletconnect/sign-client');
+      expect(SignClient.init).toHaveBeenCalled();
+    });
+  });
+
+  describe('Multi-Chain Support', () => {
+    it('should support XRPL connection', async () => {
+      mockSignClient.connect = vi.fn().mockResolvedValue({
+        uri: 'wc:xrpl-uri',
+        approval: vi.fn().mockResolvedValue({
+          topic: 'xrpl-topic',
+          namespaces: {
+            xrpl: {
+              accounts: ['xrpl:testnet:rN7n7otQDd6FczFgLdlqtyMVrn3HMfeeZE'],
+              methods: ['xrpl_signTransaction'],
+              chains: ['xrpl:testnet']
+            }
+          }
+        })
+      });
+      
+      await provider.connect({
+        type: 'walletconnect-v2',
+        projectId: 'test-project-id',
+        ledgerId: 'xrpl',
+        networkId: 'xrpl:testnet'
+      });
+      
+      expect(provider.status()).toBe('connected');
+      expect(provider.accounts()[0].ledgerId).toBe('xrpl');
+    });
+
+    it('should use correct signer for each ledger', async () => {
+      // SignerFactory uses static methods
+      const hederaSigner = SignerFactory.getSigner('hedera');
+      const xrplSigner = SignerFactory.getSigner('xrpl');
+      
+      expect(hederaSigner.ledgerId).toBe('hedera');
+      expect(xrplSigner.ledgerId).toBe('xrpl');
+      expect(hederaSigner).not.toBe(xrplSigner);
+    });
+  });
+});