@aztec/p2p 0.0.1-commit.4d79d1f2d → 0.0.1-commit.4d9804df

package/src/mem_pools/tx_pool_v2/eviction/index.ts

@@ -6,9 +6,13 @@ export {
   type EvictionResult,
   type EvictionRule,
   type PoolOperations,
+  type PreAddContext,
   type PreAddPoolAccess,
   type PreAddResult,
   type PreAddRule,
+  type TaggedEviction,
+  TxPoolRejectionCode,
+  type TxPoolRejectionError,
 } from './interfaces.js';
 
 // Pre-add rules
@@ -17,6 +21,7 @@ export { FeePayerBalancePreAddRule } from './fee_payer_balance_pre_add_rule.js';
 export { LowPriorityPreAddRule } from './low_priority_pre_add_rule.js';
 
 // Post-event eviction rules
+export { InsufficientFeePerGasEvictionRule } from './insufficient_fee_per_gas_eviction_rule.js';
 export { InvalidTxsAfterMiningRule } from './invalid_txs_after_mining_rule.js';
 export { InvalidTxsAfterReorgRule } from './invalid_txs_after_reorg_rule.js';
 export { FeePayerBalanceEvictionRule } from './fee_payer_balance_eviction_rule.js';

package/src/mem_pools/tx_pool_v2/eviction/insufficient_fee_per_gas_eviction_rule.ts

@@ -0,0 +1,65 @@
+import { createLogger } from '@aztec/foundation/log';
+import type { BlockMinFeesProvider } from '@aztec/stdlib/gas';
+
+import type { EvictionContext, EvictionResult, EvictionRule, PoolOperations } from './interfaces.js';
+import { EvictionEvent } from './interfaces.js';
+
+/**
+ * Eviction rule that removes transactions whose maxFeesPerGas no longer meets
+ * the projected minimum gas fees after a new block is mined.
+ * Uses the BlockMinFeesProvider (forward-looking) to get the projected minimum fees.
+ * Only triggers on BLOCK_MINED events.
+ */
+export class InsufficientFeePerGasEvictionRule implements EvictionRule {
+  public readonly name = 'InsufficientFeePerGas';
+
+  private log = createLogger('p2p:tx_pool_v2:insufficient_fee_per_gas_eviction_rule');
+
+  constructor(private blockMinFeesProvider: BlockMinFeesProvider) {}
+
+  async evict(context: EvictionContext, pool: PoolOperations): Promise<EvictionResult> {
+    if (context.event !== EvictionEvent.BLOCK_MINED) {
+      return {
+        reason: 'insufficient_fee_per_gas',
+        success: true,
+        txsEvicted: [],
+      };
+    }
+
+    try {
+      const gasFees = await this.blockMinFeesProvider.getCurrentMinFees();
+      const txsToEvict: string[] = [];
+      const pendingTxs = pool.getPendingTxs();
+
+      for (const meta of pendingTxs) {
+        const maxFeesPerGas = meta.data.constants.txContext.gasSettings.maxFeesPerGas;
+        if (maxFeesPerGas.feePerDaGas < gasFees.feePerDaGas || maxFeesPerGas.feePerL2Gas < gasFees.feePerL2Gas) {
+          this.log.verbose(`Evicting tx ${meta.txHash} from pool due to insufficient fee per gas`, {
+            txMaxFeesPerGas: maxFeesPerGas.toInspect(),
+            blockGasFees: gasFees.toInspect(),
+          });
+          txsToEvict.push(meta.txHash);
+        }
+      }
+
+      if (txsToEvict.length > 0) {
+        this.log.info(`Evicted ${txsToEvict.length} txs with insufficient fee per gas after block mined`);
+        await pool.deleteTxs(txsToEvict, this.name);
+      }
+
+      return {
+        reason: 'insufficient_fee_per_gas',
+        success: true,
+        txsEvicted: txsToEvict,
+      };
+    } catch (err) {
+      this.log.error('Failed to evict transactions with insufficient fee per gas', { err });
+      return {
+        reason: 'insufficient_fee_per_gas',
+        success: false,
+        txsEvicted: [],
+        error: new Error('Failed to evict txs with insufficient fee per gas', { cause: err }),
+      };
+    }
+  }
+}

package/src/mem_pools/tx_pool_v2/eviction/interfaces.ts

