@mentaproject/client 0.2.0 → 0.2.2

package/dist/managers/GasManager.d.ts

@@ -0,0 +1,36 @@
+import { MentaAccountClient } from "@mentaproject/core/types";
+import { GasTracker, GasEstimate, GasEstimates } from "@mentaproject/transactions";
+export type GasStrategy = "slow" | "medium" | "fast";
+/**
+ * Manages gas estimation and configuration.
+ *
+ * @example
+ * ```ts
+ * // Get all prices
+ * const prices = await client.gas.getPrices();
+ * console.log(prices.fast.maxFeePerGas);
+ *
+ * // Get specific estimate
+ * const fast = await client.gas.estimate("fast");
+ * tx.withGasConfig(fast);
+ * ```
+ */
+export declare class GasManager {
+    private client;
+    private tracker;
+    constructor(client: MentaAccountClient);
+    /**
+     * Gets all gas price estimates (slow, medium, fast).
+     */
+    getPrices(): Promise<GasEstimates>;
+    /**
+     * Gets a specific gas estimate by strategy.
+     *
+     * @param strategy - "slow", "medium", or "fast"
+     */
+    estimate(strategy: GasStrategy): Promise<GasEstimate>;
+    /**
+     * Gets the underlying GasTracker for advanced usage.
+     */
+    getTracker(): GasTracker;
+}

package/dist/managers/TransactionManager.d.ts

@@ -2,19 +2,21 @@
  * @module TransactionManager
  */
 import { GetTransactionParameters, SendTransactionParameters } from "@mentaproject/core/types";
-import { Transaction as RichTransaction } from "../structures/Transaction";
+import { TransactionRecord } from "../structures/TransactionRecord";
 import { MulticallTransaction } from "@mentaproject/transactions";
 import { MentaClient } from "../structures";
 import { JSONTransaction } from "../types";
+import { WithGas } from "../utils/withGasSupport";
 /**
  * Manages blockchain transaction-related operations.
  *
  * @example
  * ```ts
- * // Create a multicall transaction
+ * // Create a multicall transaction with gas support
  * const pending = await client.transactions.create()
  *   .addCall(account.sendEth(parseEther("1")))
  *   .addCall(erc20.transfer(to, amount))
+ *   .withGas("fast")
  *   .execute();
  *
  * const receipt = await pending.confirm();
@@ -29,23 +31,24 @@ export declare class TransactionManager {
     constructor(client: MentaClient);
     /**
      * Creates a new MulticallTransaction for batching multiple calls.
+     * Enhanced with withGas() support for easy gas configuration.
      *
-     * @returns A MulticallTransaction builder
+     * @returns A MulticallTransaction builder with withGas() support
      *
      * @example
      * ```ts
      * const pending = await client.transactions.create()
      *   .addCall(account.sendEth(parseEther("1")))
-     *   .addCall(erc20.transfer(to, amount))
+     *   .withGas("fast")
      *   .execute();
      * ```
      */
-    create(): MulticallTransaction;
+    create(): WithGas<MulticallTransaction>;
     /**
-     * Retrieves a rich transaction by its hash.
+     * Retrieves a transaction record by its hash.
      *
      * @param hash - The transaction hash
-     * @returns A rich Transaction with receipt, block, etc.
+     * @returns A TransactionRecord with receipt, block, etc.
      *
      * @example
      * ```ts
@@ -53,18 +56,18 @@ export declare class TransactionManager {
      * console.log(tx.from, tx.to, tx.value);
      * ```
      */
-    fromHash(hash: `0x${string}`): Promise<RichTransaction>;
+    fromHash(hash: `0x${string}`): Promise<TransactionRecord>;
     /**
      * Retrieves a transaction by its hash or block number and index.
      */
-    get(params: GetTransactionParameters): Promise<RichTransaction>;
+    get(params: GetTransactionParameters): Promise<TransactionRecord>;
     /**
      * Parse a transaction object from a JSON converted transaction data object.
      */
