@aztec/ethereum 0.0.0-test.1 → 0.0.1-commit.001888fc

package/src/l1_tx_utils/config.ts

@@ -0,0 +1,181 @@
+import {
+  type ConfigMappingsType,
+  booleanConfigHelper,
+  floatConfigHelper,
+  getConfigFromMappings,
+  getDefaultConfig,
+  numberConfigHelper,
+  optionalNumberConfigHelper,
+} from '@aztec/foundation/config';
+
+export interface L1TxUtilsConfig {
+  /**
+   * How much to increase calculated gas limit.
+   */
+  gasLimitBufferPercentage?: number;
+  /**
+   * Maximum gas price in gwei
+   */
+  maxGwei?: number;
+  /**
+   * Maximum blob fee per gas in gwei
+   */
+  maxBlobGwei?: number;
+  /**
+   * Priority fee bump percentage
+   */
+  priorityFeeBumpPercentage?: number;
+  /**
+   * How much to increase priority fee by each attempt (percentage)
+   */
+  priorityFeeRetryBumpPercentage?: number;
+  /**
+   * Minimum priority fee per gas in Gwei. Acts as a floor for the computed priority fee.
+   */
+  minimumPriorityFeePerGas?: number;
+  /**
+   * Maximum number of speed-up attempts
+   */
+  maxSpeedUpAttempts?: number;
+  /**
+   * How often to check tx status
+   */
+  checkIntervalMs?: number;
+  /**
+   * How long before considering tx stalled
+   */
+  stallTimeMs?: number;
+  /**
+   * How long to wait for a tx to be mined before giving up
+   */
+  txTimeoutMs?: number;
+  /**
+   * Whether to attempt to cancel a tx if it's not mined after txTimeoutMs
+   */
+  cancelTxOnTimeout?: boolean;
+  /**
+   * How long to wait for a cancellation tx to be mined after its last attempt before giving up
+   */
+  txCancellationFinalTimeoutMs?: number;
+  /**
+   * How long a tx nonce can be unseen in the mempool before considering it dropped
+   */
+  txUnseenConsideredDroppedMs?: number;
+  /** Enable tx delayer. When true, wraps the viem client to intercept and delay txs. Test-only. */
+  enableDelayer?: boolean;
+  /** Max seconds into an L1 slot for tx inclusion. Txs sent later are deferred to next slot. Only used when enableDelayer is true. */
+  txDelayerMaxInclusionTimeIntoSlot?: number;
+  /** How many seconds an L1 slot lasts. */
+  ethereumSlotDuration?: number;
+}
+
+export const l1TxUtilsConfigMappings: ConfigMappingsType<L1TxUtilsConfig> = {
+  gasLimitBufferPercentage: {
+    description: 'How much to increase calculated gas limit by (percentage)',
+    env: 'L1_GAS_LIMIT_BUFFER_PERCENTAGE',
+    ...numberConfigHelper(20),
+  },
+  maxGwei: {
+    description: 'Maximum gas price in gwei to be used for transactions.',
+    env: 'L1_GAS_PRICE_MAX',
+    fallback: ['L1_FEE_PER_GAS_GWEI_MAX'],
+    ...floatConfigHelper(2000),
+  },
+  maxBlobGwei: {
+    description: 'Maximum blob fee per gas in gwei',
+    env: 'L1_BLOB_FEE_PER_GAS_MAX',
+    fallback: ['L1_BLOB_FEE_PER_GAS_GWEI_MAX'],
+    ...floatConfigHelper(3000),
+  },
+  priorityFeeBumpPercentage: {
+    description: 'How much to increase priority fee by each attempt (percentage)',
+    env: 'L1_PRIORITY_FEE_BUMP_PERCENTAGE',
+    ...numberConfigHelper(20),
+  },
+  priorityFeeRetryBumpPercentage: {
+    description: 'How much to increase priority fee by each retry attempt (percentage)',
+    env: 'L1_PRIORITY_FEE_RETRY_BUMP_PERCENTAGE',
+    ...numberConfigHelper(50),
+  },
+  minimumPriorityFeePerGas: {
+    description:
+      'Minimum priority fee per gas in Gwei. Acts as a floor for the computed priority fee. If network conditions require a higher fee, the higher fee will be used.',
+    env: 'L1_MINIMUM_PRIORITY_FEE_PER_GAS_GWEI',
+    fallback: ['L1_FIXED_PRIORITY_FEE_PER_GAS', 'L1_FIXED_PRIORITY_FEE_PER_GAS_GWEI'],
+    deprecatedFallback: [
+      {
+        env: 'L1_FIXED_PRIORITY_FEE_PER_GAS',
+        message: deprecatedFixedFeeMessage('L1_FIXED_PRIORITY_FEE_PER_GAS'),
+      },
+      {
+        env: 'L1_FIXED_PRIORITY_FEE_PER_GAS_GWEI',
+        message: deprecatedFixedFeeMessage('L1_FIXED_PRIORITY_FEE_PER_GAS_GWEI'),
+      },
+    ],
+    ...floatConfigHelper(0),
+  },
+  maxSpeedUpAttempts: {
+    description: 'Maximum number of speed-up attempts',
+    env: 'L1_TX_MONITOR_MAX_ATTEMPTS',
+    ...numberConfigHelper(3),
+  },
+  checkIntervalMs: {
+    description: 'How often to check tx status',
+    env: 'L1_TX_MONITOR_CHECK_INTERVAL_MS',
+    ...numberConfigHelper(1_000),
+  },
+  stallTimeMs: {
+    description: 'How long before considering tx stalled',
+    env: 'L1_TX_MONITOR_STALL_TIME_MS',
+    ...numberConfigHelper(12_000), // 12s, 1 ethereum slot
+  },
+  txTimeoutMs: {
+    description: 'How long to wait for a tx to be mined before giving up. Set to 0 to disable.',
+    env: 'L1_TX_MONITOR_TX_TIMEOUT_MS',
+    ...numberConfigHelper(120_000), // 2 mins
+  },
+  cancelTxOnTimeout: {
+    description: "Whether to attempt to cancel a tx if it's not mined after txTimeoutMs",
+    env: 'L1_TX_MONITOR_CANCEL_TX_ON_TIMEOUT',
+    ...booleanConfigHelper(true),
+  },
+  txCancellationFinalTimeoutMs: {
+    description: 'How long to wait for a cancellation tx after its last attempt before giving up',
+    env: 'L1_TX_MONITOR_TX_CANCELLATION_TIMEOUT_MS',
+    ...numberConfigHelper(24 * 12 * 1000), // 24 L1 blocks
+  },
+  txUnseenConsideredDroppedMs: {
+    description: 'How long a tx nonce can be unseen in the mempool before considering it dropped',
+    env: 'L1_TX_MONITOR_TX_UNSEEN_CONSIDERED_DROPPED_MS',
+    ...numberConfigHelper(6 * 12 * 1000), // 6 L1 blocks
+  },
+  enableDelayer: {
+    description: 'Enable tx delayer for testing.',
+    ...booleanConfigHelper(false),
+  },
+  txDelayerMaxInclusionTimeIntoSlot: {
+    description: 'Max seconds into L1 slot for tx inclusion when delayer is enabled.',
+    ...optionalNumberConfigHelper(),
+  },
+  ethereumSlotDuration: {
+    env: 'ETHEREUM_SLOT_DURATION',
+    description: 'How many seconds an L1 slot lasts.',
+    ...numberConfigHelper(12),
+  },
+};
+
+// We abuse the fact that all mappings above have a non null default value and force-type this to Required
+export const defaultL1TxUtilsConfig = getDefaultConfig<L1TxUtilsConfig>(
+  l1TxUtilsConfigMappings,
+) as Required<L1TxUtilsConfig>;
+
+export function getL1TxUtilsConfigEnvVars(): L1TxUtilsConfig {
+  return getConfigFromMappings(l1TxUtilsConfigMappings);
+}
+
+function deprecatedFixedFeeMessage(envVar: string): string {
+  return (
+    `Environment variable ${envVar} is deprecated. It is now used as a MINIMUM priority fee rather than a fixed value. ` +
+    'Please use L1_MINIMUM_PRIORITY_FEE_PER_GAS_GWEI instead. If network conditions require a higher fee, the higher fee will be used.'
+  );
+}

