@aztec/ethereum 4.0.0-nightly.20250907 → 4.0.0-nightly.20260107

package/src/l1_tx_utils/fee-strategies/p75_competitive_blob_txs_only.ts

@@ -0,0 +1,245 @@
+import { median } from '@aztec/foundation/collection';
+
+import { type GetFeeHistoryReturnType, formatGwei } from 'viem';
+
+import type { ViemClient } from '../../types.js';
+import { calculatePercentile, isBlobTransaction } from '../../utils.js';
+import { WEI_CONST } from '../constants.js';
+import {
+  HISTORICAL_BLOCK_COUNT,
+  type PriorityFeeStrategy,
+  type PriorityFeeStrategyContext,
+  type PriorityFeeStrategyResult,
+} from './types.js';
+
+/**
+ * Fetches historical blocks and calculates reward percentiles for blob transactions only.
+ * Returns data in the same format as getFeeHistory for easy drop-in replacement.
+ *
+ * @param client - Viem client to use for RPC calls
+ * @param blockCount - Number of historical blocks to fetch
+ * @param rewardPercentiles - Array of percentiles to calculate (e.g., [75] for 75th percentile)
+ * @returns Object with reward field containing percentile fees for each block, similar to getFeeHistory
+ * @throws Error if fetching blocks fails
+ */
+export async function getBlobPriorityFeeHistory(
+  client: ViemClient,
+  blockCount: number,
+  rewardPercentiles: number[],
+): Promise<GetFeeHistoryReturnType> {
+  const latestBlockNumber = await client.getBlockNumber();
+
+  // Fetch multiple blocks in parallel
+  const blockPromises = Array.from({ length: blockCount }, (_, i) =>
+    client.getBlock({
+      blockNumber: latestBlockNumber - BigInt(i),
+      includeTransactions: true,
+    }),
+  );
+
+  const blocks = await Promise.all(blockPromises);
+
+  // Process each block to extract blob transaction fees and other data
+  const baseFeePerGas: bigint[] = [];
+  const gasUsedRatio: number[] = [];
+  const reward: bigint[][] = [];
+
+  for (const block of blocks) {
+    // Collect base fee per gas
+    baseFeePerGas.push(block.baseFeePerGas || 0n);
+
+    // Calculate gas used ratio
+    const gasUsed = block.gasUsed || 0n;
+    const gasLimit = block.gasLimit || 1n; // Avoid division by zero
+    gasUsedRatio.push(Number(gasUsed) / Number(gasLimit));
+
+    if (!block.transactions || block.transactions.length === 0) {
+      // No transactions in this block - return zeros for each percentile
+      reward.push(rewardPercentiles.map(() => 0n));
+      continue;
+    }
+
+    // Extract priority fees from blob transactions only
+    const blobFees = block.transactions
+      .map(tx => {
+        // Transaction can be just a hash string
+        if (typeof tx === 'string') {
+          return 0n;
+        }
+
+        if (!isBlobTransaction(tx)) {
+          return 0n;
+        }
+        return tx.maxPriorityFeePerGas || 0n;
+      })
+      .filter((fee: bigint) => fee > 0n);
+
+    if (blobFees.length === 0) {
+      // No blob transactions in this block - return zeros for each percentile
+      reward.push(rewardPercentiles.map(() => 0n));
+      continue;
+    }
+
+    // Calculate requested percentiles
+    const percentiles = rewardPercentiles.map(percentile => calculatePercentile(blobFees, percentile));
+
+    reward.push(percentiles);
+  }
+
+  // Calculate oldest block number (the last block in our array)
+  const oldestBlock = latestBlockNumber - BigInt(blockCount - 1);
+
+  // Reverse arrays to match getFeeHistory behavior (oldest first)
+  return {
+    baseFeePerGas: baseFeePerGas.reverse(),
+    gasUsedRatio: gasUsedRatio.reverse(),
+    oldestBlock,
+    reward: reward.reverse(),
+  };
+}
+
+/**
+ * Similar to our current competitive priority fee strategy, but only considers blob transactions
+ * when calculating competitive priority fee for blob transactions.
+ * This strategy also has NO cap on the competitive fee if it's much higher than the network estimate.
+ * Analyzes p75 of pending transactions and 5-block fee history to determine a competitive priority fee.
+ * Falls back to network estimate if data is unavailable.
+ */
+export const P75BlobTxsOnlyPriorityFeeStrategy: PriorityFeeStrategy = {
+  name: 'Competitive (P75 + History) - Blob Txs Only',
+  id: 'p75_pending_txs_and_history_blob_txs_only',
+
+  async execute(client: ViemClient, context: PriorityFeeStrategyContext): Promise<PriorityFeeStrategyResult> {
+    const { isBlobTx, logger } = context;
+
+    // Fire all RPC calls in parallel
+    const [latestBlockResult, blobBaseFeeResult, networkEstimateResult, pendingBlockResult, feeHistoryResult] =
+      await Promise.allSettled([
+        client.getBlock({ blockTag: 'latest' }),
+        isBlobTx ? client.getBlobBaseFee() : Promise.resolve(undefined),
+        client.estimateMaxPriorityFeePerGas().catch(() => 0n),
+        client.getBlock({ blockTag: 'pending', includeTransactions: true }).catch(() => null),
+        isBlobTx
+          ? getBlobPriorityFeeHistory(client, HISTORICAL_BLOCK_COUNT, [75])
+          : client
+              .getFeeHistory({
+                blockCount: HISTORICAL_BLOCK_COUNT,
+                rewardPercentiles: [75],
+                blockTag: 'latest',
+              })
+              .catch(() => null),
+      ]);
+
+    // Extract latest block (required)
+    if (latestBlockResult.status === 'rejected') {
+      throw new Error(`Failed to get latest block: ${latestBlockResult.reason}`);
+    }
+    const latestBlock = latestBlockResult.value;
+
+    // Extract blob base fee (only for blob txs)
+    let blobBaseFee: bigint | undefined;
+    if (isBlobTx) {
+      if (blobBaseFeeResult.status === 'fulfilled' && typeof blobBaseFeeResult.value === 'bigint') {
+        blobBaseFee = blobBaseFeeResult.value;
+      } else {
+        logger?.warn('Failed to get L1 blob base fee');
+      }
+    }
+
+    // Extract network estimate
+    const networkEstimate =
+      networkEstimateResult.status === 'fulfilled' && typeof networkEstimateResult.value === 'bigint'
+        ? networkEstimateResult.value
+        : 0n;
+
+    let competitiveFee = networkEstimate;
+    const debugInfo: Record<string, string | number> = {
+      networkEstimateGwei: formatGwei(networkEstimate),
+    };
+
+    // Extract pending block
+    const pendingBlock = pendingBlockResult.status === 'fulfilled' ? pendingBlockResult.value : null;
+
+    // Analyze pending block transactions
+    if (pendingBlock?.transactions && pendingBlock.transactions.length > 0) {
+      const pendingFees = pendingBlock.transactions
+        .map(tx => {
+          if (typeof tx === 'string') {
+            return 0n;
+          }
+          if (isBlobTx) {
+            if (!isBlobTransaction(tx)) {
+              return 0n;
+            }
+          }
+          return tx.maxPriorityFeePerGas || 0n;
+        })
+        .filter((fee: bigint) => fee > 0n);
+
+      if (pendingFees.length > 0) {
+        const pendingCompetitiveFee = calculatePercentile(pendingFees, 75);
+
+        if (pendingCompetitiveFee > competitiveFee) {
+          competitiveFee = pendingCompetitiveFee;
+        }
+
+        debugInfo.pendingTxCount = pendingFees.length;
+        debugInfo.pendingP75Gwei = formatGwei(pendingCompetitiveFee);
+
+        logger?.debug('Analyzed pending transactions for competitive pricing', {
+          pendingTxCount: pendingFees.length,
+          pendingP75: formatGwei(pendingCompetitiveFee),
+        });
+      }
+    }
+
+    // Extract fee history
+    const feeHistory = feeHistoryResult.status === 'fulfilled' ? feeHistoryResult.value : null;
+
+    // Analyze fee history
+    if (feeHistory?.reward && feeHistory.reward.length > 0) {
+      // Extract 75th percentile fees from each block
+      const percentile75Fees = feeHistory.reward.map(rewards => rewards[0] || 0n).filter(fee => fee > 0n);
+
+      if (percentile75Fees.length > 0) {
+        // Calculate median of the 75th percentile fees across blocks
+        const medianHistoricalFee = median(percentile75Fees) ?? 0n;
+
+        // Debug: Log suspicious fees from history
+        if (medianHistoricalFee > 100n * WEI_CONST) {
+          logger?.warn('Suspicious high fee in history', {
+            historicalMedian: formatGwei(medianHistoricalFee),
+            allP75Fees: percentile75Fees.map(f => formatGwei(f)),
+          });
+        }
+
+        if (medianHistoricalFee > competitiveFee) {
+          competitiveFee = medianHistoricalFee;
+        }
+
+        debugInfo.historicalMedianGwei = formatGwei(medianHistoricalFee);
+
+        logger?.debug('Analyzed fee history for competitive pricing', {
+          historicalMedian: formatGwei(medianHistoricalFee),
+        });
+      }
+    }
+
+    // Log final decision
+    if (competitiveFee > networkEstimate) {
+      logger?.debug('Using competitive fee from market analysis', {
+        networkEstimate: formatGwei(networkEstimate),
+        competitive: formatGwei(competitiveFee),
+      });
+    }
+
+    debugInfo.finalFeeGwei = formatGwei(competitiveFee);
+
+    return {
+      priorityFee: competitiveFee,
+      latestBlock,
+      blobBaseFee,
+      debugInfo,
+    };
+  },
+};

