@mentaproject/client 0.1.23 → 0.1.25

package/dist/managers/PersistenceManager.d.ts

@@ -1,7 +1,7 @@
 import { Address } from '@mentaproject/core/types';
 import { Account } from '../structures/Account';
-import { MentaClient, Transaction } from '../structures';
-import { GetTransactionsParams, IPersistenceAdapter } from 'src/types';
+import { MentaClient } from '../structures';
+import { GetTransactionsParams, IPersistenceAdapter, JSONTransaction } from 'src/types';
 /**
  * Manages the persistence of data, including transactions, using a specified persistence adapter.
  * It handles fetching data from both local storage and remote sources, and synchronizing them.
@@ -20,7 +20,7 @@ export declare class PersistenceManager {
      * @param params - Parameters for retrieving transactions.
      * @returns A promise that resolves to an array of transactions with associated account information.
      */
-    getTransactions(address: Address, params: GetTransactionsParams): Promise<Transaction[]>;
+    getTransactions(address: Address, params: GetTransactionsParams): Promise<JSONTransaction<0>[]>;
     /**
      * 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.

package/dist/managers/TransactionManager.d.ts

@@ -40,7 +40,7 @@ export declare class TransactionManager {
      * @param {J} data - The JSON converted transaction data object.
      * @returns {Transaction} A Transaction instance representing the parsed transaction.
      */
-    parse<J extends JSONTransaction<number>>(data: J): Transaction;
+    parse<J extends JSONTransaction<0>>(data: J): Transaction;
     /**
      * Sends a transaction to the blockchain network.
      * @description This method submits a new transaction to the blockchain. After the transaction

package/dist/structures/Account.d.ts

@@ -100,5 +100,5 @@ export declare class Account implements AccountData {
      *  @param params - The parameters for the block range exploration.
      *  @returns A Promise that resolves to an array of transaction hashes.
      */
-    protected _fetchTransactions({ fromBlock, toBlock, limit }: FetchTransactionParams): Promise<Hash[]>;
+    protected _fetchTransactions({ fromBlock, toBlock, limit, }: FetchTransactionParams): Promise<Hash[]>;
 }

package/dist/structures/Account.js

@@ -1,4 +1,4 @@
-import { fetchByBlockRange, getBalance, getBlockNumber, getCode, getTransaction, getTransactionCount, sendTransaction, traceFilter } from "@mentaproject/core/actions";
+import { fetchByBlockRange, getBalance, getBlockNumber, getCode, getTransaction, getTransactionCount, sendTransaction, traceFilter, } from "@mentaproject/core/actions";
 import { Transaction } from "./Transaction";
 import { toHex } from "@mentaproject/core/utils";
 import { getContractType } from "@mentaproject/contracts";