@@ -67,6 +67,50 @@ export interface PreAddPoolAccess {
   getLowestPriorityPendingTx(): TxMetaData | undefined;
 }
 
+/** A single eviction tagged with the rule that caused it. */
+export interface TaggedEviction {
+  readonly txHash: string;
+  readonly reason: string;
+}
+
+/**
+ * Machine-readable rejection codes for pre-add rule rejections.
+ */
+export const TxPoolRejectionCode = {
+  LOW_PRIORITY_FEE: 'LOW_PRIORITY_FEE',
+  INSUFFICIENT_FEE_PAYER_BALANCE: 'INSUFFICIENT_FEE_PAYER_BALANCE',
+  NULLIFIER_CONFLICT: 'NULLIFIER_CONFLICT',
+  INTERNAL_ERROR: 'INTERNAL_ERROR',
+} as const;
+
+export type TxPoolRejectionCode = (typeof TxPoolRejectionCode)[keyof typeof TxPoolRejectionCode];
+
+/** Structured rejection reason returned by pre-add rules. */
+export type TxPoolRejectionError =
+  | {
+      code: typeof TxPoolRejectionCode.LOW_PRIORITY_FEE;
+      message: string;
+      minimumPriorityFee: bigint;
+      txPriorityFee: bigint;
+    }
+  | {
+      code: typeof TxPoolRejectionCode.INSUFFICIENT_FEE_PAYER_BALANCE;
+      message: string;
+      currentBalance: bigint;
+      availableBalance: bigint;
+      feeLimit: bigint;
+    }
+  | {
+      code: typeof TxPoolRejectionCode.NULLIFIER_CONFLICT;
+      message: string;
+      conflictingTxHash: string;
+      /** Minimum fee needed to replace the conflicting tx (only set when price bump applies). */
+      minimumPriceBumpFee?: bigint;
+      /** Incoming tx's priority fee. */
+      txPriorityFee?: bigint;
+    }
+  | { code: typeof TxPoolRejectionCode.INTERNAL_ERROR; message: string };
+
 /**
  * Result of a pre-add check for a single transaction.
  */
@@ -75,8 +119,18 @@ export interface PreAddResult {
   readonly shouldIgnore: boolean;
   /** Tx hashes (as strings) that should be evicted if this tx is added */
   readonly txHashesToEvict: string[];
+  /** Evictions tagged with the rule name that produced them. Populated by EvictionManager. */
+  readonly evictions?: TaggedEviction[];
   /** Optional reason for ignoring */
-  readonly reason?: string;
+  readonly reason?: TxPoolRejectionError;
+}
+
+/** Context passed to pre-add rules from addPendingTxs. */
+export interface PreAddContext {
+  /** If true, compare priority fee only (no tx hash tiebreaker). Used for RPC submissions. */
+  feeComparisonOnly?: boolean;
+  /** Percentage-based price bump required for tx replacement. Only set for RPC submissions. */
+  priceBumpPercentage?: bigint;
 }
 
 /**
@@ -90,9 +144,10 @@ export interface PreAddRule {
    * Check if incoming tx should be added and which existing txs to evict.
    * @param incomingMeta - Metadata for the incoming transaction
    * @param poolAccess - Read-only access to current pool state
+   * @param context - Optional context from addPendingTxs caller
    * @returns Result indicating whether to ignore and what to evict
    */
-  check(incomingMeta: TxMetaData, poolAccess: PreAddPoolAccess): Promise<PreAddResult>;
+  check(incomingMeta: TxMetaData, poolAccess: PreAddPoolAccess, context?: PreAddContext): Promise<PreAddResult>;
 
   /**
    * Updates the configuration for this rule.
@@ -120,8 +175,8 @@ export interface PoolOperations {
   /** Get the N lowest priority pending tx hashes */
   getLowestPriorityPending(limit: number): string[];
 
