@aztec/p2p 0.0.1-commit.f504929 → 0.0.1-commit.f5a9928

package/src/mem_pools/tx_pool_v2/tx_metadata.ts

@@ -1,12 +1,12 @@
+import { minBigint } from '@aztec/foundation/bigint';
 import { BlockNumber } from '@aztec/foundation/branded-types';
 import { Fr } from '@aztec/foundation/curves/bn254';
 import { ProtocolContractAddress } from '@aztec/protocol-contracts';
 import { BlockHash, type L2BlockId } from '@aztec/stdlib/block';
-import { Gas } from '@aztec/stdlib/gas';
+import { Gas, GasFees } from '@aztec/stdlib/gas';
 import { type Tx, TxHash } from '@aztec/stdlib/tx';
 
 import { getFeePayerBalanceDelta } from '../../msg_validators/tx_validator/fee_payer_balance.js';
-import { getTxPriorityFee } from '../tx_pool/priority.js';
 import { type PreAddResult, TxPoolRejectionCode } from './eviction/interfaces.js';
 
 /** Validator-compatible data interface, mirroring the subset of PrivateKernelTailCircuitPublicInputs used by validators. */
@@ -23,7 +23,7 @@ export type TxMetaValidationData = {
       };
     };
     txContext: {
-      gasSettings: { gasLimits: Gas };
+      gasSettings: { gasLimits: Gas; maxFeesPerGas: GasFees };
     };
   };
 };
