@mentaproject/client 0.1.24 → 0.1.28

package/src/structures/Account.ts

@@ -1,8 +1,26 @@
-import { fetchByBlockRange, getBalance, getBlockNumber, getCode, getTransaction, getTransactionCount, sendTransaction, traceFilter } from "@mentaproject/core/actions";
-import type { Address, Hash, onBlockRangeCallback } from "@mentaproject/core/types";
+import {
+  fetchByBlockRange,
+  getBalance,
+  getBlockNumber,
+  getCode,
+  getTransaction,
+  getTransactionCount,
+  sendTransaction,
+  traceFilter,
+} from "@mentaproject/core/actions";
+import type {
+  Address,
+  Hash,
+  onBlockRangeCallback,
+} from "@mentaproject/core/types";
 import { Transaction } from "./Transaction";
 import { toHex } from "@mentaproject/core/utils";
-import { AccountData, FetchTransactionParams, GetTransactionsParams, JSONAccount } from "../types/Account";
+import {
+  AccountData,
+  FetchTransactionParams,
+  GetTransactionsParams,
+  JSONAccount,
+} from "../types/Account";
 import { getContractType } from "@mentaproject/contracts";
 import { toJSON } from "../utils/toJSON";
 import { PersistenceManager } from "../managers/PersistenceManager";
