@hsuite/native-connect-angular 1.0.0

package/src/lib/services/transaction-builders/base-transaction-builder.service.ts

@@ -0,0 +1,585 @@
+/**
+ * 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 Abstract base class for transaction builder services.
+ *
+ * @file base-transaction-builder.service.ts
+ * @description Provides common functionality for building blockchain transactions
+ * across different ledger types (Hedera, XRPL, etc.).
+ *
+ * This abstract base class extracts shared patterns from ledger-specific
+ * transaction builders, including:
+ * - Common validation logic for accounts, amounts, and parameters
+ * - Error handling patterns with standardized error types
+ * - Amount parsing utilities for different decimal formats
+ * - Base64/hex encoding utilities
+ *
+ * Ledger-specific builders should extend this class and implement
+ * the abstract methods for their specific blockchain.
+ *
+ * @Injectable({ providedIn: 'root' })
+ * export class MyLedgerTransactionBuilderService extends BaseTransactionBuilderService {
+ *   protected readonly ledgerType = 'my-ledger';
+ *
+ *   protected async serializeTransactionImpl(tx: unknown): Promise<string> {
+ *     // Ledger-specific serialization
+ *     return btoa(JSON.stringify(tx));
+ *   }
+ * }
+ * ```
+ */
+
+import { inject } from '@angular/core';
+import type { Logger } from '@hsuite/native-connect-sdk';
+
+import { LoggerService } from '../logger.service';
+
+/**
+ * Error codes for transaction builder errors.
+ *
+ * Standardized error codes for identifying specific error conditions
+ * in transaction building operations.
+ */
+export enum TransactionBuilderErrorCode {
+  /** Invalid account ID format */
+  INVALID_ACCOUNT = 'INVALID_ACCOUNT',
+  /** Invalid amount (negative, NaN, or exceeds limits) */
+  INVALID_AMOUNT = 'INVALID_AMOUNT',
+  /** Invalid token ID format */
+  INVALID_TOKEN_ID = 'INVALID_TOKEN_ID',
+  /** Missing required parameter */
+  MISSING_PARAMETER = 'MISSING_PARAMETER',
+  /** No active wallet session */
+  NO_ACTIVE_SESSION = 'NO_ACTIVE_SESSION',
+  /** Transaction serialization failed */
+  SERIALIZATION_FAILED = 'SERIALIZATION_FAILED',
+  /** Network-related error */
+  NETWORK_ERROR = 'NETWORK_ERROR',
+  /** General validation error */
+  VALIDATION_ERROR = 'VALIDATION_ERROR',
+}
+
+/**
+ * Structured error for transaction builder operations.
+ *
+ * Provides detailed error information including error code, message,
+ * and optional context for debugging.
+ */
+export class TransactionBuilderError extends Error {
+  /**
+   * Creates a new TransactionBuilderError.
+   *
+   * @param code - The error code identifying the error type
+   * @param message - Human-readable error message
+   * @param context - Optional context object with additional details
+   */
+  constructor(
+    public readonly code: TransactionBuilderErrorCode,
+    message: string,
+    public readonly context?: Record<string, unknown>,
+  ) {
+    super(message);
+    this.name = 'TransactionBuilderError';
+
+    // Maintains proper stack trace for where error was thrown (V8 engines)
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, TransactionBuilderError);
+    }
+  }
+
+  /**
+   * Creates an error for invalid account format.
+   * @param account
+   * @param ledgerType
+   */
+  static invalidAccount(account: string, ledgerType: string): TransactionBuilderError {
+    return new TransactionBuilderError(
+      TransactionBuilderErrorCode.INVALID_ACCOUNT,
+      `Invalid ${ledgerType} account format: ${account}`,
+      { account, ledgerType },
+    );
+  }
+
+  /**
+   * Creates an error for invalid amount.
+   * @param amount
+   * @param reason
+   */
+  static invalidAmount(amount: unknown, reason: string): TransactionBuilderError {
+    return new TransactionBuilderError(
+      TransactionBuilderErrorCode.INVALID_AMOUNT,
+      `Invalid amount: ${reason}`,
+      { amount, reason },
+    );
+  }
+
+  /**
+   * Creates an error for invalid token ID.
+   * @param tokenId
+   * @param ledgerType
+   */
+  static invalidTokenId(tokenId: string, ledgerType: string): TransactionBuilderError {
+    return new TransactionBuilderError(
+      TransactionBuilderErrorCode.INVALID_TOKEN_ID,
+      `Invalid ${ledgerType} token ID format: ${tokenId}`,
+      { tokenId, ledgerType },
+    );
+  }
+
+  /**
+   * Creates an error for missing required parameter.
+   * @param paramName
+   * @param operation
+   */
+  static missingParameter(paramName: string, operation: string): TransactionBuilderError {
+    return new TransactionBuilderError(
+      TransactionBuilderErrorCode.MISSING_PARAMETER,
+      `Missing required parameter '${paramName}' for ${operation}`,
+      { paramName, operation },
+    );
+  }
+
+  /**
+   * Creates an error for no active session.
+   */
+  static noActiveSession(): TransactionBuilderError {
+    return new TransactionBuilderError(
+      TransactionBuilderErrorCode.NO_ACTIVE_SESSION,
+      'No active wallet session. Please connect your wallet first.',
+    );
+  }
+
+  /**
+   * Creates an error for serialization failure.
+   * @param reason
+   * @param cause
+   */
+  static serializationFailed(reason: string, cause?: unknown): TransactionBuilderError {
+    return new TransactionBuilderError(
+      TransactionBuilderErrorCode.SERIALIZATION_FAILED,
+      `Transaction serialization failed: ${reason}`,
+      { reason, cause: cause instanceof Error ? cause.message : String(cause) },
+    );
+  }
+}
+
+/**
+ * Result of amount parsing with normalized values.
+ *
+ * Contains the parsed amount in different formats for flexibility
+ * in different ledger transaction requirements.
+ */
+export interface ParsedAmount {
+  /** Original input value */
+  original: number | string;
+  /** Amount as a floating-point number */
+  asNumber: number;
+  /** Amount as a string (for precision-sensitive operations) */
+  asString: string;
+  /** Amount in smallest unit (e.g., tinybars, drops) */
+  inSmallestUnit: bigint;
+  /** Number of decimals used */
+  decimals: number;
+}
+
+/**
+ * Configuration for amount parsing.
+ */
+export interface AmountParseOptions {
+  /** Number of decimal places for the asset (default: 0) */
+  decimals?: number;
+  /** Whether to allow negative amounts (default: false) */
+  allowNegative?: boolean;
+  /** Maximum allowed amount (optional) */
+  maxAmount?: number | bigint;
+  /** Minimum allowed amount (optional, default: 0 unless allowNegative) */
+  minAmount?: number | bigint;
+}
+
+/**
+ * Abstract base class for transaction builder services.
+ *
+ * Provides common functionality for building blockchain transactions
+ * including validation, error handling, and amount parsing utilities.
+ *
+ * Ledger-specific builders (Hedera, XRPL, etc.) should extend this class
+ * and implement the abstract methods for their specific requirements.
+ */
+export abstract class BaseTransactionBuilderService {
+  /**
+   * Logger instance for this service.
+   * Injected via Angular DI and scoped to the ledger type.
+   */
+  protected readonly logger: Logger;
+
+  /**
+   * The type of ledger this builder supports (e.g., 'hedera', 'xrpl').
+   * Used for error messages and logging context.
+   */
+  protected abstract readonly ledgerType: string;
+
+  /**
+   *
+   */
+  constructor() {
+    // Inject LoggerService and create scoped logger
+    // Note: Subclasses should call super() and the logger will be set up
+    const loggerService = inject(LoggerService);
+    this.logger = loggerService.scoped(this.constructor.name);
+  }
+
+  // ============================================================================
+  // Validation Methods
+  // ============================================================================
+
+  /**
+   * Validates that a string is a non-empty, valid account identifier.
+   *
+   * Override in subclasses for ledger-specific account format validation.
+   *
+   * @param account - The account identifier to validate
+   * @param paramName - Parameter name for error messages
+   * @throws TransactionBuilderError if validation fails
+   */
+  protected validateAccount(account: string, paramName = 'account'): void {
+    if (!account || typeof account !== 'string') {
+      throw TransactionBuilderError.missingParameter(paramName, 'transaction');
+    }
+
+    const trimmed = account.trim();
+    if (trimmed.length === 0) {
+      throw TransactionBuilderError.invalidAccount(account, this.ledgerType);
+    }
+
+    // Subclasses should override for specific format validation
+    this.validateAccountFormat(trimmed);
+  }
+
+  /**
+   * Validates the account format specific to the ledger type.
+   * Override in subclasses for ledger-specific validation.
+   *
+   * @param account - The trimmed account identifier
+   * @throws TransactionBuilderError if format is invalid
+   */
+  protected validateAccountFormat(account: string): void {
+    // Default implementation - subclasses should override
+    this.logger.debug('Using default account format validation', { account });
+  }
+
+  /**
+   * Validates that an amount is a valid positive number.
+   *
+   * Checks for NaN, Infinity, and negative values (unless allowed).
+   *
+   * @param amount - The amount to validate
+   * @param options - Validation options
+   * @throws TransactionBuilderError if validation fails
+   */
+  protected validateAmount(amount: number | string, options: AmountParseOptions = {}): void {
+    const { allowNegative = false, maxAmount, minAmount } = options;
+
+    const numAmount = typeof amount === 'string' ? parseFloat(amount) : amount;
+
+    if (typeof numAmount !== 'number' || isNaN(numAmount)) {
+      throw TransactionBuilderError.invalidAmount(amount, 'must be a valid number');
+    }
+
+    if (!isFinite(numAmount)) {
+      throw TransactionBuilderError.invalidAmount(amount, 'must be a finite number');
+    }
+
+    if (!allowNegative && numAmount < 0) {
+      throw TransactionBuilderError.invalidAmount(amount, 'must be non-negative');
+    }
+
+    const effectiveMin =
+      minAmount !== undefined ? Number(minAmount) : allowNegative ? -Infinity : 0;
+    if (numAmount < effectiveMin) {
+      throw TransactionBuilderError.invalidAmount(amount, `must be at least ${effectiveMin}`);
+    }
+
+    if (maxAmount !== undefined && numAmount > Number(maxAmount)) {
+      throw TransactionBuilderError.invalidAmount(amount, `must not exceed ${maxAmount}`);
+    }
+  }
+
+  /**
+   * Validates that a token ID is valid for the ledger type.
+   *
+   * @param tokenId - The token identifier to validate
+   * @throws TransactionBuilderError if validation fails
+   */
+  protected validateTokenId(tokenId: string): void {
+    if (!tokenId || typeof tokenId !== 'string') {
+      throw TransactionBuilderError.missingParameter('tokenId', 'token transaction');
+    }
+
+    const trimmed = tokenId.trim();
+    if (trimmed.length === 0) {
+      throw TransactionBuilderError.invalidTokenId(tokenId, this.ledgerType);
+    }
+
+    // Subclasses should override for specific format validation
+    this.validateTokenIdFormat(trimmed);
+  }
+
+  /**
+   * Validates the token ID format specific to the ledger type.
+   * Override in subclasses for ledger-specific validation.
+   *
+   * @param tokenId - The trimmed token identifier
+   * @throws TransactionBuilderError if format is invalid
+   */
+  protected validateTokenIdFormat(tokenId: string): void {
+    // Default implementation - subclasses should override
+    this.logger.debug('Using default token ID format validation', { tokenId });
+  }
+
+  /**
+   * Validates that a required parameter is present.
+   *
+   * @param value - The value to check
+   * @param paramName - The parameter name for error messages
+   * @param operation - The operation name for error messages
+   * @throws TransactionBuilderError if the value is null/undefined
+   */
+  protected requireParam<T>(
+    value: T | null | undefined,
+    paramName: string,
+    operation: string,
+  ): asserts value is T {
+    if (value === null || value === undefined) {
+      throw TransactionBuilderError.missingParameter(paramName, operation);
+    }
+  }
+
+  // ============================================================================
+  // Amount Parsing Utilities
+  // ============================================================================
+
+  /**
+   * Parses an amount into various formats needed for transactions.
+   *
+   * Converts amounts between display format and smallest unit format,
+   * handling decimal precision correctly to avoid floating-point errors.
+   *
+   * @param amount - The amount to parse (number or string)
+   * @param options - Parsing options including decimals
+   * @returns Parsed amount in multiple formats
+   * @throws TransactionBuilderError if amount is invalid
+   */
+  protected parseAmount(amount: number | string, options: AmountParseOptions = {}): ParsedAmount {
+    const { decimals = 0 } = options;
+
+    // Validate the amount first
+    this.validateAmount(amount, options);
+
+    const numAmount = typeof amount === 'string' ? parseFloat(amount) : amount;
+    const strAmount = String(amount);
+
+    // Calculate smallest unit using precise arithmetic
+    // Multiply by 10^decimals to get smallest unit
+    const _multiplier = BigInt(Math.pow(10, decimals));
+
+    // Handle the conversion carefully to avoid precision issues
+    // Split the number into integer and fractional parts
+    const [intPart, fracPart = ''] = strAmount.split('.');
+    const paddedFrac = fracPart.padEnd(decimals, '0').slice(0, decimals);
+    const combinedStr = intPart + paddedFrac;
+
+    // Remove leading zeros but keep at least one digit
+    const normalizedStr = combinedStr.replace(/^0+/, '') || '0';
+    const inSmallestUnit = BigInt(normalizedStr);
+
+    return {
+      original: amount,
+      asNumber: numAmount,
+      asString: strAmount,
+      inSmallestUnit,
+      decimals,
+    };
+  }
+
+  /**
+   * Converts an amount from smallest unit to display format.
+   *
+   * @param smallestUnit - Amount in smallest unit (bigint or number)
+   * @param decimals - Number of decimal places
+   * @returns Formatted string with proper decimal places
+   */
+  protected formatFromSmallestUnit(smallestUnit: bigint | number, decimals: number): string {
+    const bigVal =
+      typeof smallestUnit === 'number' ? BigInt(Math.floor(smallestUnit)) : smallestUnit;
+
+    if (decimals === 0) {
+      return bigVal.toString();
+    }
+
+    const divisor = BigInt(Math.pow(10, decimals));
+    const intPart = bigVal / divisor;
+    const fracPart = bigVal % divisor;
+
+    if (fracPart === 0n) {
+      return intPart.toString();
+    }
+
+    const fracStr = fracPart.toString().padStart(decimals, '0');
+    // Trim trailing zeros from fraction
+    const trimmedFrac = fracStr.replace(/0+$/, '');
+
+    return `${intPart}.${trimmedFrac}`;
+  }
+
+  // ============================================================================
+  // Encoding Utilities
+  // ============================================================================
+
+  /**
+   * Converts a Uint8Array to a base64 string.
+   *
+   * @param bytes - The byte array to encode
+   * @returns Base64 encoded string
+   */
+  protected uint8ArrayToBase64(bytes: Uint8Array): string {
+    let binary = '';
+    for (let i = 0; i < bytes.length; i++) {
+      binary += String.fromCharCode(bytes[i]);
+    }
+    return btoa(binary);
+  }
+
+  /**
+   * Converts a base64 string to a Uint8Array.
+   *
+   * @param base64 - The base64 string to decode
+   * @returns Decoded byte array
+   */
+  protected base64ToUint8Array(base64: string): Uint8Array {
+    const binary = atob(base64);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+      bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes;
+  }
+
+  /**
+   * Converts a Uint8Array to a hex string.
+   *
+   * @param bytes - The byte array to encode
+   * @returns Hex encoded string (lowercase, no prefix)
+   */
+  protected uint8ArrayToHex(bytes: Uint8Array): string {
+    return Array.from(bytes)
+      .map((b) => b.toString(16).padStart(2, '0'))
+      .join('');
+  }
+
+  /**
+   * Converts a hex string to a Uint8Array.
+   *
+   * @param hex - The hex string to decode (with or without 0x prefix)
+   * @returns Decoded byte array
+   */
+  protected hexToUint8Array(hex: string): Uint8Array {
+    const cleanHex = hex.startsWith('0x') ? hex.slice(2) : hex;
+    const bytes = new Uint8Array(cleanHex.length / 2);
+    for (let i = 0; i < bytes.length; i++) {
+      bytes[i] = parseInt(cleanHex.substr(i * 2, 2), 16);
+    }
+    return bytes;
+  }
+
+  /**
+   * Converts a string to a hex-encoded string.
+   *
+   * @param str - The string to encode
+   * @returns Hex encoded string
+   */
+  protected stringToHex(str: string): string {
+    const encoder = new TextEncoder();
+    return this.uint8ArrayToHex(encoder.encode(str));
+  }
+
+  /**
+   * Converts a hex-encoded string back to a regular string.
+   *
+   * @param hex - The hex string to decode
+   * @returns Decoded string
+   */
+  protected hexToString(hex: string): string {
+    const bytes = this.hexToUint8Array(hex);
+    const decoder = new TextDecoder();
+    return decoder.decode(bytes);
+  }
+
+  // ============================================================================
+  // Error Handling
+  // ============================================================================
+
+  /**
+   * Wraps an async operation with standardized error handling.
+   *
+   * Catches errors from the operation and wraps them in
+   * TransactionBuilderError with appropriate context.
+   *
+   * @param operation - Name of the operation for error context
+   * @param fn - The async function to execute
+   * @returns The result of the function
+   * @throws TransactionBuilderError with context if operation fails
+   */
+  protected async withErrorHandling<T>(operation: string, fn: () => Promise<T>): Promise<T> {
+    try {
+      return await fn();
+    } catch (error) {
+      // If it's already a TransactionBuilderError, re-throw
+      if (error instanceof TransactionBuilderError) {
+        this.logger.error(`${operation} failed`, {
+          code: error.code,
+          message: error.message,
+          context: error.context,
+        });
+        throw error;
+      }
+
+      // Wrap other errors
+      const message = error instanceof Error ? error.message : String(error);
+      this.logger.error(`${operation} failed with unexpected error`, {
+        operation,
+        error: message,
+      });
+
+      throw new TransactionBuilderError(
+        TransactionBuilderErrorCode.VALIDATION_ERROR,
+        `${operation} failed: ${message}`,
+        { operation, originalError: message },
+      );
+    }
+  }
+
+  // ============================================================================
+  // Abstract Methods (to be implemented by subclasses)
+  // ============================================================================
+
+  /**
+   * Serializes a transaction to a base64-encoded string.
+   * Must be implemented by ledger-specific subclasses.
+   *
+   * @param transaction - The transaction object to serialize
+   * @param payerAccount - The account paying for the transaction
+   * @returns Base64 encoded transaction bytes
+   */
+  protected abstract serializeTransaction(
+    transaction: unknown,
+    payerAccount: string,
+  ): Promise<string>;
+}

