@mentaproject/client 0.1.22 → 0.1.24

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;

package/src/types/MentaClient.ts

@@ -0,0 +1,67 @@
+/**
+ * @module MentaClientTypes
+ */
+import { CoreClientConfig } from "@mentaproject/core/types";
+import { ICache } from "./Cache";
+import { watchBlockNumber, watchBlocks } from "@mentaproject/core/actions";
+import { IPersistenceAdapter } from "./PersistenceAdapter";
+
+/**
+ * Configuration for the client's cache.
+ * @interface CacheConfig
+ */
+export interface CacheConfig {
+    /**
+     * Time-to-live policies for different RPC methods.
+     * Keys are RPC method names (e.g., "eth_getBlockByNumber"), and values are
+     * the TTL in milliseconds for caching responses from those methods.
+     */
+    ttl_policies: Record<string, number>;
+};
+
+/**
+ * Configuration options for the MentaClient.
+ * Extends {@link CoreClientConfig} from `@mentaproject/core`.
+ * @interface MentaClientConfig
+ */
+export interface MentaClientConfig extends CoreClientConfig {
+    /**
+     * Optional cache implementation for the client.
+     * If provided, the client will use this cache for RPC responses.
+     */
+    cache?: ICache;
+    /**
+     * Optional persistence adapter for local data storage.
+     * If provided, the client will use this adapter to persist and retrieve data.
+     */
+    persistenceAdapter?: IPersistenceAdapter;
+};
+
+/**
+ * Defines the available client events and their corresponding watch functions.
+ * These functions are used to subscribe to real-time updates from the client.
+ */
+export const 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,
+};
+
+/**
+ * Utility type to extract the callback function type for a given event.
+ * This type dynamically determines the expected callback signature for a specific client event.
+ * @template TEvent The name of the event (e.g., 'block' or 'blockNumber') for which to get the listener callback type.
+ */
+export type GetListenerCallback<TEvent extends keyof typeof ClientEvents> =
+    Parameters<typeof ClientEvents[TEvent]>[1] extends infer P
+        ? P extends { [K in `on${Capitalize<TEvent>}`]: infer TCallback }
+            ? TCallback
+            : never
+        : never;

package/src/types/PersistenceAdapter.ts

@@ -0,0 +1,44 @@
+import { Address } from '@mentaproject/core/types';
+
+import { Transaction } from '../structures/Transaction';
+import { GetTransactionsParams } from './Account';
+import { JSONTransaction } from './Transaction';
+
+/**
+ * @interface IPersistenceAdapter
+ * @description Defines the contract for persistence layers, ensuring consistent data storage and retrieval operations.
+ */
+export interface IPersistenceAdapter {
+    /**
+     * @method upsertTransactions
+     * @description Inserts or updates a list of transactions. The operation must be atomic.
+     * @param {Transaction[]} transactions - An array of transaction data, including associated account addresses and timestamps.
+     * @returns {Promise<void>} A Promise that resolves when the transactions have been successfully inserted or updated.
+     */
+    upsertTransactions(transactions: Transaction[]): Promise<void>;
+
+    /**
+     * @method getTransactions
+     * @description Retrieves a paginated list of transactions for a specific account based on provided filters.
+     * @param {GetTransactionsFilters} filters - An object containing filters for retrieving transactions, such as account address, block range, pagination, and sort order.
+     * @returns {Promise<JSONTransaction[]>} A Promise that resolves with transactions objects.
+     */
+    getTransactions(address: Address, params: GetTransactionsParams): Promise<JSONTransaction<0>[]>;
+
+    /**
+     * @method getLastSyncedBlock
+     * @description Retrieves the last synced block number for a given account. This is used to track the synchronization progress of an account's transactions.
+     * @param {string} accountAddress - The address of the account for which to retrieve the last synced block number.
+     * @returns {Promise<number | null>} A Promise that resolves with the last synced block number, or `null` if no block has been synced for the account.
+     */
+    getLastSyncedBlock(accountAddress: string): Promise<bigint | null>;
+
+    /**
+     * @method setLastSyncedBlock
+     * @description Saves the last synced block number for a given account. This updates the synchronization progress for an account.
+     * @param {string} accountAddress - The address of the account for which to save the last synced block number.
+     * @param {bigint} blockNumber - The block number to save as the last synced block for the account.
+     * @returns {Promise<void>} A Promise that resolves when the last synced block number has been successfully saved.
+     */
+    setLastSyncedBlock(accountAddress: string, blockNumber: bigint): Promise<void>;
+}