@@ -13,194 +31,221 @@ import { MentaClient } from "./MentaClient";
  * This class provides methods to query account information, send transactions, and manage account-related data.
  */
 export class Account implements AccountData {
-    /**
-     * The blockchain address of the account.
-     */
-    public address: Address;
-
-    private persistenceManager?: PersistenceManager;
-
-    /**
-     * Creates an instance of the Account class.
-     * @param client.rpc The CoreClient instance used for blockchain interactions.
-     * @param address The blockchain address of the account.
-     * @param persistenceManager An optional PersistenceManager instance for caching and data synchronization.
-     */
-    constructor(public client: MentaClient, data: AccountData, persistenceManager?: PersistenceManager) {
-        this.address = data.address;
-        this.persistenceManager = persistenceManager;
+  /**
+   * The blockchain address of the account.
+   */
+  public address: Address;
+
+  private persistenceManager?: PersistenceManager;
+
+  /**
+   * Creates an instance of the Account class.
+   * @param client.rpc The CoreClient instance used for blockchain interactions.
+   * @param address The blockchain address of the account.
+   * @param persistenceManager An optional PersistenceManager instance for caching and data synchronization.
+   */
+  constructor(
+    public client: MentaClient,
+    data: AccountData,
+    persistenceManager?: PersistenceManager,
+  ) {
+    this.address = data.address;
+    this.persistenceManager = persistenceManager;
+  }
+
+  /**
+   * Checks if the account's address belongs to a smart contract.
+   * @description This method queries the blockchain for the code associated with the account's address.
+   * If code is found, it indicates that the account is a contract.
+   * @returns {Promise<boolean>} A promise that resolves to `true` if the account is a contract, `false` otherwise.
+   */
+  async isContract(): Promise<boolean> {
+    const code = await getCode(this.client.rpc, { address: this.address });
+
+    if (!code || code === "0x") return false;
+    return true;
+  }
+
+  /**
+   * Retrieves the type of the contract if the account is a smart contract.
+   * @description This method first checks if the account is a contract using `isContract()`.
+   * If it is a contract, it then attempts to determine and return its type.
+   * @returns {Promise<any>} A promise that resolves to the contract type (e.g., 'ERC20', 'ERC721') or `undefined` if the account is not a contract or its type cannot be determined.
+   */
+  async contractType(): Promise<any> {
+    const isContract = await this.isContract();
+    if (!isContract) return undefined;
+
+    return await getContractType(this.client.rpc, this.address);
+  }
+
+  /**
+   * Sends a specified amount of native cryptocurrency (ETH) to this account.
+   * @description This method constructs and sends a transaction to transfer ETH to the account's address.
+   * @param {bigint} amount The amount of ETH to send, specified in wei (the smallest denomination of Ether).
+   * @returns {Promise<Transaction>} A promise that resolves to a `Transaction` object representing the sent transaction.
+   */
+  async sendETH(amount: bigint): Promise<Transaction> {
+    const hash = await sendTransaction(this.client.rpc, {
+      calls: [
+        {
+          to: this.address,
+          value: amount,
+        },
+      ],
+    });
+
+    const data = await getTransaction(this.client.rpc, { hash });
+    return new Transaction(this.client, data);
+  }
+
+  /**
+   * Retrieves the current native cryptocurrency (ETH) balance of the account.
+   * @description This method queries the blockchain to get the balance associated with the account's address.
+   * @returns {Promise<bigint>} A promise that resolves to the ETH balance of the account, in wei.
+   */
+  async ETHBalance(): Promise<bigint> {
+    return await getBalance(this.client.rpc, {
+      address: this.address,
+    });
+  }
+
+  /**
+   * Retrieves the transaction count (nonce) for the account.
+   * @description The transaction count represents the number of transactions sent from this account,
+   * which is also used as the nonce for new transactions to prevent replay attacks.
+   * @returns {Promise<number>} A promise that resolves to the transaction count of the account.
+   */
+  async transactionCount(): Promise<number> {
+    return await getTransactionCount(this.client.rpc, {
+      address: this.address,
+    });
+  }
+
+  /**
+   * Retrieves all transactions involving this account.
+   * @description If a `PersistenceManager` is configured, this method will first attempt to retrieve transactions from the local cache.
+   * If not found in cache or if no `PersistenceManager` is configured, it will fetch transactions directly from the remote RPC.
+   * @param {GetTransactionsOptions} [options] - Optional parameters for filtering, pagination, and sorting the transactions.
+   * @param {number} [options.startBlock] - The starting block number (inclusive) from which to retrieve transactions.
+   * @param {number} [options.endBlock] - The ending block number (inclusive) up to which to retrieve transactions.
+   * @param {number} [options.page] - The page number for paginated results.
+   * @param {number} [options.offset] - The number of items to skip from the beginning of the result set.
+   * @param {'asc' | 'desc'} [options.sort] - The sorting order for transactions based on block number ('asc' for ascending, 'desc' for descending).
+   * @param {boolean} [forceFetch=false] - Forces the method to fetch transactions from the remote source even if they are already cached. (mostly used internally)
+   * @returns {Promise<Transaction[]>} A promise that resolves to an array of transactions.
+   */
+  async transactions(
+    params: GetTransactionsParams,
+    forceFetch = false,
+  ): Promise<Transaction[]> {
+    if (!this.persistenceManager || forceFetch) {
+      // If persistence is not configured, fetch directly from remote
+      const hashes = await this._fetchTransactions(params);
+      const transactions = await Promise.all(
+        hashes.map((hash) => this.client.transactions.get({ hash })),
+      );
+
+      return transactions;
     }
 
-    /**
-     * Checks if the account's address belongs to a smart contract.
-     * @description This method queries the blockchain for the code associated with the account's address.
-     * If code is found, it indicates that the account is a contract.
-     * @returns {Promise<boolean>} A promise that resolves to `true` if the account is a contract, `false` otherwise.
-     */
-    async isContract(): Promise<boolean> {
-        const code = await getCode(this.client.rpc, { address: this.address });
-
-        if (!code || code === "0x") return false;
-        return true;
+    const jsons = await this.persistenceManager.getTransactions(
+      this.address,
+      params,
+    );
+    return jsons.map((j) => this.client.transactions.parse(j));
+  }
+
+  /**
+   * Synchronizes the account's transactions with the remote data source using the configured `PersistenceManager`.
+   * @description This method initiates a synchronization process to ensure that the local cache of transactions
+   * for this account is up-to-date with the blockchain.
+   * @param {number} [limit] The maximum number of transactions to synchronize.
+   * @returns {Promise<void>} A promise that resolves when the synchronization process is complete.
+   * @throws {Error} If the persistence module is not configured.
+   */
+  async syncTransactions(limit: number = 1000): Promise<void> {
+    if (!this.persistenceManager)
+      throw new Error("The persistence module is not configured.");
+    await this.persistenceManager.syncTransactions(this, limit);
+  }
+
+  /**
+   * Retrieves transactions involving a specific token. (not implemented yet)
+   * @description This method queries the persistence adapter to retrieve transactions involving a specific token.
+   * @param {Address} tokenAddress The address of the token.
+   * @returns {Promise<any>} A promise that resolves to an array of transactions involving the token.
+   * @throws {Error} If the persistence module is not configured.
+   */
+  async tokenTransactions(tokenAddress: Address): Promise<any> {
+    if (!this.persistenceManager)
+      throw new Error("The persistence module is not configured.");
+
+    return {};
+  }
+
+  /**
+   * Converts the Account instance into a JSON-serializable representation.
+   * @description This method leverages a utility function to convert the `Account` object,
+   * including its asynchronous properties (like `isContract`, `ETHBalance`), into a plain JSON object.
+   * @param {number} [depth=1] The depth to which nested objects should be converted. A depth of 1 means only direct properties are included.
+   * @returns {Promise<object>} A promise that resolves to the JSON representation of the account.
+   */
+  async toJSON<D extends number = 1>(depth: D): Promise<JSONAccount<D>> {
+    return await toJSON({
+      obj: {
+        address: this.address,
+        isContract: this.isContract.bind(this),
+        contractType: this.contractType.bind(this),
+        ETHBalance: this.ETHBalance.bind(this),
+        transactionCount: this.transactionCount.bind(this),
+      },
+      depth,
+    });
+  }
+
+  /**
+   * Fetches transactions from the account using a block range exploration with trace_filter calls.
+   *
+   *  @param params - The parameters for the block range exploration.
+   *  @returns A Promise that resolves to an array of transaction hashes.
+   */
+  protected async _fetchTransactions({
+    fromBlock,
+    toBlock,
+    limit = 50,
+  }: FetchTransactionParams): Promise<Hash[]> {
+    const lastBlock = await getBlockNumber(this.client.rpc);
+
+    const onBlockRange: onBlockRangeCallback = async (
+      { fromBlock, toBlock },
+      stop,
+    ) => {
+      const outgoing = await traceFilter(this.client.rpc, {
+        fromBlock: toHex(fromBlock),
+        toBlock: toHex(toBlock),
+        fromAddress: this.address,
+      });
+
+      const incoming = await traceFilter(this.client.rpc, {
+        fromBlock: toHex(fromBlock),
+        toBlock: toHex(toBlock),
+        toAddress: this.address,
+      });
+
+      const traces = outgoing
+        .concat(incoming)
+        .sort((a, b) => a.blockNumber - b.blockNumber);
+
+      return traces.map((t) => t.transactionHash as Hash);
     };
 
-    /**
-     * Retrieves the type of the contract if the account is a smart contract.
-     * @description This method first checks if the account is a contract using `isContract()`.
-     * If it is a contract, it then attempts to determine and return its type.
-     * @returns {Promise<any>} A promise that resolves to the contract type (e.g., 'ERC20', 'ERC721') or `undefined` if the account is not a contract or its type cannot be determined.
-     */
-    async contractType(): Promise<any> {
-        const isContract = await this.isContract();
-        if (!isContract) return undefined;
-
-        return await getContractType(this.client.rpc, this.address);
-    };
-
-    /**
-     * Sends a specified amount of native cryptocurrency (ETH) to this account.
-     * @description This method constructs and sends a transaction to transfer ETH to the account's address.
-     * @param {bigint} amount The amount of ETH to send, specified in wei (the smallest denomination of Ether).
-     * @returns {Promise<Transaction>} A promise that resolves to a `Transaction` object representing the sent transaction.
-     */
-    async sendETH(amount: bigint): Promise<Transaction> {
-        const hash = await sendTransaction(this.client.rpc, {
-            calls: [{
-                to: this.address,
-                value: amount,
-            }]
-        });
-
-        const data = await getTransaction(this.client.rpc, { hash });
-        return new Transaction(this.client, data);
-    };
-
-    /**
-     * Retrieves the current native cryptocurrency (ETH) balance of the account.
-     * @description This method queries the blockchain to get the balance associated with the account's address.
-     * @returns {Promise<bigint>} A promise that resolves to the ETH balance of the account, in wei.
-     */
-    async ETHBalance(): Promise<bigint> {
-        return await getBalance(this.client.rpc, {
-            address: this.address,
-        });
-    };
-
-    /**
-     * Retrieves the transaction count (nonce) for the account.
-     * @description The transaction count represents the number of transactions sent from this account,
-     * which is also used as the nonce for new transactions to prevent replay attacks.
-     * @returns {Promise<number>} A promise that resolves to the transaction count of the account.
-     */
-    async transactionCount(): Promise<number> {
-        return await getTransactionCount(this.client.rpc, { address: this.address });
-    }
-
-    /**
-     * Retrieves all transactions involving this account.
-     * @description If a `PersistenceManager` is configured, this method will first attempt to retrieve transactions from the local cache.
-     * If not found in cache or if no `PersistenceManager` is configured, it will fetch transactions directly from the remote RPC.
-     * @param {GetTransactionsOptions} [options] - Optional parameters for filtering, pagination, and sorting the transactions.
-     * @param {number} [options.startBlock] - The starting block number (inclusive) from which to retrieve transactions.
-     * @param {number} [options.endBlock] - The ending block number (inclusive) up to which to retrieve transactions.
-     * @param {number} [options.page] - The page number for paginated results.
-     * @param {number} [options.offset] - The number of items to skip from the beginning of the result set.
-     * @param {'asc' | 'desc'} [options.sort] - The sorting order for transactions based on block number ('asc' for ascending, 'desc' for descending).
-     * @param {boolean} [forceFetch=false] - Forces the method to fetch transactions from the remote source even if they are already cached. (mostly used internally)
-     * @returns {Promise<Transaction[]>} A promise that resolves to an array of transactions.
-     */
-    async transactions(params: GetTransactionsParams, forceFetch = false): Promise<Transaction[]> {
-        if (!this.persistenceManager || forceFetch) {
-            // If persistence is not configured, fetch directly from remote
-            const hashes = await this._fetchTransactions(params);
-            const transactions = await Promise.all(hashes.map(hash => this.client.transactions.get({ hash })));
-
-            return transactions;
-        }
-
-        const jsons = await this.persistenceManager.getTransactions(this.address, params);
-        return jsons.map(j => this.client.transactions.parse(j));
-    }
-
-    /**
-     * Synchronizes the account's transactions with the remote data source using the configured `PersistenceManager`.
-     * @description This method initiates a synchronization process to ensure that the local cache of transactions
-     * for this account is up-to-date with the blockchain.
-     * @param {number} [limit] The maximum number of transactions to synchronize.
-     * @returns {Promise<void>} A promise that resolves when the synchronization process is complete.
-     * @throws {Error} If the persistence module is not configured.
-     */
-    async syncTransactions(limit: number = 1000): Promise<void> {
-        if (!this.persistenceManager) throw new Error("The persistence module is not configured.");
-        await this.persistenceManager.syncTransactions(this, limit);
-    }
-
-    /**
-     * Retrieves transactions involving a specific token. (not implemented yet)
-     * @description This method queries the persistence adapter to retrieve transactions involving a specific token.
-     * @param {Address} tokenAddress The address of the token.
-     * @returns {Promise<any>} A promise that resolves to an array of transactions involving the token.
-     * @throws {Error} If the persistence module is not configured.
-     */
-    async tokenTransactions(tokenAddress: Address): Promise<any> {
-        if (!this.persistenceManager) throw new Error('The persistence module is not configured.');
-
-        return {};
-    }
-
-    /**
-     * Converts the Account instance into a JSON-serializable representation.
-     * @description This method leverages a utility function to convert the `Account` object,
-     * including its asynchronous properties (like `isContract`, `ETHBalance`), into a plain JSON object.
-     * @param {number} [depth=1] The depth to which nested objects should be converted. A depth of 1 means only direct properties are included.
-     * @returns {Promise<object>} A promise that resolves to the JSON representation of the account.
-     */
-    async toJSON<D extends number = 1>(depth: D): Promise<JSONAccount<D>> {
-        return await toJSON({
-            obj: {
-                address: this.address,
-                isContract: this.isContract.bind(this),
-                contractType: this.contractType.bind(this),
-                ETHBalance: this.ETHBalance.bind(this),
-                transactionCount: this.transactionCount.bind(this),
-            },
-            depth
-        });
-    }
-
-    /**
-     * Fetches transactions from the account using a block range exploration with trace_filter calls.
-     * 
-     *  @param params - The parameters for the block range exploration.
-     *  @returns A Promise that resolves to an array of transaction hashes.
-     */
-    protected async _fetchTransactions({ fromBlock, toBlock, limit = 50 }: FetchTransactionParams): Promise<Hash[]> {
-        const lastBlock = await getBlockNumber(this.client.rpc);
-
-        const onBlockRange: onBlockRangeCallback = async ({ fromBlock, toBlock }, stop) => {
-            const outgoing = await traceFilter(this.client.rpc, {
-                fromBlock: toHex(fromBlock),
-                toBlock: toHex(toBlock),
-                fromAddress: this.address
-            });
-
-            const incoming = await traceFilter(this.client.rpc, {
-                fromBlock: toHex(fromBlock),
-                toBlock: toHex(toBlock),
-                toAddress: this.address
-            });
-
-            const traces = outgoing.concat(incoming).sort((a, b) => a.blockNumber - b.blockNumber);
-
-            return traces.map(t => t.transactionHash as Hash)
-        };
-
-        return await fetchByBlockRange({
-            toBlock: BigInt(toBlock !== undefined ? toBlock : 0),
-            fromBlock: BigInt(fromBlock !== undefined ? fromBlock : lastBlock),
-            direction: "backward",
-            itemLimit: limit,
-            onBlockRange
-        });
-    }
-};
+    return await fetchByBlockRange({
+      toBlock: BigInt(toBlock !== undefined ? toBlock : 0),
+      fromBlock: BigInt(fromBlock !== undefined ? fromBlock : lastBlock),
+      direction: "backward",
+      itemLimit: limit,
+      onBlockRange,
+    });
+  }
+}