npm package: @mentaproject/transactions
Description: Transaction builder and gas utilities for Menta - Build, batch, and execute EVM transactions with ERC-4337 support
Author: @mentaproject
Latest version: 0.0.5

# @mentaproject/transactions

Transaction builder and gas utilities for Menta. Build, batch, and execute EVM transactions with ERC-4337 Account Abstraction support.

## Installation

```bash
npm install @mentaproject/transactions @mentaproject/core
```

## Features

- **TransactionBuilder**: Fluent API to build and batch multiple contract calls
- **GasTracker**: EIP-1559 gas estimation with slow/medium/fast tiers
- **ERC-4337 Support**: Built for Account Abstraction with UserOperation gas limits
- **Simulation**: Dry-run transactions before execution

## Usage

### TransactionBuilder

Build and execute batched transactions:

```typescript
import { TransactionBuilder } from "@mentaproject/transactions";

// Single call
const hash = await new TransactionBuilder(client)
  .addCall(erc20.transfer({ to: recipient, amount: 100n }))
  .execute();

// Batch multiple calls
const hash = await new TransactionBuilder(client)
  .addCalls([
    erc20.approve({ spender: router, amount: 1000n }),
    swap.exactIn({ tokenIn: USDC, tokenOut: ETH, amount: 1000n }),
  ])
  .execute();
```

### With Gas Configuration

```typescript
import { TransactionBuilder, GasTracker } from "@mentaproject/transactions";

const gasTracker = new GasTracker(client);
const { fast } = await gasTracker.getEstimates();

await new TransactionBuilder(client)
  .addCall(erc20.transfer({ to: recipient, amount: 100n }))
  .withGasConfig(fast)
  .execute();
```

### Simulation

Test transactions before sending:

```typescript
const builder = new TransactionBuilder(client)
  .addCall(erc20.transfer({ to: recipient, amount: 100n }));

const simulation = await builder.simulate();

// Check asset changes
for (const change of simulation.assetChanges) {
  console.log(`${change.token.symbol}: ${change.value.diff}`);
}

// Execute if simulation succeeded
await builder.execute();
```

### Gas Estimation

```typescript
import { GasTracker } from "@mentaproject/transactions";

const tracker = new GasTracker(client);
const { slow, medium, fast, baseFee } = await tracker.getEstimates();

console.log(`Base fee: ${baseFee}`);
console.log(`Fast: ${fast.maxFeePerGas} (priority: ${fast.maxPriorityFeePerGas})`);
```

Custom configuration for L2s:

```typescript
const tracker = new GasTracker(client, {
  blockCount: 10,
  percentiles: [10, 50, 90],
  minPriorityFee: 1_000_000n, // 0.001 gwei
  baseFeeMultiplierPercent: 110n, // 1.1x for stable L2s
});
```

### Transaction Metadata

Add metadata for UI display:

```typescript
const builder = new TransactionBuilder(client)
  .addCall(swap.exactIn({ ... }))
  .withMetadata({
    title: "Swap 100 USDC to ETH",
    description: "Via Uniswap V3",
  })
  .addWarning("Slippage: 0.5%");

// Get summary for UI
const summary = builder.toJSON();
// { title, description, warnings, callCount, calls }
```

### Estimate Gas Limits (ERC-4337)

```typescript
const limits = await builder.estimateGasLimits();
// {
//   callGasLimit: 150000n,        // Execution cost
//   verificationGasLimit: 250000n, // Signature validation
//   preVerificationGas: 55000n,    // Calldata overhead
// }

const totalGas = limits.callGasLimit + 
                 limits.verificationGasLimit + 
                 limits.preVerificationGas;
```

## API Reference

### TransactionBuilder

| Method | Description |
|--------|-------------|
| `addCall(call)` | Add a single call |
| `addCalls(calls)` | Add multiple calls |
| `withGasConfig(config)` | Set gas configuration |
| `withMetadata(meta)` | Set transaction metadata |
| `addWarning(warning)` | Add a warning message |
| `simulate()` | Dry-run the transaction |
| `estimateGasLimits()` | Get ERC-4337 gas limits |
| `execute()` | Send the transaction |
| `toJSON()` | Get summary for UI |

### GasTracker

| Method | Description |
|--------|-------------|
| `getEstimates()` | Get slow/medium/fast estimates |
| `slow()` | Get slow estimate only |
| `medium()` | Get medium estimate only |
| `fast()` | Get fast estimate only |

### Types

```typescript
interface GasEstimate {
  maxFeePerGas: bigint;
  maxPriorityFeePerGas: bigint;
}

interface GasLimits {
  callGasLimit: bigint;
  verificationGasLimit: bigint;
  preVerificationGas: bigint;
}

interface TransactionMetadata {
  title?: string;
  description?: string;
  warnings?: string[];
}
```

## License

MIT