package/src/lib/services/transaction-builders/hedera-amount-utils.ts

@@ -0,0 +1,84 @@
+/**
+ * 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
+ */
+
+/**
+ * Scale a whole-token amount up to base units using the token's decimals
+ * value, with bigint arithmetic so 10^decimals never overflows JS number
+ * precision.
+ *
+ * Mirror of the canonical helper at
+ * `packages/transaction-builders/src/lib/hedera-amount-utils.ts`. Kept in
+ * sync deliberately — the angular-sdk does not depend on the
+ * transaction-builders package (each maintains its own builder copy), so a
+ * shared re-export is not currently possible without introducing a new
+ * workspace dep. The canonical file carries the vitest spec; this copy
+ * exists solely so consumers importing from `@hsuite/native-connect-angular`
+ * have a single import surface.
+ *
+ * @param amount
+ * @param decimals
+ * @see packages/transaction-builders/src/lib/hedera-amount-utils.ts
+ */
+// SYNC-START: scaleHederaAmountToBaseUnits — see __tests__/sync.spec.ts
+export function scaleHederaAmountToBaseUnits(amount: number, decimals: number): bigint {
+  if (!Number.isFinite(amount)) {
+    throw new RangeError(
+      `scaleHederaAmountToBaseUnits: amount must be a finite number, got ${amount}`,
+    );
+  }
+  if (amount < 0) {
+    throw new RangeError(
+      `scaleHederaAmountToBaseUnits: amount must be non-negative, got ${amount}`,
+    );
+  }
+  if (!Number.isInteger(decimals)) {
+    throw new RangeError(
+      `scaleHederaAmountToBaseUnits: decimals must be an integer, got ${decimals}`,
+    );
+  }
+  if (decimals < 0) {
+    throw new RangeError(
+      `scaleHederaAmountToBaseUnits: decimals must be non-negative, got ${decimals}`,
+    );
+  }
+  if (amount === 0) return 0n;
+  const whole = Math.trunc(amount);
+  const fraction = amount - whole;
+  const scale = 10n ** BigInt(decimals);
+  const wholePart = BigInt(whole) * scale;
+  if (fraction === 0) return wholePart;
+  const fractionalPart = BigInt(Math.round(fraction * Number(scale)));
+  return wholePart + fractionalPart;
+}
+// SYNC-END: scaleHederaAmountToBaseUnits
+
+/**
+ * Narrow a `bigint` to a JS `number` after asserting it fits within
+ * `Number.MAX_SAFE_INTEGER`. Throws `RangeError` with the supplied context
+ * on overflow.
+ *
+ * Mirror of the canonical helper at
+ * `packages/transaction-builders/src/lib/hedera-amount-utils.ts`. Kept in
+ * sync deliberately — see the SYNC note above.
+ * @param value
+ * @param context
+ */
+// SYNC-START: assertSafeInteger — see __tests__/sync.spec.ts
+export function assertSafeInteger(value: bigint, context: string): number {
+  const max = BigInt(Number.MAX_SAFE_INTEGER);
+  const min = BigInt(Number.MIN_SAFE_INTEGER);
+  if (value > max || value < min) {
+    throw new RangeError(
+      `${context}: value ${value.toString()} exceeds JS safe-integer range (${Number.MIN_SAFE_INTEGER}..${Number.MAX_SAFE_INTEGER}). The Hedera SDK accepts Long for larger values; if you need >2^53 base units, the builder signature must widen to accept Long/bigint.`,
+    );
+  }
+  return Number(value);
+}
+// SYNC-END: assertSafeInteger