@mentaproject/client 0.1.37 → 0.2.0

package/dist/structures/Action.d.ts

@@ -0,0 +1,55 @@
+import { Call, Hex, TransactionReceipt } from "@mentaproject/core";
+import { MentaAccountClient } from "@mentaproject/core/types";
+/**
+ * Represents a transaction that has been sent but not yet confirmed.
+ */
+export declare class PendingTransaction {
+    private client;
+    readonly hash: Hex;
+    constructor(client: MentaAccountClient, hash: Hex);
+    /**
+     * Waits for the transaction to be confirmed.
+     *
+     * @param confirmations Number of block confirmations to wait for (default: 1)
+     * @returns The transaction receipt
+     */
+    confirm(confirmations?: number): Promise<TransactionReceipt>;
+}
+/**
+ * Generic action object that wraps a single call.
+ *
+ * Provides `.call()` for batching with TransactionBuilder
+ * and `.execute()` for direct execution.
+ *
+ * @example
+ * ```ts
+ * // Direct execution
+ * const pending = await account.sendEth(parseEther("1")).execute();
+ * const receipt = await pending.confirm();
+ *
+ * // Batching with TransactionBuilder
+ * new TransactionBuilder(client.rpc)
+ *   .addCall(account.sendEth(parseEther("1")))
+ *   .addCall(token.transfer(to, amount))
+ *   .execute();
+ * ```
+ */
+export declare class Action {
+    private client;
+    private _call;
+    constructor(client: MentaAccountClient, _call: Call);
+    /**
+     * Returns the Call object for use with TransactionBuilder.
+     */
+    call(): Call;
+    /**
+     * Simulates the action without executing.
+     */
+    simulate(): Promise<import("viem").SimulateCallsReturnType<readonly [Call]>>;
+    /**
+     * Executes the action directly.
+     *
+     * @returns A PendingTransaction with the hash and .confirm() method
+     */
+    execute(): Promise<PendingTransaction>;
+}

package/dist/structures/TransferAction.d.ts

@@ -0,0 +1,41 @@
+import { Call, Hex, SimulateCallsReturnType } from "@mentaproject/core";
+import { MentaAccountClient } from "@mentaproject/core/types";
+import type { Address } from "@mentaproject/core/types";
+/**
+ * Action object for ETH transfers.
+ *
+ * Provides both `.call()` for batching with TransactionBuilder
+ * and `.execute()` for direct execution.
+ *
+ * @example
+ * ```ts
+ * // Direct execution
+ * await account.sendEth(parseEther("1")).execute();
+ *
+ * // Batching with TransactionBuilder
+ * new TransactionBuilder(client.rpc)
+ *   .addCall(account.sendEth(parseEther("1")))
+ *   .addCall(erc20.transfer(to, amount))
+ *   .execute();
+ * ```
+ */
+export declare class TransferAction {
+    private client;
+    private to;
+    private amount;
+    constructor(client: MentaAccountClient, to: Address, amount: bigint);
+    /**
+     * Returns the Call object for use with TransactionBuilder.
+     */
+    call(): Call;
+    /**
+     * Simulates the transfer without executing.
+     */
+    simulate(): Promise<SimulateCallsReturnType<Call[]>>;
+    /**
+     * Executes the transfer directly.
+     *
+     * @returns Transaction hash
+     */
+    execute(): Promise<Hex>;
+}

package/dist/structures/index.d.ts

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

package/dist/types/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/types/index.ts"],"sourcesContent":["export * from './Account';\nexport * from './Block';\nexport * from './Transaction';\nexport * from './Cache';\nexport * from './PersistenceAdapter';\nexport * from './Utils';\n\nexport * from \"@mentaproject/core/types\";"],"mappings":";;;;;;;;;;;;;;;;;AAAA;AAAA;AAOA,0BAAc,qCAPd;","names":[]}
+{"version":3,"sources":["../../src/types/index.ts"],"sourcesContent":["export * from \"./Account\";\nexport * from \"./Block\";\nexport * from \"./Transaction\";\nexport * from \"./Cache\";\nexport * from \"./PersistenceAdapter\";\nexport * from \"./Utils\";\n\nexport * from \"@mentaproject/core/types\";\n"],"mappings":";;;;;;;;;;;;;;;;;AAAA;AAAA;AAOA,0BAAc,qCAPd;","names":[]}