-    parse<J extends JSONTransaction<0>>(data: J): RichTransaction;
+    parse<J extends JSONTransaction<0>>(data: J): TransactionRecord;
     /**
      * Sends a transaction to the blockchain network.
      * @deprecated Use client.transactions.create() for new transactions
      */
-    send(params: SendTransactionParameters): Promise<RichTransaction>;
+    send(params: SendTransactionParameters): Promise<TransactionRecord>;
 }

package/dist/managers/index.d.ts

@@ -1,4 +1,5 @@
 export * from './AccountManager';
 export * from './BlockManager';
 export * from './ContractManager';
+export * from './GasManager';
 export * from './TransactionManager';

package/dist/structures/Account.d.ts

@@ -1,9 +1,10 @@
 import type { Address, Hash } from "@mentaproject/core/types";
-import { Transaction as RichTransaction } from "./Transaction";
+import { TransactionRecord } from "./TransactionRecord";
 import { Transaction } from "@mentaproject/transactions";
 import { AccountData, FetchTransactionParams, GetTransactionsParams, JSONAccount } from "../types/Account";
 import { PersistenceManager } from "../managers/PersistenceManager";
 import { MentaClient } from "./MentaClient";
+import { WithGas } from "../utils/withGasSupport";
 /**
  * Represents a blockchain account with functionalities to interact with the Menta blockchain.
  */
