@mentaproject/client 0.1.23 → 0.1.25

package/src/managers/TransactionManager.ts

@@ -0,0 +1,92 @@
+/**
+ * @module TransactionManager
+ */
+import {  GetTransactionParameters, Transaction as RawTransaction, SendTransactionParameters } from "@mentaproject/core/types";
+import { Transaction } from "../structures/Transaction";
+import { getTransaction, sendTransaction } from "@mentaproject/core/actions";
+import { MentaClient } from "../structures";
+import { JSONTransaction } from "../types";
+import { parseBingints } from "../utils/bigint";
+
+/**
+ * Manages blockchain transaction-related operations, providing methods to retrieve and send transactions.
+ * @class
+ * @description This class provides an interface to interact with blockchain transactions,
+ * allowing for retrieval of transaction details and submission of new transactions
+ * to the network via an RPC client.
+ */
+export class TransactionManager {
+    /**
+     * Creates an instance of `TransactionManager`.
+     * @constructor
+     * @param {MentaClient} client - The instance of MentaClient used to interact with the blockchain.
+     */
+    constructor(public client: MentaClient) {};
+
+    /**
+     * Retrieves a transaction by its hash or block number and index.
+     * @description This method fetches detailed information about a specific transaction
+     * from the blockchain using the provided parameters.
+     * @param {GetTransactionParameters} params - The parameters for retrieving the transaction,
+     * typically including `hash` or `blockNumber` and `index`.
+     * @returns {Promise<Transaction>} A promise that resolves to a {@link Transaction} instance
+     * containing the retrieved transaction data.
+     * @example
+     * const txHash = '0x...'; // Replace with a valid transaction hash
+     * const transaction = await client.transactions.get({ hash: txHash });
+     * console.log(transaction);
+     */
+    async get(params: GetTransactionParameters): Promise<Transaction> {
+        const data = await getTransaction(this.client.rpc, params);
+        return new Transaction(this.client, data);
+    };
+
+    /**
+     * Parse a transaction object from a JSON converted transaction data object.
+     * 
+     * @param {J} data - The JSON converted transaction data object.
+     * @returns {Transaction} A Transaction instance representing the parsed transaction.
+     */
+    parse<J extends JSONTransaction<0>>(data: J): Transaction {
+        const parsed = parseBingints(data);
+
+        const rawData = {
+            ...parsed,
+            from: parsed.from.address,
+            to: parsed.to ? parsed.to.address : null,
+        };
+        
+        return new Transaction(this.client, rawData as RawTransaction);
+    };
+
+    /**
+     * Sends a transaction to the blockchain network.
+     * @description This method submits a new transaction to the blockchain. After the transaction
+     * is successfully sent, it retrieves and returns the full transaction details.
+     * @param {SendTransactionParameters} params - The parameters required to send the transaction,
+     * such as `to`, `value`, `data`, `gasLimit`, etc.
+     * @returns {Promise<Transaction>} A promise that resolves to a {@link Transaction} instance
+     * representing the sent transaction, including its hash and other details.
+     * @example
+     * import { MentaClient } from '@mentaproject/client';
+     * import { http } from '@mentaproject/core';
+     *
+     * // This example assumes you have an account with funds, which is available to the client.
+     * const client = new MentaClient({
+     *   chain: 'mainnet',
+     *   transport: http('http://rpcurlhere.com')
+     * });
+     *
+     * const transactionResult = await client.transactions.send({
+     *   to: '0xRecipientAddress...', // Replace with a valid recipient address
+     *   value: 1000000000000000000n, // 1 ETH in wei
+     * });
+     *
+     * console.log('Transaction sent with hash:', transactionResult.hash);
+     */
+    async send(params: SendTransactionParameters): Promise<Transaction> {
+        const hash = await sendTransaction(this.client.rpc, params);
+        
+        return await this.get({ hash });
+    };
+};

package/src/managers/index.ts

@@ -0,0 +1,4 @@
+export * from './AccountManager';
+export * from './BlockManager';
+export * from './ContractManager';
+export * from './TransactionManager';

package/src/structures/Account.ts

