@aztec/p2p 0.0.1-commit.7d4e6cd → 0.0.1-commit.87a0206

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

@@ -0,0 +1,74 @@
+import { createLogger } from '@aztec/foundation/log';
+
+import type { EvictionContext, EvictionResult, EvictionRule, PoolOperations } from './interfaces.js';
+import { EvictionEvent } from './interfaces.js';
+
+/**
+ * Eviction rule that removes invalid transactions after a block is mined.
+ * Only triggers on BLOCK_MINED events.
+ *
+ * Eviction criteria includes:
+ * - Transactions with nullifiers that are already included in the mined block
+ * - Transactions with an expiration timestamp less than or equal to the mined block timestamp
+ */
+export class InvalidTxsAfterMiningRule implements EvictionRule {
+  public readonly name = 'InvalidTxsAfterMining';
+
+  private log = createLogger('p2p:tx_pool_v2:invalid_txs_after_mining_rule');
+
+  async evict(context: EvictionContext, pool: PoolOperations): Promise<EvictionResult> {
+    if (context.event !== EvictionEvent.BLOCK_MINED) {
+      return {
+        reason: 'block_mined_invalid_txs',
+        success: true,
+        txsEvicted: [],
+      };
+    }
+
+    try {
+      const { timestamp } = context.block.globalVariables;
+      const minedNullifiers = new Set(context.newNullifiers);
+
+      const txsToEvict: string[] = [];
+      const pendingTxs = pool.getPendingTxs();
+
+      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) {
+          this.log.verbose(
+            `Evicting tx ${meta.txHash} from pool due to the tx being expired (includeByTimestamp: ${meta.includeByTimestamp}, mined block timestamp: ${timestamp})`,
+          );
+          txsToEvict.push(meta.txHash);
+          continue;
+        }
+      }
+
+      if (txsToEvict.length > 0) {
+        await pool.deleteTxs(txsToEvict);
+      }
+
+      this.log.debug(`Evicted ${txsToEvict.length} invalid txs after block mined`);
+
+      return {
+        reason: 'block_mined_invalid_txs',
+        success: true,
+        txsEvicted: txsToEvict,
+      };
+    } catch (err) {
+      this.log.error('Failed to evict invalid transactions after mining', { err });
+      return {
+        reason: 'block_mined_invalid_txs',
+        success: false,
+        txsEvicted: [],
+        error: new Error('Failed to evict invalid txs after mining', { cause: err }),
+      };
+    }
+  }
+}

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

@@ -0,0 +1,101 @@
+import { Fr } from '@aztec/foundation/curves/bn254';
+import { createLogger } from '@aztec/foundation/log';
+import type { WorldStateSynchronizer } from '@aztec/stdlib/interfaces/server';
+import { MerkleTreeId } from '@aztec/stdlib/trees';
+
+import type { EvictionContext, EvictionResult, EvictionRule, PoolOperations } from './interfaces.js';
+import { EvictionEvent } from './interfaces.js';
+
+/**
+ * Eviction rule that removes invalid transactions after a blockchain reorganization.
+ * Only triggers on CHAIN_PRUNED events.
+ *
+ * Eviction criteria includes:
+ * - Transactions that reference pruned block hashes (invalid by definition)
+ */
+export class InvalidTxsAfterReorgRule implements EvictionRule {
+  public readonly name = 'InvalidTxsAfterReorg';
+
+  private log = createLogger('p2p:tx_pool_v2:invalid_txs_after_reorg_rule');
+
+  constructor(private worldState: WorldStateSynchronizer) {}
+
+  async evict(context: EvictionContext, pool: PoolOperations): Promise<EvictionResult> {
+    if (context.event !== EvictionEvent.CHAIN_PRUNED) {
+      return {
+        reason: 'reorg_invalid_txs',
+        success: true,
+        txsEvicted: [],
+      };
+    }
+
+    try {
+      const pendingTxs = pool.getPendingTxs();
+
+      // Deduplicate block hashes to reduce redundant DB lookups
+      const uniqueBlockHashes = new Map<string, Fr>();
+      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));
+        }
+        txsByBlockHash.get(blockHashStr)!.push(meta.txHash);
+      }
+
+      // Ensure world state is synced to this block before accessing the snapshot
+      await this.worldState.syncImmediate(context.blockNumber);
+      const db = this.worldState.getSnapshot(context.blockNumber);
+
+      // Check which blocks exist in the archive
+      const blockHashArray = Array.from(uniqueBlockHashes.values());
+      const blocksFromDb = await db.findLeafIndices(MerkleTreeId.ARCHIVE, blockHashArray);
+
+      // Build set of pruned block hashes
+      const prunedBlockHashes = new Set<string>();
+      let i = 0;
+      for (const [blockHashStr] of uniqueBlockHashes) {
+        if (blocksFromDb[i] === undefined) {
+          prunedBlockHashes.add(blockHashStr);
+        }
+        i++;
+      }
+
+      // Identify txs whose anchor block was pruned
+      const txsToEvict: string[] = [];
+      for (const [blockHashStr, txHashes] of txsByBlockHash) {
+        if (prunedBlockHashes.has(blockHashStr)) {
+          txsToEvict.push(...txHashes);
+        }
+      }
+
+      if (txsToEvict.length > 0) {
+        this.log.verbose(`Evicting ${txsToEvict.length} txs from pool due to referencing pruned blocks`);
+        await pool.deleteTxs(txsToEvict);
+      }
+
+      const keptCount = pendingTxs.length - txsToEvict.length;
+      if (keptCount > 0) {
+        this.log.verbose(`Kept ${keptCount} txs that did not reference pruned blocks`);
+      }
+
+      this.log.debug(`Evicted ${txsToEvict.length} invalid txs after reorg`);
+
+      return {
+        reason: 'reorg_invalid_txs',
+        success: true,
+        txsEvicted: txsToEvict,
+      };
+    } catch (err) {
+      this.log.error('Failed to evict invalid transactions after reorg', { err });
+      return {
+        reason: 'reorg_invalid_txs',
+        success: false,
+        txsEvicted: [],
+        error: new Error('Failed to evict invalid txs after reorg', { cause: err }),
+      };
+    }
+  }
+}

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