-  /** Delete transactions by hash */
-  deleteTxs(txHashes: string[]): Promise<void>;
+  /** Delete transactions by hash, with an optional reason for metrics */
+  deleteTxs(txHashes: string[], reason?: string): Promise<void>;
 }
 
 /**

package/src/mem_pools/tx_pool_v2/eviction/invalid_txs_after_mining_rule.ts

@@ -35,15 +35,14 @@ export class InvalidTxsAfterMiningRule implements EvictionRule {
       for (const meta of pendingTxs) {
         // Evict pending txs that share nullifiers with mined txs
         if (meta.nullifiers.some(nullifier => minedNullifiers.has(nullifier))) {
-          this.log.verbose(`Evicting tx ${meta.txHash} from pool due to a duplicate nullifier with a mined tx`);
           txsToEvict.push(meta.txHash);
           continue;
         }
 
         // Evict pending txs with an expiration timestamp less than or equal to the mined block timestamp
-        if (meta.includeByTimestamp <= timestamp) {
+        if (meta.expirationTimestamp <= timestamp) {
           this.log.verbose(
-            `Evicting tx ${meta.txHash} from pool due to the tx being expired (includeByTimestamp: ${meta.includeByTimestamp}, mined block timestamp: ${timestamp})`,
+            `Evicting tx ${meta.txHash} from pool due to the tx being expired (expirationTimestamp: ${meta.expirationTimestamp}, mined block timestamp: ${timestamp})`,
           );
           txsToEvict.push(meta.txHash);
           continue;
@@ -51,10 +50,11 @@ export class InvalidTxsAfterMiningRule implements EvictionRule {
       }
 
       if (txsToEvict.length > 0) {
-        await pool.deleteTxs(txsToEvict);
+        this.log.info(`Evicted ${txsToEvict.length} invalid txs after block mined`);
+        await pool.deleteTxs(txsToEvict, this.name);
       }
 
-      this.log.debug(`Evicted ${txsToEvict.length} invalid txs after block mined`);
+      this.log.debug(`Evicted ${txsToEvict.length} invalid txs after block mined`, { txHashes: txsToEvict });
 
       return {
         reason: 'block_mined_invalid_txs',

package/src/mem_pools/tx_pool_v2/eviction/invalid_txs_after_reorg_rule.ts

@@ -1,5 +1,5 @@
-import { Fr } from '@aztec/foundation/curves/bn254';
 import { createLogger } from '@aztec/foundation/log';
+import { BlockHash } from '@aztec/stdlib/block';
 import type { WorldStateSynchronizer } from '@aztec/stdlib/interfaces/server';
 import { MerkleTreeId } from '@aztec/stdlib/trees';
 
@@ -33,20 +33,20 @@ export class InvalidTxsAfterReorgRule implements EvictionRule {
       const pendingTxs = pool.getPendingTxs();
 
       // Deduplicate block hashes to reduce redundant DB lookups
-      const uniqueBlockHashes = new Map<string, Fr>();
+      const uniqueBlockHashes = new Map<string, BlockHash>();
       const txsByBlockHash = new Map<string, string[]>();
 
       for (const meta of pendingTxs) {
         const blockHashStr = meta.anchorBlockHeaderHash;
         if (!txsByBlockHash.has(blockHashStr)) {
           txsByBlockHash.set(blockHashStr, []);
-          uniqueBlockHashes.set(blockHashStr, Fr.fromHexString(blockHashStr));
+          uniqueBlockHashes.set(blockHashStr, BlockHash.fromString(blockHashStr));
         }
         txsByBlockHash.get(blockHashStr)!.push(meta.txHash);
       }
 
-      // Ensure world state is synced to this block before accessing the snapshot
-      await this.worldState.syncImmediate(context.blockNumber);
+      // Sync without a block number to ensure the world state processes the prune event.
+      await this.worldState.syncImmediate();
       const db = this.worldState.getSnapshot(context.blockNumber);
 
       // Check which blocks exist in the archive
@@ -72,8 +72,8 @@ export class InvalidTxsAfterReorgRule implements EvictionRule {
       }
 
       if (txsToEvict.length > 0) {
-        this.log.verbose(`Evicting ${txsToEvict.length} txs from pool due to referencing pruned blocks`);
-        await pool.deleteTxs(txsToEvict);
+        this.log.info(`Evicting ${txsToEvict.length} txs from pool due to referencing pruned blocks`);
+        await pool.deleteTxs(txsToEvict, this.name);
       }
 
       const keptCount = pendingTxs.length - txsToEvict.length;
@@ -81,7 +81,7 @@ export class InvalidTxsAfterReorgRule implements EvictionRule {
         this.log.verbose(`Kept ${keptCount} txs that did not reference pruned blocks`);
       }
 
-      this.log.debug(`Evicted ${txsToEvict.length} invalid txs after reorg`);
+      this.log.debug(`Evicted ${txsToEvict.length} invalid txs after reorg`, { txHashes: txsToEvict });
 
       return {
         reason: 'reorg_invalid_txs',

package/src/mem_pools/tx_pool_v2/eviction/low_priority_eviction_rule.ts

@@ -5,7 +5,7 @@ import { EvictionEvent } from './interfaces.js';
 
 /**
  * Eviction rule that removes low-priority transactions when the pool exceeds configured limits.
- * Only triggers on TXS_ADDED events.
+ * Triggers on TXS_ADDED and CHAIN_PRUNED events.
  */
 export class LowPriorityEvictionRule implements EvictionRule {
   public readonly name = 'LowPriorityEviction';
@@ -18,7 +18,7 @@ export class LowPriorityEvictionRule implements EvictionRule {
   }
 
   async evict(context: EvictionContext, pool: PoolOperations): Promise<EvictionResult> {
-    if (context.event !== EvictionEvent.TXS_ADDED) {
+    if (context.event !== EvictionEvent.TXS_ADDED && context.event !== EvictionEvent.CHAIN_PRUNED) {
       return {
         reason: 'low_priority',
         success: true,
@@ -48,19 +48,24 @@ export class LowPriorityEvictionRule implements EvictionRule {
         };
       }
 
-      this.log.verbose(
-        `Evicting low priority txs. Pending tx count above limit: ${currentTxCount} > ${this.maxPoolSize}`,
-      );
+      this.log.info(`Evicting low priority txs. Pending tx count above limit: ${currentTxCount} > ${this.maxPoolSize}`);
       const numberToEvict = currentTxCount - this.maxPoolSize;
       const txsToEvict = pool.getLowestPriorityPending(numberToEvict);
 
       if (txsToEvict.length > 0) {
-        await pool.deleteTxs(txsToEvict);
+        if (context.event === EvictionEvent.TXS_ADDED) {
+          const toEvictSet = new Set(txsToEvict);
+          const numNewTxsEvicted = context.newTxHashes.filter(newTxHash => toEvictSet.has(newTxHash)).length;
+          this.log.info(`Evicted ${txsToEvict.length} low priority txs, including ${numNewTxsEvicted} newly added txs`);
+        } else {
+          this.log.info(`Evicted ${txsToEvict.length} low priority txs after chain prune`);
+        }
+        await pool.deleteTxs(txsToEvict, this.name);
       }
 
-      const numNewTxsEvicted = context.newTxHashes.filter(newTxHash => txsToEvict.includes(newTxHash)).length;
-
-      this.log.verbose(`Evicted ${txsToEvict.length} low priority txs, including ${numNewTxsEvicted} newly added txs`);
+      this.log.debug(`Evicted ${txsToEvict.length} low priority txs`, {
+        txHashes: txsToEvict,
+      });
 
       return {
         reason: 'low_priority',

package/src/mem_pools/tx_pool_v2/eviction/low_priority_pre_add_rule.ts

@@ -1,7 +1,14 @@
 import { createLogger } from '@aztec/foundation/log';
 
-import type { TxMetaData } from '../tx_metadata.js';
-import type { EvictionConfig, PreAddPoolAccess, PreAddResult, PreAddRule } from './interfaces.js';
+import { type TxMetaData, comparePriority, getMinimumPriceBumpFee } from '../tx_metadata.js';
+import {
+  type EvictionConfig,
+  type PreAddContext,
+  type PreAddPoolAccess,
+  type PreAddResult,
+  type PreAddRule,
+  TxPoolRejectionCode,
+} from './interfaces.js';
 
 /**
  * Pre-add rule that checks if the pool is at capacity and handles low-priority eviction.
@@ -20,7 +27,7 @@ export class LowPriorityPreAddRule implements PreAddRule {
     this.maxPoolSize = config.maxPoolSize;
   }
 
-  check(incomingMeta: TxMetaData, poolAccess: PreAddPoolAccess): Promise<PreAddResult> {
+  check(incomingMeta: TxMetaData, poolAccess: PreAddPoolAccess, context?: PreAddContext): Promise<PreAddResult> {
     // Skip if max pool size is disabled (0 = unlimited)
     if (this.maxPoolSize === 0) {
       return Promise.resolve({ shouldIgnore: false, txHashesToEvict: [] });
@@ -40,8 +47,18 @@ export class LowPriorityPreAddRule implements PreAddRule {
       return Promise.resolve({ shouldIgnore: false, txHashesToEvict: [] });
     }
 
-    // If incoming tx has strictly higher priority, evict the lowest priority tx
-    if (incomingMeta.priorityFee > lowestPriorityMeta.priorityFee) {
+    // Compare incoming tx against lowest priority tx.
+    // feeOnly mode (RPC): use strict fee comparison only — avoids churn from hash ordering.
+    // When price bump is also set, require the bumped fee threshold.
+    // Default (gossip): use full comparePriority (fee + tx hash tiebreaker) for determinism.
+    const isHigherPriority = context?.feeComparisonOnly
+      ? context.priceBumpPercentage !== undefined
+        ? incomingMeta.priorityFee >=
+          getMinimumPriceBumpFee(lowestPriorityMeta.priorityFee, context.priceBumpPercentage)
+        : incomingMeta.priorityFee > lowestPriorityMeta.priorityFee
+      : comparePriority(incomingMeta, lowestPriorityMeta) > 0;
+
+    if (isHigherPriority) {
       this.log.debug(
         `Pool at capacity (${currentCount}/${this.maxPoolSize}), evicting ${lowestPriorityMeta.txHash} ` +
           `(priority ${lowestPriorityMeta.priorityFee}) for ${incomingMeta.txHash} (priority ${incomingMeta.priorityFee})`,
@@ -53,6 +70,11 @@ export class LowPriorityPreAddRule implements PreAddRule {
     }
 
     // Incoming tx has equal or lower priority - ignore it (it would be evicted anyway)
+    const minimumFee =
+      context?.feeComparisonOnly && context.priceBumpPercentage !== undefined
+        ? getMinimumPriceBumpFee(lowestPriorityMeta.priorityFee, context.priceBumpPercentage)
+        : lowestPriorityMeta.priorityFee + 1n;
+
     this.log.debug(
       `Pool at capacity (${currentCount}/${this.maxPoolSize}), ignoring ${incomingMeta.txHash} ` +
         `(priority ${incomingMeta.priorityFee}) - lower than existing minimum (priority ${lowestPriorityMeta.priorityFee})`,
@@ -60,7 +82,12 @@ export class LowPriorityPreAddRule implements PreAddRule {
     return Promise.resolve({
       shouldIgnore: true,
       txHashesToEvict: [],
-      reason: `pool at capacity and tx has lower priority than existing transactions`,
+      reason: {
+        code: TxPoolRejectionCode.LOW_PRIORITY_FEE,
+        message: `Tx does not meet minimum priority fee. Required: ${minimumFee}, got: ${incomingMeta.priorityFee}`,
+        minimumPriorityFee: minimumFee,
+        txPriorityFee: incomingMeta.priorityFee,
+      },
     });
   }
 

package/src/mem_pools/tx_pool_v2/eviction/nullifier_conflict_rule.ts

@@ -1,7 +1,7 @@
 import { createLogger } from '@aztec/foundation/log';
 
 import { type TxMetaData, checkNullifierConflict } from '../tx_metadata.js';
-import type { PreAddPoolAccess, PreAddResult, PreAddRule } from './interfaces.js';
+import type { PreAddContext, PreAddPoolAccess, PreAddResult, PreAddRule } from './interfaces.js';
 
 /**
  * Pre-add rule that checks for nullifier conflicts between incoming and existing transactions.
@@ -15,15 +15,16 @@ export class NullifierConflictRule implements PreAddRule {
 
   private log = createLogger('p2p:tx_pool_v2:nullifier_conflict_rule');
 
-  check(incomingMeta: TxMetaData, poolAccess: PreAddPoolAccess): Promise<PreAddResult> {
+  check(incomingMeta: TxMetaData, poolAccess: PreAddPoolAccess, context?: PreAddContext): Promise<PreAddResult> {
     const result = checkNullifierConflict(
       incomingMeta,
       nullifier => poolAccess.getTxHashByNullifier(nullifier),
       txHash => poolAccess.getMetadata(txHash),
+      context?.priceBumpPercentage,
     );
 
     if (result.shouldIgnore) {
-      this.log.debug(`Ignoring tx ${incomingMeta.txHash}: ${result.reason}`);
+      this.log.debug(`Ignoring tx ${incomingMeta.txHash}: ${result.reason?.message}`);
     }
 
     return Promise.resolve(result);

package/src/mem_pools/tx_pool_v2/index.ts

@@ -7,6 +7,6 @@ export {
   type PoolReadAccess,
   DEFAULT_TX_POOL_V2_CONFIG,
 } from './interfaces.js';
-export { type TxMetaData, type TxState, buildTxMetaData, comparePriority } from './tx_metadata.js';
+export { type TxMetaData, type TxState, buildTxMetaData, comparePriority, stubTxMetaData } from './tx_metadata.js';
 export { TxArchive } from './archive/index.js';
 export { DeletedPool } from './deleted_pool.js';

package/src/mem_pools/tx_pool_v2/instrumentation.ts

@@ -0,0 +1,69 @@
+import {
+  Attributes,
+  type Meter,
+  Metrics,
+  type ObservableGauge,
+  type ObservableResult,
+  type TelemetryClient,
+  type UpDownCounter,
+  createUpDownCounterWithDefault,
+} from '@aztec/telemetry-client';
+
+/** Callback that returns the current estimated metadata memory in bytes. */
+export type MetadataMemoryCallback = () => number;
+
+/** Instrumentation for TxPoolV2Impl internal operations. */
+export class TxPoolV2Instrumentation {
+  #evictedCounter: UpDownCounter;
+  #ignoredCounter: UpDownCounter;
+  #rejectedCounter: UpDownCounter;
+  #softDeletedHitsCounter: UpDownCounter;
+  #missingOnProtectCounter: UpDownCounter;
+  #missingPreviouslyEvictedCounter: UpDownCounter;
+  #metadataMemoryGauge: ObservableGauge;
+
+  constructor(telemetry: TelemetryClient, metadataMemoryCallback: MetadataMemoryCallback) {
+    const meter: Meter = telemetry.getMeter('TxPoolV2Impl');
+
+    this.#evictedCounter = createUpDownCounterWithDefault(meter, Metrics.MEMPOOL_TX_POOL_V2_EVICTED_COUNT);
+    this.#ignoredCounter = createUpDownCounterWithDefault(meter, Metrics.MEMPOOL_TX_POOL_V2_IGNORED_COUNT);
+    this.#rejectedCounter = createUpDownCounterWithDefault(meter, Metrics.MEMPOOL_TX_POOL_V2_REJECTED_COUNT);
+    this.#softDeletedHitsCounter = createUpDownCounterWithDefault(meter, Metrics.MEMPOOL_TX_POOL_V2_SOFT_DELETED_HITS);
+    this.#missingOnProtectCounter = createUpDownCounterWithDefault(
+      meter,
+      Metrics.MEMPOOL_TX_POOL_V2_MISSING_ON_PROTECT,
+    );
+    this.#missingPreviouslyEvictedCounter = createUpDownCounterWithDefault(
+      meter,
+      Metrics.MEMPOOL_TX_POOL_V2_MISSING_PREVIOUSLY_EVICTED,
+    );
+    this.#metadataMemoryGauge = meter.createObservableGauge(Metrics.MEMPOOL_TX_POOL_V2_METADATA_MEMORY);
+    this.#metadataMemoryGauge.addCallback((result: ObservableResult) => {
+      result.observe(metadataMemoryCallback());
+    });
+  }
+
+  recordEvictions(count: number, reason: string) {
+    this.#evictedCounter.add(count, { [Attributes.TX_POOL_EVICTION_REASON]: reason });
+  }
+
+  recordIgnored(count: number) {
+    this.#ignoredCounter.add(count);
+  }
+
+  recordRejected(count: number) {
+    this.#rejectedCounter.add(count);
+  }
+
+  recordSoftDeletedHits(count: number) {
+    this.#softDeletedHitsCounter.add(count);
+  }
+
+  recordMissingOnProtect(count: number) {
+    this.#missingOnProtectCounter.add(count);
+  }
+
+  recordMissingPreviouslyEvicted(count: number) {
+    this.#missingPreviouslyEvictedCounter.add(count);
+  }
+}

package/src/mem_pools/tx_pool_v2/interfaces.ts

@@ -1,9 +1,11 @@
 import type { SlotNumber } from '@aztec/foundation/branded-types';
 import type { TypedEventEmitter } from '@aztec/foundation/types';
 import type { L2Block, L2BlockId, L2BlockSource } from '@aztec/stdlib/block';
+import type { BlockMinFeesProvider } from '@aztec/stdlib/gas';
 import type { WorldStateSynchronizer } from '@aztec/stdlib/interfaces/server';
 import type { BlockHeader, Tx, TxHash, TxValidator } from '@aztec/stdlib/tx';
 
+import type { TxPoolRejectionError } from './eviction/interfaces.js';
 import type { TxMetaData, TxState } from './tx_metadata.js';
 
 /**
@@ -17,6 +19,8 @@ export type AddTxsResult = {
   ignored: TxHash[];
   /** Transactions rejected because they failed validation (e.g., invalid proof, expired timestamp) */
   rejected: TxHash[];
+  /** Optional rejection errors, only present when there are rejections with structured errors. */
+  errors?: Map<string, TxPoolRejectionError>;
 };
 
 /**
@@ -37,6 +41,19 @@ export type TxPoolV2Config = {
   maxPendingTxCount: number;
   /** Maximum number of archived transactions to retain (0 = disabled) */
   archivedTxLimit: number;