package/src/types/Transaction.ts

@@ -0,0 +1,52 @@
+/**
+ * @module TransactionTypes
+ */
+
+import { Hex, TransactionReceipt, Transaction as RawTransaction } from "@mentaproject/core";
+import { Account } from "../structures";
+import { JSONBlock } from "./Block";
+import { JSONAccount } from "./Account";
+import { WithBigintStringified } from "./Utils";
+
+/**
+ * Defines the direction of a transaction relative to an account.
+ * "in" for incoming transactions, "out" for outgoing transactions.
+ * Defines the direction of a transaction relative to an account.
+ * "in" for incoming transactions, "out" for outgoing transactions.
+ */
+export type TransactionDirection = "in" | "out";
+
+/**
+/**
+ * Parameters for retrieving a transaction's block.
+ * @interface IGetTransactionBlockParams
+ */
+export interface IGetTransactionBlockParams {
+    /**
+     * Whether to include full transaction objects in the block.
+     * @type {boolean}
+     */
+    includeTransactions?: boolean;
+};
+
+export type TransactionCall = {
+    from: Account;
+    to: Account;
+    value: bigint;
+    input: Hex;
+    gas: bigint;
+    callType: string;
+};
+
+export type JSONTransaction<depth extends number> = depth extends 0
+  ? WithBigintStringified<Omit<RawTransaction, 'from' | 'to'>> & {
+      from: JSONAccount<depth>;
+      to?: JSONAccount<depth>;
+    }
+  : WithBigintStringified<Omit<RawTransaction, 'from' | 'to'>> & {
+      from: JSONAccount<depth>;
+      to?: JSONAccount<depth>;
+      block: JSONBlock<depth>;
+      receipt: WithBigintStringified<TransactionReceipt>;
+      calls?: WithBigintStringified<TransactionCall>[];
+    };

package/src/types/Utils.ts

@@ -0,0 +1,30 @@
+export type BigintStringified = `${number}n`;
+
+// -- TRANSFORMATION EN CHAÎNE (AVEC RÉCURSIVITÉ) --
+
+export type WithBigintStringified<T> = T extends bigint
+  // Cas de base : c'est un bigint, on le transforme
+  ? BigintStringified
+  // Cas récursif pour les tableaux : on applique la transformation à chaque élément
+  : T extends (infer E)[]
+  ? Array<WithBigintStringified<E>>
+  // Cas récursif pour les objets : on parcourt les propriétés et on ré-applique le type
+  : T extends object
+  ? { [K in keyof T]: WithBigintStringified<T[K]> }
+  // Cas de base : ce n'est ni un bigint, ni un objet, ni un tableau, on ne touche à rien
+  : T;
+
+
+// -- TRANSFORMATION EN BIGINT (AVEC RÉCURSIVITÉ) --
+
+export type WithoutBigintStringified<T> = T extends BigintStringified
+  // Cas de base : c'est une chaîne bigint, on la transforme
+  ? bigint
+  // Cas récursif pour les tableaux
+  : T extends (infer E)[]
+  ? Array<WithoutBigintStringified<E>>
+  // Cas récursif pour les objets
+  : T extends object
+  ? { [K in keyof T]: WithoutBigintStringified<T[K]> }
+  // Cas de base : on ne touche à rien
+  : T;

package/src/types/index.ts

@@ -0,0 +1,8 @@
+export * from './Account';
+export * from './Block';
+export * from './Transaction';
+export * from './Cache';
+export * from './PersistenceAdapter';
+export * from './Utils';
+
+export * from "@mentaproject/core/types";

package/src/utils/bigint.ts

@@ -0,0 +1,59 @@
+import { WithoutBigintStringified } from "../types/Utils";
+
+export const bigIntMax = (...args: bigint[]) => args.reduce((m, e) => e > m ? e : m);
+export const bigIntMin = (...args: bigint[]) => args.reduce((m, e) => e < m ? e : m);
+
+export function bigIntReviver(key: string, value: any) {
+    if (typeof value === 'string') {
+        if (value.endsWith('n')) {
+            try {
+                return BigInt(value.slice(0, -1));
+            } catch (e) {
+                return value;
+            }
+        };
+    };
+
+    return value;
+};
+
+export function stringifyBingints(obj: any) {
+        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;
+};
+
+export function parseBingints<T extends { [key: string]: any }>(obj: T): WithoutBigintStringified<T> {
+    if (typeof obj !== 'object' || obj === null) {
+        return obj;
+    }
+
+    if (Array.isArray(obj)) {
+        return obj.map((item, index) => bigIntReviver(index.toString(), parseBingints(item))) as WithoutBigintStringified<T>;
+    }
+
+    const newObj: { [key: string]: any } = {};
+    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 as WithoutBigintStringified<T>;
+};