@@ -0,0 +1,86 @@
+import { createLogger } from '@aztec/foundation/log';
+
+import type { EvictionConfig, EvictionContext, EvictionResult, EvictionRule, PoolOperations } from './interfaces.js';
+import { EvictionEvent } from './interfaces.js';
+
+/**
+ * Eviction rule that removes low-priority transactions when the pool exceeds configured limits.
+ * Only triggers on TXS_ADDED events.
+ */
+export class LowPriorityEvictionRule implements EvictionRule {
+  public readonly name = 'LowPriorityEviction';
+
+  private log = createLogger('p2p:tx_pool_v2:low_priority_eviction_rule');
+  private maxPoolSize: number;
+
+  constructor(config: { maxPoolSize: number }) {
+    this.maxPoolSize = config.maxPoolSize;
+  }
+
+  async evict(context: EvictionContext, pool: PoolOperations): Promise<EvictionResult> {
+    if (context.event !== EvictionEvent.TXS_ADDED) {
+      return {
+        reason: 'low_priority',
+        success: true,
+        txsEvicted: [],
+      };
+    }
+
+    if (this.maxPoolSize === 0) {
+      return {
+        reason: 'low_priority',
+        success: true,
+        txsEvicted: [],
+      };
+    }
+
+    try {
+      const currentTxCount = pool.getPendingTxCount();
+
+      if (currentTxCount <= this.maxPoolSize) {
+        this.log.trace(
+          `Not evicting low priority txs. Pending tx count below limit ${currentTxCount} <= ${this.maxPoolSize}`,
+        );
+        return {
+          reason: 'low_priority',
+          success: true,
+          txsEvicted: [],
+        };
+      }
+
+      this.log.verbose(
+        `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);
+      }
+
+      const numNewTxsEvicted = context.newTxHashes.filter(newTxHash => txsToEvict.includes(newTxHash)).length;
+
+      this.log.verbose(`Evicted ${txsToEvict.length} low priority txs, including ${numNewTxsEvicted} newly added txs`);
+
+      return {
+        reason: 'low_priority',
+        success: true,
+        txsEvicted: txsToEvict,
+      };
+    } catch (err) {
+      this.log.error('Failed to evict low priority transactions', { err });
+      return {
+        reason: 'low_priority',
+        success: false,
+        txsEvicted: [],
+        error: new Error('Failed to evict low priority txs', { cause: err }),
+      };
+    }
+  }
+
+  updateConfig(config: EvictionConfig): void {
+    if (config.maxPendingTxCount !== undefined) {
+      this.maxPoolSize = config.maxPendingTxCount;
+    }
+  }
+}

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

@@ -0,0 +1,72 @@
+import { createLogger } from '@aztec/foundation/log';
+
+import type { TxMetaData } from '../tx_metadata.js';
+import type { EvictionConfig, PreAddPoolAccess, PreAddResult, PreAddRule } from './interfaces.js';
+
+/**
+ * Pre-add rule that checks if the pool is at capacity and handles low-priority eviction.
+ *
+ * When the pool is at capacity:
+ * - If incoming tx has higher priority than the lowest priority tx, evict the lowest and accept incoming
+ * - If incoming tx has equal or lower priority than the lowest, ignore incoming (it would be evicted anyway)
+ */
+export class LowPriorityPreAddRule implements PreAddRule {
+  public readonly name = 'LowPriorityPreAdd';
+
+  private log = createLogger('p2p:tx_pool_v2:low_priority_pre_add_rule');
+  private maxPoolSize: number;
+
+  constructor(config: { maxPoolSize: number }) {
+    this.maxPoolSize = config.maxPoolSize;
+  }
+
+  check(incomingMeta: TxMetaData, poolAccess: PreAddPoolAccess): Promise<PreAddResult> {
+    // Skip if max pool size is disabled (0 = unlimited)
+    if (this.maxPoolSize === 0) {
+      return Promise.resolve({ shouldIgnore: false, txHashesToEvict: [] });
+    }
+
+    const currentCount = poolAccess.getPendingTxCount();
+
+    // If pool is not at capacity, accept the tx
+    if (currentCount < this.maxPoolSize) {
+      return Promise.resolve({ shouldIgnore: false, txHashesToEvict: [] });
+    }
+
+    // Pool is at capacity - need to compare priorities
+    const lowestPriorityMeta = poolAccess.getLowestPriorityPendingTx();
+    if (!lowestPriorityMeta) {
+      // No pending txs (shouldn't happen if count > 0, but handle gracefully)
+      return Promise.resolve({ shouldIgnore: false, txHashesToEvict: [] });
+    }
+
+    // If incoming tx has strictly higher priority, evict the lowest priority tx
+    if (incomingMeta.priorityFee > lowestPriorityMeta.priorityFee) {
+      this.log.debug(
+        `Pool at capacity (${currentCount}/${this.maxPoolSize}), evicting ${lowestPriorityMeta.txHash} ` +
+          `(priority ${lowestPriorityMeta.priorityFee}) for ${incomingMeta.txHash} (priority ${incomingMeta.priorityFee})`,
+      );
+      return Promise.resolve({
+        shouldIgnore: false,
+        txHashesToEvict: [lowestPriorityMeta.txHash],
+      });
+    }
+
+    // Incoming tx has equal or lower priority - ignore it (it would be evicted anyway)
+    this.log.debug(
+      `Pool at capacity (${currentCount}/${this.maxPoolSize}), ignoring ${incomingMeta.txHash} ` +
+        `(priority ${incomingMeta.priorityFee}) - lower than existing minimum (priority ${lowestPriorityMeta.priorityFee})`,
+    );
+    return Promise.resolve({
+      shouldIgnore: true,
+      txHashesToEvict: [],
+      reason: `pool at capacity and tx has lower priority than existing transactions`,
+    });
+  }
+
+  updateConfig(config: EvictionConfig): void {
+    if (config.maxPendingTxCount !== undefined) {
+      this.maxPoolSize = config.maxPendingTxCount;
+    }
+  }
+}

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

@@ -0,0 +1,31 @@
+import { createLogger } from '@aztec/foundation/log';
+
+import { type TxMetaData, checkNullifierConflict } from '../tx_metadata.js';
+import type { PreAddPoolAccess, PreAddResult, PreAddRule } from './interfaces.js';
+
+/**
+ * Pre-add rule that checks for nullifier conflicts between incoming and existing transactions.
+ *
+ * When an incoming tx shares nullifiers with existing pending txs:
+ * - If the incoming tx has strictly higher priority, evict all conflicting txs
+ * - If any conflicting tx has equal or higher priority, ignore the incoming tx
+ */
+export class NullifierConflictRule implements PreAddRule {
+  public readonly name = 'NullifierConflict';
+
+  private log = createLogger('p2p:tx_pool_v2:nullifier_conflict_rule');
+
+  check(incomingMeta: TxMetaData, poolAccess: PreAddPoolAccess): Promise<PreAddResult> {
+    const result = checkNullifierConflict(
+      incomingMeta,
+      nullifier => poolAccess.getTxHashByNullifier(nullifier),
+      txHash => poolAccess.getMetadata(txHash),
+    );
+
+    if (result.shouldIgnore) {
+      this.log.debug(`Ignoring tx ${incomingMeta.txHash}: ${result.reason}`);
+    }
+
+    return Promise.resolve(result);
+  }
+}

package/src/mem_pools/tx_pool_v2/index.ts

@@ -0,0 +1,11 @@
+export { AztecKVTxPoolV2 } from './tx_pool_v2.js';
+export {
+  type TxPoolV2,
+  type TxPoolV2Config,
+  type TxPoolV2Events,
+  type AddTxsResult,
+  type PoolReadAccess,
+  DEFAULT_TX_POOL_V2_CONFIG,
+} from './interfaces.js';
+export { type TxMetaData, type TxState, buildTxMetaData, comparePriority } from './tx_metadata.js';
+export { TxArchive } from './archive/index.js';

package/src/mem_pools/tx_pool_v2/interfaces.ts

@@ -0,0 +1,227 @@
+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 { WorldStateSynchronizer } from '@aztec/stdlib/interfaces/server';
+import type { BlockHeader, Tx, TxHash, TxValidator } from '@aztec/stdlib/tx';
+
+import type { TxMetaData, TxState } from './tx_metadata.js';
+
+/**
+ * Result of adding transactions to the pending pool.
+ * Categorizes transactions by their outcome.
+ */
+export type AddTxsResult = {
+  /** Transactions successfully added to the pool */
+  accepted: TxHash[];
+  /** Transactions ignored because they're valid but undesirable (e.g., duplicate, lower priority nullifier conflict) */
+  ignored: TxHash[];
+  /** Transactions rejected because they failed validation (e.g., invalid proof, expired timestamp) */
+  rejected: TxHash[];
+};
+
+/**
+ * Events emitted by TxPoolV2.
+ */
+export type TxPoolV2Events = {
+  /** Emitted when transactions are successfully added to the pool */
+  'txs-added': (args: { txs: Tx[]; source?: string }) => void;
+  /** Emitted when transactions are removed from the pool */
+  'txs-removed': (args: { txHashes: TxHash[] }) => void;
+};
+
+/**
+ * Configuration options for TxPoolV2.
+ */
+export type TxPoolV2Config = {
+  /** Maximum number of pending transactions before low-priority eviction */
+  maxPendingTxCount: number;
+  /** Maximum number of archived transactions to retain (0 = disabled) */
+  archivedTxLimit: number;
+};
+
+/**
+ * Default configuration values for TxPoolV2.
+ */
+export const DEFAULT_TX_POOL_V2_CONFIG: TxPoolV2Config = {
+  maxPendingTxCount: 0, // 0 = disabled
+  archivedTxLimit: 0, // 0 = disabled
+};
+
+/**
+ * Dependencies required by TxPoolV2.
+ */
+export type TxPoolV2Dependencies = {
+  /** Block source (Archiver) for checking mined status and verifying pruned blocks */
+  l2BlockSource: L2BlockSource;
+  /** World state synchronizer for validating transactions after chain prunes */
+  worldStateSynchronizer: WorldStateSynchronizer;
+  /** Validator for transactions entering the pending pool */
+  pendingTxValidator: TxValidator<Tx>;
+};
+
+/**
+ * Read-only access to pool state for pre-add checks.
+ * Used by eviction rules to inspect pool state during transaction addition.
+ */
+export interface PoolReadAccess {
+  /** Get metadata for a transaction by its hash (as string) */
+  getMetadata(txHash: string): TxMetaData | undefined;
+  /** Get the transaction hash that uses a specific nullifier (as string) */
+  getTxHashByNullifier(nullifier: string): string | undefined;
+  /** Get all transaction hashes for a fee payer (as string) */
+  getTxHashesByFeePayer(feePayer: string): Set<string> | undefined;
+  /** Get the current pending transaction count */
+  getPendingTxCount(): number;
+}
+
+/**
+ *
+ * The pool manages transactions through a state machine:
+ * - Pending: Transaction is awaiting inclusion in a block
+ * - Protected: Transaction is being considered for a block proposal
+ * - Mined: Transaction has been included in a block
+ * - Deleted: Transaction has been removed from the pool
+ *
+ * All state-mutating operations are serialized through a handler queue
+ * to prevent race conditions.
+ */
+export interface TxPoolV2 extends TypedEventEmitter<TxPoolV2Events> {
+  // === Core Operations ===
+
+  /**
+   * Adds transactions to the pending pool with challenge and validation.
+   * Handles nullifier conflicts via the challenge mechanism.
+   * @param txs - Transactions to add
+   * @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>;
+
+  /**
+   * Checks if a transaction can be added without modifying the pool.
+   * Performs the same validation as addPendingTxs but doesn't persist changes.
+   * @param tx - Transaction to check
+   * @returns Result: 'accepted', 'ignored' (if already in pool or undesirable), or 'rejected' (if validation fails)
+   */
+  canAddPendingTx(tx: Tx): Promise<'accepted' | 'ignored' | 'rejected'>;
+
+  /**
+   * Adds transactions as immediately protected for a given slot.
+   * Used when receiving transactions from a block proposal we're validating.
+   * @param txs - Transactions to add as protected
+   * @param block - Block header providing slot context
+   * @param opts - Optional metadata (e.g., source for logging)
+   */
+  addProtectedTxs(txs: Tx[], block: BlockHeader, opts?: { source?: string }): Promise<void>;
+
+  /**
+   * Protects existing transactions by hash for a given slot.
+   * Returns hashes of transactions that weren't found in the pool.
+   * Records unknown hashes for automatic protection when received via gossip.
+   * @param txHashes - Hashes of transactions to protect
+   * @param block - Block header providing slot context
+   * @returns Hashes of transactions not found in the pool
+   */
+  protectTxs(txHashes: TxHash[], block: BlockHeader): Promise<TxHash[]>;
+
+  /**
+   * Adds transactions as already mined.
+   * Used by prover nodes fetching transactions via request/response.
+   * @param txs - Transactions to add as mined
+   * @param block - Block header the transactions were mined in
+   * @param opts - Optional metadata (e.g., source for logging)
+   */
+  addMinedTxs(txs: Tx[], block: BlockHeader, opts?: { source?: string }): Promise<void>;
+
+  // === State Transition Handlers ===
+
+  /**
+   * Handles a mined block - marks transactions as mined and evicts conflicting pending txs.
+   * Uses nullifiers directly from the block to evict pending transactions with conflicts.
+   * @param block - The complete mined block
+   */
+  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
+   */
+  prepareForSlot(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>;
+
+  /**
+   * Handles failed transaction execution.
+   * Deletes transactions that failed during block building.
+   * @param txHashes - Hashes of transactions that failed
+   */
+  handleFailedExecution(txHashes: TxHash[]): Promise<void>;
+
+  /**
+   * Handles a finalized block.
+   * Permanently deletes mined transactions and optionally archives them.
+   * @param block - Header of the finalized block
+   */
+  handleFinalizedBlock(block: BlockHeader): Promise<void>;
+
+  /** Gets a transaction by its hash */
+  getTxByHash(txHash: TxHash): Promise<Tx | undefined>;
+
+  /** Gets multiple transactions by their hashes */
+  getTxsByHash(txHashes: TxHash[]): Promise<(Tx | undefined)[]>;
+
+  /** Checks if transactions exist in the pool */
+  hasTxs(txHashes: TxHash[]): Promise<boolean[]>;
+
+  /** Gets the status of a transaction */
+  getTxStatus(txHash: TxHash): Promise<TxState | 'deleted' | undefined>;
+
+  /** Gets pending transaction hashes sorted by priority (highest first) */
+  getPendingTxHashes(): Promise<TxHash[]>;
+
+  /** Gets the count of pending transactions */
+  getPendingTxCount(): Promise<number>;
+
+  /** Gets mined transaction hashes with their block IDs */
+  getMinedTxHashes(): Promise<[TxHash, L2BlockId][]>;
+
+  /** Gets the count of mined transactions */
+  getMinedTxCount(): Promise<number>;
+
+  /** Checks if the pool is empty */
+  isEmpty(): Promise<boolean>;
+
+  /** Gets an archived transaction by its hash */
+  getArchivedTxByHash(txHash: TxHash): Promise<Tx | undefined>;
+
+  /** Gets the lowest priority pending transactions */
+  getLowestPriorityPending(limit: number): Promise<TxHash[]>;
+
+  // === Configuration ===
+
+  /** Updates the pool configuration */
+  updateConfig(config: Partial<TxPoolV2Config>): Promise<void>;
+
+  // === Lifecycle ===
+
+  /**
+   * Starts the pool and initializes state from persistence.
+   * Must be called before other operations.
+   * - Reads all transactions from the database
+   * - Checks each against the Archiver to determine mined status
+   * - Validates all non-mined transactions
+   * - Populates in-memory indices
+   */
+  start(): Promise<void>;
+
+  /** Stops the pool and releases resources */
+  stop(): Promise<void>;
+}