@@ -31,7 +31,6 @@ export class Account {
             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()`.
@@ -44,7 +43,6 @@ export class Account {
             return undefined;
         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.
@@ -53,15 +51,16 @@ export class Account {
      */
     async sendETH(amount) {
         const hash = await sendTransaction(this.client.rpc, {
-            calls: [{
+            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.
@@ -72,7 +71,6 @@ export class Account {
             address: this.address,
         });
     }
-    ;
     /**
      * Retrieves the transaction count (nonce) for the account.
      * @description The transaction count represents the number of transactions sent from this account,
@@ -80,7 +78,9 @@ export class Account {
      * @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 });
+        return await getTransactionCount(this.client.rpc, {
+            address: this.address,
+        });
     }
     /**
      * Retrieves all transactions involving this account.
@@ -99,10 +99,11 @@ export class Account {
         if (!this.persistenceManager || forceFetch) {
             // If persistence is not configured, fetch directly from remote
             const hashes = await this._fetchTransactions(params);
-            const transactions = await Promise.all(hashes.map(hash => this.client.transactions.get({ hash })));
+            const transactions = await Promise.all(hashes.map((hash) => this.client.transactions.get({ hash })));
             return transactions;
         }
-        return await this.persistenceManager.getTransactions(this.address, params);
+        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`.
@@ -126,7 +127,7 @@ export class Account {
      */
     async tokenTransactions(tokenAddress) {
         if (!this.persistenceManager)
-            throw new Error('The persistence module is not configured.');
+            throw new Error("The persistence module is not configured.");
         return {};
     }
     /**
@@ -145,7 +146,7 @@ export class Account {
                 ETHBalance: this.ETHBalance.bind(this),
                 transactionCount: this.transactionCount.bind(this),
             },
-            depth
+            depth,
         });
     }
     /**
@@ -154,29 +155,30 @@ export class Account {
      *  @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 }) {
+    async _fetchTransactions({ fromBlock, toBlock, limit = 50, }) {
         const lastBlock = await getBlockNumber(this.client.rpc);
         const onBlockRange = async ({ fromBlock, toBlock }, stop) => {
             const outgoing = await traceFilter(this.client.rpc, {
                 fromBlock: toHex(fromBlock),
                 toBlock: toHex(toBlock),
-                fromAddress: this.address
+                fromAddress: this.address,
             });
             const incoming = await traceFilter(this.client.rpc, {
                 fromBlock: toHex(fromBlock),
                 toBlock: toHex(toBlock),
-                toAddress: this.address
+                toAddress: this.address,
             });
-            const traces = outgoing.concat(incoming).sort((a, b) => a.blockNumber - b.blockNumber);
-            return traces.map(t => t.transactionHash);
+            const traces = outgoing
+                .concat(incoming)
+                .sort((a, b) => a.blockNumber - b.blockNumber);
+            return traces.map((t) => t.transactionHash);
         };
         return await fetchByBlockRange({
             toBlock: BigInt(toBlock !== undefined ? toBlock : 0),
             fromBlock: BigInt(fromBlock !== undefined ? fromBlock : lastBlock),
             direction: "backward",
             itemLimit: limit,
-            onBlockRange
+            onBlockRange,
         });
     }
 }
-;

package/dist/structures/MentaClient.d.ts

@@ -1,7 +1,7 @@
 /**
  * @module MentaClient
  */
-import type { CoreClient } from "@mentaproject/core/types";
+import type { MentaAccountClient } from "@mentaproject/core/types";
 import { BlockManager } from "../managers/BlockManager";
 import { TransactionManager } from "../managers/TransactionManager";
 import { ContractManager } from "../managers/ContractManager";
@@ -17,11 +17,13 @@ import { ClientEvents, GetListenerCallback, MentaClientConfig } from "../types/M
  * simplifying common operations.
  */
 export declare class MentaClient {
+    protected params: MentaClientConfig;
+    protected _rpc?: MentaAccountClient;
     /**
      * The underlying RPC client used for blockchain interactions.
      * @description This client is responsible for low-level communication with the RPC node.
      */
-    rpc: CoreClient;
+    get rpc(): MentaAccountClient;
     /**
      * Manager for block-related operations.
      * @description Provides methods to query and interact with blockchain blocks.
@@ -85,6 +87,7 @@ export declare class MentaClient {
      * });
      */
     constructor(params: MentaClientConfig);
+    init(): Promise<void>;
     /**
      * Optional manager for persistence-related operations.
      * @description This manager is initialized if a persistence adapter is provided in the client configuration,

package/dist/structures/MentaClient.js

@@ -1,11 +1,12 @@
-import { createClient } from "@mentaproject/core";
+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 } from "../types/MentaClient";
+import { ClientEvents, } 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.
@@ -15,6 +16,16 @@ import { withCache } from "../utils/withCache";
  * 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.
+     */
+    get rpc() {
+        if (!this._rpc) {
+            throw new Error("RPC client not initialized");
+        }
+        return this._rpc;
+    }
     /**
      * Subscribes to a specific client event.
      * @template TEvent The type of the event to listen for.
@@ -66,9 +77,7 @@ export class MentaClient {
      * });
      */
     constructor(params) {
-        this.rpc = createClient(params);
-        if (params.cache)
-            this.rpc = withCache(this.rpc, params.cache);
+        this.params = params;
         this.blocks = new BlockManager(this);
         this.transactions = new TransactionManager(this);
         this.contracts = new ContractManager(this);
@@ -80,4 +89,14 @@ export class MentaClient {
             this.accounts = new AccountManager(this);
         }
     }
+    async init() {
+        let coreClient = createClient(this.params);
+        if (this.params.cache) {
+            coreClient = withCache(coreClient, this.params.cache);
+        }
+        this._rpc = await createMentaAccount(coreClient, {
+            signer: this.params.signer,
+            bundlerTransport: this.params.bundlerTransport,
+        });
+    }
 }

package/dist/types/MentaClient.d.ts

@@ -1,7 +1,7 @@
 /**
  * @module MentaClientTypes
  */
-import { CoreClientConfig } from "@mentaproject/core/types";
+import { CoreClientConfig, PasskeySigner, Transport } from "@mentaproject/core/types";
 import { ICache } from "./Cache";
 import { watchBlockNumber, watchBlocks } from "@mentaproject/core/actions";
 import { IPersistenceAdapter } from "./PersistenceAdapter";
@@ -33,6 +33,14 @@ export interface MentaClientConfig extends CoreClientConfig {
      * 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.
@@ -55,6 +63,6 @@ export declare const ClientEvents: {
  * 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 {
+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/dist/types/MentaClient.js

@@ -1,6 +1,4 @@
 import { watchBlockNumber, watchBlocks } from "@mentaproject/core/actions";
-;
-;
 /**
  * Defines the available client events and their corresponding watch functions.
  * These functions are used to subscribe to real-time updates from the client.

package/dist/types/PersistenceAdapter.d.ts

@@ -1,6 +1,7 @@
 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.
@@ -17,9 +18,9 @@ export interface IPersistenceAdapter {
      * @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<Transaction[]>} A Promise that resolves with transactions objects.
+     * @returns {Promise<JSONTransaction[]>} A Promise that resolves with transactions objects.
      */
-    getTransactions(address: Address, params: GetTransactionsParams): Promise<Transaction[]>;
+    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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mentaproject/client",
-  "version": "0.1.23",
+  "version": "0.1.25",
   "description": "High level EVM library used into the Menta App to facilitate Blockchain interactions. ",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -22,7 +22,7 @@
   },
   "scripts": {
     "test:file": "tsx test.ts",
-    "test": "jest",
+    "test": "jest -i",
     "build": "tsc --project tsconfig.json",
     "patch": "npm version patch && npm run build && npm publish --access public",
     "minor": "npm version minor && npm run build && npm publish --access public",
@@ -31,8 +31,8 @@
   "author": "@mentaproject",
   "license": "ISC",
   "dependencies": {
-    "@mentaproject/contracts": "^0.0.9",
-    "@mentaproject/core": "^0.5.3",
+    "@mentaproject/contracts": "^0.0.11",
+    "@mentaproject/core": "^0.5.13",
     "@modelcontextprotocol/sdk": "^1.13.0",
     "@shazow/whatsabi": "^0.21.1"
   },

package/src/index.ts

@@ -0,0 +1,21 @@
+/**
+ * @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";

package/src/managers/AccountManager.ts

@@ -0,0 +1,51 @@
+/**
+ * @module AccountManager
+ */
+import { Address } from "@mentaproject/core/types";
+import { Account } from "../structures/Account";
+import { PersistenceManager } from "./PersistenceManager";
+import { MentaClient } from "../structures";
+
+/**
+ * Manages blockchain account operations.
+ * This class provides methods to interact with accounts,
+ * including retrieving and managing them via an RPC client and a persistence manager.
+ *
+ * @class AccountManager
+ */
+export class AccountManager {
+    /**
+     * 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(public client: MentaClient, private 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: Address): Account {
+        return new Account(this.client, { address: address }, this.persistenceManager);
+    };
+}

package/src/managers/BlockManager.ts

@@ -0,0 +1,51 @@
+/**
+ * @module BlockManager
+ */
+import { BlockTag, GetBlockParameters } from "@mentaproject/core/types";
+import { Block } from "../structures/Block";
+import { getBlock } from "@mentaproject/core/actions";
+import { MentaClient } from "../structures";
+
+/**
+ * Manages blockchain block-related operations, providing methods to interact with and retrieve block data.
+ */
+export class BlockManager {
+    /**
+     * Creates an instance of BlockManager.
+     * @param client - The instance of MentaClient used to interact with the blockchain.
+     */
+    constructor(public client: MentaClient) {};
+
+    /**
+     * 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: GetBlockParameters<boolean, BlockTag>): Promise<Block> {
+        const data = await getBlock(this.client.rpc, params);
+        return new Block(this.client, data);
+    };
+}

package/src/managers/ContractManager.ts

@@ -0,0 +1,60 @@
+/**
+ * @module ContractManager
+ */
+import type { AbiItem } from "@mentaproject/core/types";
+import { getContract, GetContractParameters } from "@mentaproject/contracts";
+import { MentaClient } from "../structures";
+
+/**
+ * Manages smart contract-related operations within the Menta client.
+ * This class provides methods to interact with smart contracts deployed on the blockchain,
+ * facilitating the retrieval of contract instances for various operations.
+ */
+export class ContractManager {
+    /**
+     * 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(protected client: MentaClient) {};
+
+    /**
+     * 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<P extends GetContractParameters<ReadonlyArray<AbiItem>>>(params: P) {
+        return getContract(this.client.rpc, params);
+    };
+};

package/src/managers/PersistenceManager.ts

@@ -0,0 +1,59 @@
+import { getBlockNumber } from '@mentaproject/core/actions';
+import { Address } from '@mentaproject/core/types';
+
+import { Account } from '../structures/Account';
+import { MentaClient, Transaction } from '../structures';
+import { bigIntMax } from '../utils/bigint';
+import { GetTransactionsParams, IPersistenceAdapter, JSONTransaction } from 'src/types';
+
+/**
+ * Manages the persistence of data, including transactions, using a specified persistence adapter.
+ * It handles fetching data from both local storage and remote sources, and synchronizing them.
+ */
+export class PersistenceManager {
+    /**
+     * 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(
+        private client: MentaClient,
+        private persistenceAdapter: IPersistenceAdapter
+    ) {}
+
+    /**
+     * 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.
+     */
+    public async getTransactions(address: Address, params: GetTransactionsParams): Promise<JSONTransaction<0>[]> {
+        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.
+     */
+    public async syncTransactions(account: Account, limit: number = 100_000): Promise<void> {
+        const lastSyncedBlock = await this.persistenceAdapter.getLastSyncedBlock(account.address);
+        const lastBlock = lastSyncedBlock ?? 0n;
+
+        const fromBlock = lastSyncedBlock ? lastSyncedBlock + 1n : (await getBlockNumber(this.client.rpc));
+
+        const newTransactions = await account.transactions({
+            fromBlock: fromBlock,
+            toBlock: lastBlock,
+            limit: 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);
+        }
+    }
+}