+  /** Minimum age (ms) a transaction must have been in the pool before it's eligible for block building */
+  minTxPoolAgeMs: number;
+  /** Maximum number of evicted tx hashes to remember for metrics tracking */
+  evictedTxCacheSize: number;
+  /** The probability (0-1) that a transaction is discarded. 0 disables dropping. For testing purposes only. */
+  dropTransactionsProbability: number;
+  /** Minimum percentage fee increase required to replace an existing tx via RPC (0 = no bump). */
+  priceBumpPercentage: bigint;
+  /**
+   * Number of slots behind the finalized tip to keep finalized txs for before deleting them. 0 deletes
+   * at the finalized tip (default).
+   */
+  keepFinalizedTxsForSlots: number;
 };
 
 /**
@@ -45,6 +62,11 @@ export type TxPoolV2Config = {
 export const DEFAULT_TX_POOL_V2_CONFIG: TxPoolV2Config = {
   maxPendingTxCount: 0, // 0 = disabled
   archivedTxLimit: 0, // 0 = disabled
+  minTxPoolAgeMs: 2_000,
+  evictedTxCacheSize: 10_000,
+  dropTransactionsProbability: 0,
+  priceBumpPercentage: 10n,
+  keepFinalizedTxsForSlots: 0,
 };
 
 /**
@@ -57,6 +79,10 @@ export type TxPoolV2Dependencies = {
   worldStateSynchronizer: WorldStateSynchronizer;
   /** Factory that creates a validator for re-validating pool transactions using metadata */
   createTxValidator: () => Promise<TxValidator<TxMetaData>>;