@@ -67,6 +67,9 @@ export type TxMetaData = {
   /** Timestamp by which the transaction must be included (for expiration checks) */
   readonly expirationTimestamp: bigint;
 
+  /** Whether the tx's setup-phase calls pass the allow list check. Computed at receipt time. */
+  readonly allowedSetupCalls: boolean;
+
   /** Validator-compatible data, providing the same access patterns as Tx.data */
   readonly data: TxMetaValidationData;
 
@@ -84,8 +87,12 @@ export type TxState = 'pending' | 'protected' | 'mined' | 'deleted';
  * Builds TxMetaData from a full Tx object.
  * Extracts all relevant fields for efficient in-memory storage and querying.
  * Fr values are captured in closures for zero-cost re-validation.
+ *
+ * @param allowedSetupCalls - Whether the tx's setup-phase calls pass the allow list.
+ *   For gossip/RPC txs this is always `true` (already validated by PhasesTxValidator).
+ *   For req/resp txs this should be computed by the caller using the phases validator.
  */
-export async function buildTxMetaData(tx: Tx): Promise<TxMetaData> {
+export async function buildTxMetaData(tx: Tx, allowedSetupCalls: boolean = true): Promise<TxMetaData> {
   const txHashObj = tx.getTxHash();
   const txHash = txHashObj.toString();
   const txHashBigInt = txHashObj.toBigInt();
@@ -112,6 +119,7 @@ export async function buildTxMetaData(tx: Tx): Promise<TxMetaData> {
     feeLimit,
     nullifiers,
     expirationTimestamp,
+    allowedSetupCalls,
     receivedAt: 0,
     estimatedSizeBytes,
     data: {
@@ -124,7 +132,10 @@ export async function buildTxMetaData(tx: Tx): Promise<TxMetaData> {
           globalVariables: { blockNumber: anchorBlockNumber },
         },
         txContext: {
-          gasSettings: { gasLimits: tx.data.constants.txContext.gasSettings.gasLimits },
+          gasSettings: {
+            gasLimits: tx.data.constants.txContext.gasSettings.gasLimits,
+            maxFeesPerGas: tx.data.constants.txContext.gasSettings.maxFeesPerGas,
+          },
         },
       },
     },
@@ -158,13 +169,13 @@ export function txHashFromBigInt(value: bigint): string {
 }
 
 /** Minimal fields required for priority comparison. */
-type PriorityComparable = Pick<TxMetaData, 'txHashBigInt' | 'priorityFee'>;
+export type PriorityComparable = Pick<TxMetaData, 'txHash' | 'txHashBigInt' | 'priorityFee'>;
 
 /**
  * Compares two priority fees in ascending order.
  * Returns negative if a < b, positive if a > b, 0 if equal.
  */
-export function compareFee(a: bigint, b: bigint): number {
+export function compareFee(a: bigint, b: bigint): -1 | 0 | 1 {
   return a < b ? -1 : a > b ? 1 : 0;
 }
 
@@ -173,7 +184,7 @@ export function compareFee(a: bigint, b: bigint): number {
  * Uses field element comparison for deterministic ordering.
  * Returns negative if a < b, positive if a > b, 0 if equal.
  */
-export function compareTxHash(a: bigint, b: bigint): number {
+export function compareTxHash(a: bigint, b: bigint): -1 | 0 | 1 {
   return Fr.cmpAsBigInt(a, b);
 }
 
@@ -182,7 +193,7 @@ export function compareTxHash(a: bigint, b: bigint): number {
  * Returns negative if a < b, positive if a > b, 0 if equal.
  * Use with sort() for ascending order, or negate/reverse for descending.
  */
-export function comparePriority(a: PriorityComparable, b: PriorityComparable): number {
+export function comparePriority(a: PriorityComparable, b: PriorityComparable): -1 | 0 | 1 {
   const feeComparison = compareFee(a.priorityFee, b.priorityFee);
   if (feeComparison !== 0) {
     return feeComparison;
@@ -190,21 +201,38 @@ export function comparePriority(a: PriorityComparable, b: PriorityComparable): n
   return compareTxHash(a.txHashBigInt, b.txHashBigInt);
 }
 
+/**
+ * Returns the minimum fee required to replace an existing tx with the given price bump percentage.
+ * Uses integer arithmetic: `existingFee + existingFee * priceBumpPercentage / 100`.
+ */
+export function getMinimumPriceBumpFee(existingFee: bigint, priceBumpPercentage: bigint): bigint {
+  const bump = (existingFee * priceBumpPercentage) / 100n;
+  // Ensure the minimum bump is at least 1, so that replacement always requires
+  // paying strictly more — even with 0% bump or zero existing fee.
+  const effectiveBump = bump > 0n ? bump : 1n;
+  return existingFee + effectiveBump;
+}
+
 /**
  * Checks for nullifier conflicts between an incoming transaction and existing pool state.
  *
  * When the incoming tx shares nullifiers with existing pending txs:
- * - If the incoming tx has strictly higher priority, mark conflicting txs for eviction
- * - If any conflicting tx has equal or higher priority, ignore the incoming tx
+ * - If the incoming tx meets or exceeds the required priority, mark conflicting txs for eviction
+ * - Otherwise, ignore the incoming tx
+ *
+ * When `priceBumpPercentage` is provided (RPC path), uses fee-only comparison with the
+ * percentage bump instead of `comparePriority`.
  *
  * @param incomingMeta - Metadata for the incoming transaction
  * @param getTxHashByNullifier - Accessor to find which tx uses a nullifier
  * @param getMetadata - Accessor to get metadata for a tx hash
+ * @param priceBumpPercentage - Optional percentage bump required for fee-based replacement
  */
 export function checkNullifierConflict(
   incomingMeta: TxMetaData,
   getTxHashByNullifier: (nullifier: string) => string | undefined,
   getMetadata: (txHash: string) => TxMetaData | undefined,
+  priceBumpPercentage?: bigint,
 ): PreAddResult {
   const txHashesToEvict: string[] = [];
 
@@ -225,19 +253,32 @@ export function checkNullifierConflict(
       continue;
     }
 
-    // If incoming tx has strictly higher priority, mark for eviction
-    // Otherwise, ignore incoming tx (ties go to existing tx)
-    // Use comparePriority for deterministic ordering (includes txHash as tiebreaker)
-    if (comparePriority(incomingMeta, conflictingMeta) > 0) {
+    // When price bump is set (RPC path), require the incoming fee to meet the bumped threshold.
+    // Otherwise (P2P path), use full comparePriority with tx hash tiebreaker.
+    const isHigherPriority =
+      priceBumpPercentage !== undefined
+        ? incomingMeta.priorityFee >= getMinimumPriceBumpFee(conflictingMeta.priorityFee, priceBumpPercentage)
+        : comparePriority(incomingMeta, conflictingMeta) > 0;
+
+    if (isHigherPriority) {
       txHashesToEvict.push(conflictingHashStr);
     } else {
+      const minimumFee =
+        priceBumpPercentage !== undefined
+          ? getMinimumPriceBumpFee(conflictingMeta.priorityFee, priceBumpPercentage)
+          : undefined;
       return {
         shouldIgnore: true,
         txHashesToEvict: [],
         reason: {
           code: TxPoolRejectionCode.NULLIFIER_CONFLICT,
-          message: `Nullifier conflict with existing tx ${conflictingHashStr}`,
+          message:
+            minimumFee !== undefined
+              ? `Nullifier conflict with existing tx ${conflictingHashStr}. Minimum required fee: ${minimumFee}, got: ${incomingMeta.priorityFee}`
+              : `Nullifier conflict with existing tx ${conflictingHashStr}`,
           conflictingTxHash: conflictingHashStr,
+          minimumPriceBumpFee: minimumFee,
+          txPriorityFee: minimumFee !== undefined ? incomingMeta.priorityFee : undefined,
         },
       };
     }
@@ -247,17 +288,19 @@ export function checkNullifierConflict(
 }
 
 /** Creates a stub TxMetaValidationData for tests that don't exercise validators. */
-export function stubTxMetaValidationData(overrides: { expirationTimestamp?: bigint } = {}): TxMetaValidationData {
+export function stubTxMetaValidationData(
+  overrides: { expirationTimestamp?: bigint; maxFeesPerGas?: GasFees } = {},
+): TxMetaValidationData {
   return {
     getNonEmptyNullifiers: () => [],
     expirationTimestamp: overrides.expirationTimestamp ?? 0n,
     constants: {
       anchorBlockHeader: {
-        hash: () => Promise.resolve(new BlockHash(Fr.ZERO)),
+        hash: () => Promise.resolve(BlockHash.ZERO),
         globalVariables: { blockNumber: BlockNumber(0) },
       },
       txContext: {
-        gasSettings: { gasLimits: Gas.empty() },
+        gasSettings: { gasLimits: Gas.empty(), maxFeesPerGas: overrides.maxFeesPerGas ?? GasFees.empty() },
       },
     },
   };
@@ -274,6 +317,8 @@ export function stubTxMetaData(
     nullifiers?: string[];
     expirationTimestamp?: bigint;
     anchorBlockHeaderHash?: string;
+    allowedSetupCalls?: boolean;
+    maxFeesPerGas?: GasFees;
   } = {},
 ): TxMetaData {
   const txHashBigInt = Fr.fromHexString(txHash).toBigInt();
@@ -290,8 +335,15 @@ export function stubTxMetaData(
     feeLimit: overrides.feeLimit ?? 100n,
     nullifiers: overrides.nullifiers ?? [`0x${normalizedTxHash.slice(2)}null1`],
     expirationTimestamp,
+    allowedSetupCalls: overrides.allowedSetupCalls ?? true,
     receivedAt: 0,
     estimatedSizeBytes: 0,
-    data: stubTxMetaValidationData({ expirationTimestamp }),
+    data: stubTxMetaValidationData({ expirationTimestamp, maxFeesPerGas: overrides.maxFeesPerGas }),
   };
 }
+
+/** Returns the priority fee for a tx, based on the L2 priority fee capped by the max fee per gas. */
+function getTxPriorityFee(tx: Tx): bigint {
+  const { maxPriorityFeesPerGas: priorityFees, maxFeesPerGas } = tx.getGasSettings();
+  return minBigint(maxFeesPerGas.feePerL2Gas, priorityFees.feePerL2Gas);
+}

package/src/mem_pools/tx_pool_v2/tx_pool_indices.ts

@@ -1,7 +1,8 @@
+import { insertIntoSortedArray, removeFromSortedArray } from '@aztec/foundation/array';
 import { SlotNumber } from '@aztec/foundation/branded-types';
 import type { L2BlockId } from '@aztec/stdlib/block';
 
-import { type TxMetaData, type TxState, compareFee, compareTxHash, txHashFromBigInt } from './tx_metadata.js';
+import { type PriorityComparable, type TxMetaData, type TxState, comparePriority } from './tx_metadata.js';
 
 /**
  * Manages in-memory indices for the transaction pool.
@@ -22,8 +23,8 @@ export class TxPoolIndices {
   #nullifierToTxHash: Map<string, string> = new Map();
   /** Fee payer to txHashes index (pending txs only) */
   #feePayerToTxHashes: Map<string, Set<string>> = new Map();
-  /** Pending txHash bigints grouped by priority fee */
-  #pendingByPriority: Map<bigint, Set<bigint>> = new Map();
+  /** Pending transactions sorted ascending by priority fee, ties broken by txHash */
+  #pendingByPriority: PriorityComparable[] = [];
   /** Protected transactions: txHash -> slotNumber */
   #protectedTransactions: Map<string, SlotNumber> = new Map();
 
@@ -73,20 +74,14 @@ export class TxPoolIndices {
    * @param order - 'desc' for highest priority first, 'asc' for lowest priority first
    */
   *iteratePendingByPriority(order: 'asc' | 'desc', filter?: (hash: string) => boolean): Generator<string> {
-    const feeCompareFn = order === 'desc' ? (a: bigint, b: bigint) => compareFee(b, a) : compareFee;
-    const hashCompareFn =
-      order === 'desc' ? (a: bigint, b: bigint) => compareTxHash(b, a) : (a: bigint, b: bigint) => compareTxHash(a, b);
-
-    const sortedFees = [...this.#pendingByPriority.keys()].sort(feeCompareFn);
-
-    for (const fee of sortedFees) {
-      const hashesAtFee = this.#pendingByPriority.get(fee)!;
-      const sortedHashes = [...hashesAtFee].sort(hashCompareFn);
-      for (const hashBigInt of sortedHashes) {
-        const hash = txHashFromBigInt(hashBigInt);
-        if (filter === undefined || filter(hash)) {
-          yield hash;
-        }
+    const arr = this.#pendingByPriority;
+    const start = order === 'asc' ? 0 : arr.length - 1;
+    const step = order === 'asc' ? 1 : -1;
+    const inBounds = order === 'asc' ? (i: number) => i < arr.length : (i: number) => i >= 0;
+
+    for (let i = start; inBounds(i); i += step) {
+      if (filter === undefined || filter(arr[i].txHash)) {
+        yield arr[i].txHash;
       }
     }
   }
@@ -136,6 +131,9 @@ export class TxPoolIndices {
     meta.minedL2BlockId = blockId;
     // Safe to call unconditionally - removeFromPendingIndices is idempotent
     this.#removeFromPendingIndices(meta);
+    // A mined tx supersedes any protection: drop the stale entry so it can't linger in the map and
+    // be matched by later protection scans.
+    this.#protectedTransactions.delete(meta.txHash);
   }
 
   /** Clears the mined status from a transaction */
@@ -227,11 +225,30 @@ export class TxPoolIndices {
 
   /** Gets the count of pending transactions */
   getPendingTxCount(): number {
+    return this.#pendingByPriority.length;
+  }
+
+  /**
+   * Returns whether at least `minCount` pending transactions were received at or before maxReceivedAt,
+   * i.e. are old enough to be eligible for block building. Stops as soon as the threshold is met, so it
+   * does not scan the whole pool when only a handful of eligible txs are needed. The total pending count
+   * is an upper bound on the eligible count, so a pool with fewer than `minCount` pending can never
+   * satisfy the threshold and short-circuits without scanning.
+   */
+  hasEligiblePendingTxs(maxReceivedAt: number, minCount: number): boolean {
+    if (minCount <= 0) {
+      return true;
+    }
+    if (this.#pendingByPriority.length < minCount) {
+      return false;
+    }
     let count = 0;
-    for (const hashes of this.#pendingByPriority.values()) {
-      count += hashes.size;
+    for (const _ of this.iterateEligiblePendingByPriority('desc', maxReceivedAt)) {
+      if (++count >= minCount) {
+        return true;
+      }
     }
-    return count;
+    return false;
   }
 
   /** Gets the lowest priority pending transaction hashes (up to limit) */
@@ -264,12 +281,10 @@ export class TxPoolIndices {
   /** Gets all pending transactions */
   getPendingTxs(): TxMetaData[] {
     const result: TxMetaData[] = [];
-    for (const hashSet of this.#pendingByPriority.values()) {
-      for (const txHashBigInt of hashSet) {
-        const meta = this.#metadata.get(txHashFromBigInt(txHashBigInt));
-        if (meta) {
-          result.push(meta);
-        }
+    for (const entry of this.#pendingByPriority) {
+      const meta = this.#metadata.get(entry.txHash);
+      if (meta) {
+        result.push(meta);
       }
     }
     return result;
@@ -327,6 +342,15 @@ export class TxPoolIndices {
     return result;
   }
 
+  /**
+   * From the given hashes, returns those whose protection is recorded at exactly the given slot.
+   * Used to release the protections a single block proposal created without disturbing entries a
+   * later proposal raised to a higher slot via updateProtection.
+   */
+  findProtectedTxsAtSlot(txHashes: string[], slotNumber: SlotNumber): string[] {
+    return txHashes.filter(txHash => this.#protectedTransactions.get(txHash) === slotNumber);
+  }
+
   /** Filters out transactions that are currently protected */
   filterUnprotected(txs: TxMetaData[]): TxMetaData[] {
     return txs.filter(meta => !this.#protectedTransactions.has(meta.txHash));
@@ -408,13 +432,12 @@ export class TxPoolIndices {
     }
     feePayerSet.add(meta.txHash);
 
-    // Add to priority bucket
-    let prioritySet = this.#pendingByPriority.get(meta.priorityFee);
-    if (!prioritySet) {
-      prioritySet = new Set();
-      this.#pendingByPriority.set(meta.priorityFee, prioritySet);
-    }
-    prioritySet.add(meta.txHashBigInt);
+    insertIntoSortedArray(
+      this.#pendingByPriority,
+      { txHash: meta.txHash, priorityFee: meta.priorityFee, txHashBigInt: meta.txHashBigInt },
+      comparePriority,
+      false,
+    );
   }
 
   #removeFromPendingIndices(meta: TxMetaData): void {
@@ -432,13 +455,11 @@ export class TxPoolIndices {
       }
     }
 
-    // Remove from priority map
-    const hashSet = this.#pendingByPriority.get(meta.priorityFee);
-    if (hashSet) {
-      hashSet.delete(meta.txHashBigInt);
-      if (hashSet.size === 0) {
-        this.#pendingByPriority.delete(meta.priorityFee);
-      }
-    }
+    // Remove from priority array
+    removeFromSortedArray(
+      this.#pendingByPriority,
+      { txHash: meta.txHash, priorityFee: meta.priorityFee, txHashBigInt: meta.txHashBigInt },
+      comparePriority,
+    );
   }
 }

package/src/mem_pools/tx_pool_v2/tx_pool_v2.ts

@@ -1,7 +1,8 @@
 import { SlotNumber } from '@aztec/foundation/branded-types';
+import { chunk } from '@aztec/foundation/collection';
 import { type Logger, createLogger } from '@aztec/foundation/log';
 import { SerialQueue } from '@aztec/foundation/queue';
-import { DateProvider } from '@aztec/foundation/timer';
+import { DateProvider, Timer } from '@aztec/foundation/timer';
 import type { TypedEventEmitter } from '@aztec/foundation/types';
 import type { AztecAsyncKVStore } from '@aztec/kv-store';
 import type { L2Block, L2BlockId } from '@aztec/stdlib/block';
@@ -11,9 +12,18 @@ import { type TelemetryClient, getTelemetryClient } from '@aztec/telemetry-clien
 import EventEmitter from 'node:events';
 
 import { PoolInstrumentation, PoolName } from '../instrumentation.js';
-import type { AddTxsResult, TxPoolV2, TxPoolV2Config, TxPoolV2Dependencies, TxPoolV2Events } from './interfaces.js';
+import { TxPoolQueueInstrumentation } from './instrumentation.js';
+import type {
+  AddTxsResult,
+  PoolReadAccess,
+  TxPoolV2,
+  TxPoolV2Config,
+  TxPoolV2Dependencies,
+  TxPoolV2Events,
+} from './interfaces.js';
 import type { TxState } from './tx_metadata.js';
-import { TxPoolV2Impl } from './tx_pool_v2_impl.js';
+import type { MinedTxInfo } from './tx_pool_v2_impl.js';
+import { FINALIZE_BLOCK_CHUNK_SIZE, TxPoolV2Impl } from './tx_pool_v2_impl.js';
 
 /**
  * Implementation of TxPoolV2 with explicit state management.
@@ -23,6 +33,9 @@ import { TxPoolV2Impl } from './tx_pool_v2_impl.js';
  */
 export class AztecKVTxPoolV2 extends (EventEmitter as new () => TypedEventEmitter<TxPoolV2Events>) implements TxPoolV2 {
   #queue: SerialQueue;
+  #queueMetrics: TxPoolQueueInstrumentation;
+  /** Serializes finalizations so their chunked #queue items never interleave with each other. */
+  #finalizationQueue = new SerialQueue();
   #impl: TxPoolV2Impl;
   #metrics?: PoolInstrumentation<Tx>;
   #store: AztecAsyncKVStore;
@@ -45,21 +58,27 @@ export class AztecKVTxPoolV2 extends (EventEmitter as new () => TypedEventEmitte
     this.#telemetry = telemetry;
     this.#log = log;
     this.#queue = new SerialQueue();
+    this.#queueMetrics = new TxPoolQueueInstrumentation(telemetry, () => this.#queue.length());
 
     // Create callbacks that the impl uses to notify us about events and metrics
     const callbacks = {
       onTxsAdded: (txs: Tx[], opts: { source?: string }) => {
-        this.#metrics?.transactionsAdded(txs);
         this.emit('txs-added', { txs, ...opts });
       },
       onTxsRemoved: (txHashes: string[] | bigint[]) => {
-        this.#metrics?.transactionsRemoved(txHashes);
         // Convert to TxHash objects for the event
         const hashes = txHashes.map(h => (typeof h === 'string' ? TxHash.fromString(h) : TxHash.fromBigInt(h)));
         this.emit('txs-removed', { txHashes: hashes });
       },
-      onTxsMined: (txHashes: string[]) => {
-        this.#metrics?.transactionsRemoved(txHashes);
+      onTxsMined: (minedTxs: MinedTxInfo[]) => {
+        // Pending-to-mined delay is derived from the tx's persisted receivedAt at the mined
+        // transition (see TxPoolV2Impl.handleMinedBlock), not the add/remove timestamp map —
+        // so eviction no longer pollutes MEMPOOL_TX_MINED_DELAY.
+        for (const { minedDelayMs } of minedTxs) {
+          if (minedDelayMs !== undefined) {
+            this.#metrics?.recordMinedDelay(minedDelayMs);
+          }
+        }
       },
     };
 
@@ -71,98 +90,151 @@ export class AztecKVTxPoolV2 extends (EventEmitter as new () => TypedEventEmitte
   // PUBLIC API - All methods queue to the implementation
   // ============================================================================
 
+  /**
+   * Enqueues an operation on the serial queue, recording how long it waited behind other queued
+   * work and how long it took to execute once running.
+   */
+  #run<T>(operation: string, fn: () => T | Promise<T>): Promise<Awaited<T>> {
+    const waitTimer = new Timer();
+    return this.#queue.put(async () => {
+      const waitMs = waitTimer.ms();
+      const executionTimer = new Timer();
+      try {
+        return await fn();
+      } finally {
+        this.#queueMetrics.record(operation, waitMs, executionTimer.ms());
+      }
+    });
+  }
+
   // === Core Operations ===
 
   addPendingTxs(txs: Tx[], opts: { source?: string; feeComparisonOnly?: boolean } = {}): Promise<AddTxsResult> {
-    return this.#queue.put(() => this.#impl.addPendingTxs(txs, opts));
+    return this.#run('addPendingTxs', () => this.#impl.addPendingTxs(txs, opts));
   }
 
   canAddPendingTx(tx: Tx): Promise<'accepted' | 'ignored'> {
-    return this.#queue.put(() => this.#impl.canAddPendingTx(tx));
+    return this.#run('canAddPendingTx', () => this.#impl.canAddPendingTx(tx));
   }
 
   addProtectedTxs(txs: Tx[], block: BlockHeader, opts: { source?: string } = {}): Promise<void> {
-    return this.#queue.put(() => this.#impl.addProtectedTxs(txs, block, opts));
+    return this.#run('addProtectedTxs', () => this.#impl.addProtectedTxs(txs, block, opts));
   }
 
   protectTxs(txHashes: TxHash[], block: BlockHeader): Promise<TxHash[]> {
-    return this.#queue.put(() => this.#impl.protectTxs(txHashes, block));
+    return this.#run('protectTxs', () => this.#impl.protectTxs(txHashes, block));
   }
 
   addMinedTxs(txs: Tx[], block: BlockHeader, opts: { source?: string } = {}): Promise<void> {
-    return this.#queue.put(() => this.#impl.addMinedTxs(txs, block, opts));
+    return this.#run('addMinedTxs', () => this.#impl.addMinedTxs(txs, block, opts));
   }
 
   // === State Transition Handlers ===
 
   handleMinedBlock(block: L2Block): Promise<void> {
-    return this.#queue.put(() => this.#impl.handleMinedBlock(block));
+    return this.#run('handleMinedBlock', () => this.#impl.handleMinedBlock(block));
   }
 
   prepareForSlot(slotNumber: SlotNumber): Promise<void> {
-    return this.#queue.put(() => this.#impl.prepareForSlot(slotNumber));
+    return this.#run('prepareForSlot', () => this.#impl.prepareForSlot(slotNumber));
+  }
+
+  unprotectTxs(txHashes: TxHash[], slotNumber: SlotNumber): Promise<void> {
+    return this.#run('unprotectTxs', () => this.#impl.unprotectTxs(txHashes, slotNumber));
   }
 
   handlePrunedBlocks(latestBlock: L2BlockId, options?: { deleteAllTxs?: boolean }): Promise<void> {
-    return this.#queue.put(() => this.#impl.handlePrunedBlocks(latestBlock, options));
+    return this.#run('handlePrunedBlocks', () => this.#impl.handlePrunedBlocks(latestBlock, options));
   }
 
   handleFailedExecution(txHashes: TxHash[]): Promise<void> {
-    return this.#queue.put(() => this.#impl.handleFailedExecution(txHashes));
+    return this.#run('handleFailedExecution', () => this.#impl.handleFailedExecution(txHashes));
   }
 
+  /**
+   * Handles a finalized block by archiving and deleting the mined txs it finalizes. The work is
+   * split into chunk-sized serial-queue items rather than one long-running item, so gossip-driven
+   * pool operations (canAddPendingTx / addPendingTxs) interleave with finalization instead of
+   * stalling behind an entire epoch's worth of tx processing. Finalizations run on their own serial
+   * queue so two concurrent calls never interleave their chunks with each other.
+   */
   handleFinalizedBlock(block: BlockHeader): Promise<void> {
-    return this.#queue.put(() => this.#impl.handleFinalizedBlock(block));
+    return this.#finalizationQueue.put(() => this.#handleFinalizedBlock(block));
+  }
+
+  async #handleFinalizedBlock(block: BlockHeader): Promise<void> {
+    const { cutoffBlock, txHashes } = await this.#run('prepareFinalization', () =>
+      this.#impl.prepareFinalization(block),
+    );
+    const batches = chunk(txHashes, FINALIZE_BLOCK_CHUNK_SIZE);
+    for (const batch of batches) {
+      await this.#run('archiveFinalizedTxs', () => this.#impl.archiveFinalizedTxs(batch));
+    }
+    for (const batch of batches) {
+      await this.#run('deleteFinalizedTxs', () => this.#impl.deleteFinalizedTxs(batch, cutoffBlock));
+    }
+    await this.#run('completeFinalization', () =>
+      this.#impl.completeFinalization(txHashes, cutoffBlock, block.globalVariables.blockNumber),
+    );
   }
 
   // === Queries ===
 
-  getTxByHash(txHash: TxHash): Promise<Tx | undefined> {
-    return this.#queue.put(() => this.#impl.getTxByHash(txHash));
+  getTxByHash(txHash: TxHash, opts?: { includeProof?: boolean }): Promise<Tx | undefined> {
+    return this.#run('getTxByHash', () => this.#impl.getTxByHash(txHash, opts));
   }
 
-  getTxsByHash(txHashes: TxHash[]): Promise<(Tx | undefined)[]> {
-    return this.#queue.put(() => this.#impl.getTxsByHash(txHashes));
+  getTxsByHash(txHashes: TxHash[], opts?: { includeProof?: boolean }): Promise<(Tx | undefined)[]> {
+    return this.#run('getTxsByHash', () => this.#impl.getTxsByHash(txHashes, opts));
   }
 
   hasTxs(txHashes: TxHash[]): Promise<boolean[]> {
-    return this.#queue.put(() => this.#impl.hasTxs(txHashes));
+    return this.#run('hasTxs', () => this.#impl.hasTxs(txHashes));
   }
 
   getTxStatus(txHash: TxHash): Promise<TxState | 'deleted' | undefined> {
-    return this.#queue.put(() => Promise.resolve(this.#impl.getTxStatus(txHash)));
+    return this.#run('getTxStatus', () => this.#impl.getTxStatus(txHash));
   }
 
   getPendingTxHashes(): Promise<TxHash[]> {
-    return this.#queue.put(() => Promise.resolve(this.#impl.getPendingTxHashes()));
+    return this.#run('getPendingTxHashes', () => this.#impl.getPendingTxHashes());
   }
 
   getEligiblePendingTxHashes(): Promise<TxHash[]> {
-    return this.#queue.put(() => Promise.resolve(this.#impl.getEligiblePendingTxHashes()));
+    return this.#run('getEligiblePendingTxHashes', () => this.#impl.getEligiblePendingTxHashes());
   }
 
   getPendingTxCount(): Promise<number> {
-    return this.#queue.put(() => Promise.resolve(this.#impl.getPendingTxCount()));
+    return this.#run('getPendingTxCount', () => this.#impl.getPendingTxCount());
+  }
+
+  hasEligiblePendingTxs(minCount: number): Promise<boolean> {
+    return this.#run('hasEligiblePendingTxs', () => this.#impl.hasEligiblePendingTxs(minCount));
   }
 
   getMinedTxHashes(): Promise<[TxHash, L2BlockId][]> {
-    return this.#queue.put(() => Promise.resolve(this.#impl.getMinedTxHashes()));
+    return this.#run('getMinedTxHashes', () => this.#impl.getMinedTxHashes());
   }
 
   getMinedTxCount(): Promise<number> {
-    return this.#queue.put(() => Promise.resolve(this.#impl.getMinedTxCount()));
+    return this.#run('getMinedTxCount', () => this.#impl.getMinedTxCount());
   }
 
   isEmpty(): Promise<boolean> {
-    return this.#queue.put(() => Promise.resolve(this.#impl.isEmpty()));
+    return this.#run('isEmpty', () => this.#impl.isEmpty());
   }
 
   getArchivedTxByHash(txHash: TxHash): Promise<Tx | undefined> {
-    return this.#queue.put(() => this.#impl.getArchivedTxByHash(txHash));
+    return this.#run('getArchivedTxByHash', () => this.#impl.getArchivedTxByHash(txHash));
   }
 
   getLowestPriorityPending(limit: number): Promise<TxHash[]> {
-    return this.#queue.put(() => Promise.resolve(this.#impl.getLowestPriorityPending(limit)));
+    return this.#run('getLowestPriorityPending', () => this.#impl.getLowestPriorityPending(limit));
+  }
+
+  /** Returns read-only access to the pool. Used for testing. */
+  getPoolReadAccess(): PoolReadAccess {
+    return this.#impl.getPoolReadAccess();
   }
 
   // === Configuration ===
@@ -186,8 +258,9 @@ export class AztecKVTxPoolV2 extends (EventEmitter as new () => TypedEventEmitte
 
     this.#log.info('Starting transaction pool...');
 
-    // Start the serial queue
+    // Start the serial queues
     this.#queue.start();
+    this.#finalizationQueue.start();
     this.#started = true;
 
     // Setup metrics - created after queue is started so callbacks can safely queue
@@ -219,6 +292,8 @@ export class AztecKVTxPoolV2 extends (EventEmitter as new () => TypedEventEmitte
 
   async stop(): Promise<void> {
     if (this.#started) {
+      // End the finalization queue first: an in-flight finalization still needs #queue to run its chunks.
+      await this.#finalizationQueue.end();
       await this.#queue.end();
       this.#started = false;
     }