package/src/l1_tx_utils/fee-strategies/types.ts

@@ -0,0 +1,56 @@
+import type { Logger } from '@aztec/foundation/log';
+
+import type { Block } from 'viem';
+
+import type { ViemClient } from '../../types.js';
+import type { L1TxUtilsConfig } from '../config.js';
+
+/**
+ * Historical block count for fee history queries
+ */
+export const HISTORICAL_BLOCK_COUNT = 5;
+
+/**
+ * Result from a priority fee strategy calculation
+ */
+export interface PriorityFeeStrategyResult {
+  /** The calculated priority fee in wei */
+  priorityFee: bigint;
+  /** The latest block (fetched as part of the strategy) */
+  latestBlock: Block;
+  /** The blob base fee (only present for blob transactions) */
+  blobBaseFee?: bigint;
+  /** Optional debug info about how the fee was calculated */
+  debugInfo?: Record<string, string | number>;
+}
+
+/**
+ * Context passed to the strategy function
+ */
+export interface PriorityFeeStrategyContext {
+  /** Gas configuration */
+  gasConfig: L1TxUtilsConfig;
+  /** Whether this is for a blob transaction */
+  isBlobTx: boolean;
+  /** Logger for debugging */
+  logger?: Logger;
+}
+
+/**
+ * A strategy for calculating the priority fee for L1 transactions.
+ * The function handles all RPC calls and returns
+ * the priority fee, along with any block data needed by the caller.
+ */
+export type PriorityFeeStrategy = {
+  /** Human-readable name for logging */
+  name: string;
+  /** Unique identifier for metrics */
+  id: string;
+  /**
+   * Calculate the priority fee.
+   * @param client - The viem client to use for RPC calls
+   * @param context - Contains gas config, whether it's a blob tx, and logger
+   * @returns The calculated priority fee result including block data
+   */
+  execute: (client: ViemClient, context: PriorityFeeStrategyContext) => Promise<PriorityFeeStrategyResult>;
+};