@@ -0,0 +1,251 @@
+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 { getContractType } from "@mentaproject/contracts";
+import { toJSON } from "../utils/toJSON";
+import { PersistenceManager } from "../managers/PersistenceManager";
+import { MentaClient } from "./MentaClient";
+
+/**
+ * Represents a blockchain account with functionalities to interact with the Menta blockchain.
+ * 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;
+  }
+
+  /**
+   * 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;
+    }
+
+    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,
+    });
+  }
+}

package/src/structures/Block.ts

@@ -0,0 +1,185 @@
+import { Block as RawBlock, Hash, Hex, Withdrawal } from "@mentaproject/core";
+
+import { Account } from "./Account";
+import { Transaction } from "./Transaction";
+import { JSONBlock } from "../types/Block";
+import { toJSON } from "../utils/toJSON";
+import { MentaClient } from "./MentaClient";
+
+/**
+ * @description Represents a blockchain block with its properties and methods.
+ * This class provides a structured way to access block-related data and interact with the blockchain client.
+ */
+export class Block implements Omit<RawBlock, "miner" | "transactions"> {
+    /**
+     * @description The base fee per gas for the block.
+     */
+    baseFeePerGas: bigint | null
+    /**
+     * @description The gas used for blobs in the block.
+     */
+    blobGasUsed: bigint
+    /**
+     * @description The block's difficulty.
+     */
+    difficulty: bigint
+    /**
+     * @description The excess blob gas in the block.
+     */
+    excessBlobGas: bigint
+    /**
+     * @description Extra data included in the block.
+     */
+    extraData: Hex
+    /**
+     * @description The gas limit for the block.
+     */
+    gasLimit: bigint
+    /**
+     * @description The gas used in the block.
+     */
+    gasUsed: bigint
+    /**
+     * @description The hash of the block.
+     */
+    hash: Hash | null
+    /**
+     * @description The logs bloom filter for the block.
+     */
+    logsBloom: Hex | null
+    /**
+     * @description The mix hash of the block.
+     */
+    mixHash: Hash
+    /**
+     * @description The nonce of the block.
+     */
+    nonce: Hex | null
+    /**
+     * @description The block number.
+     */
+    number: bigint | null
+    /**
+     * @description The parent beacon block root.
+     */
+    parentBeaconBlockRoot?: Hex
+    /**
+     * @description The hash of the parent block.
+     */
+    parentHash: Hash
+    /**
+     * @description The root of the receipts trie.
+     */
+    receiptsRoot: Hex
+    /**
+     * @description The seal fields of the block.
+     */
+    sealFields: Hex[]
+    /**
+     * @description The SHA3 uncles hash.
+     */
+    sha3Uncles: Hash
+    /**
+     * @description The size of the block in bytes.
+     */
+    size: bigint
+    /**
+     * @description The state root of the block.
+     */
+    stateRoot: Hash
+    /**
+     * @description The timestamp of the block.
+     */
+    timestamp: bigint
+    /**
+     * @description The total difficulty of the chain up to this block.
+     */
+    totalDifficulty: bigint | null
+    /**
+     * @description The root of the transactions trie.
+     */
+    transactionsRoot: Hash
+    /**
+     * @description The list of uncle hashes.
+     */
+    uncles: Hash[]
+    /**
+     * @description The list of withdrawals.
+     */
+    withdrawals?: Withdrawal[]
+    /**
+     * @description The root of the withdrawals trie.
+     */
+    withdrawalsRoot?: Hex
+
+    /**
+     * @description The miner of the block, represented as an Account instance.
+     */
+    miner: Account
+    /**
+     * @description The transactions included in the block, represented as an array of Transaction instances.
+     */
+    transactions?: Transaction[] | Hash[]
+
+    /**
+     * @description Creates an instance of Block.
+     * @param client - The instance of MentaClient used to interact with the blockchain.
+     * @param data The raw block data conforming to IBlockData.
+     * @param includeTransactions Whether to include full transaction objects. Defaults to false.
+     */
+    constructor(public client: MentaClient, data: RawBlock) {
+        this.baseFeePerGas = data.baseFeePerGas;
+        this.blobGasUsed = data.blobGasUsed;
+        this.difficulty = data.difficulty;
+        this.excessBlobGas = data.excessBlobGas;
+        this.extraData = data.extraData;
+        this.gasLimit = data.gasLimit;
+        this.gasUsed = data.gasUsed;
+        this.hash = data.hash;
+        this.logsBloom = data.logsBloom;
+        this.mixHash = data.mixHash;
+        this.nonce = data.nonce;
+        this.number = data.number;
+        this.parentBeaconBlockRoot = data.parentBeaconBlockRoot;
+        this.parentHash = data.parentHash;
+        this.receiptsRoot = data.receiptsRoot;
+        this.sealFields = data.sealFields;
+        this.sha3Uncles = data.sha3Uncles;
+        this.size = data.size;
+        this.stateRoot = data.stateRoot;
+        this.timestamp = data.timestamp;
+        this.totalDifficulty = data.totalDifficulty;
+        this.transactionsRoot = data.transactionsRoot;
+        this.uncles = data.uncles;
+        this.withdrawals = data.withdrawals;
+        this.withdrawalsRoot = data.withdrawalsRoot;
+
+        this.miner = new Account(this.client, { address: data.miner});
+        
+        if (!data.transactions || data.transactions.length === 0) {
+            const parsed = data.transactions.map((data) => typeof data === "string" ? data : new Transaction(this.client, data))
+            this.transactions = parsed as Transaction[] | Hash[];
+        }
+    };
+
+    protected includeTransactions(): this is this & { transactions: Transaction[] } {
+        if (!this.transactions || this.transactions.length === 0) return false;
+        return true
+    }
+
+    /**
+     * @description Converts the Block instance to a JSON representation.
+     * This method serializes the block's properties into a plain JavaScript object,
+     * suitable for JSON serialization.
+     * @param depth The depth of the conversion. Defaults to 1.
+     * @returns A promise that resolves to the JSON representation of the block.
+     */
+    async toJSON<D extends number = 1>(depth: D): Promise<JSONBlock<D>> {
+        return await toJSON({
+            obj: {
+                ...this,
+            },
+            depth
+        });
+    }
+};