@@ -16,24 +17,27 @@ export declare class Account implements AccountData {
     contractType(): Promise<any>;
     /**
      * Creates a Transaction to send ETH to this account.
+     * Enhanced with withGas() support for easy gas configuration.
      *
      * @param amount The amount of ETH to send, in wei.
-     * @returns A Transaction with .call(), .simulate(), and .execute() methods.
+     * @returns A Transaction with withGas(), .call(), .simulate(), and .execute() methods.
      *
      * @example
      * ```ts
-     * // Direct execution
-     * const pending = await account.sendEth(parseEther("1")).execute();
+     * // With gas config
+     * const pending = await account.sendEth(parseEther("1"))
+     *   .withGas("fast")
+     *   .execute();
      * const receipt = await pending.confirm();
      *
      * // Batch with MulticallTransaction
      * multicall.addCall(account.sendEth(parseEther("1")));
      * ```
      */
-    sendEth(amount: bigint): Transaction;
+    sendEth(amount: bigint): WithGas<Transaction>;
     ETHBalance(): Promise<bigint>;
     transactionCount(): Promise<number>;
-    transactions(params: GetTransactionsParams, forceFetch?: boolean): Promise<RichTransaction[]>;
+    transactions(params: GetTransactionsParams, forceFetch?: boolean): Promise<TransactionRecord[]>;
     syncTransactions(limit?: number): Promise<void>;
     tokenTransactions(tokenAddress: Address): Promise<any>;
     toJSON<D extends number = 1>(depth: D): Promise<JSONAccount<D>>;

package/dist/structures/Block.d.ts

@@ -1,6 +1,6 @@
 import { Block as RawBlock, Hash, Hex, Withdrawal } from "@mentaproject/core";
 import { Account } from "./Account";
-import { Transaction } from "./Transaction";
+import { TransactionRecord } from "./TransactionRecord";
 import { JSONBlock } from "../types/Block";
 import { MentaClient } from "./MentaClient";
 /**
@@ -116,7 +116,7 @@ export declare class Block implements Omit<RawBlock, "miner" | "transactions"> {
     /**
      * @description The transactions included in the block, represented as an array of Transaction instances.
      */
-    transactions?: Transaction[] | Hash[];
+    transactions?: TransactionRecord[] | Hash[];
     /**
      * @description Creates an instance of Block.
      * @param client - The instance of MentaClient used to interact with the blockchain.
@@ -125,7 +125,7 @@ export declare class Block implements Omit<RawBlock, "miner" | "transactions"> {
      */
     constructor(client: MentaClient, data: RawBlock);
     protected includeTransactions(): this is this & {
-        transactions: Transaction[];
+        transactions: TransactionRecord[];
     };
     /**
      * @description Converts the Block instance to a JSON representation.

package/dist/structures/MentaClient.d.ts

@@ -7,98 +7,75 @@ import { TransactionManager } from "../managers/TransactionManager";
 import { ContractManager } from "../managers/ContractManager";
 import { AccountManager } from "../managers/AccountManager";
 import { PersistenceManager } from "../managers/PersistenceManager";
+import { GasManager, GasStrategy } from "../managers/GasManager";
 import { ClientEvents, GetListenerCallback, MentaClientConfig } from "../types/MentaClient";
 import { Account } from "./Account";
 /**
  * The main client for interacting with the Menta API.
- * It provides managers for blocks, transactions, contracts, and accounts.
+ * It provides managers for blocks, transactions, contracts, accounts, and gas.
  *
- * @description This class serves as the primary entry point for interacting with the Menta blockchain.
- * It encapsulates the core RPC client and provides specialized managers for various blockchain entities,
- * simplifying common operations.
+ * @example
+ * ```ts
+ * const client = new MentaClient({
+ *   url: 'http://rpcurlhere.com',
+ *   gas: { strategy: 'fast' }, // Default gas strategy
+ * });
+ *
+ * await client.init();
+ *
+ * // Use gas manager
+ * const prices = await client.gas.getPrices();
+ * const fastConfig = await client.gas.estimate('fast');
+ * ```
  */
 export declare class MentaClient {
     protected params: MentaClientConfig;
     protected _rpc?: MentaAccountClient;
     protected _account?: Account;
+    protected _gas?: GasManager;
     /**
      * The underlying RPC client used for blockchain interactions.
-     * @description This client is responsible for low-level communication with the RPC node.
      */
     get rpc(): MentaAccountClient;
     /**
      * The account associated with the client.
-     * @description This account is used for signing transactions and interacting with the blockchain.
      */
     get account(): Account;
+    /**
+     * Manager for gas estimation and configuration.
+     */
+    get gas(): GasManager;
+    /**
+     * Default gas strategy for transactions.
+     */
+    defaultGasStrategy?: GasStrategy;
     /**
      * Manager for block-related operations.
-     * @description Provides methods to query and interact with blockchain blocks.
      */
     blocks: BlockManager;
     /**
      * Manager for transaction-related operations.
-     * @description Provides methods to send, query, and manage blockchain transactions.
      */
     transactions: TransactionManager;
     /**
      * Manager for contract-related operations.
-     * @description Provides methods to deploy, interact with, and query smart contracts.
      */
     contracts: ContractManager;
     /**
      * Manager for account-related operations.
-     * @description Provides methods to manage and interact with blockchain accounts.
      */
     accounts: AccountManager;
+    /**
+     * Optional manager for persistence-related operations.
+     */
+    persistenceManager?: PersistenceManager;
     /**
      * Subscribes to a specific client event.
-     * @template TEvent The type of the event to listen for.
-     * @param {TEvent} event - The event to listen for (e.g., 'block', 'transaction').
-     * @param {GetListenerCallback<TEvent>} callback - The callback function to execute when the event is triggered.
-     * @returns {() => void} An unsubscribe function to stop listening to the event.
-     * @description This method allows the client to listen for real-time events from the blockchain, such as new blocks or transactions.
-     * @example
-     * import { MentaClient } from '@mentaproject/client';
-     *
-     * const client = new MentaClient({ url: 'http://rpcurlhere.com' });
-     *
-     * // Subscribe to new blocks
-     * const unsubscribe = client.on('block', (block) => {
-     *   console.log('New block received:', block);
-     * });
-     *
-     * // To stop listening
-     * // unsubscribe();
      */
     on<TEvent extends keyof typeof ClientEvents>(event: TEvent, callback: GetListenerCallback<TEvent>): any;
     /**
      * Creates an instance of MentaClient.
-     * @param {MentaClientConfig} params - The configuration parameters for the client.
-     * @description The constructor initializes the RPC client and the various managers based on the provided configuration.
-     * It also applies caching and persistence if specified in the configuration.
-     * @example
-     * import { MentaClient } from '@mentaproject/client';
-     *
-     * // Basic initialization
-     * const client = new MentaClient({
-     *   url: 'http://rpcurlhere.com',
-     * });
-     *
-     * // Initialization with a persistent cache
-     * const clientWithCache = new MentaClient({
-     *   url: 'http://rpcurlhere.com',
-     *   cache: {
-     *     ttl: 60000, // 1 minute
-     *   },
-     * });
      */
     constructor(params: MentaClientConfig);
     init(): Promise<void>;
-    /**
-     * Optional manager for persistence-related operations.
-     * @description This manager is initialized if a persistence adapter is provided in the client configuration,
-     * allowing for data storage and retrieval.
-     */
-    persistenceManager?: PersistenceManager;
 }

package/dist/structures/TransactionRecord.d.ts

@@ -0,0 +1,138 @@
+import { AccessList, Hash, Hex, Transaction as RawTransaction, WaitForTransactionReceiptReturnType } from '@mentaproject/core/types';
+import { Account } from './Account';
+import { Block } from './Block';
+import { MentaClient } from './MentaClient';
+import { JSONTransaction, TransactionCall } from '../types';
+/**
+ * Represents a blockchain transaction with its properties and methods.
+ *
+ * @description This class encapsulates the data and functionalities related to an Ethereum-like transaction,
+ * providing methods to interact with the blockchain to retrieve transaction-related information such as
+ * internal calls, receipts, and the block it belongs to.
+ */
+export declare class TransactionRecord implements Omit<RawTransaction, "from" | "to"> {
+    protected client: MentaClient;
+    /**
+     * @description The access list for the transaction.
+     */
+    accessList?: AccessList;
+    /**
+     * @description The blob versioned hashes.
+     */
+    blobVersionedHashes?: readonly Hex[];
+    /**
+     * @description The gas limit for the transaction.
+     */
+    gas: bigint;
+    /**
+     * @description The gas price for the transaction.
+     */
+    gasPrice?: bigint;
+    /**
+     * @description The hash of the transaction.
+     */
+    hash: Hash;
+    /**
+     * @description The input data for the transaction.
+     */
+    input: Hex;
+    /**
+     * @description The maximum fee per gas.
+     */
+    maxFeePerGas?: bigint;
+    /**
+     * @description The maximum priority fee per gas.
+     */
+    maxPriorityFeePerGas?: bigint;
+    /**
+     * @description The nonce of the transaction.
+     */
+    nonce: number;
+    /**
+     * @description The r value of the signature.
+     */
+    r: Hex;
+    /**
+     * @description The s value of the signature.
+     */
+    s: Hex;
+    /**
+     * @description The index of the transaction within the block.
+     */
+    transactionIndex: number | null;
+    /**
+     * @description The type of the transaction.
+     */
+    type: "legacy" | "eip2930" | "eip1559" | "eip4844" | "eip7702";
+    /**
+     * @description The v value of the signature.
+     */
+    v: bigint;
+    /**
+     * @description The value transferred in the transaction.
+     */
+    value: bigint;
+    /**
+     * @description The y parity of the signature.
+     */
+    yParity?: number;
+    /**
+     * @description The hash of the block containing this transaction.
+     */
+    blockHash: Hash | null;
+    /**
+     * @description The number of the block containing this transaction.
+     */
+    blockNumber: bigint | null;
+    /**
+     * @description The hex representation of the type of the transaction.
+     */
+    typeHex: `0x${string}` | null;
+    /**
+     * @description The sender account of the transaction.
+     */
+    from?: Account;
+    /**
+     * @description The recipient account of the transaction.
+     */
+    to?: Account;
+    /**
+     * Creates an instance of Transaction.
+     * @description Initializes a new Transaction instance with the provided RPC client and transaction data.
+     * @param {MentaClient} client - The instance of MentaClient used to interact with the blockchain.
+     * @param {ITransactionData} data The raw transaction data.
+     */
+    constructor(client: MentaClient, data: RawTransaction);
+    /**
+     * Retrieves the internal calls made by this transaction.
+     * @description Fetches and processes the transaction traces to extract internal call details.
+     * @returns {Promise<TransactionCall[] | undefined>} A promise that resolves to an array of call objects, each representing an internal call with sender, recipient, value, input data, gas used, and call type.
+     */
+    calls(): Promise<TransactionCall[] | undefined>;
+    /**
+     * Waits for the transaction receipt to be available.
+     * @description Asynchronously waits for the transaction to be confirmed on the blockchain and its receipt to be available.
+     * @param {number} [confirmations] The number of confirmations to wait for. Defaults to 1.
+     * @returns {Promise<WaitForTransactionReceiptReturnType>} A promise that resolves to the transaction receipt once the specified number of confirmations are met.
+     */
+    waitForReceipt(confirmations?: number): Promise<WaitForTransactionReceiptReturnType>;
+    /**
+     * Retrieves the transaction receipt.
+     * @description Fetches the transaction receipt for the current transaction hash.
+     * @returns {Promise<WaitForTransactionReceiptReturnType>} A promise that resolves to the transaction receipt.
+     */
+    receipt(): Promise<WaitForTransactionReceiptReturnType | undefined>;
+    /**
+     * Retrieves the block containing this transaction.
+     * @description Fetches the block data using the transaction's block hash and returns a Block instance.
+     * @returns {Promise<Block>} A promise that resolves to a Block instance representing the block that includes this transaction.
+     */
+    block(): Promise<Block>;
+    /**
+     * Converts the Transaction instance to a JSON representation.
+     * @description Serializes the transaction instance into a JSON object, including nested representations of related entities like block, receipt, and internal calls based on the specified depth.
+     * @param {number} [depth=1] The depth of the conversion. Controls how deeply nested objects are serialized.
+     * @returns {Promise<object>} A promise that resolves to the JSON representation of the transaction.
+     */
+    toJSON<D extends number = 1>(depth: D): Promise<JSONTransaction<D>>;
+}

package/dist/structures/index.d.ts

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

package/dist/types/MentaClient.d.ts

@@ -6,6 +6,7 @@ import { ICache } from "./Cache";
 import { watchBlockNumber, watchBlocks } from "@mentaproject/core/actions";
 import { IPersistenceAdapter } from "./PersistenceAdapter";
 import { WebAuthnAccount } from "@mentaproject/core/account-abstraction";
+import { GasStrategy } from "../managers/GasManager";
 /**
  * Configuration for the client's cache.
  * @interface CacheConfig
@@ -18,6 +19,16 @@ export interface CacheConfig {
      */
     ttl_policies: Record<string, number>;
 }
