@mentaproject/client 0.1.35 → 0.1.36

package/dist/index.js

@@ -1,19 +1,1011 @@
-/**
- * @module @mentaproject/client
- * @description This library provides the client-side functionalities for interacting with the Menta blockchain.
- * It includes managers for accounts, blocks, contracts, persistence, and transactions,
- * as well as core data structures and utility types.
- */
-/**
- * Re-exports all core data structures like MentaClient, Account, Block, and Transaction.
- */
-export * from './structures';
-/**
- * Re-exports all manager classes for interacting with different aspects of the Menta blockchain.
- */
-export * from './managers';
-/**
- * Re-exports the Cache structure for managing cached data.
- */
-export * from './structures/Cache';
-export * from "./utils/bigint";
+import {
+  TransactionReceiptNotFoundError
+} from "./chunk-ZEQAXTUF.js";
+import "./chunk-NV2TBI2O.js";
+import "./chunk-PR4QN5HX.js";
+
+// src/structures/Account.ts
+import {
+  fetchByBlockRange,
+  getBalance,
+  getBlockNumber,
+  getCode,
+  getTransaction,
+  getTransactionCount,
+  sendTransaction,
+  traceFilter
+} from "@mentaproject/core/actions";
+
+// src/structures/Transaction.ts
+import { getBlock, getTransactionReceipt, traceTransaction, waitForTransactionReceipt } from "@mentaproject/core/actions";
+import { hexToBigInt } from "@mentaproject/core/utils";
+
+// src/utils/toJSON.ts
+function isClassInstance(obj) {
+  if (!obj) return false;
+  const constructor = obj.constructor;
+  const nativeConstructors = [Array, Date, RegExp, Map, Set, Promise, Function, Number, String, Boolean, Error, Object];
+  if (nativeConstructors.includes(constructor)) {
+    return false;
+  }
+  return true;
+}
+function convertBigintsToStrings(obj) {
+  if (typeof obj === "bigint") {
+    return obj.toString() + "n";
+  }
+  if (typeof obj === "object") {
+    for (const key in obj) {
+      obj[key] = convertBigintsToStrings(obj[key]);
+    }
+  }
+  if (Array.isArray(obj)) {
+    for (let i = 0; i < obj.length; i++) {
+      obj[i] = convertBigintsToStrings(obj[i]);
+    }
+  }
+  return obj;
+}
+async function toJSON({ obj, depth = 0 }) {
+  const data = {};
+  const promises = [];
+  for (const key in obj) {
+    if (key === "toJSON" || key === "constructor" || key === "client" || key === "persistenceManager") continue;
+    const prop = obj[key];
+    if (typeof prop === "function") {
+      if (depth === 0) continue;
+      const promise = async () => {
+        const value = await obj[key]();
+        if (typeof value === "object" && isClassInstance(value)) return data[key] = await toJSON({ obj: value, depth: depth - 1 });
+        data[key] = value;
+      };
+      promises.push(promise());
+    }
+    ;
+    if (typeof prop === "object" && isClassInstance(prop)) {
+      if (depth === 0) {
+        const promise2 = async () => {
+          data[key] = await toJSON({
+            obj: prop,
+            depth: depth - 1
+          });
+        };
+        promises.push(promise2());
+        continue;
+      }
+      ;
+      const promise = async () => {
+        data[key] = await prop.toJSON({ depth: depth - 1 });
+      };
+      promises.push(promise());
+      continue;
+    }
+    ;
+    data[key] = prop;
+  }
+  ;
+  await Promise.all(promises);
+  return convertBigintsToStrings(data);
+}
+
+// src/structures/Block.ts
+var Block = class {
+  /**
+   * @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(client, data) {
+    this.client = client;
+    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((data2) => typeof data2 === "string" ? data2 : new Transaction(this.client, data2));
+      this.transactions = parsed;
+    }
+  }
+  includeTransactions() {
+    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(depth) {
+    return await toJSON({
+      obj: {
+        ...this
+      },
+      depth
+    });
+  }
+};
+
+// src/structures/Transaction.ts
+var Transaction = class {
+  /**
+   * Creates an instance of Transaction.
+   * @description Initializes a new Transaction instance with the provided RPC client and transaction data.
+   * @param {MentaClient} client - The instance of MentaClient used to interact with the blockchain.
+   * @param {ITransactionData} data The raw transaction data.
+   */
+  constructor(client, data) {
+    this.client = client;
+    this.accessList = data.accessList;
+    this.blobVersionedHashes = data.blobVersionedHashes;
+    this.gas = data.gas;
+    this.gasPrice = data.gasPrice;
+    this.hash = data.hash;
+    this.input = data.input;
+    this.maxFeePerGas = data.maxFeePerGas;
+    this.maxPriorityFeePerGas = data.maxPriorityFeePerGas;
+    this.nonce = data.nonce;
+    this.r = data.r;
+    this.s = data.s;
+    this.transactionIndex = data.transactionIndex;
+    this.type = data.type;
+    this.v = data.v;
+    this.value = data.value;
+    this.yParity = data.yParity;
+    this.blockHash = data.blockHash;
+    this.blockNumber = data.blockNumber;
+    this.typeHex = data.typeHex;
+    this.from = data.from ? this.client.accounts.get(data.from) : void 0;
+    this.to = data.to ? this.client.accounts.get(data.to) : void 0;
+  }
+  /**
+   * Retrieves the internal calls made by this transaction.
+   * @description Fetches and processes the transaction traces to extract internal call details.
+   * @returns {Promise<TransactionCall[] | undefined>} A promise that resolves to an array of call objects, each representing an internal call with sender, recipient, value, input data, gas used, and call type.
+   */
+  async calls() {
+    const traces = await traceTransaction(this.client.rpc, this.hash);
+    if (!traces) return void 0;
+    const calls = traces.filter((t) => t.type === "call" && t.action !== void 0);
+    return calls.map((c) => ({
+      from: new Account(this.client, { address: c.action.from }),
+      to: new Account(this.client, { address: c.action.to }),
+      value: hexToBigInt(c.action.value),
+      input: c.action.input,
+      gas: hexToBigInt(c.action.gas),
+      callType: c.action.callType
+    }));
+  }
+  /**
+   * Waits for the transaction receipt to be available.
+   * @description Asynchronously waits for the transaction to be confirmed on the blockchain and its receipt to be available.
+   * @param {number} [confirmations] The number of confirmations to wait for. Defaults to 1.
+   * @returns {Promise<WaitForTransactionReceiptReturnType>} A promise that resolves to the transaction receipt once the specified number of confirmations are met.
+   */
+  async waitForReceipt(confirmations) {
+    return await waitForTransactionReceipt(this.client.rpc, {
+      hash: this.hash,
+      confirmations: confirmations || 1
+    });
+  }
+  /**
+   * Retrieves the transaction receipt.
+   * @description Fetches the transaction receipt for the current transaction hash.
+   * @returns {Promise<WaitForTransactionReceiptReturnType>} A promise that resolves to the transaction receipt.
+   */
+  async receipt() {
+    try {
+      return await getTransactionReceipt(this.client.rpc, { hash: this.hash });
+    } catch (error) {
+      if (error instanceof TransactionReceiptNotFoundError) {
+        return void 0;
+      }
+    }
+  }
+  /**
+   * Retrieves the block containing this transaction.
+   * @description Fetches the block data using the transaction's block hash and returns a Block instance.
+   * @returns {Promise<Block>} A promise that resolves to a Block instance representing the block that includes this transaction.
+   */
+  async block() {
+    const data = await getBlock(this.client.rpc, { blockHash: this.blockHash });
+    return new Block(this.client, data);
+  }
+  /**
+   * Converts the Transaction instance to a JSON representation.
+   * @description Serializes the transaction instance into a JSON object, including nested representations of related entities like block, receipt, and internal calls based on the specified depth.
+   * @param {number} [depth=1] The depth of the conversion. Controls how deeply nested objects are serialized.
+   * @returns {Promise<object>} A promise that resolves to the JSON representation of the transaction.
+   */
+  async toJSON(depth) {
+    return await toJSON({
+      obj: {
+        ...this,
+        block: this.block,
+        receipt: this.receipt,
+        calls: async () => {
+          const calls = await this.calls();
+          if (!calls) return void 0;
+          return Promise.all(calls.map(async (c) => await toJSON({ obj: c, depth })));
+        }
+      },
+      depth
+    });
+  }
+};
+
+// src/structures/Account.ts
+import { toHex } from "@mentaproject/core/utils";
+import { getContractType } from "@mentaproject/contracts";
+var Account = class {
+  /**
+   * 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(client, data, persistenceManager) {
+    this.client = client;
+    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() {
+    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() {
+    const isContract = await this.isContract();
+    if (!isContract) return void 0;
+    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) {
+    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() {
+    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() {
+    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, forceFetch = false) {
+    if (!this.persistenceManager || forceFetch) {
+      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 = 1e3) {
+    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) {
+    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(depth) {
+    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.
+   */
+  async _fetchTransactions({
+    fromBlock,
+    toBlock,
+    limit = 50
+  }) {
+    const lastBlock = await getBlockNumber(this.client.rpc);
+    const onBlockRange = async ({ fromBlock: fromBlock2, toBlock: toBlock2 }, stop) => {
+      const outgoing = await traceFilter(this.client.rpc, {
+        fromBlock: toHex(fromBlock2),
+        toBlock: toHex(toBlock2),
+        fromAddress: this.address
+      });
+      const incoming = await traceFilter(this.client.rpc, {
+        fromBlock: toHex(fromBlock2),
+        toBlock: toHex(toBlock2),
+        toAddress: this.address
+      });
+      const traces = outgoing.concat(incoming).sort((a, b) => a.blockNumber - b.blockNumber);
+      return traces.map((t) => t.transactionHash);
+    };
+    return await fetchByBlockRange({
+      toBlock: BigInt(toBlock !== void 0 ? toBlock : 0),
+      fromBlock: BigInt(fromBlock !== void 0 ? fromBlock : lastBlock),
+      direction: "backward",
+      itemLimit: limit,
+      onBlockRange
+    });
+  }
+};
+
+// src/structures/MentaClient.ts
+import { createMentaAccount } from "@mentaproject/core/clients";
+import { createClient } from "@mentaproject/core";
+
+// src/managers/BlockManager.ts
+import { getBlock as getBlock2 } from "@mentaproject/core/actions";
+var BlockManager = class {
+  /**
+   * Creates an instance of BlockManager.
+   * @param client - The instance of MentaClient used to interact with the blockchain.
+   */
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Retrieves a block from the blockchain based on the provided parameters.
+   * This method uses the underlying RPC client to fetch block data and then
+   * encapsulates it within a {@link Block} instance.
+   * @param params The parameters for retrieving the block, including block hash, block number, or block tag.
+   * @returns A promise that resolves to a {@link Block} instance representing the retrieved block.
+   * @example
+   * import { http } from '@mentaproject/core';
+   * import { mainnet } from '@mentaproject/core/chains';
+   * import { MentaClient } from '@mentaproject/client';
+   *
+   * // Initialize the MentaClient
+   * const mentaClient = new MentaClient({ chain: mainnet, transport: http("http://rpcurlhere.com") });
+   *
+   * async function fetchBlock() {
+   *   // Retrieve the latest block
+   *   const latestBlock = await mentaClient.blocks.get({ blockTag: 'latest' });
+   *   console.log('Latest block number:', latestBlock.number);
+   *
+   *   // Retrieve a specific block by its number
+   *   if (latestBlock.number) {
+   *     const specificBlock = await mentaClient.blocks.get({ blockNumber: latestBlock.number - 10n });
+   *     console.log('Specific block hash:', specificBlock.hash);
+   *   }
+   * }
+   *
+   * fetchBlock();
+   */
+  async get(params) {
+    const data = await getBlock2(this.client.rpc, params);
+    return new Block(this.client, data);
+  }
+};
+
+// src/managers/TransactionManager.ts
+import { getTransaction as getTransaction2, sendTransaction as sendTransaction2 } from "@mentaproject/core/actions";
+
+// src/utils/bigint.ts
+var bigIntMax = (...args) => args.reduce((m, e) => e > m ? e : m);
+var bigIntMin = (...args) => args.reduce((m, e) => e < m ? e : m);
+function bigIntReviver(key, value) {
+  if (typeof value === "string") {
+    if (value.endsWith("n")) {
+      try {
+        return BigInt(value.slice(0, -1));
+      } catch (e) {
+        return value;
+      }
+    }
+    ;
+  }
+  ;
+  return value;
+}
+function stringifyBingints(obj) {
+  if (typeof obj === "bigint") {
+    return obj.toString() + "n";
+  }
+  if (typeof obj === "object") {
+    for (const key in obj) {
+      obj[key] = stringifyBingints(obj[key]);
+    }
+  }
+  if (Array.isArray(obj)) {
+    for (let i = 0; i < obj.length; i++) {
+      obj[i] = stringifyBingints(obj[i]);
+    }
+  }
+  return obj;
+}
+function parseBingints(obj) {
+  if (typeof obj !== "object" || obj === null) {
+    return obj;
+  }
+  if (Array.isArray(obj)) {
+    return obj.map((item, index) => bigIntReviver(index.toString(), parseBingints(item)));
+  }
+  const newObj = {};
+  for (const key in obj) {
+    if (Object.prototype.hasOwnProperty.call(obj, key)) {
+      const value = obj[key];
+      const processedValue = parseBingints(value);
+      newObj[key] = bigIntReviver(key, processedValue);
+    }
+  }
+  ;
+  return newObj;
+}
+
+// src/managers/TransactionManager.ts
+var TransactionManager = class {
+  /**
+   * Creates an instance of `TransactionManager`.
+   * @constructor
+   * @param {MentaClient} client - The instance of MentaClient used to interact with the blockchain.
+   */
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * 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) {
+    const data = await getTransaction2(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(data) {
+    const parsed = parseBingints(data);
+    const rawData = {
+      ...parsed,
+      from: parsed.from.address,
+      to: parsed.to ? parsed.to.address : null
+    };
+    return new Transaction(this.client, rawData);
+  }
+  /**
+   * 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) {
+    const hash = await sendTransaction2(this.client.rpc, params);
+    return await this.get({ hash });
+  }
+};
+
+// src/managers/ContractManager.ts
+import { getContract } from "@mentaproject/contracts";
+var ContractManager = class {
+  /**
+   * Creates an instance of ContractManager.
+   * @description Initializes the ContractManager with a CoreClient instance, which is used for RPC communication.
+   * @param client - The instance of MentaClient used to interact with the blockchain.
+   */
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Retrieves a contract instance to interact with it.
+   * @description This method fetches a contract instance based on the provided parameters, allowing for interaction with its methods and events.
+   * @template P The type of the contract retrieval parameters, extending `GetContractParameters` with `AbiItem` array.
+   * @param {P} params The parameters for retrieving the contract, including its Application Binary Interface (ABI) and address.
+   * @returns {ReturnType<typeof getContract<ReadonlyArray<AbiItem>, P>>} A contract instance that can be used to call contract methods or listen to events.
+   * @example
+   * import { MentaClient } from '@mentaproject/client';
+   * import { http } from '@mentaproject/core';
+   *
+   * // Initialize the MentaClient with a transport
+   * const client = new MentaClient({
+   *   transport: http('http://rpcurlhere.com'),
+   * });
+   *
+   * // Define the ABI and address for the smart contract
+   * const abi = [
+   *   {
+   *     "type": "function",
+   *     "name": "greet",
+   *     "stateMutability": "view",
+   *     "inputs": [],
+   *     "outputs": [{ "name": "", "type": "string" }]
+   *   }
+   * ] as const;
+   * const contractAddress = '0x...'; // Replace with your contract address
+   *
+   * // Retrieve the contract instance
+   * const contract = client.contracts.get({
+   *   abi,
+   *   address: contractAddress,
+   * });
+   *
+   * // Example of interacting with the contract
+   * const greeting = await contract.greet();
+   */
+  get(params) {
+    return getContract(this.client.rpc, params);
+  }
+};
+
+// src/managers/AccountManager.ts
+var AccountManager = class {
+  /**
+   * Creates an instance of AccountManager.
+   *
+   * @param {MentaClient} client - The instance of MentaClient used to interact with the blockchain.
+   * @param {persistenceManager} persistenceManager - The optional persistence manager to store and retrieve account data.
+   */
+  constructor(client, persistenceManager) {
+    this.client = client;
+    this.persistenceManager = persistenceManager;
+  }
+  /**
+   * Retrieves an account instance by its blockchain address.
+   * @param address - The blockchain address of the account to retrieve.
+   * @returns An instance of the `Account` class.
+   * @example
+  * ```typescript
+  * import { MentaClient } from '@mentaproject/client';
+  * import { http } from '@mentaproject/core';
+  *
+  * // Initialize the MentaClient
+  * const client = new MentaClient({
+  *     transport: http('http://rpcurlhere.com'),
+  * });
+  *
+  * // The address of the account to retrieve
+  * const accountAddress = '0x1234567890123456789012345678901234567890';
+  *
+  * // Retrieve the account instance using the account manager from the client
+  * const account = client.accounts.get(accountAddress);
+  *
+  * console.log(account.address); // 0x1234567890123456789012345678901234567890
+  * ```
+   */
+  get(address) {
+    return new Account(this.client, { address }, this.persistenceManager);
+  }
+};
+
+// src/managers/PersistenceManager.ts
+import { getBlockNumber as getBlockNumber2 } from "@mentaproject/core/actions";
+var PersistenceManager = class {
+  /**
+   * Creates an instance of PersistenceManager.
+   * @param client - The instance of MentaClient used to interact with the blockchain.
+   * @param persistenceAdapter - The adapter responsible for actual data persistence operations.
+   */
+  constructor(client, persistenceAdapter) {
+    this.client = client;
+    this.persistenceAdapter = persistenceAdapter;
+  }
+  /**
+   * Retrieves transactions for a given account, applying a "stale-while-revalidate" strategy.
+   * @param params - Parameters for retrieving transactions.
+   * @returns A promise that resolves to an array of transactions with associated account information.
+   */
+  async getTransactions(address, params) {
+    return await this.persistenceAdapter.getTransactions(address, params);
+  }
+  /**
+   * Synchronizes an account's transactions from the remote source to the local persistence.
+   * It fetches new transactions starting from the last synced block and updates the local storage.
+   * @param account - The account whose transactions are to be synchronized.
+   * @param limit - The maximum number of transactions to fetch.
+   * @returns A promise that resolves when the synchronization is complete.
+   */
+  async syncTransactions(account, limit = 1e5) {
+    const lastSyncedBlock = await this.persistenceAdapter.getLastSyncedBlock(account.address);
+    const lastBlock = lastSyncedBlock ?? 0n;
+    const fromBlock = lastSyncedBlock ? lastSyncedBlock + 1n : await getBlockNumber2(this.client.rpc);
+    const newTransactions = await account.transactions({
+      fromBlock,
+      toBlock: lastBlock,
+      limit
+    }, true);
+    if (newTransactions.length > 0) {
+      await this.persistenceAdapter.upsertTransactions(newTransactions);
+      const latestBlock = bigIntMax(...newTransactions.map((t) => t.blockNumber || 0n));
+      await this.persistenceAdapter.setLastSyncedBlock(account.address, latestBlock);
+    }
+  }
+};
+
+// src/types/MentaClient.ts
+import { watchBlockNumber, watchBlocks } from "@mentaproject/core/actions";
+var ClientEvents = {
+  /**
+   * Event for new blocks.
+   * Uses the {@link watchBlocks} function from `@mentaproject/core`.
+   */
+  block: watchBlocks,
+  /**
+   * Event for new block numbers.
+   * Uses the {@link watchBlockNumber} function from `@mentaproject/core`.
+   */
+  blockNumber: watchBlockNumber
+};
+
+// src/utils/withCache.ts
+import { watchBlockNumber as watchBlockNumber2 } from "@mentaproject/core/actions";
+function withCache(client, cache) {
+  watchBlockNumber2(client, {
+    onBlockNumber: (blockNumber) => {
+      cache.setBlockNumber(blockNumber);
+    },
+    pollingInterval: 1e3
+  });
+  const originalRequest = client.request;
+  client.request = (async (args) => {
+    const { method, params } = args;
+    const cacheKey = `${client.chain.id}:${method}:${JSON.stringify(params || [], (_, v) => typeof v === "bigint" ? v.toString() : v)}`;
+    let result;
+    if (method !== "eth_blockNumber") result = cache.get(cacheKey);
+    if (!result) {
+      result = await originalRequest(args);
+    }
+    ;
+    if (result !== null && result !== void 0 && method !== "eth_blockNumber") {
+      const ttl = cache.config.ttlPolicies[method] || cache.config.defaultTtl;
+      await cache.set(cacheKey, result, ttl);
+    }
+    return result;
+  });
+  return client;
+}
+
+// src/structures/MentaClient.ts
+var MentaClient = class {
+  /**
+   * Creates an instance of MentaClient.
+   * @param {MentaClientConfig} params - The configuration parameters for the client.
+   * @description The constructor initializes the RPC client and the various managers based on the provided configuration.
+   * It also applies caching and persistence if specified in the configuration.
+   * @example
+   * import { MentaClient } from '@mentaproject/client';
+   *
+   * // Basic initialization
+   * const client = new MentaClient({
+   *   url: 'http://rpcurlhere.com',
+   * });
+   *
+   * // Initialization with a persistent cache
+   * const clientWithCache = new MentaClient({
+   *   url: 'http://rpcurlhere.com',
+   *   cache: {
+   *     ttl: 60000, // 1 minute
+   *   },
+   * });
+   */
+  constructor(params) {
+    this.params = params;
+    this.blocks = new BlockManager(this);
+    this.transactions = new TransactionManager(this);
+    this.contracts = new ContractManager(this);
+    if (params.persistenceAdapter) {
+      this.persistenceManager = new PersistenceManager(
+        this,
+        params.persistenceAdapter
+      );
+      this.accounts = new AccountManager(this, this.persistenceManager);
+    } else {
+      this.accounts = new AccountManager(this);
+    }
+  }
+  /**
+   * The underlying RPC client used for blockchain interactions.
+   * @description This client is responsible for low-level communication with the RPC node.
+   */
+  get rpc() {
+    if (!this._rpc) {
+      throw new Error("RPC client not initialized");
+    }
+    return this._rpc;
+  }
+  /**
+   * The account associated with the client.
+   * @description This account is used for signing transactions and interacting with the blockchain.
+   */
+  get account() {
+    if (!this._account) {
+      throw new Error("Account not initialized");
+    }
+    return this._account;
+  }
+  /**
+   * Subscribes to a specific client event.
+   * @template TEvent The type of the event to listen for.
+   * @param {TEvent} event - The event to listen for (e.g., 'block', 'transaction').
+   * @param {GetListenerCallback<TEvent>} callback - The callback function to execute when the event is triggered.
+   * @returns {() => void} An unsubscribe function to stop listening to the event.
+   * @description This method allows the client to listen for real-time events from the blockchain, such as new blocks or transactions.
+   * @example
+   * import { MentaClient } from '@mentaproject/client';
+   *
+   * const client = new MentaClient({ url: 'http://rpcurlhere.com' });
+   *
+   * // Subscribe to new blocks
+   * const unsubscribe = client.on('block', (block) => {
+   *   console.log('New block received:', block);
+   * });
+   *
+   * // To stop listening
+   * // unsubscribe();
+   */
+  on(event, callback) {
+    const eventFunction = ClientEvents[event];
+    const capitalizedEvent = event.charAt(0).toUpperCase() + event.slice(1);
+    const params = {
+      [`on${capitalizedEvent}`]: callback,
+      pollingInterval: 1e3
+    };
+    return eventFunction(this.rpc, params);
+  }
+  async init() {
+    let coreClient = createClient(this.params);
+    if (this.params.cache) {
+      coreClient = withCache(coreClient, this.params.cache);
+    }
+    this._rpc = await createMentaAccount(coreClient, {
+      bundlerTransport: this.params.bundlerTransport,
+      publicTransport: this.params.transport,
+      signer: this.params.signer,
+      validatorAddress: this.params.validatorAddress
+    });
+    this._account = this.accounts.get(this.rpc.account.address);
+  }
+};
+
+// src/structures/Cache.ts
+var MemoryCache = class {
+  /**
+   * @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, options) {
+    /**
+     * @property {Map<string, ICacheEntry<any>>} cache - The internal Map used to store cache entries.
+     * @private
+     */
+    this.cache = /* @__PURE__ */ new Map();
+    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
+   */
+  isExpired(expiry) {
+    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) {
+    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(key, value, ttl = this.config.defaultTtl) {
+    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(key) {
+    const entry = this.cache.get(key);
+    if (!entry) return void 0;
+    if (this.isExpired(entry.expiry)) {
+      this.cache.delete(key);
+      return void 0;
+    }
+    this.cache.delete(key);
+    this.cache.set(key, entry);
+    return entry.value;
+  }
+  /**
+   * @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
+   */
+  evict() {
+    const oldestKey = this.cache.keys().next().value;
+    if (!oldestKey) return;
+    this.cache.delete(oldestKey);
+  }
+};
+export {
+  Account,
+  AccountManager,
+  Block,
+  BlockManager,
+  ContractManager,
+  MemoryCache,
+  MentaClient,
+  Transaction,
+  TransactionManager,
+  bigIntMax,
+  bigIntMin,
+  bigIntReviver,
+  parseBingints,
+  stringifyBingints
+};
+//# sourceMappingURL=index.js.map