package/src/structures/Cache.ts

@@ -0,0 +1,126 @@
+/**
+ * @module MemoryCache
+ */
+import { ICache, ICacheEntry, ICacheConfig } from '../types/Cache';
+
+/**
+/**
+ * @class MemoryCache
+ * @description A simple in-memory cache implementation that adheres to the ICache interface.
+ * It stores key-value pairs with an associated time-to-live (TTL) based on block numbers.
+ * The cache automatically evicts the oldest entries when its maximum size is reached.
+ */
+export class MemoryCache implements ICache {
+  /**
+   * @property {Map<string, ICacheEntry<any>>} cache - The internal Map used to store cache entries.
+   * @private
+   */
+  private cache = new Map<string, ICacheEntry<any>>();
+  /**
+   * @property {ICacheConfig} config - The configuration object for the cache, including maxSize, defaultTtl, and ttlPolicies.
+   */
+  public config: ICacheConfig;
+  /**
+   * @property {bigint} blockNumber - The current block number used for TTL calculations.
+   * @private
+   */
+  private blockNumber: bigint;
+
+ /**
+  * @constructor
+  * @description Creates an instance of MemoryCache.
+  * @param {bigint} blockNumber - The current block number to use for TTL calculations.
+  * @param {Partial<ICacheConfig>} [options] - Optional configuration for the cache.
+  * @param {number} [options.maxSize=500] - The maximum number of entries the cache can hold.
+  * @param {number} [options.defaultTtl=1] - The default time-to-live in blocks for cache entries if not specified.
+  * @param {Object.<string, number>} [options.ttlPolicies={}] - A map of specific TTL policies for different keys.
+  */
+ constructor(blockNumber: bigint, options?: Partial<ICacheConfig>) {
+   this.blockNumber = blockNumber;
+   this.config = {
+     maxSize: 500,
+     defaultTtl: 1,
+     ttlPolicies: options?.ttlPolicies || {},
+     ...options,
+   };
+ };
+
+ /**
+  * @method isExpired
+  * @description Checks if a cache entry has expired based on the current block number and the entry's expiry block.
+  * @param {bigint} expiry - The expiry block number of the cache entry.
+  * @returns {boolean} `true` if the entry has expired, `false` otherwise.
+  * @protected
+  */
+ protected isExpired(expiry: bigint): boolean {
+   return this.blockNumber > expiry;
+ };
+
+ /**
+  * @method setBlockNumber
+  * @description Sets the current block number for TTL calculations. This is crucial for managing cache entry expiry.
+  * @param {bigint} blockNumber - The new current block number.
+  * @returns {void}
+  */
+ setBlockNumber(blockNumber: bigint): void {
+   this.blockNumber = blockNumber;
+ }
+
+ /**
+  * @method set
+  * @description Sets a value in the cache. If the key already exists, its entry will be updated.
+  * If the cache reaches its maximum size, the oldest entry will be evicted before adding the new one.
+  * @template T - The type of the value being stored.
+  * @param {string} key - The unique key for the cache entry.
+  * @param {T} value - The value to store in the cache.
+  * @param {number} [ttl=this.config.defaultTtl] - The time-to-live (in blocks) for this specific entry. Defaults to the cache's `defaultTtl`.
+  * @returns {void}
+  */
+ set<T>(key: string, value: T, ttl: number = this.config.defaultTtl): void {
+   if (this.cache.has(key)) {
+     this.cache.delete(key);
+   }
+
+    if (this.cache.size >= this.config.maxSize) this.evict();
+    
+    const expiry = this.blockNumber + BigInt(ttl);
+    this.cache.set(key, { value, expiry });
+  }
+
+ /**
+  * @method get
+  * @description Retrieves a value from the cache. If the entry is found and has not expired,
+  * it is moved to the end of the cache (making it the most recently used) to prevent premature eviction.
+  * @template T - The expected type of the value.
+  * @param {string} key - The key of the cache entry to retrieve.
+  * @returns {T | undefined} The cached value if found and not expired, otherwise `undefined`.
+  */
+ get<T>(key: string): T | undefined {
+   const entry = this.cache.get(key);
+   if (!entry) return undefined;
+
+    if (this.isExpired(entry.expiry)) {
+      this.cache.delete(key);
+      return undefined;
+    }
+
+    this.cache.delete(key);
+    this.cache.set(key, entry);
+
+    return entry.value as T;
+  }
+
+ /**
+  * @method evict
+  * @description Evicts the oldest entry from the cache. This method is called internally when the cache
+  * reaches its `maxSize` to make room for new entries.
+  * @returns {void}
+  * @private
+  */
+ private evict(): void {
+   const oldestKey = this.cache.keys().next().value;
+   if (!oldestKey) return;
+
+    this.cache.delete(oldestKey);
+  }
+}