package/src/l1_tx_utils/constants.ts

@@ -0,0 +1,29 @@
+// 1_000_000_000 Gwei = 1 ETH
+// 1_000_000_000 Wei = 1 Gwei
+// 1_000_000_000_000_000_000 Wei = 1 ETH
+export const WEI_CONST = 1_000_000_000n;
+
+// EIP-7825: protocol-level cap on tx gas limit (2^24). Clients reject above this.
+export const MAX_L1_TX_LIMIT = 16_777_216n;
+
+// setting a minimum bump percentage to 10% due to geth's implementation
+// https://github.com/ethereum/go-ethereum/blob/e3d61e6db028c412f74bc4d4c7e117a9e29d0de0/core/txpool/legacypool/list.go#L298
+export const MIN_REPLACEMENT_BUMP_PERCENTAGE = 10;
+
+// setting a minimum bump percentage to 100% due to geth's implementation
+// https://github.com/ethereum/go-ethereum/blob/e3d61e6db028c412f74bc4d4c7e117a9e29d0de0/core/txpool/blobpool/config.go#L34
+export const MIN_BLOB_REPLACEMENT_BUMP_PERCENTAGE = 100;
+
+// Avg ethereum block time is ~12s
+export const BLOCK_TIME_MS = 12_000;
+
+// Gas per blob (EIP-4844)
+export const GAS_PER_BLOB = 131072n;
+
+// Blob capacity schedule based on Ethereum upgrades
+export const BLOB_CAPACITY_SCHEDULE = [
+  { timestamp: 1734357600, target: 14, max: 21 }, // BPO2: Dec 17, 2025
+  { timestamp: 1733752800, target: 10, max: 15 }, // BPO1: Dec 9, 2025
+  { timestamp: 1733234400, target: 6, max: 9 }, // Fusaka: Dec 3, 2025
+  { timestamp: 0, target: 6, max: 9 }, // Pectra/earlier
+];