package/dist/types/index.d.ts

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

package/dist/types/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/types/index.ts"],"sourcesContent":["export * from './Account';\nexport * from './Block';\nexport * from './Transaction';\nexport * from './Cache';\nexport * from './PersistenceAdapter';\nexport * from './Utils';\n\nexport * from \"@mentaproject/core/types\";"],"mappings":";AAOA,cAAc;","names":[]}
+{"version":3,"sources":["../../src/types/index.ts"],"sourcesContent":["export * from \"./Account\";\nexport * from \"./Block\";\nexport * from \"./Transaction\";\nexport * from \"./Cache\";\nexport * from \"./PersistenceAdapter\";\nexport * from \"./Utils\";\n\nexport * from \"@mentaproject/core/types\";\n"],"mappings":";AAOA,cAAc;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mentaproject/client",
-  "version": "0.1.37",
+  "version": "0.2.0",
   "description": "High level EVM library used into the Menta App to facilitate Blockchain interactions. ",
   "main": "dist/index.cjs",
   "module": "dist/index.mjs",
@@ -36,6 +36,7 @@
   "dependencies": {
     "@mentaproject/contracts": "^0.0.11",
     "@mentaproject/core": "^0.7.3",
+    "@mentaproject/transactions": "^0.0.3",
     "@modelcontextprotocol/sdk": "^1.13.0",
     "@shazow/whatsabi": "^0.21.1"
   },

package/src/managers/TransactionManager.ts

@@ -1,92 +1,97 @@
 /**
  * @module TransactionManager
  */
-import {  GetTransactionParameters, Transaction as RawTransaction, SendTransactionParameters } from "@mentaproject/core/types";
-import { Transaction } from "../structures/Transaction";
+import { GetTransactionParameters, Transaction as RawTransaction, SendTransactionParameters } from "@mentaproject/core/types";
+import { Transaction as RichTransaction } from "../structures/Transaction";
+import { MulticallTransaction } from "@mentaproject/transactions";
 import { getTransaction, sendTransaction } from "@mentaproject/core/actions";
 import { MentaClient } from "../structures";
 import { JSONTransaction } from "../types";
 import { parseBingints } from "../utils/bigint";
 
 /**
- * Manages blockchain transaction-related operations, providing methods to retrieve and send transactions.
- * @class
- * @description This class provides an interface to interact with blockchain transactions,
- * allowing for retrieval of transaction details and submission of new transactions
- * to the network via an RPC client.
+ * Manages blockchain transaction-related operations.
+ *
+ * @example
+ * ```ts
+ * // Create a multicall transaction
+ * const pending = await client.transactions.create()
+ *   .addCall(account.sendEth(parseEther("1")))
+ *   .addCall(erc20.transfer(to, amount))
+ *   .execute();
+ *
+ * const receipt = await pending.confirm();
+ *
+ * // Get a transaction by hash
+ * const tx = await client.transactions.fromHash(hash);
+ * console.log(tx.receipt, tx.block);
+ * ```
  */
 export class TransactionManager {
-    /**
-     * Creates an instance of `TransactionManager`.
-     * @constructor
-     * @param {MentaClient} client - The instance of MentaClient used to interact with the blockchain.
-     */
-    constructor(public client: MentaClient) {};
+  constructor(public client: MentaClient) {}
 
-    /**
-     * Retrieves a transaction by its hash or block number and index.
-     * @description This method fetches detailed information about a specific transaction
-     * from the blockchain using the provided parameters.
-     * @param {GetTransactionParameters} params - The parameters for retrieving the transaction,
-     * typically including `hash` or `blockNumber` and `index`.
-     * @returns {Promise<Transaction>} A promise that resolves to a {@link Transaction} instance
-     * containing the retrieved transaction data.
-     * @example
-     * const txHash = '0x...'; // Replace with a valid transaction hash
-     * const transaction = await client.transactions.get({ hash: txHash });
-     * console.log(transaction);
-     */
-    async get(params: GetTransactionParameters): Promise<Transaction> {
-        const data = await getTransaction(this.client.rpc, params);
-        return new Transaction(this.client, data);
-    };
+  /**
+   * Creates a new MulticallTransaction for batching multiple calls.
+   *
+   * @returns A MulticallTransaction builder
+   *
+   * @example
+   * ```ts
+   * const pending = await client.transactions.create()
+   *   .addCall(account.sendEth(parseEther("1")))
+   *   .addCall(erc20.transfer(to, amount))
+   *   .execute();
+   * ```
+   */
+  create(): MulticallTransaction {
+    return new MulticallTransaction(this.client.rpc);
+  }
 
-    /**
-     * Parse a transaction object from a JSON converted transaction data object.
-     * 
-     * @param {J} data - The JSON converted transaction data object.
-     * @returns {Transaction} A Transaction instance representing the parsed transaction.
-     */
-    parse<J extends JSONTransaction<0>>(data: J): Transaction {
-        const parsed = parseBingints(data);
+  /**
+   * Retrieves a rich transaction by its hash.
+   *
+   * @param hash - The transaction hash
+   * @returns A rich Transaction with receipt, block, etc.
+   *
+   * @example
+   * ```ts
+   * const tx = await client.transactions.fromHash(hash);
+   * console.log(tx.from, tx.to, tx.value);
+   * ```
+   */
+  async fromHash(hash: `0x${string}`): Promise<RichTransaction> {
+    return this.get({ hash });
+  }
 
-        const rawData = {
-            ...parsed,
-            from: parsed.from.address,
-            to: parsed.to ? parsed.to.address : null,
-        };
-        
-        return new Transaction(this.client, rawData as RawTransaction);
-    };
+  /**
+   * Retrieves a transaction by its hash or block number and index.
+   */
+  async get(params: GetTransactionParameters): Promise<RichTransaction> {
+    const data = await getTransaction(this.client.rpc, params);
+    return new RichTransaction(this.client, data);
+  }
+
+  /**
+   * Parse a transaction object from a JSON converted transaction data object.
+   */
+  parse<J extends JSONTransaction<0>>(data: J): RichTransaction {
+    const parsed = parseBingints(data);
 
-    /**
-     * Sends a transaction to the blockchain network.
-     * @description This method submits a new transaction to the blockchain. After the transaction
-     * is successfully sent, it retrieves and returns the full transaction details.
-     * @param {SendTransactionParameters} params - The parameters required to send the transaction,
-     * such as `to`, `value`, `data`, `gasLimit`, etc.
-     * @returns {Promise<Transaction>} A promise that resolves to a {@link Transaction} instance
-     * representing the sent transaction, including its hash and other details.
-     * @example
-     * import { MentaClient } from '@mentaproject/client';
-     * import { http } from '@mentaproject/core';
-     *
-     * // This example assumes you have an account with funds, which is available to the client.
-     * const client = new MentaClient({
-     *   chain: 'mainnet',
-     *   transport: http('http://rpcurlhere.com')
-     * });
-     *
-     * const transactionResult = await client.transactions.send({
-     *   to: '0xRecipientAddress...', // Replace with a valid recipient address
-     *   value: 1000000000000000000n, // 1 ETH in wei
-     * });
-     *
-     * console.log('Transaction sent with hash:', transactionResult.hash);
-     */
-    async send(params: SendTransactionParameters): Promise<Transaction> {
-        const hash = await sendTransaction(this.client.rpc, params);
-        
-        return await this.get({ hash });
+    const rawData = {
+      ...parsed,
+      from: parsed.from.address,
+      to: parsed.to ? parsed.to.address : null,
     };
-};
+
+    return new RichTransaction(this.client, rawData as RawTransaction);
+  }
+
+  /**
+   * Sends a transaction to the blockchain network.
+   * @deprecated Use client.transactions.create() for new transactions
+   */
+  async send(params: SendTransactionParameters): Promise<RichTransaction> {
+    const hash = await sendTransaction(this.client.rpc, params);
+    return await this.get({ hash });
+  }
+}

package/src/structures/Account.ts

@@ -3,9 +3,7 @@ import {
   getBalance,
   getBlockNumber,
   getCode,
-  getTransaction,
   getTransactionCount,
-  sendTransaction,
   traceFilter,
 } from "@mentaproject/core/actions";
 import type {
@@ -13,7 +11,8 @@ import type {
   Hash,
   onBlockRangeCallback,
 } from "@mentaproject/core/types";
-import { Transaction } from "./Transaction";
+import { Transaction as RichTransaction } from "./Transaction";
+import { Transaction } from "@mentaproject/transactions";
 import { toHex } from "@mentaproject/core/utils";
 import {
   AccountData,
@@ -28,22 +27,11 @@ import { MentaClient } from "./MentaClient";
 
 /**
  * Represents a blockchain account with functionalities to interact with the Menta blockchain.
- * This class provides methods to query account information, send transactions, and manage account-related data.
  */
 export class Account implements AccountData {
-  /**
-   * The blockchain address of the account.
-   */
   public address: Address;
-
   private persistenceManager?: PersistenceManager;
 
-  /**
-   * Creates an instance of the Account class.
-   * @param client.rpc The CoreClient instance used for blockchain interactions.
-   * @param address The blockchain address of the account.
-   * @param persistenceManager An optional PersistenceManager instance for caching and data synchronization.
-   */
   constructor(
     public client: MentaClient,
     data: AccountData,
@@ -53,99 +41,58 @@ export class Account implements AccountData {
     this.persistenceManager = persistenceManager;
   }
 
-  /**
-   * Checks if the account's address belongs to a smart contract.
-   * @description This method queries the blockchain for the code associated with the account's address.
-   * If code is found, it indicates that the account is a contract.
-   * @returns {Promise<boolean>} A promise that resolves to `true` if the account is a contract, `false` otherwise.
-   */
   async isContract(): Promise<boolean> {
     const code = await getCode(this.client.rpc, { address: this.address });
-
     if (!code || code === "0x") 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()`.
-   * If it is a contract, it then attempts to determine and return its type.
-   * @returns {Promise<any>} A promise that resolves to the contract type (e.g., 'ERC20', 'ERC721') or `undefined` if the account is not a contract or its type cannot be determined.
-   */
   async contractType(): Promise<any> {
     const isContract = await this.isContract();
     if (!isContract) 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.
-   * @param {bigint} amount The amount of ETH to send, specified in wei (the smallest denomination of Ether).
-   * @returns {Promise<Transaction>} A promise that resolves to a `Transaction` object representing the sent transaction.
+   * Creates a Transaction to send ETH to this account.
+   *
+   * @param amount The amount of ETH to send, in wei.
+   * @returns A Transaction with .call(), .simulate(), and .execute() methods.
+   *
+   * @example
+   * ```ts
+   * // Direct execution
+   * const pending = await account.sendEth(parseEther("1")).execute();
+   * const receipt = await pending.confirm();
+   *
+   * // Batch with MulticallTransaction
+   * multicall.addCall(account.sendEth(parseEther("1")));
+   * ```
    */
-  async sendETH(amount: bigint): Promise<Transaction> {
-    const hash = await sendTransaction(this.client.rpc, {
-      calls: [
-        {
-          to: this.address,
-          value: amount,
-        },
-      ],
+  sendEth(amount: bigint): Transaction {
+    return new Transaction(this.client.rpc, {
+      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.
-   * @returns {Promise<bigint>} A promise that resolves to the ETH balance of the account, in wei.
-   */
   async ETHBalance(): Promise<bigint> {
-    return await getBalance(this.client.rpc, {
-      address: this.address,
-    });
+    return await getBalance(this.client.rpc, { address: this.address });
   }
 
-  /**
-   * Retrieves the transaction count (nonce) for the account.
-   * @description The transaction count represents the number of transactions sent from this account,
-   * which is also used as the nonce for new transactions to prevent replay attacks.
-   * @returns {Promise<number>} A promise that resolves to the transaction count of the account.
-   */
   async transactionCount(): Promise<number> {
-    return await getTransactionCount(this.client.rpc, {
-      address: this.address,
-    });
+    return await getTransactionCount(this.client.rpc, { address: this.address });
   }
 
-  /**
-   * Retrieves all transactions involving this account.
-   * @description If a `PersistenceManager` is configured, this method will first attempt to retrieve transactions from the local cache.
-   * If not found in cache or if no `PersistenceManager` is configured, it will fetch transactions directly from the remote RPC.
-   * @param {GetTransactionsOptions} [options] - Optional parameters for filtering, pagination, and sorting the transactions.
-   * @param {number} [options.startBlock] - The starting block number (inclusive) from which to retrieve transactions.
-   * @param {number} [options.endBlock] - The ending block number (inclusive) up to which to retrieve transactions.
-   * @param {number} [options.page] - The page number for paginated results.
-   * @param {number} [options.offset] - The number of items to skip from the beginning of the result set.
-   * @param {'asc' | 'desc'} [options.sort] - The sorting order for transactions based on block number ('asc' for ascending, 'desc' for descending).
-   * @param {boolean} [forceFetch=false] - Forces the method to fetch transactions from the remote source even if they are already cached. (mostly used internally)
-   * @returns {Promise<Transaction[]>} A promise that resolves to an array of transactions.
-   */
   async transactions(
     params: GetTransactionsParams,
     forceFetch = false,
-  ): Promise<Transaction[]> {
+  ): Promise<RichTransaction[]> {
     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 })),
       );
-
       return transactions;
     }
 
@@ -156,41 +103,18 @@ export class Account implements AccountData {
     return jsons.map((j) => this.client.transactions.parse(j));
   }
 
-  /**
-   * Synchronizes the account's transactions with the remote data source using the configured `PersistenceManager`.
-   * @description This method initiates a synchronization process to ensure that the local cache of transactions
-   * for this account is up-to-date with the blockchain.
-   * @param {number} [limit] The maximum number of transactions to synchronize.
-   * @returns {Promise<void>} A promise that resolves when the synchronization process is complete.
-   * @throws {Error} If the persistence module is not configured.
-   */
   async syncTransactions(limit: number = 1000): Promise<void> {
     if (!this.persistenceManager)
       throw new Error("The persistence module is not configured.");
     await this.persistenceManager.syncTransactions(this, limit);
   }
 
-  /**
-   * Retrieves transactions involving a specific token. (not implemented yet)
-   * @description This method queries the persistence adapter to retrieve transactions involving a specific token.
-   * @param {Address} tokenAddress The address of the token.
-   * @returns {Promise<any>} A promise that resolves to an array of transactions involving the token.
-   * @throws {Error} If the persistence module is not configured.
-   */
   async tokenTransactions(tokenAddress: Address): Promise<any> {
     if (!this.persistenceManager)
       throw new Error("The persistence module is not configured.");
-
     return {};
   }
 
-  /**
-   * Converts the Account instance into a JSON-serializable representation.
-   * @description This method leverages a utility function to convert the `Account` object,
-   * including its asynchronous properties (like `isContract`, `ETHBalance`), into a plain JSON object.
-   * @param {number} [depth=1] The depth to which nested objects should be converted. A depth of 1 means only direct properties are included.
-   * @returns {Promise<object>} A promise that resolves to the JSON representation of the account.
-   */
   async toJSON<D extends number = 1>(depth: D): Promise<JSONAccount<D>> {
     return await toJSON({
       obj: {
@@ -204,12 +128,6 @@ export class Account implements AccountData {
     });
   }
 
-  /**
-   * Fetches transactions from the account using a block range exploration with trace_filter calls.
-   *
-   *  @param params - The parameters for the block range exploration.
-   *  @returns A Promise that resolves to an array of transaction hashes.
-   */
   protected async _fetchTransactions({
     fromBlock,
     toBlock,

package/src/structures/index.ts

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

package/src/types/index.ts

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