@mentaproject/client 0.1.23 → 0.1.25

package/src/structures/MentaClient.ts

@@ -0,0 +1,152 @@
+/**
+ * @module MentaClient
+ */
+import type { CoreClient, MentaAccountClient } from "@mentaproject/core/types";
+import { createMentaAccount } from "@mentaproject/core/clients";
+
+import { BlockManager } from "../managers/BlockManager";
+import { TransactionManager } from "../managers/TransactionManager";
+import { ContractManager } from "../managers/ContractManager";
+import { AccountManager } from "../managers/AccountManager";
+import { PersistenceManager } from "../managers/PersistenceManager";
+import {
+  ClientEvents,
+  GetListenerCallback,
+  MentaClientConfig,
+} from "../types/MentaClient";
+import { withCache } from "../utils/withCache";
+import { createClient } from "@mentaproject/core";
+
+/**
+ * The main client for interacting with the Menta API.
+ * It provides managers for blocks, transactions, contracts, and accounts.
+ *
+ * @description This class serves as the primary entry point for interacting with the Menta blockchain.
+ * It encapsulates the core RPC client and provides specialized managers for various blockchain entities,
+ * simplifying common operations.
+ */
+export class MentaClient {
+  protected _rpc?: MentaAccountClient;
+  /**
+   * The underlying RPC client used for blockchain interactions.
+   * @description This client is responsible for low-level communication with the RPC node.
+   */
+  public get rpc(): MentaAccountClient {
+    if (!this._rpc) {
+      throw new Error("RPC client not initialized");
+    }
+    return this._rpc;
+  }
+
+  /**
+   * Manager for block-related operations.
+   * @description Provides methods to query and interact with blockchain blocks.
+   */
+  public blocks!: BlockManager;
+  /**
+   * Manager for transaction-related operations.
+   * @description Provides methods to send, query, and manage blockchain transactions.
+   */
+  public transactions!: TransactionManager;
+  /**
+   * Manager for contract-related operations.
+   * @description Provides methods to deploy, interact with, and query smart contracts.
+   */
+  public contracts!: ContractManager;
+  /**
+   * Manager for account-related operations.
+   * @description Provides methods to manage and interact with blockchain accounts.
+   */
+  public accounts!: AccountManager;
+
+  /**
+   * 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<TEvent extends keyof typeof ClientEvents>(
+    event: TEvent,
+    callback: GetListenerCallback<TEvent>,
+  ) {
+    const eventFunction = ClientEvents[event];
+    const capitalizedEvent = event.charAt(0).toUpperCase() + event.slice(1);
+    const params = {
+      [`on${capitalizedEvent}`]: callback,
+      pollingInterval: 1000,
+    };
+
+    return (eventFunction as any)(this.rpc, params);
+  }
+
+  /**
+   * 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(protected params: MentaClientConfig) {
+    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);
+    }
+  }
+
+  async init() {
+    let coreClient = createClient(this.params) as CoreClient;
+
+    if (this.params.cache) {
+      coreClient = withCache(coreClient, this.params.cache);
+    }
+
+    this._rpc = await createMentaAccount(coreClient, {
+      signer: this.params.signer,
+      bundlerTransport: this.params.bundlerTransport,
+    });
+  }
+
+  /**
+   * Optional manager for persistence-related operations.
+   * @description This manager is initialized if a persistence adapter is provided in the client configuration,
+   * allowing for data storage and retrieval.
+   */
+  public persistenceManager?: PersistenceManager;
+}

package/src/structures/Transaction.ts