+/**
+ * Gas configuration for the client.
+ */
+export interface GasConfig {
+    /**
+     * Default gas strategy for all transactions.
+     * Can be overridden per transaction with withGas() or withGasConfig().
+     */
+    strategy: GasStrategy;
+}
 /**
  * Configuration options for the MentaClient.
  * Extends {@link CoreClientConfig} from `@mentaproject/core`.
@@ -46,6 +57,11 @@ export interface MentaClientConfig extends CoreClientConfig {
      * Validator address used for userOperations
      */
     validatorAddress: Address;
+    /**
+     * Optional gas configuration.
+     * If provided, sets the default gas strategy for all transactions.
+     */
+    gas?: GasConfig;
 }
 /**
  * Defines the available client events and their corresponding watch functions.

package/dist/types/PersistenceAdapter.d.ts

@@ -1,5 +1,5 @@
 import { Address } from '@mentaproject/core/types';
-import { Transaction } from '../structures/Transaction';
+import { TransactionRecord } from '../structures/TransactionRecord';
 import { GetTransactionsParams } from './Account';
 import { JSONTransaction } from './Transaction';
 /**
@@ -10,15 +10,15 @@ 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.
+     * @param {TransactionRecord[]} 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>;
+    upsertTransactions(transactions: TransactionRecord[]): 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.
+     * @returns {Promise<JSONTransactionRecord[]>} A Promise that resolves with transactions objects.
      */
     getTransactions(address: Address, params: GetTransactionsParams): Promise<JSONTransaction<0>[]>;
     /**

package/dist/utils/withGasSupport.d.ts

@@ -0,0 +1,35 @@
+import { BaseTransaction } from "@mentaproject/transactions";
+import { GasManager, GasStrategy } from "../managers/GasManager";
+/**
+ * Transaction enhanced with withGas() support.
+ */
+export type WithGas<T extends BaseTransaction> = T & {
+    /**
+     * Sets gas configuration using a strategy (easy mode).
+     * Uses the client's GasManager for estimation.
+     *
+     * @param strategy - "slow", "medium", or "fast"
+     *
+     * @example
+     * ```ts
+     * await tx.withGas("fast").execute();
+     * ```
+     */
+    withGas(strategy: GasStrategy): Promise<T>;
+};
+/**
+ * Enhances a transaction with withGas() support.
+ * This injects the client's GasManager for gas estimation.
+ *
+ * @param tx - The transaction to enhance
+ * @param gasManager - The client's GasManager
+ * @returns The enhanced transaction with withGas() method
+ *
+ * @example
+ * ```ts
+ * const tx = new Transaction(client.rpc, call);
+ * const enhanced = withGasSupport(tx, client.gas);
+ * await enhanced.withGas("fast").execute();
+ * ```
+ */
+export declare function withGasSupport<T extends BaseTransaction>(tx: T, gasManager: GasManager): WithGas<T>;

