@hashgraphonline/standards-sdk 0.0.101 → 0.0.103

package/dist/es/standards-sdk.es21.js

@@ -1,15 +1,36 @@
 import Buffer from "./standards-sdk.es25.js";
-import { PublicKey, Timestamp } from "@hashgraph/sdk";
+import { PublicKey, Timestamp, AccountId } from "@hashgraph/sdk";
 import "./standards-sdk.es31.js";
+import { Logger } from "./standards-sdk.es15.js";
 import { proto } from "@hashgraph/proto";
 import axios from "./standards-sdk.es32.js";
 class HederaMirrorNode {
   constructor(network, logger) {
+    this.maxRetries = 3;
+    this.initialDelayMs = 1e3;
+    this.maxDelayMs = 3e4;
+    this.backoffFactor = 2;
     this.network = network;
     this.baseUrl = this.getMirrorNodeUrl();
-    this.logger = logger;
+    this.logger = logger || new Logger({
+      level: "debug",
+      module: "MirrorNode"
+    });
     this.isServerEnvironment = typeof window === "undefined";
   }
+  /**
+   * Configures the retry mechanism for API requests.
+   * @param config The retry configuration.
+   */
+  configureRetry(config) {
+    this.maxRetries = config.maxRetries ?? this.maxRetries;
+    this.initialDelayMs = config.initialDelayMs ?? this.initialDelayMs;
+    this.maxDelayMs = config.maxDelayMs ?? this.maxDelayMs;
+    this.backoffFactor = config.backoffFactor ?? this.backoffFactor;
+    this.logger.info(
+      `Retry configuration updated: maxRetries=${this.maxRetries}, initialDelayMs=${this.initialDelayMs}, maxDelayMs=${this.maxDelayMs}, backoffFactor=${this.backoffFactor}`
+    );
+  }
   getMirrorNodeUrl() {
     return this.network === "mainnet" ? "https://mainnet-public.mirrornode.hedera.com" : "https://testnet.mirrornode.hedera.com";
   }
@@ -46,29 +67,24 @@ class HederaMirrorNode {
    * @throws An error if the account ID is invalid or the memo cannot be retrieved.
    */
   async getAccountMemo(accountId) {
-    const maxRetries = 3;
-    for (let attempt = 0; attempt < maxRetries; attempt++) {
-      try {
-        const accountInfoUrl = `${this.baseUrl}/api/v1/accounts/${accountId}`;
-        const response = await axios.get(accountInfoUrl);
-        const accountInfo = response.data;
-        if (accountInfo && accountInfo.memo) {
-          return accountInfo.memo;
-        }
-        this.logger.error(`No memo found for account ${accountId}`);
-        if (attempt < maxRetries - 1) {
-          await new Promise((resolve) => setTimeout(resolve, 2e3));
-        }
-      } catch (e) {
-        const error = e;
-        const logMessage = `Error getting account memo (attempt ${attempt + 1}): ${error.message}`;
-        this.logger.error(logMessage);
-        if (attempt < maxRetries - 1) {
-          await new Promise((resolve) => setTimeout(resolve, 2e3));
-        }
+    this.logger.info(`Getting account memo for account ID: ${accountId}`);
+    const accountInfoUrl = `${this.baseUrl}/api/v1/accounts/${accountId}`;
+    try {
+      const accountInfo = await this._requestWithRetry(
+        accountInfoUrl
+      );
+      if (accountInfo?.memo) {
+        return accountInfo.memo;
       }
+      this.logger.warn(`No memo found for account ${accountId}`);
+      return null;
+    } catch (e) {
+      const error = e;
+      this.logger.error(
+        `Failed to get account memo for ${accountId} after retries: ${error.message}`
+      );
+      return null;
     }
-    return null;
   }
   /**
    * Retrieves topic information for a given topic ID from the mirror node.
@@ -79,11 +95,12 @@ class HederaMirrorNode {
   async getTopicInfo(topicId) {
     try {
       const topicInfoUrl = `${this.baseUrl}/api/v1/topics/${topicId}`;
-      const response = await axios.get(topicInfoUrl);
-      return response.data;
+      this.logger.debug(`Fetching topic info from ${topicInfoUrl}`);
+      const data = await this._requestWithRetry(topicInfoUrl);
+      return data;
     } catch (e) {
       const error = e;
-      const logMessage = `Error retrieving topic information: ${error.message}`;
+      const logMessage = `Error retrieving topic information for ${topicId} after retries: ${error.message}`;
       this.logger.error(logMessage);
       throw new Error(logMessage);
     }
@@ -114,10 +131,9 @@ class HederaMirrorNode {
   async getHBARPrice(date) {
     try {
       const timestamp = Timestamp.fromDate(date).toString();
-      const request = await fetch(
-        `https://mainnet-public.mirrornode.hedera.com/api/v1/network/exchangerate?timestamp=${timestamp}`
-      );
-      const response = await request.json();
+      const url = `https://mainnet-public.mirrornode.hedera.com/api/v1/network/exchangerate?timestamp=${timestamp}`;
+      this.logger.debug(`Fetching HBAR price from ${url}`);
+      const response = await this._fetchWithRetry(url);
       const usdPrice = Number(response?.current_rate?.cent_equivalent) / Number(response?.current_rate?.hbar_equivalent) / 100;
       return usdPrice;
     } catch (e) {
@@ -137,10 +153,12 @@ class HederaMirrorNode {
     this.logger.debug(`Fetching token info for ${tokenId}`);
     try {
       const tokenInfoUrl = `${this.baseUrl}/api/v1/tokens/${tokenId}`;
-      const response = await axios.get(tokenInfoUrl);
-      if (response.data) {
-        this.logger.trace(`Token info found for ${tokenId}:`, response.data);
-        return response.data;
+      const data = await this._requestWithRetry(
+        tokenInfoUrl
+      );
+      if (data) {
+        this.logger.trace(`Token info found for ${tokenId}:`, data);
+        return data;
       }
       this.logger.warn(`No token info found for ${tokenId}`);
       return null;
@@ -163,8 +181,9 @@ class HederaMirrorNode {
     const messages = [];
     while (nextUrl) {
       try {
-        const response = await axios.get(nextUrl);
-        const data = response.data;
+        const data = await this._requestWithRetry(
+          nextUrl
+        );
         if (data.messages && data.messages.length > 0) {
           for (const message of data.messages) {
             try {
@@ -197,7 +216,7 @@ class HederaMirrorNode {
               } catch (error) {
                 const logMessage = `Invalid JSON message content: ${messageContent}`;
                 this.logger.error(logMessage);
-                return;
+                continue;
               }
               messageJson.sequence_number = message.sequence_number;
               messages.push({
@@ -215,7 +234,7 @@ class HederaMirrorNode {
         nextUrl = data.links?.next ? `${this.baseUrl}${data.links.next}` : "";
       } catch (e) {
         const error = e;
-        const logMessage = `Error querying topic messages: ${error.message} on ${topicId}`;
+        const logMessage = `Error querying topic messages for topic ${topicId} (URL: ${nextUrl}) after retries: ${error.message}`;
         this.logger.error(logMessage);
         throw new Error(logMessage);
       }
@@ -231,16 +250,19 @@ class HederaMirrorNode {
   async requestAccount(accountId) {
     try {
       const accountInfoUrl = `${this.baseUrl}/api/v1/accounts/${accountId}`;
-      const response = await axios.get(accountInfoUrl);
-      if (!response.data) {
+      this.logger.debug(`Requesting account info from ${accountInfoUrl}`);
+      const data = await this._requestWithRetry(
+        accountInfoUrl
+      );
+      if (!data) {
         throw new Error(
-          `Failed to make request to mirror node for account: ${accountId}`
+          `No data received from mirror node for account: ${accountId}`
         );
       }
-      return response.data;
+      return data;
     } catch (e) {
       const error = e;
-      const logMessage = `Failed to fetch account: ${error.message}`;
+      const logMessage = `Failed to fetch account ${accountId} after retries: ${error.message}`;
       this.logger.error(logMessage);
       throw new Error(logMessage);
     }
@@ -344,13 +366,18 @@ class HederaMirrorNode {
         `Getting information for scheduled transaction ${scheduleId}`
       );
       const url = `${this.baseUrl}/api/v1/schedules/${scheduleId}`;
-      const response = await axios.get(url);
-      if (response.data) {
-        return response.data;
+      const data = await this._requestWithRetry(url);
+      if (data) {
+        return data;
       }
+      this.logger.warn(
+        `No schedule info found for ${scheduleId} after retries.`
+      );
       return null;
     } catch (error) {
-      this.logger.error(`Error fetching schedule info: ${error.message}`);
+      this.logger.error(
+        `Error fetching schedule info for ${scheduleId} after retries: ${error.message}`
+      );
       return null;
     }
   }
@@ -380,6 +407,440 @@ class HederaMirrorNode {
       throw error;
     }
   }
+  /**
+   * Retrieves details for a given transaction ID or hash from the mirror node.
+   * @param transactionIdOrHash The ID or hash of the transaction.
+   * @returns A promise that resolves to the transaction details.
+   * @throws An error if the transaction ID/hash is invalid or details cannot be retrieved.
+   */
+  async getTransaction(transactionIdOrHash) {
+    this.logger.info(
+      `Getting transaction details for ID/hash: ${transactionIdOrHash}`
+    );
+    const endpoint = transactionIdOrHash.includes("-") ? `transactions/${transactionIdOrHash}` : `transactions/${transactionIdOrHash}`;
+    const transactionDetailsUrl = `${this.baseUrl}/api/v1/${endpoint}`;
+    try {
+      const response = await this._requestWithRetry(transactionDetailsUrl);
+      if (response?.transactions?.length > 0) {
+        this.logger.trace(
+          `Transaction details found for ${transactionIdOrHash}:`,
+          response.transactions[0]
+        );
+        return response.transactions[0];
+      }
+      this.logger.warn(
+        `No transaction details found for ${transactionIdOrHash} or unexpected response structure.`
+      );
+      return null;
+    } catch (e) {
+      const error = e;
+      this.logger.error(
+        `Failed to get transaction details for ${transactionIdOrHash} after retries: ${error.message}`
+      );
+      return null;
+    }
+  }
+  /**
+   * Private helper to make GET requests with retry logic using Axios.
+   */
+  async _requestWithRetry(url, axiosConfig) {
+    let attempt = 0;
+    let delay = this.initialDelayMs;
+    while (attempt < this.maxRetries) {
+      try {
+        const response = await axios.get(url, axiosConfig);
+        return response.data;
+      } catch (error) {
+        attempt++;
+        const isLastAttempt = attempt >= this.maxRetries;
+        const statusCode = error.response?.status;
+        if (statusCode && statusCode >= 400 && statusCode < 500 && statusCode !== 429) {
+          this.logger.error(
+            `Client error for ${url} (status ${statusCode}): ${error.message}. Not retrying.`
+          );
+          throw error;
+        }
+        if (isLastAttempt) {
+          this.logger.error(
+            `Max retries (${this.maxRetries}) reached for ${url}. Last error: ${error.message}`
+          );
+          throw error;
+        }
+        this.logger.warn(
+          `Attempt ${attempt}/${this.maxRetries} failed for ${url}: ${error.message}. Retrying in ${delay}ms...`
+        );
+        await new Promise((resolve) => setTimeout(resolve, delay));
+        delay = Math.min(delay * this.backoffFactor, this.maxDelayMs);
+      }
+    }
+    throw new Error(
+      `Failed to fetch data from ${url} after ${this.maxRetries} attempts.`
+    );
+  }
+  /**
+   * Private helper to make fetch requests with retry logic.
+   */
+  async _fetchWithRetry(url, fetchOptions) {
+    let attempt = 0;
+    let delay = this.initialDelayMs;
+    while (attempt < this.maxRetries) {
+      try {
+        const request = await fetch(url, fetchOptions);
+        if (!request.ok) {
+          if (request.status >= 400 && request.status < 500 && request.status !== 429) {
+            this.logger.error(
+              `Client error for ${url} (status ${request.status}): ${request.statusText}. Not retrying.`
+            );
+            throw new Error(
+              `Fetch failed with status ${request.status}: ${request.statusText} for URL: ${url}`
+            );
+          }
+          throw new Error(
+            `Fetch failed with status ${request.status}: ${request.statusText} for URL: ${url}`
+          );
+        }
+        const response = await request.json();
+        return response;
+      } catch (error) {
+        attempt++;
+        if (attempt >= this.maxRetries) {
+          this.logger.error(
+            `Max retries (${this.maxRetries}) reached for ${url}. Last error: ${error.message}`
+          );
+          throw error;
+        }
+        this.logger.warn(
+          `Attempt ${attempt}/${this.maxRetries} failed for ${url}: ${error.message}. Retrying in ${delay}ms...`
+        );
+        await new Promise((resolve) => setTimeout(resolve, delay));
+        delay = Math.min(delay * this.backoffFactor, this.maxDelayMs);
+      }
+    }
+    throw new Error(
+      `Failed to fetch data from ${url} after ${this.maxRetries} attempts.`
+    );
+  }
+  /**
+   * Retrieves the numerical balance (in HBAR) for a given account ID.
+   * @param accountId The ID of the account.
+   * @returns A promise that resolves to the HBAR balance or null if an error occurs.
+   */
+  async getAccountBalanceNumerical(accountId) {
+    this.logger.info(`Getting numerical balance for account ${accountId}`);
+    try {
+      const accountInfo = await this.requestAccount(accountId);
+      if (accountInfo && accountInfo.balance) {
+        const hbarBalance = accountInfo.balance.balance / 1e8;
+        return hbarBalance;
+      }
+      this.logger.warn(
+        `Could not retrieve balance for account ${accountId} from account info.`
+      );
+      return null;
+    } catch (error) {
+      this.logger.error(
+        `Error fetching numerical balance for account ${accountId}: ${error.message}`
+      );
+      return null;
+    }
+  }
+  /**
+   * Retrieves messages for a given topic ID with optional filters.
+   * @param topicId The ID of the topic.
+   * @param sequenceNumber Filter by sequence number (e.g., "gt:10", "lte:20").
+   * @param startTime Filter by consensus timestamp (e.g., "gt:1629400000.000000000").
+   * @param endTime Filter by consensus timestamp (e.g., "lt:1629500000.000000000").
+   * @param limit The maximum number of messages to return.
+   * @returns A promise that resolves to an array of HCSMessages or null.
+   */
+  async getTopicMessagesByFilter(topicId, options) {
+    this.logger.trace(
+      `Querying messages for topic ${topicId} with filters: ${JSON.stringify(
+        options
+      )}`
+    );
+    let nextUrl = `${this.baseUrl}/api/v1/topics/${topicId}/messages`;
+    const params = new URLSearchParams();
+    if (options?.limit) {
+      params.append("limit", options.limit.toString());
+    }
+    if (options?.sequenceNumber) {
+      params.append("sequencenumber", options.sequenceNumber);
+    }
+    if (options?.startTime) {
+      params.append("timestamp", `gte:${options.startTime}`);
+    }
+    if (options?.endTime) {
+      params.append("timestamp", `lt:${options.endTime}`);
+    }
+    if (options?.order) {
+      params.append("order", options.order);
+    }
+    const queryString = params.toString();
+    if (queryString) {
+      nextUrl += `?${queryString}`;
+    }
+    const messages = [];
+    let pagesFetched = 0;
+    const maxPages = 10;
+    try {
+      while (nextUrl && pagesFetched < maxPages) {
+        pagesFetched++;
+        const data = await this._requestWithRetry(
+          nextUrl
+        );
+        if (data.messages && data.messages.length > 0) {
+          for (const message of data.messages) {
+            try {
+              if (!message.message) {
+                continue;
+              }
+              let messageContent;
+              if (this.isServerEnvironment) {
+                messageContent = Buffer.from(
+                  message.message,
+                  "base64"
+                ).toString("utf-8");
+              } else {
+                messageContent = new TextDecoder().decode(
+                  Uint8Array.from(atob(message.message), (c) => c.charCodeAt(0))
+                );
+              }
+              let messageJson = {};
+              try {
+                messageJson = JSON.parse(messageContent);
+              } catch (parseError) {
+                this.logger.debug(
+                  `Message content is not valid JSON, using raw: ${messageContent}`
+                );
+                messageJson = { raw_content: messageContent };
+              }
+              const parsedContent = messageJson;
+              const hcsMsg = {
+                ...parsedContent,
+                consensus_timestamp: message.consensus_timestamp,
+                sequence_number: message.sequence_number,
+                payer_account_id: message.payer_account_id,
+                topic_id: message.topic_id,
+                running_hash: message.running_hash,
+                running_hash_version: message.running_hash_version,
+                chunk_info: message.chunk_info,
+                created: new Date(
+                  Number(message.consensus_timestamp.split(".")[0]) * 1e3 + Number(message.consensus_timestamp.split(".")[1] || 0) / 1e6
+                ),
+                payer: message.payer_account_id
+              };
+              messages.push(hcsMsg);
+            } catch (error) {
+              this.logger.error(
+                `Error processing individual message: ${error.message}`
+              );
+            }
+          }
+        }
+        if (options?.limit && messages.length >= options.limit) break;
+        nextUrl = data.links?.next ? `${this.baseUrl}${data.links.next}` : "";
+      }
+      return messages;
+    } catch (e) {
+      const error = e;
+      this.logger.error(
+        `Error querying filtered topic messages for ${topicId}: ${error.message}`
+      );
+      return null;
+    }
+  }
+  /**
+   * Retrieves token balances for a given account ID.
+   * @param accountId The ID of the account.
+   * @param limit The maximum number of tokens to return.
+   * @returns A promise that resolves to an array of AccountTokenBalance or null.
+   */
+  async getAccountTokens(accountId, limit = 100) {
+    this.logger.info(`Getting tokens for account ${accountId}`);
+    let allTokens = [];
+    let url = `${this.baseUrl}/api/v1/accounts/${accountId}/tokens?limit=${limit}`;
+    try {
+      for (let i = 0; i < 10 && url; i++) {
+        const response = await this._requestWithRetry(
+          url
+        );
+        if (response && response.tokens) {
+          allTokens = allTokens.concat(response.tokens);
+        }
+        url = response.links?.next ? `${this.baseUrl}${response.links.next}` : "";
+        if (!url || limit && allTokens.length >= limit) {
+          if (limit && allTokens.length > limit) {
+            allTokens = allTokens.slice(0, limit);
+          }
+          break;
+        }
+      }
+      return allTokens;
+    } catch (error) {
+      this.logger.error(
+        `Error fetching tokens for account ${accountId}: ${error.message}`
+      );
+      return null;
+    }
+  }
+  /**
+   * Retrieves transaction details by consensus timestamp.
+   * @param timestamp The consensus timestamp of the transaction (e.g., "1629400000.000000000").
+   * @returns A promise that resolves to the transaction details or null.
+   */
+  async getTransactionByTimestamp(timestamp) {
+    this.logger.info(`Getting transaction by timestamp: ${timestamp}`);
+    const url = `${this.baseUrl}/api/v1/transactions?timestamp=${timestamp}&limit=1`;
+    try {
+      const response = await this._requestWithRetry(url);
+      if (response && response.transactions && response.transactions.length > 0) {
+        const specificTransactionId = response.transactions[0].transaction_id;
+        this.logger.debug(
+          `Transaction found by timestamp, fetching full details for ID: ${specificTransactionId}`
+        );
+        return this.getTransaction(specificTransactionId);
+      }
+      this.logger.warn(`No transaction found for timestamp: ${timestamp}`);
+      return null;
+    } catch (error) {
+      this.logger.error(
+        `Error fetching transaction by timestamp ${timestamp}: ${error.message}`
+      );
+      return null;
+    }
+  }
+  /**
+   * Retrieves NFTs for a given account ID, optionally filtered by token ID.
+   * @param accountId The ID of the account.
+   * @param tokenId Optional ID of the token to filter NFTs by.
+   * @param limit The maximum number of NFTs to return per page (API has its own max).
+   * @returns A promise that resolves to an array of NftDetail or null.
+   */
+  async getAccountNfts(accountId, tokenId, limit = 100) {
+    this.logger.info(
+      `Getting NFTs for account ${accountId}${tokenId ? ` for token ${tokenId}` : ""}`
+    );
+    let allNfts = [];
+    let url = `${this.baseUrl}/api/v1/accounts/${accountId}/nfts?limit=${limit}`;
+    if (tokenId) {
+      url += `&token.id=${tokenId}`;
+    }
+    try {
+      for (let i = 0; i < 10 && url; i++) {
+        const response = await this._requestWithRetry(url);
+        if (response && response.nfts) {
+          const nftsWithUri = response.nfts.map((nft) => {
+            let tokenUri = void 0;
+            if (nft.metadata) {
+              try {
+                if (this.isServerEnvironment) {
+                  tokenUri = Buffer.from(nft.metadata, "base64").toString(
+                    "utf-8"
+                  );
+                } else {
+                  tokenUri = new TextDecoder().decode(
+                    Uint8Array.from(atob(nft.metadata), (c) => c.charCodeAt(0))
+                  );
+                }
+              } catch (e) {
+                this.logger.warn(
+                  `Failed to decode metadata for NFT ${nft.token_id} SN ${nft.serial_number}: ${e.message}`
+                );
+              }
+            }
+            return { ...nft, token_uri: tokenUri };
+          });
+          allNfts = allNfts.concat(nftsWithUri);
+        }
+        url = response.links?.next ? `${this.baseUrl}${response.links.next}` : "";
+        if (!url) break;
+      }
+      return allNfts;
+    } catch (error) {
+      this.logger.error(
+        `Error fetching NFTs for account ${accountId}: ${error.message}`
+      );
+      return null;
+    }
+  }
+  /**
+   * Validates NFT ownership by checking if a specific serial number of a token ID exists for an account.
+   * @param accountId The ID of the account.
+   * @param tokenId The ID of the NFT's token.
+   * @param serialNumber The serial number of the NFT.
+   * @returns A promise that resolves to the NftDetail if owned, or null otherwise.
+   */
+  async validateNFTOwnership(accountId, tokenId, serialNumber) {
+    this.logger.info(
+      `Validating ownership of NFT ${tokenId} SN ${serialNumber} for account ${accountId}`
+    );
+    try {
+      const nfts = await this.getAccountNfts(accountId, tokenId);
+      if (nfts) {
+        const foundNft = nfts.find(
+          (nft) => nft.token_id === tokenId && nft.serial_number === serialNumber
+        );
+        return foundNft || null;
+      }
+      return null;
+    } catch (error) {
+      this.logger.error(`Error validating NFT ownership: ${error.message}`);
+      return null;
+    }
+  }
+  /**
+   * Performs a read-only query against a smart contract (eth_call like).
+   * @param contractIdOrAddress The contract ID (e.g., "0.0.123") or EVM address (e.g., "0x...").
+   * @param functionSelector The function selector and encoded parameters (e.g., "0xabcdef12...").
+   * @param payerAccountId The account ID of the payer (not strictly payer for read-only, but often required as 'from').
+   * @param estimate Whether this is an estimate call. Mirror node might not support this directly in /contracts/call for true estimation.
+   * @param block Block parameter, e.g., "latest", "pending", or block number.
+   * @param value The value in tinybars to send with the call (for payable view/pure functions, usually 0).
+   * @returns A promise that resolves to the contract call query response or null.
+   */
+  async readSmartContractQuery(contractIdOrAddress, functionSelector, payerAccountId, options) {
+    this.logger.info(
+      `Reading smart contract ${contractIdOrAddress} with selector ${functionSelector}`
+    );
+    const url = `${this.baseUrl}/api/v1/contracts/call`;
+    const toAddress = contractIdOrAddress.startsWith("0x") ? contractIdOrAddress : `0x${AccountId.fromString(contractIdOrAddress).toSolidityAddress()}`;
+    const fromAddress = payerAccountId.startsWith("0x") ? payerAccountId : `0x${AccountId.fromString(payerAccountId).toSolidityAddress()}`;
+    const body = {
+      block: options?.block || "latest",
+      data: functionSelector,
+      estimate: options?.estimate || false,
+      from: fromAddress,
+      to: toAddress,
+      gas: options?.gas,
+      gasPrice: options?.gasPrice,
+      value: options?.value || 0
+    };
+    Object.keys(body).forEach((key) => {
+      const K = key;
+      if (body[K] === void 0) {
+        delete body[K];
+      }
+    });
+    try {
+      const response = await this._fetchWithRetry(
+        url,
+        {
+          method: "POST",
+          body: JSON.stringify(body),
+          headers: {
+            "Content-Type": "application/json"
+          }
+        }
+      );
+      return response;
+    } catch (error) {
+      this.logger.error(
+        `Error reading smart contract ${contractIdOrAddress}: ${error.message}`
+      );
+      return null;
+    }
+  }
 }
 export {
   HederaMirrorNode