package/src/l1_tx_utils/factory.ts

@@ -0,0 +1,64 @@
+import type { BlobKzgInstance } from '@aztec/blob-lib/types';
+import { EthAddress } from '@aztec/foundation/eth-address';
+import type { Logger } from '@aztec/foundation/log';
+import { DateProvider } from '@aztec/foundation/timer';
+
+import type { EthSigner } from '../eth-signer/eth-signer.js';
+import type { ExtendedViemWalletClient, ViemClient } from '../types.js';
+import type { L1TxUtilsConfig } from './config.js';
+import type { IL1TxMetrics, IL1TxStore } from './interfaces.js';
+import { L1TxUtils } from './l1_tx_utils.js';
+import { createViemSigner } from './signer.js';
+import { Delayer } from './tx_delayer.js';
+import type { SigningCallback } from './types.js';
+
+/** Source of signing capability: either a wallet client or a separate client + signer. */
+export type L1SignerSource = ExtendedViemWalletClient | { client: ViemClient; signer: EthSigner };
+
+export function resolveSignerSource(source: L1SignerSource): {
+  client: ViemClient;
+  address: EthAddress;
+  signingCallback: SigningCallback;
+} {
+  if ('account' in source && source.account) {
+    return {
+      client: source as ExtendedViemWalletClient,
+      address: EthAddress.fromString((source as ExtendedViemWalletClient).account.address),
+      signingCallback: createViemSigner(source as ExtendedViemWalletClient),
+    };
+  }
+  const { client, signer } = source as { client: ViemClient; signer: EthSigner };
+  return {
+    client,
+    address: signer.address,
+    signingCallback: async (tx, _addr) => (await signer.signTransaction(tx)).toViemTransactionSignature(),
+  };
+}
+
+export function createL1TxUtils(
+  source: L1SignerSource,
+  deps?: {
+    logger?: Logger;
+    dateProvider?: DateProvider;
+    store?: IL1TxStore;
+    metrics?: IL1TxMetrics;
+    kzg?: BlobKzgInstance;
+    delayer?: Delayer;
+  },
+  config?: Partial<L1TxUtilsConfig> & { debugMaxGasLimit?: boolean },
+): L1TxUtils {
+  const { client, address, signingCallback } = resolveSignerSource(source);
+  return new L1TxUtils(
+    client,
+    address,
+    signingCallback,
+    deps?.logger,
+    deps?.dateProvider,
+    config,
+    config?.debugMaxGasLimit ?? false,
+    deps?.store,
+    deps?.metrics,
+    deps?.kzg,
+    deps?.delayer,
+  );
+}

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

