@hsuite/native-connect-angular 1.0.0

package/src/lib/providers/walletconnect/signers/xrpl-signer.ts

@@ -0,0 +1,478 @@
+/**
+ * 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 xrpl-signer.ts
+ * @description XRPL-specific WalletConnect signer implementation
+ *
+ * Implements the IWalletConnectSigner interface for XRPL ledger.
+ * Handles XRPL-specific JSON-RPC methods and transaction formats.
+ */
+
+import { XrplTransactionEncoder } from '@hsuite/native-connect-sdk';
+import { getLogger } from '@hsuite/native-connect-sdk';
+
+import type { SignResult, SubmitResult } from '../../base-wallet-provider';
+import type { IWalletConnectSigner, SignerOperationParams } from '../core/base-signer.interface';
+
+const logger = getLogger().scoped?.('XrplSigner') ?? getLogger();
+
+/**
+ * Extract a meaningful error message from various error shapes.
+ * WalletConnect SDK throws errors that are not standard Error instances.
+ *
+ * Handles:
+ * - Standard Error objects
+ * - WalletConnect SDK errors: { code, message }
+ * - Nested errors: { error: { message } }
+ * - PIN_REQUIRED errors from wallet
+ * - DOMException objects
+ * - Objects that stringify to {} (enumerable property check)
+ *
+ * @param error - Error from WalletConnect SDK (can be Error, object, or string)
+ * @returns Human-readable error message
+ */
+function extractErrorMessage(error: unknown): string {
+  // Log raw error for debugging
+  logger.debug('Raw error object', {
+    errorType: typeof error,
+    isError: error instanceof Error,
+    errorKeys: typeof error === 'object' && error !== null ? Object.keys(error) : [],
+    errorProto:
+      typeof error === 'object' && error !== null
+        ? Object.getPrototypeOf(error)?.constructor?.name
+        : 'N/A',
+    rawError: error,
+  });
+
+  if (error instanceof Error) {
+    return error.message;
+  }
+
+  if (typeof error === 'object' && error !== null) {
+    const errorObj = error as Record<string, unknown>;
+
+    // Check for code property first (common in SDK errors like PIN_REQUIRED)
+    if (typeof errorObj['code'] === 'string') {
+      const codeMsg = errorObj['message']
+        ? `${errorObj['code']}: ${errorObj['message']}`
+        : errorObj['code'];
+      return codeMsg as string;
+    }
+
+    // WalletConnect error format: { code, message }
+    if ('message' in errorObj && typeof errorObj['message'] === 'string') {
+      return errorObj['message'];
+    }
+
+    // Nested error: { error: { message } }
+    if (
+      'error' in errorObj &&
+      typeof errorObj['error'] === 'object' &&
+      errorObj['error'] !== null
+    ) {
+      const nested = errorObj['error'] as Record<string, unknown>;
+      if ('message' in nested && typeof nested['message'] === 'string') {
+        return nested['message'];
+      }
+      if ('code' in nested && typeof nested['code'] === 'string') {
+        return nested['code'];
+      }
+    }
+
+    // Check for 'context' property which WalletConnect sometimes uses
+    if ('context' in errorObj && typeof errorObj['context'] === 'string') {
+      return errorObj['context'];
+    }
+
+    // Check for DOMException
+    if (error instanceof DOMException) {
+      return error.message || error.name;
+    }
+
+    // Check for reason/cause properties (common in rejected promises)
+    if ('reason' in errorObj && typeof errorObj['reason'] === 'string') {
+      return errorObj['reason'];
+    }
+    if ('cause' in errorObj && typeof errorObj['cause'] === 'string') {
+      return errorObj['cause'];
+    }
+
+    // WalletConnect JSON-RPC error format: { code: number, message: string }
+    if ('code' in errorObj && 'message' in errorObj) {
+      const code = errorObj['code'];
+      const msg = errorObj['message'];
+      if (typeof msg === 'string') {
+        return typeof code === 'number' ? `[${code}] ${msg}` : msg;
+      }
+    }
+
+    // Error with 'name' property (common for built-in errors)
+    if ('name' in errorObj && typeof errorObj['name'] === 'string') {
+      const name = errorObj['name'];
+      if (name && name !== 'Error' && name !== 'Object') {
+        return name;
+      }
+    }
+
+    // Try to stringify, but check if result is empty object
+    try {
+      const jsonStr = JSON.stringify(error);
+      // Don't return empty objects as error messages
+      if (jsonStr && jsonStr !== '{}' && jsonStr !== '[]') {
+        return jsonStr;
+      }
+
+      // If stringify returned {}, try Object.keys to get property names
+      const keys = Object.keys(errorObj);
+      if (keys.length > 0) {
+        return `Error object with keys: ${keys.join(', ')}`;
+      }
+    } catch {
+      // If stringify fails, try toString
+      const str = String(error);
+      if (str !== '[object Object]') {
+        return str;
+      }
+    }
+
+    return 'Unknown error object';
+  }
+
+  if (typeof error === 'string') {
+    return error;
+  }
+
+  return 'Unknown error';
+}
+
+/**
+ * Signer implementation for XRPL ledger.
+ *
+ * Supports XRPL-specific WalletConnect methods:
+ * - xrpl_signTransaction (sign-only, returns signed blob)
+ * - xrpl_signAndSubmit (sign + submit, returns transaction hash)
+ * - xrpl_submit (submit pre-signed transaction)
+ * - xrpl_signMessage (arbitrary message signing)
+ *
+ * Uses XRPL address format: xrpl:<network>:rAddress...
+ */
+export class XrplSigner implements IWalletConnectSigner {
+  readonly ledgerId = 'xrpl';
+
+  /**
+   * Build XRPL namespace configuration for WalletConnect.
+   * Defines the JSON-RPC methods and chains this signer supports.
+   *
+   * @param networkId - Network identifier (e.g., 'xrpl:testnet', 'xrpl:mainnet')
+   * @returns Namespace configuration object
+   */
+  buildNamespace(networkId: string): {
+    methods: string[];
+    chains: string[];
+    events: string[];
+  } {
+    // Extract network name (testnet, mainnet, devnet)
+    const network = networkId.includes('mainnet')
+      ? 'mainnet'
+      : networkId.includes('devnet')
+        ? 'devnet'
+        : 'testnet';
+
+    return {
+      methods: ['xrpl_signTransaction', 'xrpl_submit', 'xrpl_signAndSubmit', 'xrpl_signMessage'],
+      chains: [`xrpl:${network}`],
+      events: ['chainChanged', 'accountsChanged'],
+    };
+  }
+
+  /**
+   * Sign an XRPL transaction without submitting to network.
+   * Uses xrpl_signTransaction method with JSON transaction object.
+   *
+   * @param params - Signing parameters
+   * @returns Promise resolving to signed transaction blob (hex-encoded)
+   */
+  async signTransaction(params: SignerOperationParams): Promise<SignResult> {
+    // Decode base64 payload to JSON transaction
+    logger.debug('Decoding XRPL transaction payload', {
+      payloadLength: params.payload?.length,
+      networkId: params.networkId,
+      topic: params.topic?.substring(0, 16) + '...',
+    });
+
+    let transaction: any;
+    try {
+      transaction = XrplTransactionEncoder.decodeTransaction(params.payload);
+      logger.debug('Transaction decoded successfully', {
+        transactionType: transaction?.TransactionType,
+        account: transaction?.Account,
+      });
+    } catch (decodeError) {
+      logger.error('Failed to decode transaction payload', {
+        error: decodeError instanceof Error ? decodeError.message : String(decodeError),
+      });
+      throw decodeError;
+    }
+
+    try {
+      logger.debug('Sending xrpl_signTransaction request to wallet', {
+        method: 'xrpl_signTransaction',
+        chainId: params.networkId,
+        topic: params.topic?.substring(0, 16) + '...',
+      });
+
+      // Use 5-minute expiry to give users time to review and approve
+      const result = await params.client.request({
+        topic: params.topic,
+        chainId: params.networkId,
+        request: {
+          method: 'xrpl_signTransaction',
+          params: {
+            transaction, // Native JSON object
+          },
+        },
+        expiry: 300, // 5 minutes in seconds
+      });
+
+      logger.debug('Received response from wallet', {
+        hasResult: !!result,
+        resultKeys: result ? Object.keys(result as object) : [],
+      });
+
+      return {
+        signedPayload:
+          (result as { tx_blob?: string; tx_json?: any }).tx_blob || JSON.stringify(result),
+        metadata: { result },
+      };
+    } catch (error) {
+      // Check if this is an empty error object (WalletConnect SDK bug)
+      const isEmptyError =
+        typeof error === 'object' &&
+        error !== null &&
+        Object.keys(error).length === 0 &&
+        !(error instanceof Error);
+
+      if (isEmptyError) {
+        logger.warn('WalletConnect SDK empty error - relay subscription may have been stale', {
+          topic: params.topic?.substring(0, 16) + '...',
+        });
+        throw new Error('WalletConnect connection issue - please try again');
+      }
+
+      const errorMsg = extractErrorMessage(error);
+      logger.error('Sign failed', { error: errorMsg });
+      throw new Error(`XRPL sign failed: ${errorMsg}`);
+    }
+  }
+
+  /**
+   * Sign and submit an XRPL transaction to the network.
+   * Uses xrpl_signAndSubmit method with JSON transaction object.
+   *
+   * @param params - Submission parameters
+   * @returns Promise resolving to transaction hash and metadata
+   */
+  async submitTransaction(params: SignerOperationParams): Promise<SubmitResult> {
+    // Decode base64 payload to JSON transaction
+    const transaction = XrplTransactionEncoder.decodeTransaction(params.payload);
+
+    try {
+      logger.debug('Sending xrpl_signAndSubmit request to wallet', {
+        method: 'xrpl_signAndSubmit',
+        chainId: params.networkId,
+        topic: params.topic?.substring(0, 16) + '...',
+      });
+
+      // Use 5-minute expiry to give users time to review and approve
+      const result = await params.client.request({
+        topic: params.topic,
+        chainId: params.networkId,
+        request: {
+          method: 'xrpl_signAndSubmit',
+          params: {
+            transaction, // Native JSON object
+          },
+        },
+        expiry: 300, // 5 minutes in seconds
+      });
+
+      logger.debug('Received xrpl_signAndSubmit response', {
+        hasResult: !!result,
+        resultKeys: result ? Object.keys(result as object) : [],
+      });
+
+      return {
+        transactionId:
+          (result as { hash?: string }).hash ||
+          (result as { tx_json?: { hash?: string } }).tx_json?.hash ||
+          '',
+        transactionHash: (result as { hash?: string }).hash,
+        metadata: { result },
+      };
+    } catch (error) {
+      // Check if this is an empty error object (WalletConnect SDK bug)
+      // This typically happens when relay subscription is stale
+      const isEmptyError =
+        typeof error === 'object' &&
+        error !== null &&
+        Object.keys(error).length === 0 &&
+        !(error instanceof Error);
+
+      if (isEmptyError) {
+        // Empty error object is a known WalletConnect SDK issue
+        // It usually means the relay subscription was stale
+        logger.warn('WalletConnect SDK empty error - relay subscription may have been stale', {
+          topic: params.topic?.substring(0, 16) + '...',
+          hint: 'This can happen when the relay WebSocket connection drops',
+        });
+        throw new Error('WalletConnect connection issue - please try again');
+      }
+
+      const errorMsg = extractErrorMessage(error);
+      logger.error('Submit failed', { error: errorMsg });
+      throw new Error(`XRPL submit failed: ${errorMsg}`);
+    }
+  }
+
+  /**
+   * Sign and execute a transaction in one call (preferred method to avoid double prompts).
+   * Uses xrpl_signAndSubmit method directly instead of sign-then-submit.
+   *
+   * @param params - Transaction parameters
+   * @returns Promise resolving to transaction hash and metadata
+   */
+  async signAndExecuteTransaction(params: SignerOperationParams): Promise<SubmitResult> {
+    // XRPL's xrpl_signAndSubmit method handles both signing and submission
+    // This is the preferred method for XRPL transactions
+    return this.submitTransaction(params);
+  }
+
+  /**
+   * Sign an arbitrary message using xrpl_signMessage method.
+   * Used for DAO votes, authentication proofs, and other non-transaction signing.
+   *
+   * @param params - Signing parameters with message string
+   * @returns Promise resolving to signature and metadata
+   */
+  async signMessage(
+    params: SignerOperationParams & { message: string; encoding?: 'utf-8' | 'base64' },
+  ): Promise<import('../../base-wallet-provider').SignMessageResult> {
+    try {
+      // Use 5-minute expiry to give users time to review and approve
+      const result = await params.client.request({
+        topic: params.topic,
+        chainId: params.networkId,
+        request: {
+          method: 'xrpl_signMessage',
+          params: {
+            message: params.message, // Can be base64 or utf-8
+          },
+        },
+        expiry: 300, // 5 minutes in seconds
+      });
+
+      return {
+        signature: (result as { signature?: string }).signature || JSON.stringify(result),
+        publicKey: (result as { publicKey?: string }).publicKey,
+        metadata: { result },
+      };
+    } catch (error) {
+      // Check if this is an empty error object (WalletConnect SDK bug)
+      const isEmptyError =
+        typeof error === 'object' &&
+        error !== null &&
+        Object.keys(error).length === 0 &&
+        !(error instanceof Error);
+
+      if (isEmptyError) {
+        logger.warn('WalletConnect SDK empty error - relay subscription may have been stale', {
+          topic: params.topic?.substring(0, 16) + '...',
+        });
+        throw new Error('WalletConnect connection issue - please try again');
+      }
+
+      const errorMsg = extractErrorMessage(error);
+      logger.error('Sign message failed', { error: errorMsg });
+      throw new Error(`XRPL sign message failed: ${errorMsg}`);
+    }
+  }
+
+  /**
+   * Parse accounts from XRPL namespace in WalletConnect session.
+   * Extracts addresses from XRPL format: xrpl:<network>:rAddress...
+   *
+   * Optionally filters accounts to only include those matching a target network.
+   * This is important for respecting the user's network selection in the dApp.
+   *
+   * @param namespace - XRPL namespace object from session
+   * @param targetNetworkId - Optional network ID to filter accounts (e.g., 'xrpl:mainnet')
+   * @returns Array of parsed account objects, filtered by target network if specified
+   */
+  parseAccounts(
+    namespace: any,
+    targetNetworkId?: string,
+  ): Array<{ address: string; chainId: string }> {
+    if (
+      !(namespace as { accounts?: string[] })?.accounts ||
+      !Array.isArray((namespace as { accounts?: string[] }).accounts)
+    ) {
+      return [];
+    }
+
+    // Parse all accounts from namespace
+    const allAccounts = ((namespace as { accounts?: string[] }).accounts || []).map(
+      (account: string) => {
+        // XRPL format: xrpl:testnet:rN7n7otQDd6FczFgLdlqtyMVrn3WnFBrDB
+        const parts = account.split(':');
+
+        if (parts.length < 3) {
+          logger.warn('Invalid account format', { account });
+          return { address: account, chainId: 'xrpl:testnet' };
+        }
+
+        return {
+          address: parts[parts.length - 1], // rAddress
+          chainId: `${parts[0]}:${parts[1]}`, // xrpl:testnet
+        };
+      },
+    );
+
+    // If target network specified, filter accounts to only that network
+    if (targetNetworkId) {
+      const targetNetwork = targetNetworkId.split(':')[1]?.toLowerCase(); // e.g., 'mainnet'
+
+      if (targetNetwork) {
+        const filteredAccounts = allAccounts.filter((acc) =>
+          acc.chainId.toLowerCase().includes(targetNetwork),
+        );
+
+        logger.debug('Filtered accounts by target network', {
+          targetNetworkId,
+          targetNetwork,
+          totalAccounts: allAccounts.length,
+          filteredCount: filteredAccounts.length,
+        });
+
+        // If no accounts match the target network, log a warning
+        if (filteredAccounts.length === 0 && allAccounts.length > 0) {
+          logger.warn('No accounts found for target network', {
+            targetNetwork,
+            availableNetworks: [...new Set(allAccounts.map((a) => a.chainId))],
+          });
+        }
+
+        return filteredAccounts;
+      }
+    }
+
+    return allAccounts;
+  }
+}