+  /** Checks whether a tx's setup-phase calls are on the allow list. Precomputed at receipt time. */
+  checkAllowedSetupCalls: (tx: Tx) => Promise<boolean>;
+  /** Provides projected minimum fees for the next block. Used by eviction rules instead of stale block header fees. */
+  blockMinFeesProvider: BlockMinFeesProvider;
 };
 
 /**
@@ -95,15 +121,15 @@ export interface TxPoolV2 extends TypedEventEmitter<TxPoolV2Events> {
    * @param opts - Optional metadata (e.g., source for logging)
    * @returns Result categorizing each transaction as accepted, rejected, or ignored
    */
-  addPendingTxs(txs: Tx[], opts?: { source?: string }): Promise<AddTxsResult>;
+  addPendingTxs(txs: Tx[], opts?: { source?: string; feeComparisonOnly?: boolean }): Promise<AddTxsResult>;
 
   /**
-   * Checks if a transaction can be added without modifying the pool.
-   * Performs the same validation as addPendingTxs but doesn't persist changes.
+   * Checks if the pool would accept a transaction without modifying state.
+   * Used as a pre-check before expensive proof verification.
    * @param tx - Transaction to check
-   * @returns Result: 'accepted', 'ignored' (if already in pool or undesirable), or 'rejected' (if validation fails)
+   * @returns 'accepted' if the pool would accept, 'ignored' if already in pool or undesirable
    */