@@ -0,0 +1,22 @@
+import { P75AllTxsPriorityFeeStrategy } from './p75_competitive.js';
+import { P75BlobTxsOnlyPriorityFeeStrategy } from './p75_competitive_blob_txs_only.js';
+import type { PriorityFeeStrategy } from './types.js';
+
+export {
+  HISTORICAL_BLOCK_COUNT,
+  type PriorityFeeStrategy,
+  type PriorityFeeStrategyContext,
+  type PriorityFeeStrategyResult,
+} from './types.js';
+
+export { P75AllTxsPriorityFeeStrategy } from './p75_competitive.js';
+export { P75BlobTxsOnlyPriorityFeeStrategy } from './p75_competitive_blob_txs_only.js';
+
+/**
+ * Default list of priority fee strategies to analyze.
+ * Add more strategies here for comparison.
+ */
+export const DEFAULT_PRIORITY_FEE_STRATEGIES: PriorityFeeStrategy[] = [
+  P75AllTxsPriorityFeeStrategy,
+  P75BlobTxsOnlyPriorityFeeStrategy,
+];

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

@@ -0,0 +1,163 @@
+import { median } from '@aztec/foundation/collection';
+
+import { formatGwei } from 'viem';
+
+import type { ViemClient } from '../../types.js';
+import { calculatePercentile } from '../../utils.js';
+import { WEI_CONST } from '../constants.js';
+import {
+  HISTORICAL_BLOCK_COUNT,
+  type PriorityFeeStrategy,
+  type PriorityFeeStrategyContext,
+  type PriorityFeeStrategyResult,
+} from './types.js';
+
+/**
+ * Our current competitive priority fee strategy.
+ * 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 P75AllTxsPriorityFeeStrategy: PriorityFeeStrategy = {
+  name: 'Competitive (P75 + History) - CURRENT',
+  id: 'p75_pending_txs_and_history_all_txs',
+
+  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),
+        client
+          .getFeeHistory({
+            blockCount: HISTORICAL_BLOCK_COUNT,
+            rewardPercentiles: [75],
+            blockTag: 'latest',
+          })
+          .catch(() => null),
+      ]);
+
+    // Extract latest block
+    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;
+          }
+          return tx.maxPriorityFeePerGas || 0n;
+        })
+        .filter((fee: bigint) => fee > 0n);
+
+      if (pendingFees.length > 0) {
+        // Use 75th percentile of pending fees to be competitive
+        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),
+        });
+      }
+    }
+
+    // Sanity check: cap competitive fee at 100x network estimate to avoid using unrealistic fees
+    const maxReasonableFee = networkEstimate * 100n;
+    if (competitiveFee > maxReasonableFee && networkEstimate > 0n) {
+      logger?.debug('Competitive fee exceeds sanity cap, using capped value', {
+        competitiveFee: formatGwei(competitiveFee),
+        networkEstimate: formatGwei(networkEstimate),
+        cappedTo: formatGwei(maxReasonableFee),
+      });
+      competitiveFee = maxReasonableFee;
+      debugInfo.cappedToGwei = formatGwei(maxReasonableFee);
+    }
+
+    // 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,
+    };
+  },
+};