@@ -0,0 +1,220 @@
+import { AccessList, Address, Hash, Hex, Transaction as RawTransaction, WaitForTransactionReceiptReturnType } from '@mentaproject/core/types';
+import { getBlock, getTransactionReceipt, traceTransaction, waitForTransactionReceipt } from '@mentaproject/core/actions';
+import { hexToBigInt } from '@mentaproject/core/utils';
+import { TransactionReceiptNotFoundError } from 'viem';
+
+import { Account } from './Account';
+import { Block } from './Block';
+import { MentaClient } from './MentaClient';
+
+import { toJSON } from '../utils/toJSON';
+import { JSONTransaction, TransactionCall } from '../types';
+
+/**
+ * Represents a blockchain transaction with its properties and methods.
+ *
+ * @description This class encapsulates the data and functionalities related to an Ethereum-like transaction,
+ * providing methods to interact with the blockchain to retrieve transaction-related information such as
+ * internal calls, receipts, and the block it belongs to.
+ */
+export class Transaction implements Omit<RawTransaction, "from" | "to"> {
+  /**
+   * @description The access list for the transaction.
+   */
+  public accessList?: AccessList;
+  /**
+   * @description The blob versioned hashes.
+   */
+  public blobVersionedHashes?: readonly Hex[];
+  /**
+   * @description The gas limit for the transaction.
+   */
+  public gas: bigint;
+  /**
+   * @description The gas price for the transaction.
+   */
+  public gasPrice?: bigint;
+  /**
+   * @description The hash of the transaction.
+   */
+  public hash: Hash;
+  /**
+   * @description The input data for the transaction.
+   */
+  public input: Hex;
+  /**
+   * @description The maximum fee per gas.
+   */
+  public maxFeePerGas?: bigint;
+  /**
+   * @description The maximum priority fee per gas.
+   */
+  public maxPriorityFeePerGas?: bigint;
+  /**
+   * @description The nonce of the transaction.
+   */
+  public nonce: number;
+  /**
+   * @description The r value of the signature.
+   */
+  public r: Hex;
+  /**
+   * @description The s value of the signature.
+   */
+  public s: Hex;
+  /**
+   * @description The index of the transaction within the block.
+   */
+  public transactionIndex: number | null;
+  /**
+   * @description The type of the transaction.
+   */
+  public type: "legacy" | "eip2930" | "eip1559" | "eip4844" | "eip7702";
+  /**
+   * @description The v value of the signature.
+   */
+  public v: bigint;
+  /**
+   * @description The value transferred in the transaction.
+   */
+  public value: bigint;
+  /**
+   * @description The y parity of the signature.
+   */
+  public yParity?: number;
+  /**
+   * @description The hash of the block containing this transaction.
+   */
+  public blockHash: Hash | null;
+  /**
+   * @description The number of the block containing this transaction.
+   */
+  public blockNumber: bigint | null;
+  /**
+   * @description The hex representation of the type of the transaction.
+   */
+  public typeHex: `0x${string}` | null;
+
+  /**
+   * @description The sender account of the transaction.
+   */
+  public from?: Account;
+  /**
+   * @description The recipient account of the transaction.
+   */
+  public to?: Account;
+
+
+  /**
+   * 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(protected client: MentaClient, data: RawTransaction) {
+    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) : undefined;
+    this.to = data.to ? this.client.accounts.get(data.to) : undefined;
+  };
+
+  /**
+   * 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.
+   */
+  public async calls(): Promise<TransactionCall[] | undefined> {
+    const traces = await traceTransaction(this.client.rpc, this.hash);
+    if (!traces) return undefined;
+
+    const calls = traces.filter(t => t.type === "call" && t.action !== undefined);
+
+    return calls.map(c => ({
+      from: new Account(this.client, { address: c.action!.from as Address }),
+      to: new Account(this.client, { address: c.action!.to as Address }),
+      value: hexToBigInt(c.action!.value as Hex),
+      input: c.action!.input as Hex,
+      gas: hexToBigInt(c.action!.gas as Hex),
+      callType: c.action!.callType,
+    })) as TransactionCall[];
+  }
+
+  /**
+   * 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?: number): Promise<WaitForTransactionReceiptReturnType> {
+    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(): Promise<WaitForTransactionReceiptReturnType | undefined> {
+    try {
+      return await getTransactionReceipt(this.client.rpc, { hash: this.hash });
+    } catch (error) {
+      if (error instanceof TransactionReceiptNotFoundError) {
+        return undefined;
+      }
+    }
+  };
+
+  /**
+   * 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(): Promise<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<D extends number = 1>(depth: D): Promise<JSONTransaction<D>> {
+    return await toJSON({
+      obj: {
+        ...this,
+        block: this.block,
+        receipt: this.receipt,
+        calls: async () => {
+          const calls = await this.calls();
+          if (!calls) return undefined;
+
+          return Promise.all(calls.map(async c => await toJSON({ obj: c, depth: depth })));
+        }
+      },
+      depth
+    });
+  }
+};

package/src/structures/index.ts

@@ -0,0 +1,5 @@
+export * from './Account';
+export * from './Block';
+export * from './MentaClient'
+export * from './Transaction';
+export * from './Cache';

package/src/types/Account.ts

@@ -0,0 +1,44 @@
+/**
+ * @module AccountTypes
+ */
+
+import { Address } from "@mentaproject/core";
+
+/**
+ * Defines the options for retrieving transactions associated with an account.
+ */
+export type GetTransactionsParams = FetchTransactionParams & {
+};
+
+/**
+ * Parameters for retrieving transactions emitted by an account by exploring blocks.
+ * @interface IGetTransactionReceiptParams
+ */
+export type FetchTransactionParams = {
+    /**
+     * The block number to start exploring from.
+     * @type {bigint}
+     */
+    fromBlock?: bigint;
+    /**
+     * The block number to stop exploring at.
+     * @type {bigint}
+     */
+    toBlock?: bigint;
+    /**
+     * The maximum number of items to retrieve.
+     * @type {number}
+     */
+    limit?: number;
+};
+
+export type AccountData = {
+    address: Address;
+}
+
+export type JSONAccount<depth extends number> = depth extends 0 ? AccountData : AccountData & {
+    isContract: boolean;
+    ETHBalance: string;
+    contractType: string;
+    transactionCount: number;
+}

package/src/types/Block.ts

@@ -0,0 +1,14 @@
+import { Address, Hash, Hex, Transaction as RawTransaction, Withdrawal } from "@mentaproject/core/types";
+import { Block as RawBlock } from "@mentaproject/core";
+import { JSONAccount } from "./Account"
+import { WithBigintStringified } from "./Utils";
+import { JSONTransaction } from "./Transaction";
+
+export type JSONBlock<depth extends number> = depth extends 0
+  ? WithBigintStringified<Omit<RawBlock, "miner" | "transactions">> & {
+      transactions?: JSONTransaction<depth>[] | Hash[],
+    }
+  : WithBigintStringified<Omit<RawBlock, "miner" | "transactions">> & {
+      miner: JSONAccount<depth>,
+      transactions?: JSONTransaction<depth>[] | Hash[],
+    }

package/src/types/Cache.ts

@@ -0,0 +1,55 @@
+import { Methods } from "./JsonRPC";
+
+/**
+ * @interface ICacheEntry
+ * Represents a single entry in the cache.
+ * @template T The type of the cached value.
+ */
+export interface ICacheEntry<T> {
+    /** The cached value. */
+    value: T;
+    /** The block number at which this entry expires. */
+    expiry: bigint;
+}
+
+/**
+ * @interface ICacheConfig
+ * Defines the configuration options for a cache.
+ */
+export interface ICacheConfig {
+    /** The maximum number of items the cache can hold. */
+    maxSize: number;
+    /** The default time-to-live (in blocks) for cache entries if no specific policy is defined. */
+    defaultTtl: number;
+    /** A map of RPC methods to their specific time-to-live policies (in blocks). */
+    ttlPolicies: Partial<Record<Methods, number>>;
+}
+
+/**
+ * @interface ICache
+ * Defines the interface for a cache implementation.
+ */
+export interface ICache {
+    /** The configuration for the cache. */
+    config: ICacheConfig;
+    /**
+     * Sets the current block number for TTL calculations.
+     * @param {bigint} blockNumber The new current block number.
+     */
+    setBlockNumber(blockNumber: bigint): void;
+    /**
+     * Retrieves a value from the cache.
+     * @template T The type of the value.
+     * @param {string} key The key for the cache entry.
+     * @returns {T | undefined} The cached value, or undefined if not found or expired.
+     */
+    get<T>(key: string): T | undefined;
+    /**
+     * Sets a value in the cache.
+     * @template T The type of the value.
+     * @param {string} key The key for the cache entry.
+     * @param {T} value The value to store.
+     * @param {number} [ttl] The time-to-live (in blocks) for the entry. If not provided, `defaultTtl` from config is used.
+     */
+    set<T>(key: string, value: T, ttl?: number): void;
+};

package/src/types/JsonRPC.ts

@@ -0,0 +1,126 @@
+/**
+ * @module JsonRPC
+ */
+
+/**
+ * Defines standard Ethereum JSON-RPC methods.
+ */
+export type StandardMethods =
+  /** Returns a list of addresses owned by client. */
+  | "eth_accounts"
+  /** Returns the current blob base fee. */
+  | "eth_blobBaseFee"
+  /** Returns the number of most recent block. */
+  | "eth_blockNumber"
+  /** Executes a new message call immediately without creating a transaction on the blockchain. */
+  | "eth_call"
+  /** Returns the current chain ID. */
+  | "eth_chainId"
+  /** Creates an EIP-2930 type access list for a transaction. */
+  | "eth_createAccessList"
+  /** Generates and returns an estimate of how much gas is necessary to allow the transaction to complete. */
+  | "eth_estimateGas"
+  /** Returns a historical log of gas prices. */
+  | "eth_feeHistory"
+  /** Returns the current price per gas in wei. */
+  | "eth_gasPrice"
+  /** Returns the balance of the account of given address. */
+  | "eth_getBalance"
+  /** Returns information about a block by hash. */
+  | "eth_getBlockByHash"
+  /** Returns information about a block by block number. */
+  | "eth_getBlockByNumber"
+  /** Returns all transaction receipts for a given block. */
+  | "eth_getBlockReceipts"
+  /** Returns the number of transactions in a block from a block matching the given block hash. */
+  | "eth_getBlockTransactionCountByHash"
+  /** Returns the number of transactions in a block from a block matching the given block number. */
+  | "eth_getBlockTransactionCountByNumber"
+  /** Returns the code at a given address. */
+  | "eth_getCode"
+  /** Returns an array of all logs matching a given filter object. */
+  | "eth_getLogs"
+  /** Returns the account and storage proof for the specified address and storage points. */
+  | "eth_getProof"
+  /** Returns the value from a storage position at a given address. */
+  | "eth_getStorageAt"
+  /** Returns information about a transaction by block hash and transaction index position. */
+  | "eth_getTransactionByBlockHashAndIndex"
+  /** Returns information about a transaction by block number and transaction index position. */
+  | "eth_getTransactionByBlockNumberAndIndex"
+  /** Returns the information about a transaction requested by transaction hash. */
+  | "eth_getTransactionByHash"
+  /** Returns the number of transactions sent from an address. */
+  | "eth_getTransactionCount"
+  /** Returns the receipt of a transaction by transaction hash. */
+  | "eth_getTransactionReceipt"
+  /** Returns information about an uncle of a block by hash and uncle index position. */
+  | "eth_getUncleByBlockHashAndIndex"
+  /** Returns information about an uncle of a block by number and uncle index position. */
+  | "eth_getUncleByBlockNumberAndIndex"
+  /** Returns the number of uncles in a block from a block matching the given block hash. */
+  | "eth_getUncleCountByBlockHash"
+  /** Returns the number of uncles in a block from a block matching the given block number. */
+  | "eth_getUncleCountByBlockNumber"
+  /** Returns the hash of the current block, the seedHash, and the boundary condition to be met. */
+  | "eth_getWork"
+  /** Returns the number of hashes per second that the node is mining with. */
+  | "eth_hashrate"
+  /** Returns a fee per gas that a user is willing to pay for their transaction to be included in the current block. */
+  | "eth_maxPriorityFeePerGas"
+  /** Returns true if client is actively mining new blocks. */
+  | "eth_mining"
+  /** Returns the current Ethereum protocol version. */
+  | "eth_protocolVersion"
+  /** Submits a signed transaction for inclusion in the blockchain. */
+  | "eth_sendRawTransaction"
+  /** Simulates a transaction execution. */
+  | "eth_simulateV1"
+  /** Used for submitting a proof-of-work solution. */
+  | "eth_submitWork"
+  /** Returns an object with data about the sync status or false. */
+  | "eth_syncing";
+
+/**
+ * Defines JSON-RPC methods related to filters.
+ */
+export type filterMethods =
+  /** Polling method for a filter, which returns an array of logs or hashes. */
+  | "eth_getFilterChanges"
+  /** Returns an array of all logs matching a given filter id. */
+  | "eth_getFilterLogs"
+  /** Creates a filter in the node, to notify when a new block arrives. */
+  | "eth_newBlockFilter"
+  /** Creates a filter object, based on filter options, to notify when the state changes (logs). */
+  | "eth_newFilter"
+  /** Uninstalls a filter with given id. */
+  | "eth_uninstallFilter";
+
+/**
+ * Defines JSON-RPC methods related to subscriptions.
+ */
+export type subscriptionMethods =
+  /** Subscribes to events. */
+  | "eth_subscribe"
+  /** Unsubscribes from events. */
+  | "eth_unsubscribe";
+
+/**
+ * Defines JSON-RPC methods related to tracing.
+ */
+export type traceMethods =
+  /** Returns traces for a given block. */
+  | "trace_block"
+  /** Returns a trace of the given transaction. */
+  | "trace_call"
+  /** Returns traces for multiple transactions. */
+  | "trace_callMany"
+  /** Returns traces matching the given filter. */
+  | "trace_filter"
+  /** Returns a trace of the given transaction. */
+  | "trace_transaction";
+
+/**
+ * Union type of all supported JSON-RPC methods.
+ */
+export type Methods = StandardMethods | filterMethods | subscriptionMethods | traceMethods;