package/package.json

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

package/src/managers/GasManager.ts

@@ -0,0 +1,50 @@
+import { MentaAccountClient } from "@mentaproject/core/types";
+import { GasTracker, GasEstimate, GasEstimates } from "@mentaproject/transactions";
+
+export type GasStrategy = "slow" | "medium" | "fast";
+
+/**
+ * Manages gas estimation and configuration.
+ *
+ * @example
+ * ```ts
+ * // Get all prices
+ * const prices = await client.gas.getPrices();
+ * console.log(prices.fast.maxFeePerGas);
+ *
+ * // Get specific estimate
+ * const fast = await client.gas.estimate("fast");
+ * tx.withGasConfig(fast);
+ * ```
+ */
+export class GasManager {
+  private tracker: GasTracker;
+
+  constructor(private client: MentaAccountClient) {
+    this.tracker = new GasTracker(client);
+  }
+
+  /**
+   * Gets all gas price estimates (slow, medium, fast).
+   */
+  async getPrices(): Promise<GasEstimates> {
+    return this.tracker.getEstimates();
+  }
+
+  /**
+   * Gets a specific gas estimate by strategy.
+   *
+   * @param strategy - "slow", "medium", or "fast"
+   */
+  async estimate(strategy: GasStrategy): Promise<GasEstimate> {
+    const prices = await this.getPrices();
+    return prices[strategy];
+  }
+
+  /**
+   * Gets the underlying GasTracker for advanced usage.
+   */
+  getTracker(): GasTracker {
+    return this.tracker;
+  }
+}

package/src/managers/PersistenceManager.ts

@@ -2,7 +2,7 @@ import { getBlockNumber } from '@mentaproject/core/actions';
 import { Address } from '@mentaproject/core/types';
 
 import { Account } from '../structures/Account';
-import { MentaClient, Transaction } from '../structures';
+import { MentaClient, TransactionRecord } from '../structures';
 import { bigIntMax } from '../utils/bigint';
 import { GetTransactionsParams, IPersistenceAdapter, JSONTransaction } from 'src/types';