package/src/l1_tx_utils/forwarder_l1_tx_utils.ts

@@ -0,0 +1,119 @@
+import { EthAddress } from '@aztec/foundation/eth-address';
+import type { Logger } from '@aztec/foundation/log';
+import type { DateProvider } from '@aztec/foundation/timer';
+
+import { type Hex, encodeFunctionData } from 'viem';
+
+import type { EthSigner } from '../eth-signer/eth-signer.js';
+import { FORWARDER_ABI } from '../forwarder_proxy.js';
+import type { ExtendedViemWalletClient, ViemClient } from '../types.js';
+import type { L1TxUtilsConfig } from './config.js';
+import type { IL1TxMetrics, IL1TxStore } from './interfaces.js';
+import { L1TxUtilsWithBlobs } from './l1_tx_utils_with_blobs.js';
+import { createViemSigner } from './signer.js';
+import type { L1BlobInputs, L1TxConfig, L1TxRequest, SigningCallback } from './types.js';
+
+/**
+ * Extends L1TxUtilsWithBlobs to wrap all transactions through a forwarder contract.
+ * This is mainly used for testing the archiver's ability to decode transactions that go through proxies.
+ */
+export class ForwarderL1TxUtils extends L1TxUtilsWithBlobs {
+  constructor(
+    client: ViemClient | ExtendedViemWalletClient,
+    senderAddress: EthAddress,
+    signingCallback: SigningCallback,
+    logger: Logger | undefined,
+    dateProvider: DateProvider | undefined,
+    config: Partial<L1TxUtilsConfig>,
+    debugMaxGasLimit: boolean,
+    store: IL1TxStore | undefined,
+    metrics: IL1TxMetrics | undefined,
+    private readonly forwarderAddress: EthAddress,
+  ) {
+    super(client, senderAddress, signingCallback, logger, dateProvider, config, debugMaxGasLimit, store, metrics);
+  }
+
+  /**
+   * Wraps the transaction request in a call to the forwarder contract.
+   */
+  private wrapInForwarder(request: L1TxRequest): L1TxRequest {
+    const forwarderCalldata = encodeFunctionData({
+      abi: FORWARDER_ABI,
+      functionName: 'forward',
+      args: [request.to as Hex, request.data as Hex],
+    });
+
+    return {
+      to: this.forwarderAddress.toString() as Hex,
+      data: forwarderCalldata,
+      value: request.value,
+      abi: request.abi, // Preserve the original ABI for error decoding
+    };
+  }
+
+  /**
+   * Override sendAndMonitorTransaction to wrap the request in a forwarder call.
+   */
+  public override sendAndMonitorTransaction(request: L1TxRequest, gasConfig?: L1TxConfig, blobInputs?: L1BlobInputs) {
+    this.logger.debug(`Wrapping transaction to ${request.to} in forwarder at ${this.forwarderAddress.toString()}`);
+    const wrappedRequest = this.wrapInForwarder(request);
+    return super.sendAndMonitorTransaction(wrappedRequest, gasConfig, blobInputs);
+  }
+}
+
+export function createForwarderL1TxUtilsFromViemWallet(
+  client: ExtendedViemWalletClient,
+  forwarderAddress: EthAddress,
+  deps: {
+    logger?: Logger;
+    dateProvider?: DateProvider;
+    store?: IL1TxStore;
+    metrics?: IL1TxMetrics;
+  } = {},
+  config: Partial<L1TxUtilsConfig> = {},
+  debugMaxGasLimit: boolean = false,
+) {
+  return new ForwarderL1TxUtils(
+    client,
+    EthAddress.fromString(client.account.address),
+    createViemSigner(client),
+    deps.logger,
+    deps.dateProvider,
+    config,
+    debugMaxGasLimit,
+    deps.store,
+    deps.metrics,
+    forwarderAddress,
+  );
+}
+
+export function createForwarderL1TxUtilsFromEthSigner(
+  client: ViemClient,
+  signer: EthSigner,
+  forwarderAddress: EthAddress,
+  deps: {
+    logger?: Logger;
+    dateProvider?: DateProvider;
+    store?: IL1TxStore;
+    metrics?: IL1TxMetrics;
+  } = {},
+  config: Partial<L1TxUtilsConfig> = {},
+  debugMaxGasLimit: boolean = false,
+) {
+  const callback: SigningCallback = async (transaction, _signingAddress) => {
+    return (await signer.signTransaction(transaction)).toViemTransactionSignature();
+  };
+
+  return new ForwarderL1TxUtils(
+    client,
+    signer.address,
+    callback,
+    deps.logger,
+    deps.dateProvider,
+    config,
+    debugMaxGasLimit,
+    deps.store,
+    deps.metrics,
+    forwarderAddress,
+  );
+}