-  canAddPendingTx(tx: Tx): Promise<'accepted' | 'ignored' | 'rejected'>;
+  canAddPendingTx(tx: Tx): Promise<'accepted' | 'ignored'>;
 
   /**
    * Adds transactions as immediately protected for a given slot.
@@ -143,20 +169,31 @@ export interface TxPoolV2 extends TypedEventEmitter<TxPoolV2Events> {
   handleMinedBlock(block: L2Block): Promise<void>;
 
   /**
-   * Prepares the pool for a new slot.
-   * Unprotects transactions from earlier slots and validates them before
-   * returning to pending state.
-   * @param slotNumber - The slot number to prepare for
+   * Prepares the pool for a new slot by unprotecting transactions from earlier
+   * slots and re-validating them before returning to pending state.
+   * @param slotNumber - The pipeline slot we are building for (i.e. the slot
+   *   the resulting blocks will target on L1).
    */
   prepareForSlot(slotNumber: SlotNumber): Promise<void>;
 
+  /**
+   * Releases the protections a failed block proposal created and restores the txs to pending.
+   * Only clears protection entries still recorded at exactly the given slot: a tx that another,
+   * still-live proposal raised to a higher slot via {@link protectTxs} keeps its protection, and
+   * mined txs (which carry no protection entry) are left untouched. Restored txs are re-validated
+   * and resolved against nullifier conflicts before re-entering the pending indices.
+   * @param txHashes - Hashes of the proposal's txs to release.
+   * @param slotNumber - The slot the failed proposal targeted; protection is released only for this slot.
+   */
+  unprotectTxs(txHashes: TxHash[], slotNumber: SlotNumber): Promise<void>;
+
   /**
    * Handles pruned blocks during a reorg.
    * Un-mines all transactions mined in blocks beyond the given latest block
    * and validates them before returning to pending.
    * @param latestBlock - The latest valid block ID after the prune
    */
