@mentaproject/client 0.1.23 → 0.1.25

package/src/types/MentaClient.ts

@@ -0,0 +1,79 @@
+/**
+ * @module MentaClientTypes
+ */
+import {
+  CoreClientConfig,
+  PasskeySigner,
+  Transport,
+} 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;
+  /**
+   * Bundler transport used for userOperations
+   */
+  bundlerTransport: Transport;
+  /**
+   * Passkey compatible signer used for signing user operations
+   */
+  signer: PasskeySigner;
+}
+
+/**
+ * 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;
+};

package/test.ts

@@ -1,89 +0,0 @@
-import { Address, checksumAddress, http } from "@mentaproject/core";
-import { MentaClient, Transaction } from "./src";
-import { privateKeyToAccount, generatePrivateKey } from "viem/accounts"
-import { mainnet } from "@mentaproject/core/chains";
-import { MemoryCache } from "./src/structures/Cache";
-import { writeFileSync } from "fs";
-
-const viemAccount = privateKeyToAccount(generatePrivateKey());
-
-let counter = 0;
-let lastSyncedBlock = new Map<Address, bigint>();
-let transactions = new Map<Address, Transaction[]>();
-
-const client = new MentaClient({
-    account: viemAccount,
-    transport: http("https://ethereum-rpc.publicnode.com", {
-        batch: {
-            batchSize: 50,
-            wait: 20,
-        },
-        onFetchRequest: async (r) => {
-            // const data = await r.json();
-            // console.log(data.map(j => `${j.method}(${j.params?.map(p => JSON.stringify(p)).join(', ')})`).join('\n'));
-            // console.log(`>> ${counter} requests`);
-
-            // console.log(`>> ${r.url}\n>> ${req.map(j => j.method).join(', ')}\n>> ${delay / 1000}s\n`)
-        },
-        // onFetchResponse: (r) => console.log(`<<: ${r.url}`),
-    }),
-    cache: new MemoryCache(0n, { maxSize: 1000, defaultTtl: 1 }),
-    persistenceAdapter: {
-        getLastSyncedBlock: async (accountAddress: Address) => {
-            return lastSyncedBlock.get(accountAddress) ?? null;
-        },
-        getTransactions: async (address: Address, params): Promise<Transaction[]> => {
-            return transactions.get(address) ?? [];
-        },
-        upsertTransactions: async (txs: Transaction[]) => {
-            console.log("upsertTransactions", txs.length);
-            for (const transaction of txs) {
-                const fromAddress = transaction.from?.address;
-                const toAddress = transaction.to?.address;
-
-                if (fromAddress) {
-                    const checksumed = checksumAddress(fromAddress);
-
-                    if (!transactions.has(checksumed)) {
-                        transactions.set(checksumed, []);
-                    };
-
-                    const jsonTransaction = await transaction.toJSON(0);
-                    const parsed = client.transactions.parse(jsonTransaction);
-
-                    transactions.get(checksumed)?.push(parsed);
-                };
-
-                if (toAddress) {
-                    const checksumed = checksumAddress(toAddress);
-
-                    if (!transactions.has(checksumed)) {
-                        transactions.set(checksumed, []);
-                    };
-
-                    const jsonTransaction = await transaction.toJSON(0);
-                    const parsed = client.transactions.parse(jsonTransaction);
-
-                    transactions.get(checksumed)?.push(parsed);
-                }
-            }
-        },
-        setLastSyncedBlock: async (accountAddress: Address, blockNumber: bigint) => {
-            lastSyncedBlock.set(accountAddress, blockNumber);
-        },
-    },
-    chain: mainnet
-});
-
-(async () => {
-    console.log("Watching for new blocks and block numbers...");
-
-    const account = client.accounts.get("0x53b9B72DC6f96Eb4B54143B211B22e2548e4cf5c");
-    await account.syncTransactions(50)
-    const res = await account.transactions({ limit: 50 });
-    console.log(res.map(r => r.blockNumber));
-    const json = await Promise.all(res.map(async t => await t.toJSON(0)));
-
-    writeFileSync("transactions.json", JSON.stringify(json, null, 2));
-    console.log("Done");
-})();