package/src/lib/services/logger.service.ts

@@ -0,0 +1,126 @@
+/**
+ * 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 Angular Logger Service for dependency injection.
+ *
+ * @module services/logger
+ *
+ * @description
+ * LoggerService wraps the SDK's logger for Angular dependency injection, providing
+ * a consistent logging interface throughout Angular applications. It enables
+ * scoped logging with component/service names, production mode filtering, and
+ * consistent log formatting.
+ *
+ * **Key Features:**
+ * - Scoped loggers for easy filtering and tracing
+ * - Production-aware log level filtering
+ * - Consistent formatting across all components
+ * - Context objects for structured logging
+ *
+ * **Log Levels:**
+ * - `debug` - Detailed debugging information (filtered in production)
+ * - `info` - General informational messages
+ * - `warn` - Warning conditions that may need attention
+ * - `error` - Error conditions requiring action
+ */
+
+import { Injectable } from '@angular/core';
+import { getLogger, Logger } from '@hsuite/native-connect-sdk';
+
+/**
+ * Angular Logger Service that wraps the SDK's logger for dependency injection.
+ *
+ * @service LoggerService
+ *
+ * @description
+ * Provides scoped logger instances for components and services. All logs go through
+ * the SDK's configurable logging infrastructure, which supports production mode
+ * filtering and scope-based log levels.
+ *
+ * **Best Practices:**
+ * - Create scoped loggers at the class level for consistent scope names
+ * - Use structured context objects for machine-readable logs
+ * - Use appropriate log levels (debug for dev, info for operations, error for failures)
+ *
+ * @providedIn root
+ */
+@Injectable({ providedIn: 'root' })
+export class LoggerService {
+  private readonly rootLogger: Logger = getLogger();
+
+  /**
+   * Returns a scoped logger instance.
+   *
+   * Scoped loggers prefix all messages with the scope name,
+   * making it easier to filter and trace logs.
+   *
+   * @param scope The scope for the logger (e.g., 'AppComponent', 'WalletService').
+   * @returns A scoped Logger instance
+   */
+  scoped(scope: string): Logger {
+    return this.rootLogger.scoped?.(scope) ?? this.rootLogger;
+  }
+
+  /**
+   * Returns the root logger instance.
+   *
+   * Use sparingly - prefer scoped() for component/service logging.
+   *
+   * @returns The root Logger instance
+   */
+  getRootLogger(): Logger {
+    return this.rootLogger;
+  }
+
+  /**
+   * Log a debug message using the root logger.
+   * Convenience method for one-off logs.
+   *
+   * @param message Log message
+   * @param context Optional context object
+   */
+  debug(message: string, context?: Record<string, unknown>): void {
+    this.rootLogger.debug(message, context);
+  }
+
+  /**
+   * Log an info message using the root logger.
+   * Convenience method for one-off logs.
+   *
+   * @param message Log message
+   * @param context Optional context object
+   */
+  info(message: string, context?: Record<string, unknown>): void {
+    this.rootLogger.info(message, context);
+  }
+
+  /**
+   * Log a warning message using the root logger.
+   * Convenience method for one-off logs.
+   *
+   * @param message Log message
+   * @param context Optional context object
+   */
+  warn(message: string, context?: Record<string, unknown>): void {
+    this.rootLogger.warn(message, context);
+  }
+
+  /**
+   * Log an error message using the root logger.
+   * Convenience method for one-off logs.
+   *
+   * @param message Log message
+   * @param context Optional context object
+   */
+  error(message: string, context?: Record<string, unknown>): void {
+    this.rootLogger.error(message, context);
+  }
+}