@mentaproject/client 0.2.0 → 0.2.2

package/src/managers/TransactionManager.ts

@@ -2,22 +2,24 @@
  * @module TransactionManager
  */
 import { GetTransactionParameters, Transaction as RawTransaction, SendTransactionParameters } from "@mentaproject/core/types";
-import { Transaction as RichTransaction } from "../structures/Transaction";
+import { TransactionRecord } from "../structures/TransactionRecord";
 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";
+import { withGasSupport, 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();
@@ -32,26 +34,28 @@ export class TransactionManager {
 
   /**
    * 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 {
-    return new MulticallTransaction(this.client.rpc);
+  create(): WithGas<MulticallTransaction> {
+    const tx = new MulticallTransaction(this.client.rpc);
+    return withGasSupport(tx, this.client.gas);
   }
 
   /**
-   * 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
@@ -59,22 +63,22 @@ export class TransactionManager {
    * console.log(tx.from, tx.to, tx.value);
    * ```
    */
-  async fromHash(hash: `0x${string}`): Promise<RichTransaction> {
+  async fromHash(hash: `0x${string}`): Promise<TransactionRecord> {
     return this.get({ hash });
   }
 
   /**
    * Retrieves a transaction by its hash or block number and index.
    */
-  async get(params: GetTransactionParameters): Promise<RichTransaction> {
+  async get(params: GetTransactionParameters): Promise<TransactionRecord> {
     const data = await getTransaction(this.client.rpc, params);
-    return new RichTransaction(this.client, data);
+    return new TransactionRecord(this.client, data);
   }
 
   /**
    * 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 {
     const parsed = parseBingints(data);
 
     const rawData = {
@@ -83,14 +87,14 @@ export class TransactionManager {
       to: parsed.to ? parsed.to.address : null,
     };
 
-    return new RichTransaction(this.client, rawData as RawTransaction);
+    return new TransactionRecord(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> {
+  async send(params: SendTransactionParameters): Promise<TransactionRecord> {
     const hash = await sendTransaction(this.client.rpc, params);
     return await this.get({ hash });
   }

package/src/managers/index.ts

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

package/src/structures/Account.ts

@@ -11,7 +11,7 @@ import type {
   Hash,
   onBlockRangeCallback,
 } from "@mentaproject/core/types";
-import { Transaction as RichTransaction } from "./Transaction";
+import { TransactionRecord } from "./TransactionRecord";
 import { Transaction } from "@mentaproject/transactions";
 import { toHex } from "@mentaproject/core/utils";
 import {
@@ -24,6 +24,7 @@ import { getContractType } from "@mentaproject/contracts";
 import { toJSON } from "../utils/toJSON";
 import { PersistenceManager } from "../managers/PersistenceManager";
 import { MentaClient } from "./MentaClient";
+import { withGasSupport, WithGas } from "../utils/withGasSupport";
 
 /**
  * Represents a blockchain account with functionalities to interact with the Menta blockchain.
@@ -55,25 +56,29 @@ export class Account implements AccountData {
 
   /**
    * 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 {
-    return new Transaction(this.client.rpc, {
+  sendEth(amount: bigint): WithGas<Transaction> {
+    const tx = new Transaction(this.client.rpc, {
       to: this.address,
       value: amount,
     });
+    return withGasSupport(tx, this.client.gas);
   }
 
   async ETHBalance(): Promise<bigint> {
@@ -87,7 +92,7 @@ export class Account implements AccountData {
   async transactions(
     params: GetTransactionsParams,
     forceFetch = false,
-  ): Promise<RichTransaction[]> {
+  ): Promise<TransactionRecord[]> {
     if (!this.persistenceManager || forceFetch) {
       const hashes = await this._fetchTransactions(params);
       const transactions = await Promise.all(

package/src/structures/Block.ts

@@ -1,7 +1,7 @@
 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 { toJSON } from "../utils/toJSON";
 import { MentaClient } from "./MentaClient";
@@ -119,7 +119,7 @@ export 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.
@@ -157,12 +157,12 @@ export class Block implements Omit<RawBlock, "miner" | "transactions"> {
         this.miner = new Account(this.client, { address: data.miner});
         
         if (!data.transactions || data.transactions.length === 0) {
-            const parsed = data.transactions.map((data) => typeof data === "string" ? data : new Transaction(this.client, data))
-            this.transactions = parsed as Transaction[] | Hash[];
+            const parsed = data.transactions.map((data) => typeof data === "string" ? data : new TransactionRecord(this.client, data))
+            this.transactions = parsed as TransactionRecord[] | Hash[];
         }
     };
 
-    protected includeTransactions(): this is this & { transactions: Transaction[] } {
+    protected includeTransactions(): this is this & { transactions: TransactionRecord[] } {
         if (!this.transactions || this.transactions.length === 0) return false;
         return true
     }

package/src/structures/MentaClient.ts

@@ -10,6 +10,7 @@ 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,
@@ -20,18 +21,29 @@ 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 class MentaClient {
   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.
    */
   public get rpc(): MentaAccountClient {
     if (!this._rpc) {
@@ -42,7 +54,6 @@ export class MentaClient {
 
   /**
    * The account associated with the client.
-   * @description This account is used for signing transactions and interacting with the blockchain.
    */
   public get account(): Account {
     if (!this._account) {
@@ -51,46 +62,44 @@ export class MentaClient {
     return this._account;
   }
 
+  /**
+   * Manager for gas estimation and configuration.
+   */
+  public get gas(): GasManager {
+    if (!this._gas) {
+      throw new Error("Gas manager not initialized");
+    }
+    return this._gas;
+  }
+
+  /**
+   * Default gas strategy for transactions.
+   */
+  public defaultGasStrategy?: GasStrategy;
+
   /**
    * Manager for block-related operations.
-   * @description Provides methods to query and interact with blockchain blocks.
    */
   public blocks!: BlockManager;
   /**
    * Manager for transaction-related operations.
-   * @description Provides methods to send, query, and manage blockchain transactions.
    */
   public transactions!: TransactionManager;
   /**
    * Manager for contract-related operations.
-   * @description Provides methods to deploy, interact with, and query smart contracts.
    */
   public contracts!: ContractManager;
   /**
    * Manager for account-related operations.
-   * @description Provides methods to manage and interact with blockchain accounts.
    */
   public accounts!: AccountManager;
+  /**
+   * Optional manager for persistence-related operations.
+   */
+  public 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,
@@ -108,30 +117,16 @@ export class MentaClient {
 
   /**
    * 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(protected params: MentaClientConfig) {
     this.blocks = new BlockManager(this);
     this.transactions = new TransactionManager(this);
     this.contracts = new ContractManager(this);
 
+    if (params.gas?.strategy) {
+      this.defaultGasStrategy = params.gas.strategy;
+    }
+
     if (params.persistenceAdapter) {
       this.persistenceManager = new PersistenceManager(
         this,
@@ -158,12 +153,6 @@ export class MentaClient {
     });
 
     this._account = this.accounts.get(this.rpc.account.address);
+    this._gas = new GasManager(this.rpc);
   }
-
-  /**
-   * 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.
-   */
-  public persistenceManager?: PersistenceManager;
 }

package/src/structures/{Transaction.ts → TransactionRecord.ts}

@@ -17,7 +17,7 @@ import { JSONTransaction, TransactionCall } from '../types';
  * providing methods to interact with the blockchain to retrieve transaction-related information such as
  * internal calls, receipts, and the block it belongs to.
  */
-export class Transaction implements Omit<RawTransaction, "from" | "to"> {
+export class TransactionRecord implements Omit<RawTransaction, "from" | "to"> {
   /**
    * @description The access list for the transaction.
    */

package/src/structures/index.ts

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

package/src/types/MentaClient.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.
@@ -20,6 +21,17 @@ 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`.
@@ -48,6 +60,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;
 }
 
 /**

package/src/types/PersistenceAdapter.ts

@@ -1,6 +1,6 @@
 import { Address } from '@mentaproject/core/types';
 
-import { Transaction } from '../structures/Transaction';
+import { TransactionRecord } from '../structures/TransactionRecord';
 import { GetTransactionsParams } from './Account';
 import { JSONTransaction } from './Transaction';
 
@@ -12,16 +12,16 @@ 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/src/utils/withGasSupport.ts

@@ -0,0 +1,50 @@
+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 function withGasSupport<T extends BaseTransaction>(
+  tx: T,
+  gasManager: GasManager,
+): WithGas<T> {
+  const enhanced = tx as WithGas<T>;
+
+  enhanced.withGas = async (strategy: GasStrategy): Promise<T> => {
+    const config = await gasManager.estimate(strategy);
+    tx.withGasConfig(config);
+    return tx;
+  };
+
+  return enhanced;
+}