@hsuite/native-connect-angular 1.0.0

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

@@ -0,0 +1,1285 @@
+/**
+ * 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 Service for building Hedera transactions using the Hashgraph SDK.
+ *
+ * @module services/transaction-builders/hedera
+ *
+ * @description
+ * HederaTransactionBuilderService provides methods to construct various Hedera transaction
+ * types and serialize them to base64 payloads ready for signing. It uses the @hashgraph/sdk
+ * library for proper transaction construction and automatically freezes transactions with
+ * the correct network client.
+ *
+ * **Supported Transaction Types:**
+ * - HBAR transfers (single and atomic multi-transfer)
+ * - Fungible token transfers
+ * - NFT transfers
+ * - Token association/dissociation
+ * - Token creation (with auto key configuration)
+ * - Token minting/burning
+ * - Topic creation (with auto key configuration)
+ * - Topic message submission
+ * - Account creation (with multisig support)
+ * - Account updates
+ * - Batch transactions
+ *
+ * **Auto-Key Configuration:**
+ * When creating entities (topics, tokens, accounts), the builder automatically
+ * inherits the key structure from the active account:
+ * - Single-sig accounts -> entity uses account's public key
+ * - Multisig accounts -> entity uses threshold key with all signers
+ */
+
+import { Injectable, inject } from '@angular/core';
+import {
+  TransferTransaction,
+  TokenAssociateTransaction,
+  TokenDissociateTransaction,
+  TokenCreateTransaction,
+  TokenMintTransaction,
+  TokenBurnTransaction,
+  TopicCreateTransaction,
+  TopicMessageSubmitTransaction,
+  AccountCreateTransaction,
+  AccountUpdateTransaction,
+  ScheduleCreateTransaction,
+  BatchTransaction,
+  Transaction,
+  Hbar,
+  AccountId,
+  TokenId,
+  NftId,
+  TransactionId,
+  Client,
+  PrivateKey,
+  PublicKey,
+  TokenType,
+  TokenSupplyType,
+  KeyList,
+  Key,
+} from '@hashgraph/sdk';
+
+import { LoggerService } from '../logger.service';
+import { UnifiedWalletService } from '../unified-wallet.service';
+
+import { scaleHederaAmountToBaseUnits, assertSafeInteger } from './hedera-amount-utils';
+
+/**
+ * Supported inner transaction types for batch transactions.
+ * Excludes 'batch-transaction' since batches cannot be nested.
+ */
+export type BatchInnerTransactionType =
+  | 'send-hbar'
+  | 'send-token'
+  | 'send-nft'
+  | 'token-associate'
+  | 'token-dissociate'
+  | 'token-create'
+  | 'token-mint'
+  | 'token-burn'
+  | 'topic-create'
+  | 'topic-message'
+  | 'account-create'
+  | 'account-update';
+
+/**
+ * Inner transaction descriptor for batch transactions.
+ * Contains all possible fields for different transaction types.
+ */
+export interface BatchInnerTransaction {
+  /** Type of transaction */
+  type: BatchInnerTransactionType;
+
+  // Transfer fields (send-hbar, send-token, send-nft)
+  /** Recipient account */
+  toAccount?: string;
+  /** Amount for HBAR (tinybars) or token transfers */
+  amount?: number;
+  /** Token ID for token operations */
+  tokenId?: string;
+  /** Serial number for NFT transfers */
+  serialNumber?: number;
+
+  // Token create fields
+  /** Token name for creation */
+  tokenName?: string;
+  /** Token symbol for creation */
+  tokenSymbol?: string;
+  /** Token decimals for creation */
+  decimals?: number;
+  /** Initial supply for fungible tokens */
+  initialSupply?: number;
+  /** Max supply (0 = infinite) */
+  maxSupply?: number;
+  /** Whether supply is finite or infinite */
+  supplyType?: 'finite' | 'infinite';
+
+  // Token mint/burn fields
+  /** Metadata for NFT minting (array for multiple NFTs) */
+  metadata?: string | string[];
+
+  // Topic fields
+  /** Topic ID for message submission */
+  topicId?: string;
+  /** Message content for topic submission */
+  message?: string;
+  /** Topic memo for creation */
+  topicMemo?: string;
+
+  // Account fields
+  /** Initial balance for account creation (tinybars) */
+  initialBalance?: number;
+  /** Memo for account update */
+  memo?: string;
+  /** Max auto associations for account */
+  maxAutoAssociations?: number;
+}
+
+/**
+ * Key configuration for entity creation transactions.
+ *
+ * For single-sig accounts: provide a single publicKey string
+ * For multisig accounts: provide signerPublicKeys array + threshold
+ */
+export interface HederaKeyConfig {
+  /**
+   * Single public key (hex/DER encoded) for single-sig accounts.
+   * If provided alone, this key is used directly.
+   */
+  publicKey?: string;
+
+  /**
+   * Array of public keys for multisig (threshold key) configuration.
+   * Requires threshold to be set.
+   */
+  signerPublicKeys?: string[];
+
+  /**
+   * Threshold for multisig - number of signatures required.
+   * Only used when signerPublicKeys is provided.
+   */
+  threshold?: number;
+}
+
+/**
+ * Extended options for topic creation with key configuration.
+ */
+export interface TopicCreateOptions {
+  /** Topic memo/description */
+  memo?: string;
+  /** Admin key - can update/delete the topic. Uses creator's key if not specified. */
+  adminKey?: HederaKeyConfig;
+  /** Submit key - required to submit messages. If not set, anyone can submit. */
+  submitKey?: HederaKeyConfig;
+  /** Auto-renew account for fees */
+  autoRenewAccountId?: string;
+}
+
+/**
+ * Extended options for token creation with key configuration.
+ */
+export interface TokenCreateOptions {
+  /** Token name */
+  name: string;
+  /** Token symbol */
+  symbol: string;
+  /** Decimal places (0 for NFTs) */
+  decimals: number;
+  /** Initial supply (0 for NFTs) */
+  initialSupply: number;
+  /** Token type: FUNGIBLE or NFT */
+  tokenType?: 'FUNGIBLE' | 'NFT';
+  /** Admin key - can update/delete token */
+  adminKey?: HederaKeyConfig;
+  /** Supply key - can mint/burn tokens */
+  supplyKey?: HederaKeyConfig;
+  /** Freeze key - can freeze/unfreeze accounts */
+  freezeKey?: HederaKeyConfig;
+  /** Wipe key - can wipe token balance from accounts */
+  wipeKey?: HederaKeyConfig;
+  /** Pause key - can pause/unpause token operations */
+  pauseKey?: HederaKeyConfig;
+  /** KYC key - can grant/revoke KYC */
+  kycKey?: HederaKeyConfig;
+  /** Fee schedule key - can update custom fees */
+  feeScheduleKey?: HederaKeyConfig;
+  /** Token memo */
+  memo?: string;
+  /** Max supply (for finite tokens) */
+  maxSupply?: number;
+}
+
+/**
+ * Extended options for account creation with key configuration.
+ */
+export interface AccountCreateOptions {
+  /** Initial HBAR balance */
+  initialBalance: number;
+  /**
+   * Key configuration for the new account.
+   * For single-sig: provide publicKey
+   * For multisig: provide signerPublicKeys + threshold
+   */
+  key?: HederaKeyConfig;
+  /** Account memo */
+  memo?: string;
+  /** Max automatic token associations */
+  maxAutomaticTokenAssociations?: number;
+  /** Receiver signature required */
+  receiverSignatureRequired?: boolean;
+}
+
+/**
+ * Service for building Hedera transactions using the Hashgraph SDK.
+ *
+ * @service HederaTransactionBuilderService
+ *
+ * @description
+ * Provides methods to construct various Hedera transaction types and serialize them
+ * to base64 payloads ready for signing. Transactions are automatically frozen with
+ * the correct network client (mainnet/testnet) based on the active wallet session.
+ *
+ * All build methods return a base64-encoded string that can be passed to
+ * UnifiedWalletService.signTransaction() or submitTransaction().
+ *
+ * @providedIn root
+ *
+ * @Component({ ... })
+ * export class SendPage {
+ *   private builder = inject(HederaTransactionBuilderService);
+ *   private wallet = inject(UnifiedWalletService);
+ *
+ *   async sendHbar(to: string, amount: number) {
+ *     const from = this.wallet.activeAccount()?.address;
+ *     const payload = await this.builder.buildSendHbar(from!, to, amount);
+ *     return this.wallet.submitTransaction({ payload });
+ *   }
+ * }
+ * ```
+ */
+@Injectable({
+  providedIn: 'root',
+})
+export class HederaTransactionBuilderService {
+  private readonly wallet = inject(UnifiedWalletService);
+  private readonly logger = inject(LoggerService).scoped('HederaTransactionBuilder');
+
+  /**
+   * Gets the network ID from the active wallet account.
+   *
+   * @description
+   * Extracts the network identifier (e.g., 'hedera:mainnet', 'hedera:testnet')
+   * from the currently active account. Used to create the appropriate Hedera
+   * client for transaction freezing.
+   *
+   * @returns Network ID string, or undefined if no active account
+   *
+   * @throws {Error} When used in methods that require a network, if no account is active
+   */
+  private getNetworkId(): string | undefined {
+    const activeAccount = this.wallet.activeAccount();
+    return activeAccount?.networkId;
+  }
+
+  /**
+   * Build a Hedera Key from configuration.
+   *
+   * For single-sig: returns PublicKey directly
+   * For multisig: returns KeyList (threshold key) with all signer public keys
+   *
+   * @param config - Key configuration (single key or threshold key)
+   * @returns Hedera Key object or undefined if config is empty
+   */
+  private buildKeyFromConfig(config?: HederaKeyConfig): Key | undefined {
+    if (!config) {
+      return undefined;
+    }
+
+    // Multisig: threshold key with multiple signers
+    if (config.signerPublicKeys && config.signerPublicKeys.length > 0 && config.threshold) {
+      const publicKeys = config.signerPublicKeys.map((pk) => PublicKey.fromString(pk));
+      const keyList = new KeyList(publicKeys, config.threshold);
+      this.logger.debug('Built threshold key', {
+        signerCount: publicKeys.length,
+        threshold: config.threshold,
+      });
+      return keyList;
+    }
+
+    // Single-sig: direct public key
+    if (config.publicKey) {
+      const key = PublicKey.fromString(config.publicKey);
+      this.logger.debug('Built single public key');
+      return key;
+    }
+
+    return undefined;
+  }
+
+  /**
+   * Get the key configuration for the active account.
+   *
+   * For single-sig: returns { publicKey: '...' }
+   * For multisig: returns { signerPublicKeys: [...], threshold: N }
+   *
+   * This allows automatic key configuration for entity creation (topics, tokens, etc.)
+   * so that entities inherit the same key structure as the creating account.
+   *
+   * @returns Key configuration or undefined if no active account
+   */
+  private getActiveAccountKeyConfig(): HederaKeyConfig | undefined {
+    const activeAccount = this.wallet.activeAccount();
+    if (!activeAccount) {
+      this.logger.debug('No active account for key config');
+      return undefined;
+    }
+
+    const metadata = activeAccount.metadata;
+
+    // Check if this is a multisig account
+    if (metadata?.['isMultisig'] === true) {
+      const signerPublicKeys = metadata['signerPublicKeys'] as string[] | undefined;
+      const threshold = metadata['threshold'] as number | undefined;
+
+      if (signerPublicKeys && signerPublicKeys.length > 0 && threshold) {
+        this.logger.debug('Active account is multisig', {
+          threshold,
+          signerCount: signerPublicKeys.length,
+        });
+        return { signerPublicKeys, threshold };
+      }
+
+      this.logger.warn('Multisig account missing signer keys or threshold in metadata');
+      return undefined;
+    }
+
+    // Single-sig account - get public key from metadata
+    const publicKey = metadata?.['publicKey'] as string | undefined;
+    if (publicKey) {
+      this.logger.debug('Active account is single-sig');
+      return { publicKey };
+    }
+
+    this.logger.debug('No public key in active account metadata');
+    return undefined;
+  }
+
+  /**
+   * Builds a simple HBAR transfer transaction.
+   *
+   * @description
+   * Creates a TransferTransaction that moves HBAR from one account to another.
+   * The transaction is automatically frozen with the appropriate network client.
+   *
+   * @param fromAccount - Sender account ID (e.g., "0.0.12345")
+   * @param toAccount - Recipient account ID
+   * @param amount - Amount in HBAR (e.g., 1.5 for 1.5 HBAR)
+   *
+   * @returns Base64 encoded transaction bytes
+   *
+   * @throws {Error} If no active wallet session
+   */
+  async buildSendHbar(fromAccount: string, toAccount: string, amount: number): Promise<string> {
+    const transaction = new TransferTransaction()
+      .addHbarTransfer(AccountId.fromString(fromAccount), new Hbar(-amount))
+      .addHbarTransfer(AccountId.fromString(toAccount), new Hbar(amount));
+
+    return this.serializeTransaction(transaction, fromAccount);
+  }
+
+  /**
+   * Builds a fungible token transfer transaction.
+   *
+   * @description
+   * Creates a TransferTransaction that moves fungible tokens between accounts.
+   * The amount is automatically converted to the smallest unit based on decimals.
+   *
+   * @param fromAccount - Sender account ID
+   * @param toAccount - Recipient account ID
+   * @param tokenId - Token ID (e.g., "0.0.98765")
+   * @param amount - Token amount in display units (e.g., 100 tokens)
+   * @param decimals - Token decimals for conversion (default 0)
+   *
+   * @returns Base64 encoded transaction bytes
+   *
+   * @throws {Error} If no active wallet session
+   */
+  async buildSendToken(
+    fromAccount: string,
+    toAccount: string,
+    tokenId: string,
+    amount: number,
+    decimals = 0,
+  ): Promise<string> {
+    const token = TokenId.fromString(tokenId);
+    // bigint scaling avoids the silent precision loss that
+    // `amount * Math.pow(10, decimals)` exhibits past Number.MAX_SAFE_INTEGER
+    // (Hedera supports up to 18 decimals). Narrow once at the SDK boundary
+    // with an explicit overflow assertion.
+    const scaled = scaleHederaAmountToBaseUnits(amount, decimals);
+    const actualAmount = assertSafeInteger(scaled, `buildSendToken tokenId=${tokenId}`);
+
+    const transaction = new TransferTransaction()
+      .addTokenTransfer(token, AccountId.fromString(fromAccount), -actualAmount)
+      .addTokenTransfer(token, AccountId.fromString(toAccount), actualAmount);
+
+    return this.serializeTransaction(transaction, fromAccount);
+  }
+
+  /**
+   * Builds an NFT transfer transaction.
+   *
+   * @description
+   * Creates a TransferTransaction that moves an NFT (identified by token ID
+   * and serial number) from one account to another.
+   *
+   * @param fromAccount - Sender account ID
+   * @param toAccount - Recipient account ID
+   * @param tokenId - NFT token ID (e.g., "0.0.98765")
+   * @param serialNumber - NFT serial number (e.g., 1, 2, 3)
+   *
+   * @returns Base64 encoded transaction bytes
+   *
+   * @throws {Error} If no active wallet session
+   */
+  async buildSendNft(
+    fromAccount: string,
+    toAccount: string,
+    tokenId: string,
+    serialNumber: number,
+  ): Promise<string> {
+    const nftId = new NftId(TokenId.fromString(tokenId), serialNumber);
+
+    const transaction = new TransferTransaction().addNftTransfer(
+      nftId,
+      AccountId.fromString(fromAccount),
+      AccountId.fromString(toAccount),
+    );
+
+    return this.serializeTransaction(transaction, fromAccount);
+  }
+
+  /**
+   * Builds a token association transaction.
+   *
+   * @description
+   * Creates a TokenAssociateTransaction that associates one or more tokens
+   * with an account. This is required before an account can receive tokens
+   * on Hedera.
+   *
+   * @param account - Account to associate tokens with
+   * @param tokenIds - Array of token IDs to associate
+   *
+   * @returns Base64 encoded transaction bytes
+   *
+   * @throws {Error} If no active wallet session
+   */
+  async buildAssociateToken(account: string, tokenIds: string[]): Promise<string> {
+    const tokens = tokenIds.map((id) => TokenId.fromString(id));
+
+    const transaction = new TokenAssociateTransaction()
+      .setAccountId(AccountId.fromString(account))
+      .setTokenIds(tokens);
+
+    return this.serializeTransaction(transaction, account);
+  }
+
+  /**
+   * Builds a token dissociation transaction.
+   *
+   * @description
+   * Creates a TokenDissociateTransaction that removes the association between
+   * an account and one or more tokens. The account must have zero balance of
+   * each token before dissociating.
+   *
+   * @param account - Account to dissociate tokens from
+   * @param tokenIds - Array of token IDs to dissociate
+   *
+   * @returns Base64 encoded transaction bytes
+   *
+   * @throws {Error} If no active wallet session
+   */
+  async buildDissociateToken(account: string, tokenIds: string[]): Promise<string> {
+    const tokens = tokenIds.map((id) => TokenId.fromString(id));
+
+    const transaction = new TokenDissociateTransaction()
+      .setAccountId(AccountId.fromString(account))
+      .setTokenIds(tokens);
+
+    return this.serializeTransaction(transaction, account);
+  }
+
+  /**
+   * Build a scheduled transaction
+   * @param innerTransactionBytes - Base64 encoded inner transaction
+   * @param payerAccount - Payer account for the scheduled transaction (required)
+   * @param memo - Optional memo
+   * @returns Base64 encoded scheduled transaction bytes
+   */
+  async buildScheduledTransaction(
+    innerTransactionBytes: string,
+    payerAccount: string,
+    memo?: string,
+  ): Promise<string> {
+    const exampleInnerTx = new TransferTransaction()
+      .addHbarTransfer(AccountId.fromString(payerAccount), new Hbar(-1))
+      .addHbarTransfer(AccountId.fromString('0.0.3'), new Hbar(1));
+
+    const transaction = new ScheduleCreateTransaction()
+      .setScheduledTransaction(exampleInnerTx)
+      .setPayerAccountId(AccountId.fromString(payerAccount));
+
+    if (memo) {
+      transaction.setScheduleMemo(memo);
+    }
+
+    return this.serializeTransaction(transaction, payerAccount);
+  }
+
+  /**
+   * Build a batch of transactions with the same payer
+   * @param transactions - Array of base64 encoded transactions
+   * @returns Array of base64 encoded transactions (ready for batch submission)
+   */
+  async buildBatchTransactions(transactions: string[]): Promise<string[]> {
+    return transactions;
+  }
+
+  /**
+   * Build a complex atomic transaction (multiple transfers in one transaction)
+   * @param transfers - Array of transfer operations
+   * @returns Base64 encoded transaction bytes
+   */
+  async buildAtomicTransaction(
+    transfers: Array<{
+      type: 'hbar' | 'token';
+      fromAccount: string;
+      toAccount: string;
+      amount: number;
+      tokenId?: string;
+      decimals?: number;
+    }>,
+  ): Promise<string> {
+    if (transfers.length === 0) {
+      throw new Error('At least one transfer is required for an atomic transaction');
+    }
+
+    const transaction = new TransferTransaction();
+    const payerAccount = transfers[0].fromAccount;
+
+    for (const transfer of transfers) {
+      if (transfer.type === 'hbar') {
+        transaction
+          .addHbarTransfer(AccountId.fromString(transfer.fromAccount), new Hbar(-transfer.amount))
+          .addHbarTransfer(AccountId.fromString(transfer.toAccount), new Hbar(transfer.amount));
+      } else if (transfer.type === 'token' && transfer.tokenId) {
+        const token = TokenId.fromString(transfer.tokenId);
+        const decimals = transfer.decimals || 0;
+        const scaled = scaleHederaAmountToBaseUnits(transfer.amount, decimals);
+        const actualAmount = assertSafeInteger(
+          scaled,
+          `atomicTransaction token=${transfer.tokenId}`,
+        );
+
+        transaction
+          .addTokenTransfer(token, AccountId.fromString(transfer.fromAccount), -actualAmount)
+          .addTokenTransfer(token, AccountId.fromString(transfer.toAccount), actualAmount);
+      }
+    }
+
+    return this.serializeTransaction(transaction, payerAccount);
+  }
+
+  /**
+   * Build a token creation transaction with automatic key configuration.
+   *
+   * **Auto-key behavior**: If no adminKey/supplyKey is provided, the token will automatically
+   * inherit the creating account's key structure:
+   * - Single-sig account → token keys = account's public key
+   * - Multisig account → token keys = threshold key with all signers
+   *
+   * This ensures tokens created from multisig accounts are also controlled by the multisig.
+   *
+   * @param treasuryAccount - Account that will hold the tokens
+   * @param options - Token creation options (keys auto-detected if not provided)
+   * @param optionsOrName
+   * @param symbol
+   * @param decimals
+   * @param initialSupply
+   * @param tokenType
+   * @returns Base64 encoded transaction bytes
+   */
+  async buildTokenCreate(
+    treasuryAccount: string,
+    optionsOrName: TokenCreateOptions | string,
+    symbol?: string,
+    decimals?: number,
+    initialSupply?: number,
+    tokenType: 'FUNGIBLE' | 'NFT' = 'FUNGIBLE',
+  ): Promise<string> {
+    // Support both object and positional arguments
+    const opts: TokenCreateOptions =
+      typeof optionsOrName === 'string'
+        ? {
+            name: optionsOrName,
+            symbol: symbol!,
+            decimals: decimals!,
+            initialSupply: initialSupply!,
+            tokenType,
+          }
+        : optionsOrName;
+
+    const transaction = new TokenCreateTransaction()
+      .setTokenName(opts.name)
+      .setTokenSymbol(opts.symbol)
+      .setDecimals(opts.decimals)
+      .setInitialSupply(opts.initialSupply)
+      .setTreasuryAccountId(AccountId.fromString(treasuryAccount))
+      .setTokenType(
+        opts.tokenType === 'NFT' ? TokenType.NonFungibleUnique : TokenType.FungibleCommon,
+      )
+      .setSupplyType(opts.maxSupply ? TokenSupplyType.Finite : TokenSupplyType.Infinite);
+
+    // Set max supply if finite
+    if (opts.maxSupply) {
+      transaction.setMaxSupply(opts.maxSupply);
+    }
+
+    // Set memo if provided
+    if (opts.memo) {
+      transaction.setTokenMemo(opts.memo);
+    }
+
+    // Auto-detect key config from active account if not explicitly provided
+    const autoKeyConfig = this.getActiveAccountKeyConfig();
+    const isAutoDetected = !!autoKeyConfig;
+
+    // Set admin key - use provided or auto-detected
+    const adminKeyConfig = opts.adminKey ?? autoKeyConfig;
+    const adminKey = this.buildKeyFromConfig(adminKeyConfig);
+    if (adminKey) {
+      transaction.setAdminKey(adminKey);
+      this.logger.debug('Token admin key set', { autoDetected: !opts.adminKey && isAutoDetected });
+    }
+
+    // Set supply key - use provided or auto-detected
+    const supplyKeyConfig = opts.supplyKey ?? autoKeyConfig;
+    const supplyKey = this.buildKeyFromConfig(supplyKeyConfig);
+    if (supplyKey) {
+      transaction.setSupplyKey(supplyKey);
+      this.logger.debug('Token supply key set', {
+        autoDetected: !opts.supplyKey && isAutoDetected,
+      });
+    }
+
+    // Set freeze key - only if explicitly provided (not auto-set)
+    const freezeKey = this.buildKeyFromConfig(opts.freezeKey);
+    if (freezeKey) {
+      transaction.setFreezeKey(freezeKey);
+      this.logger.debug('Token freeze key set');
+    }
+
+    // Set wipe key - only if explicitly provided (not auto-set)
+    const wipeKey = this.buildKeyFromConfig(opts.wipeKey);
+    if (wipeKey) {
+      transaction.setWipeKey(wipeKey);
+      this.logger.debug('Token wipe key set');
+    }
+
+    // Set pause key - only if explicitly provided (not auto-set)
+    const pauseKey = this.buildKeyFromConfig(opts.pauseKey);
+    if (pauseKey) {
+      transaction.setPauseKey(pauseKey);
+      this.logger.debug('Token pause key set');
+    }
+
+    // Set KYC key - only if explicitly provided (not auto-set)
+    const kycKey = this.buildKeyFromConfig(opts.kycKey);
+    if (kycKey) {
+      transaction.setKycKey(kycKey);
+      this.logger.debug('Token KYC key set');
+    }
+
+    // Set fee schedule key - only if explicitly provided (not auto-set)
+    const feeScheduleKey = this.buildKeyFromConfig(opts.feeScheduleKey);
+    if (feeScheduleKey) {
+      transaction.setFeeScheduleKey(feeScheduleKey);
+      this.logger.debug('Token fee schedule key set');
+    }
+
+    return this.serializeTransaction(transaction, treasuryAccount);
+  }
+
+  /**
+   * Build a token mint transaction
+   * @param tokenId - Token ID to mint
+   * @param amount - Amount to mint
+   * @param account - Account performing the mint
+   * @returns Base64 encoded transaction bytes
+   */
+  async buildTokenMint(tokenId: string, amount: number, account: string): Promise<string> {
+    const transaction = new TokenMintTransaction()
+      .setTokenId(TokenId.fromString(tokenId))
+      .setAmount(amount);
+
+    return this.serializeTransaction(transaction, account);
+  }
+
+  /**
+   * Build a token burn transaction
+   * @param tokenId - Token ID to burn
+   * @param amount - Amount to burn
+   * @param account - Account performing the burn
+   * @returns Base64 encoded transaction bytes
+   */
+  async buildTokenBurn(tokenId: string, amount: number, account: string): Promise<string> {
+    const transaction = new TokenBurnTransaction()
+      .setTokenId(TokenId.fromString(tokenId))
+      .setAmount(amount);
+
+    return this.serializeTransaction(transaction, account);
+  }
+
+  /**
+   * Build a topic creation transaction with automatic key configuration.
+   *
+   * **Auto-key behavior**: If no adminKey is provided, the topic will automatically
+   * inherit the creating account's key structure:
+   * - Single-sig account → topic adminKey = account's public key
+   * - Multisig account → topic adminKey = threshold key with all signers
+   *
+   * This ensures topics created from multisig accounts are also controlled by the multisig.
+   *
+   * @param account - Account creating the topic
+   * @param options - Topic creation options (keys auto-detected if not provided)
+   * @returns Base64 encoded transaction bytes
+   */
+  async buildTopicCreate(
+    account: string,
+    options?: TopicCreateOptions | string, // string treated as memo
+  ): Promise<string> {
+    const transaction = new TopicCreateTransaction();
+
+    // Support both object and string (memo shorthand)
+    const opts: TopicCreateOptions =
+      typeof options === 'string' ? { memo: options } : (options ?? {});
+
+    if (opts.memo) {
+      transaction.setTopicMemo(opts.memo);
+    }
+
+    // Auto-detect key config from active account if not explicitly provided
+    const autoKeyConfig = this.getActiveAccountKeyConfig();
+
+    // Set admin key - use provided or auto-detected
+    const adminKeyConfig = opts.adminKey ?? autoKeyConfig;
+    const adminKey = this.buildKeyFromConfig(adminKeyConfig);
+    if (adminKey) {
+      transaction.setAdminKey(adminKey);
+      this.logger.debug('Topic admin key set', {
+        isThreshold: adminKeyConfig?.signerPublicKeys ? true : false,
+        autoDetected: !opts.adminKey && !!autoKeyConfig,
+      });
+    }
+
+    // Set submit key - use provided or auto-detected (same as admin by default)
+    const submitKeyConfig = opts.submitKey ?? autoKeyConfig;
+    const submitKey = this.buildKeyFromConfig(submitKeyConfig);
+    if (submitKey) {
+      transaction.setSubmitKey(submitKey);
+      this.logger.debug('Topic submit key set', {
+        isThreshold: submitKeyConfig?.signerPublicKeys ? true : false,
+        autoDetected: !opts.submitKey && !!autoKeyConfig,
+      });
+    }
+
+    // Set auto-renew account if provided
+    if (opts.autoRenewAccountId) {
+      transaction.setAutoRenewAccountId(AccountId.fromString(opts.autoRenewAccountId));
+    }
+
+    return this.serializeTransaction(transaction, account);
+  }
+
+  /**
+   * Build a topic message submit transaction
+   * @param topicId - Topic ID (e.g., "0.0.12345")
+   * @param message - Message to submit
+   * @param account - Account submitting the message
+   * @returns Base64 encoded transaction bytes
+   */
+  async buildTopicMessageSubmit(
+    topicId: string,
+    message: string,
+    account: string,
+  ): Promise<string> {
+    const transaction = new TopicMessageSubmitTransaction().setTopicId(topicId).setMessage(message);
+
+    return this.serializeTransaction(transaction, account);
+  }
+
+  /**
+   * Build an account creation transaction with key configuration.
+   *
+   * For single-sig accounts: pass { publicKey: '...' }
+   * For multisig accounts: pass { signerPublicKeys: [...], threshold: N }
+   *
+   * If no key is provided, a random key is generated (NOT RECOMMENDED for production).
+   *
+   * @param creatorAccount - Account creating the new account
+   * @param options - Account creation options including key config
+   * @param optionsOrBalance
+   * @returns Base64 encoded transaction bytes
+   */
+  async buildAccountCreate(
+    creatorAccount: string,
+    optionsOrBalance: AccountCreateOptions | number,
+  ): Promise<string> {
+    // Support both object and number (initial balance shorthand)
+    const opts: AccountCreateOptions =
+      typeof optionsOrBalance === 'number'
+        ? { initialBalance: optionsOrBalance }
+        : optionsOrBalance;
+
+    const transaction = new AccountCreateTransaction().setInitialBalance(
+      new Hbar(opts.initialBalance),
+    );
+
+    // Auto-detect key config from active account if not explicitly provided
+    // This ensures accounts created from multisig wallets inherit the multisig key structure
+    const autoKeyConfig = this.getActiveAccountKeyConfig();
+    const keyConfig = opts.key ?? autoKeyConfig;
+
+    // Set account key - use provided or auto-detected
+    const accountKey = this.buildKeyFromConfig(keyConfig);
+    if (accountKey) {
+      transaction.setKey(accountKey);
+      this.logger.debug('Account key set', {
+        isThreshold: keyConfig?.signerPublicKeys ? true : false,
+        autoDetected: !opts.key && !!autoKeyConfig,
+      });
+    } else {
+      // Fallback: generate random key (not recommended for production)
+      const newKey = PrivateKey.generateED25519();
+      transaction.setKey(newKey.publicKey);
+      this.logger.warn(
+        'Generated random key for new account - provide key config for production use',
+      );
+    }
+
+    // Set memo if provided
+    if (opts.memo) {
+      transaction.setAccountMemo(opts.memo);
+    }
+
+    // Set max automatic token associations
+    if (opts.maxAutomaticTokenAssociations !== undefined) {
+      transaction.setMaxAutomaticTokenAssociations(opts.maxAutomaticTokenAssociations);
+    }
+
+    // Set receiver signature required
+    if (opts.receiverSignatureRequired !== undefined) {
+      transaction.setReceiverSignatureRequired(opts.receiverSignatureRequired);
+    }
+
+    return this.serializeTransaction(transaction, creatorAccount);
+  }
+
+  /**
+   * Build an account update transaction
+   * @param accountId - Account to update
+   * @param memo - New account memo
+   * @returns Base64 encoded transaction bytes
+   */
+  async buildAccountUpdate(accountId: string, memo: string): Promise<string> {
+    const transaction = new AccountUpdateTransaction()
+      .setAccountId(AccountId.fromString(accountId))
+      .setAccountMemo(memo);
+
+    return this.serializeTransaction(transaction, accountId);
+  }
+
+  /**
+   * Build a batch transaction with multiple inner transactions
+   * @param innerTransactions - Array of transaction descriptors
+   * @param payerAccount - Account paying for the batch transaction
+   * @returns Base64 encoded batch transaction bytes
+   */
+  async buildBatchTransaction(
+    innerTransactions: Array<{
+      type: 'send-hbar' | 'send-token' | 'token-mint';
+      toAccount?: string;
+      amount: number;
+      tokenId?: string;
+    }>,
+    payerAccount: string,
+  ): Promise<string> {
+    const networkId = this.getNetworkId();
+
+    if (!networkId) {
+      throw new Error('No active wallet session. Please connect your wallet first.');
+    }
+
+    const client = this.createClientForNetwork(networkId);
+    const batchKey = PrivateKey.generateED25519();
+    const batchPublicKey = batchKey.publicKey;
+    const preparedTransactions = [];
+
+    for (const tx of innerTransactions) {
+      let transaction;
+
+      switch (tx.type) {
+        case 'send-hbar':
+          transaction = new TransferTransaction()
+            .addHbarTransfer(AccountId.fromString(payerAccount), new Hbar(-tx.amount))
+            .addHbarTransfer(AccountId.fromString(tx.toAccount!), new Hbar(tx.amount))
+            .setTransactionId(TransactionId.generate(AccountId.fromString(payerAccount)))
+            .setBatchKey(batchPublicKey);
+          break;
+
+        case 'send-token':
+          transaction = new TransferTransaction()
+            .addTokenTransfer(
+              TokenId.fromString(tx.tokenId!),
+              AccountId.fromString(payerAccount),
+              -tx.amount,
+            )
+            .addTokenTransfer(
+              TokenId.fromString(tx.tokenId!),
+              AccountId.fromString(tx.toAccount!),
+              tx.amount,
+            )
+            .setTransactionId(TransactionId.generate(AccountId.fromString(payerAccount)))
+            .setBatchKey(batchPublicKey);
+          break;
+
+        case 'token-mint':
+          transaction = new TokenMintTransaction()
+            .setTokenId(TokenId.fromString(tx.tokenId!))
+            .setAmount(tx.amount)
+            .setTransactionId(TransactionId.generate(AccountId.fromString(payerAccount)))
+            .setBatchKey(batchPublicKey);
+          break;
+
+        default:
+          continue;
+      }
+
+      if (transaction) {
+        const frozen = await transaction.freezeWith(client);
+        preparedTransactions.push(frozen);
+      }
+    }
+
+    const batchTransaction = new BatchTransaction().setTransactionId(
+      TransactionId.generate(AccountId.fromString(payerAccount)),
+    );
+
+    for (const tx of preparedTransactions) {
+      batchTransaction.addInnerTransaction(tx);
+    }
+
+    const frozenBatch = await batchTransaction.freezeWith(client);
+    const signedBatch = await frozenBatch.sign(batchKey);
+    const bytes = signedBatch.toBytes();
+
+    return this.uint8ArrayToBase64(bytes);
+  }
+
+  /**
+   * Build inner transactions for batch (unsigned, with batchKey set)
+   * @param account - Account executing the batch
+   * @param batchKey - Public key for batch transactions
+   * @param innerTransactions - Array of transaction descriptors
+   * @returns Array of base64 encoded unsigned inner transactions
+   */
+  async buildBatchInnerTransactions(
+    account: string,
+    batchKey: string,
+    innerTransactions: Array<BatchInnerTransaction>,
+  ): Promise<Array<{ payload: string; description: string }>> {
+    const accountId = AccountId.fromString(account);
+    const batchPublicKey = PublicKey.fromString(batchKey);
+
+    const networkId = this.getNetworkId();
+
+    if (!networkId) {
+      throw new Error('No active wallet session. Please connect your wallet first.');
+    }
+
+    const client = this.createClientForNetwork(networkId);
+    const results: Array<{ payload: string; description: string }> = [];
+
+    for (const tx of innerTransactions) {
+      let transaction: Transaction;
+      let description: string;
+
+      try {
+        switch (tx.type) {
+          case 'send-hbar':
+            transaction = new TransferTransaction()
+              .setTransactionId(TransactionId.generate(accountId))
+              .addHbarTransfer(accountId, Hbar.fromTinybars(-(tx.amount || 0)))
+              .addHbarTransfer(
+                AccountId.fromString(tx.toAccount!),
+                Hbar.fromTinybars(tx.amount || 0),
+              )
+              .setBatchKey(batchPublicKey);
+            description = `Send ${tx.amount} tinybar to ${tx.toAccount}`;
+            break;
+
+          case 'send-token':
+            transaction = new TransferTransaction()
+              .setTransactionId(TransactionId.generate(accountId))
+              .addTokenTransfer(TokenId.fromString(tx.tokenId!), accountId, -(tx.amount || 0))
+              .addTokenTransfer(
+                TokenId.fromString(tx.tokenId!),
+                AccountId.fromString(tx.toAccount!),
+                tx.amount || 0,
+              )
+              .setBatchKey(batchPublicKey);
+            description = `Send ${tx.amount} of token ${tx.tokenId} to ${tx.toAccount}`;
+            break;
+
+          case 'send-nft':
+            transaction = new TransferTransaction()
+              .setTransactionId(TransactionId.generate(accountId))
+              .addNftTransfer(
+                new NftId(TokenId.fromString(tx.tokenId!), tx.serialNumber || 1),
+                accountId,
+                AccountId.fromString(tx.toAccount!),
+              )
+              .setBatchKey(batchPublicKey);
+            description = `Send NFT ${tx.tokenId}#${tx.serialNumber} to ${tx.toAccount}`;
+            break;
+
+          case 'token-associate':
+            transaction = new TokenAssociateTransaction()
+              .setTransactionId(TransactionId.generate(accountId))
+              .setAccountId(accountId)
+              .setTokenIds([TokenId.fromString(tx.tokenId!)])
+              .setBatchKey(batchPublicKey);
+            description = `Associate token ${tx.tokenId}`;
+            break;
+
+          case 'token-dissociate':
+            transaction = new TokenDissociateTransaction()
+              .setTransactionId(TransactionId.generate(accountId))
+              .setAccountId(accountId)
+              .setTokenIds([TokenId.fromString(tx.tokenId!)])
+              .setBatchKey(batchPublicKey);
+            description = `Dissociate token ${tx.tokenId}`;
+            break;
+
+          case 'token-create': {
+            const createTx = new TokenCreateTransaction()
+              .setTransactionId(TransactionId.generate(accountId))
+              .setTokenName(tx.tokenName || 'Token')
+              .setTokenSymbol(tx.tokenSymbol || 'TKN')
+              .setDecimals(tx.decimals ?? 0)
+              .setInitialSupply(tx.initialSupply ?? 0)
+              .setTreasuryAccountId(accountId)
+              .setTokenType(
+                tx.decimals === 0 ? TokenType.NonFungibleUnique : TokenType.FungibleCommon,
+              )
+              .setSupplyType(
+                tx.supplyType === 'finite' ? TokenSupplyType.Finite : TokenSupplyType.Infinite,
+              )
+              .setBatchKey(batchPublicKey);
+            if (tx.maxSupply && tx.supplyType === 'finite') {
+              createTx.setMaxSupply(tx.maxSupply);
+            }
+            transaction = createTx;
+            description = `Create token ${tx.tokenName} (${tx.tokenSymbol})`;
+            break;
+          }
+
+          case 'token-mint': {
+            const mintTx = new TokenMintTransaction()
+              .setTransactionId(TransactionId.generate(accountId))
+              .setTokenId(TokenId.fromString(tx.tokenId!))
+              .setBatchKey(batchPublicKey);
+            // Handle NFT metadata (array) vs fungible amount
+            if (tx.metadata) {
+              const encoder = new TextEncoder();
+              if (Array.isArray(tx.metadata)) {
+                mintTx.setMetadata(tx.metadata.map((m) => encoder.encode(m)));
+              } else {
+                mintTx.setMetadata([encoder.encode(tx.metadata)]);
+              }
+            } else {
+              mintTx.setAmount(tx.amount || 1);
+            }
+            transaction = mintTx;
+            description = tx.metadata
+              ? `Mint NFT for token ${tx.tokenId}`
+              : `Mint ${tx.amount} of token ${tx.tokenId}`;
+            break;
+          }
+
+          case 'token-burn': {
+            const burnTx = new TokenBurnTransaction()
+              .setTransactionId(TransactionId.generate(accountId))
+              .setTokenId(TokenId.fromString(tx.tokenId!))
+              .setBatchKey(batchPublicKey);
+            if (tx.serialNumber) {
+              burnTx.setSerials([tx.serialNumber]);
+            } else {
+              burnTx.setAmount(tx.amount || 1);
+            }
+            transaction = burnTx;
+            description = tx.serialNumber
+              ? `Burn NFT ${tx.tokenId}#${tx.serialNumber}`
+              : `Burn ${tx.amount} of token ${tx.tokenId}`;
+            break;
+          }
+
+          case 'topic-create': {
+            const topicTx = new TopicCreateTransaction()
+              .setTransactionId(TransactionId.generate(accountId))
+              .setBatchKey(batchPublicKey);
+            if (tx.topicMemo) {
+              topicTx.setTopicMemo(tx.topicMemo);
+            }
+            transaction = topicTx;
+            description = tx.topicMemo ? `Create topic: ${tx.topicMemo}` : 'Create topic';
+            break;
+          }
+
+          case 'topic-message':
+            transaction = new TopicMessageSubmitTransaction()
+              .setTransactionId(TransactionId.generate(accountId))
+              .setTopicId(tx.topicId!)
+              .setMessage(tx.message || '')
+              .setBatchKey(batchPublicKey);
+            description = `Submit message to topic ${tx.topicId}`;
+            break;
+
+          case 'account-create': {
+            const acctTx = new AccountCreateTransaction()
+              .setTransactionId(TransactionId.generate(accountId))
+              .setInitialBalance(Hbar.fromTinybars(tx.initialBalance || 0))
+              .setBatchKey(batchPublicKey);
+            if (tx.maxAutoAssociations !== undefined) {
+              acctTx.setMaxAutomaticTokenAssociations(tx.maxAutoAssociations);
+            }
+            transaction = acctTx;
+            description = `Create account with ${tx.initialBalance} tinybar`;
+            break;
+          }
+
+          case 'account-update': {
+            const updateTx = new AccountUpdateTransaction()
+              .setTransactionId(TransactionId.generate(accountId))
+              .setAccountId(accountId)
+              .setBatchKey(batchPublicKey);
+            if (tx.memo !== undefined) {
+              updateTx.setAccountMemo(tx.memo);
+            }
+            if (tx.maxAutoAssociations !== undefined) {
+              updateTx.setMaxAutomaticTokenAssociations(tx.maxAutoAssociations);
+            }
+            transaction = updateTx;
+            description = `Update account ${account}`;
+            break;
+          }
+
+          default:
+            throw new Error(`Unknown transaction type: ${(tx as any).type}`);
+        }
+
+        this.logger.debug('Freezing transaction', { type: tx.type });
+        const frozen = await transaction.freezeWith(client);
+
+        this.logger.debug('Frozen transaction, serializing', { type: tx.type });
+        const bytes = frozen.toBytes();
+
+        this.logger.debug('Serialized transaction', { type: tx.type, length: bytes.length });
+
+        results.push({
+          payload: this.uint8ArrayToBase64(bytes),
+          description,
+        });
+
+        this.logger.debug('Successfully processed transaction', { type: tx.type });
+      } catch (error) {
+        this.logger.error('Failed to process transaction', { type: tx.type, error });
+        throw new Error(`Failed to build ${tx.type} transaction: ${error}`);
+      }
+    }
+
+    return results;
+  }
+
+  /**
+   * Serialize a transaction to base64 encoded bytes
+   * @param transaction
+   * @param payerAccountId
+   */
+  private async serializeTransaction(transaction: any, payerAccountId: string): Promise<string> {
+    const networkId = this.getNetworkId();
+
+    if (!networkId) {
+      throw new Error('No active wallet session. Please connect your wallet first.');
+    }
+
+    transaction.setTransactionId(TransactionId.generate(AccountId.fromString(payerAccountId)));
+    const client = this.createClientForNetwork(networkId);
+    const frozen = await transaction.freezeWith(client);
+    const bytes = frozen.toBytes();
+
+    return this.uint8ArrayToBase64(bytes);
+  }
+
+  /**
+   * Create a Hedera client for the specified network
+   * @param networkId
+   */
+  private createClientForNetwork(networkId: string): Client {
+    const network = networkId.split(':')[1]?.toLowerCase();
+
+    switch (network) {
+      case 'mainnet':
+        return Client.forMainnet();
+      case 'testnet':
+        return Client.forTestnet();
+      default:
+        this.logger.warn('Unknown Hedera network, defaulting to testnet', { network });
+        return Client.forTestnet();
+    }
+  }
+
+  /**
+   * Convert Uint8Array to base64 string
+   * @param bytes
+   */
+  private uint8ArrayToBase64(bytes: Uint8Array): string {
+    let binary = '';
+    for (let i = 0; i < bytes.length; i++) {
+      binary += String.fromCharCode(bytes[i]);
+    }
+    return btoa(binary);
+  }
+
+  /**
+   * Convert base64 string to Uint8Array
+   * @param base64
+   */
+  private 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;
+  }
+}