package/src/l1_tx_utils/index-blobs.ts

@@ -0,0 +1,2 @@
+export * from './forwarder_l1_tx_utils.js';
+export * from './l1_tx_utils_with_blobs.js';

package/src/l1_tx_utils/index.ts

@@ -0,0 +1,14 @@
+export * from './config.js';
+export * from './constants.js';
+export * from './factory.js';
+export * from './fee-strategies/index.js';
+export * from './interfaces.js';
+export * from './l1_fee_analyzer.js';
+export * from './l1_tx_utils.js';
+export * from './readonly_l1_tx_utils.js';
+export * from './signer.js';
+export * from './types.js';
+export * from './utils.js';
+
+// Note: We intentionally do not export l1_tx_utils_with_blobs.js
+// to avoid accidentally importing blob-lib dependency.

package/src/l1_tx_utils/interfaces.ts

@@ -0,0 +1,86 @@
+import type { L1BlobInputs, L1TxState } from './types.js';
+
+/**
+ * Interface for L1 transaction state storage.
+ * Implementations handle persistence of transaction states across restarts.
+ */
+export interface IL1TxStore {
+  /**
+   * Gets the next available state ID for an account.
+   */
+  consumeNextStateId(account: string): Promise<number>;
+
+  /**
+   * Saves a single transaction state for a specific account.
+   * Does not save blob data (see saveBlobs).
+   * @param account - The sender account address
+   * @param state - Transaction state to save
+   */
+  saveState(account: string, state: L1TxState): Promise<L1TxState>;
+
+  /**
+   * Saves blobs for a given state.
+   * @param account - The sender account address
+   * @param stateId - The state ID
+   * @param blobInputs - Blob inputs to save
+   */
+  saveBlobs(account: string, stateId: number, blobInputs: L1BlobInputs | undefined): Promise<void>;
+
+  /**
+   * Loads all transaction states for a specific account.
+   * @param account - The sender account address
+   * @returns Array of transaction states with their IDs
+   */
+  loadStates(account: string): Promise<L1TxState[]>;
+
+  /**
+   * Loads a single state by ID.
+   * @param account - The sender account address
+   * @param stateId - The state ID
+   * @returns The transaction state or undefined if not found
+   */
+  loadState(account: string, stateId: number): Promise<L1TxState | undefined>;
+
+  /**
+   * Deletes a specific state and its associated blobs.
+   * @param account - The sender account address
+   * @param stateId - The state ID to delete
+   */
+  deleteState(account: string, ...stateId: number[]): Promise<void>;
+
+  /**
+   * Clears all transaction states for a specific account.
+   * @param account - The sender account address
+   */
+  clearStates(account: string): Promise<void>;
+
+  /**
+   * Gets all accounts that have stored states.
+   * @returns Array of account addresses
+   */
+  getAllAccounts(): Promise<string[]>;
+
+  /**
+   * Closes the store.
+   */
+  close(): Promise<void>;
+}
+
+/**
+ * Interface for L1 transaction metrics recording.
+ * Implementations handle tracking of transaction lifecycle and gas costs.
+ */
+export interface IL1TxMetrics {
+  /**
+   * Records metrics when a transaction is mined
+   * @param state - The L1 transaction state
+   * @param l1Timestamp - The current L1 timestamp
+   */
+  recordMinedTx(state: L1TxState, l1Timestamp: Date): void;
+
+  /**
+   * Records metrics when a transaction is dropped
+   * @param state - The L1 transaction state
+   */
+  recordDroppedTx(state: L1TxState): void;
+}