-  handlePrunedBlocks(latestBlock: L2BlockId): Promise<void>;
+  handlePrunedBlocks(latestBlock: L2BlockId, options?: { deleteAllTxs?: boolean }): Promise<void>;
 
   /**
    * Handles failed transaction execution.
@@ -172,11 +209,11 @@ export interface TxPoolV2 extends TypedEventEmitter<TxPoolV2Events> {
    */
   handleFinalizedBlock(block: BlockHeader): Promise<void>;
 
-  /** Gets a transaction by its hash */
-  getTxByHash(txHash: TxHash): Promise<Tx | undefined>;
+  /** Gets a transaction by its hash. Set `includeProof: false` to skip loading the proof from the DB. */
+  getTxByHash(txHash: TxHash, opts?: { includeProof?: boolean }): Promise<Tx | undefined>;
 
-  /** Gets multiple transactions by their hashes */
-  getTxsByHash(txHashes: TxHash[]): Promise<(Tx | undefined)[]>;
+  /** Gets multiple transactions by their hashes. Set `includeProof: false` to skip loading proofs from the DB. */
+  getTxsByHash(txHashes: TxHash[], opts?: { includeProof?: boolean }): Promise<(Tx | undefined)[]>;
 
   /** Checks if transactions exist in the pool */
   hasTxs(txHashes: TxHash[]): Promise<boolean[]>;
@@ -187,9 +224,19 @@ export interface TxPoolV2 extends TypedEventEmitter<TxPoolV2Events> {
   /** Gets pending transaction hashes sorted by priority (highest first) */
   getPendingTxHashes(): Promise<TxHash[]>;
 
+  /** Gets pending transaction hashes that have been in the pool long enough per minTxPoolAgeMs, sorted by priority (highest first) */
+  getEligiblePendingTxHashes(): Promise<TxHash[]>;
+
   /** Gets the count of pending transactions */
   getPendingTxCount(): Promise<number>;
 
+  /**
+   * Returns whether at least `minCount` pending transactions are old enough per minTxPoolAgeMs to be eligible
+   * for block building. Stops scanning once the threshold is reached, so it is cheaper than counting all
+   * eligible txs when only a few are needed.
+   */
+  hasEligiblePendingTxs(minCount: number): Promise<boolean>;
+
   /** Gets mined transaction hashes with their block IDs */
   getMinedTxHashes(): Promise<[TxHash, L2BlockId][]>;