package/src/utils/toJSON.ts

@@ -0,0 +1,123 @@
+/**
+ * @module toJSON
+ */
+
+/**
+ * Interface for parameters passed to the toJSON function.
+ * @template T The type of the object to be converted to JSON.
+ */
+export interface IToJSONParams<T extends { [key: string]: any } = { [key: string]: any }> {
+    /** The object to convert. */
+    obj: T;
+    /** The depth for recursive conversion. Defaults to 0. */
+    depth?: number;
+}
+
+/**
+ * Checks if an object is a class instance (not a native JavaScript object like Array, Date, etc.).
+ * @param {any} obj The object to check.
+ * @returns {boolean} True if the object is a class instance, false otherwise.
+ */
+function isClassInstance(obj: any): boolean {
+    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
+};
+
+/**
+ * Recursively converts BigInt values in an object to strings.
+ * @param {any} obj The object to convert.
+ * @returns {any} The object with BigInts converted to strings.
+ */
+function convertBigintsToStrings(obj: any): any {
+    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;
+}
+
+/**
+ * Converts an object, including its nested class instances and getter methods, into a plain JSON object.
+ * BigInt values are converted to strings.
+ *
+ * @param params - The parameters for conversion.
+ * @param params.obj - The object to convert.
+ * @param [params.depth=0] - The depth for recursive conversion. Defaults to 0.
+ * @returns A promise that resolves to the JSON representation of the object.
+ */
+export async function toJSON({ obj, depth = 0 }: IToJSONParams) {
+    const data: any = {};
+    const promises: Promise<any>[] = [];
+
+    for (const key in obj) {
+        // skip class related properties
+        if (key === "toJSON" || key === "constructor" || key === "client" || key === "persistenceManager") continue;
+
+        const prop: any = obj[key];
+
+        if (typeof prop === "function") {
+            // do not fetch getters if depth is 0
+            if (depth === 0) continue;
+
+            const promise = async () => {
+                const value = await obj[key]();
+
+                // if the value is a class instance, convert it to JSON recursively
+                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 is 0, just flatten the object using recursion
+            if (depth === 0) {
+                const promise = async () => {
+                    data[key] = await toJSON({
+                        obj: prop,
+                        depth: depth - 1
+                    });
+                };
+                promises.push(promise());
+
+                continue;
+            };
+            
+            // If depth is not 0, fetch the object
+            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);
+};

package/src/utils/withCache.ts

@@ -0,0 +1,50 @@
+/**
+ * @module withCache
+ */
+import { watchBlockNumber } from "@mentaproject/core/actions";
+import { CoreClient } from "../types";
+import { ICache } from "../types/Cache";
+import { Methods } from "../types/JsonRPC";
+
+/**
+ * A higher-order function that enhances a class method with caching capabilities.
+ * It intercepts RPC requests made through the client and caches their responses
+ * based on the provided cache implementation.
+ *
+ * @param client The CoreClient instance to enhance with caching.
+ * @param cache The cache implementation (ICache) to use for storing and retrieving responses.
+ * @returns The enhanced CoreClient instance with caching enabled.
+ */
+export function withCache(client: CoreClient, cache: ICache) {
+    watchBlockNumber(client, {
+        onBlockNumber: (blockNumber) => {
+            cache.setBlockNumber(blockNumber);
+        },
+        pollingInterval: 1000,
+    });
+    // 2. We keep a reference to the original request method
+    const originalRequest = client.request;
+
+    // 3. We replace the client's `request` method
+    client.request = (async (args: { method: Methods, params: any }) => {
+        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 as any);
+        };
+
+        if (result !== null && result !== undefined && method !== "eth_blockNumber") {
+            const ttl = cache.config.ttlPolicies[method] || cache.config.defaultTtl;
+            await cache.set(cacheKey, result, ttl);
+        }
+
+        return result;
+    }) as any;
+
+    return client;
+};