@mentaproject/client 0.1.23 → 0.1.24

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);
+  }
+}

package/src/structures/MentaClient.ts

@@ -0,0 +1,127 @@
+/**
+ * @module MentaClient
+ */
+import type { CoreClient } from "@mentaproject/core/types";
+import { createClient } from "@mentaproject/core";
+
+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";
+
+/**
+ * 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 {
+    /**
+     * The underlying RPC client used for blockchain interactions.
+     * @description This client is responsible for low-level communication with the RPC node.
+     */
+    public rpc: CoreClient;
+
+    /**
+     * 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(params: MentaClientConfig) {
+        this.rpc = createClient(params) as CoreClient;
+        if (params.cache) this.rpc = withCache(this.rpc, params.cache);
+
+        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);
+        }
+    }
+
+    /**
+     * 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';