@aztec/p2p 0.0.0-test.1 → 0.0.1-commit.03f7ef2

package/src/mem_pools/tx_pool/aztec_kv_tx_pool.ts

@@ -1,30 +1,69 @@
+import { BlockNumber } from '@aztec/foundation/branded-types';
+import { Fr } from '@aztec/foundation/curves/bn254';
 import { toArray } from '@aztec/foundation/iterable';
 import { type Logger, createLogger } from '@aztec/foundation/log';
-import type { AztecAsyncKVStore, AztecAsyncMap, AztecAsyncMultiMap } from '@aztec/kv-store';
-import { ClientIvcProof } from '@aztec/stdlib/proofs';
+import type { TypedEventEmitter } from '@aztec/foundation/types';
+import type { AztecAsyncKVStore, AztecAsyncMap, AztecAsyncMultiMap, AztecAsyncSingleton } from '@aztec/kv-store';
+import { ProtocolContractAddress } from '@aztec/protocol-contracts';
+import { GasFees } from '@aztec/stdlib/gas';
+import type { MerkleTreeReadOperations, WorldStateSynchronizer } from '@aztec/stdlib/interfaces/server';
+import { ChonkProof } from '@aztec/stdlib/proofs';
 import type { TxAddedToPoolStats } from '@aztec/stdlib/stats';
-import { Tx, TxHash } from '@aztec/stdlib/tx';
+import { DatabasePublicStateSource } from '@aztec/stdlib/trees';
+import { BlockHeader, Tx, TxHash } from '@aztec/stdlib/tx';
 import { type TelemetryClient, getTelemetryClient } from '@aztec/telemetry-client';
 
-import { PoolInstrumentation, PoolName } from '../instrumentation.js';
+import assert from 'assert';
+import EventEmitter from 'node:events';
+
+import { ArchiveCache } from '../../msg_validators/tx_validator/archive_cache.js';
+import { GasTxValidator } from '../../msg_validators/tx_validator/gas_validator.js';
+import { PoolInstrumentation, PoolName, type PoolStatsCallback } from '../instrumentation.js';
 import { getPendingTxPriority } from './priority.js';
-import type { TxPool } from './tx_pool.js';
+import type { TxPool, TxPoolEvents, TxPoolOptions } from './tx_pool.js';
 
 /**
  * KV implementation of the Transaction Pool.
  */
-export class AztecKVTxPool implements TxPool {
+export class AztecKVTxPool extends (EventEmitter as new () => TypedEventEmitter<TxPoolEvents>) implements TxPool {
   #store: AztecAsyncKVStore;
 
   /** Our tx pool, stored as a Map, with K: tx hash and V: the transaction. */
   #txs: AztecAsyncMap<string, Buffer>;
 
+  /** The maximum cumulative tx size that the pending txs in the pool take up. */
+  #maxTxPoolSize: number = 0;
+
+  /** The tx evicion logic will kick after pool size is greater than maxTxPoolSize * txPoolOverflowFactor */
+  txPoolOverflowFactor: number = 1;
+
   /** Index from tx hash to the block number in which they were mined, filtered by mined txs. */
-  #minedTxHashToBlock: AztecAsyncMap<string, number>;
+  #minedTxHashToBlock: AztecAsyncMap<string, BlockNumber>;
 
   /** Index from tx priority (stored as hex) to its tx hash, filtered by pending txs. */
   #pendingTxPriorityToHash: AztecAsyncMultiMap<string, string>;
 
+  /** Index from tx hash to its tx size (in bytes), filtered by pending txs. */
+  #pendingTxHashToSize: AztecAsyncMap<string, number>;
+
+  /** Index from tx hash to its header hash, filtered by pending txs. */
+  #pendingTxHashToHeaderHash: AztecAsyncMap<string, string>;
+
+  /** Map from tx hash to the block number it was originally mined in (for soft-deleted txs). */
+  #deletedMinedTxHashes: AztecAsyncMap<string, BlockNumber>;
+
+  /** MultiMap from block number to deleted mined tx hashes for efficient cleanup. */
+  #blockToDeletedMinedTxHash: AztecAsyncMultiMap<BlockNumber, string>;
+
+  /** The cumulative tx size in bytes that the pending txs in the pool take up. */
+  #pendingTxSize: AztecAsyncSingleton<number>;
+
+  /** In-memory mapping of pending tx hashes to the hydrated pending tx in the pool. */
+  #pendingTxs: Map<string, Tx>;
+
+  /** In-memory set of txs that should not be evicted from the pool. */
+  #nonEvictableTxs: Set<string>;
+
   /** KV store for archived txs. */
   #archive: AztecAsyncKVStore;
 
@@ -35,7 +74,10 @@ export class AztecKVTxPool implements TxPool {
   #archivedTxIndices: AztecAsyncMap<number, string>;
 
   /** Number of txs to archive. */
-  #archivedTxLimit: number;
+  #archivedTxLimit: number = 0;
+
+  /** The world state synchronizer used in the node. */
+  #worldStateSynchronizer: WorldStateSynchronizer;
 
   #log: Logger;
 
@@ -52,85 +94,160 @@ export class AztecKVTxPool implements TxPool {
   constructor(
     store: AztecAsyncKVStore,
     archive: AztecAsyncKVStore,
+    worldStateSynchronizer: WorldStateSynchronizer,
     telemetry: TelemetryClient = getTelemetryClient(),
-    archivedTxLimit: number = 0,
+    config: TxPoolOptions = {},
     log = createLogger('p2p:tx_pool'),
   ) {
+    super();
+
+    this.#log = log;
+    this.updateConfig(config);
+
     this.#txs = store.openMap('txs');
     this.#minedTxHashToBlock = store.openMap('txHashToBlockMined');
     this.#pendingTxPriorityToHash = store.openMultiMap('pendingTxFeeToHash');
+    this.#pendingTxHashToSize = store.openMap('pendingTxHashToSize');
+    this.#pendingTxHashToHeaderHash = store.openMap('pendingTxHashToHeaderHash');
+    this.#pendingTxSize = store.openSingleton('pendingTxSize');
+    this.#deletedMinedTxHashes = store.openMap('deletedMinedTxHashes');
+    this.#blockToDeletedMinedTxHash = store.openMultiMap('blockToDeletedMinedTxHash');
+
+    this.#pendingTxs = new Map<string, Tx>();
+    this.#nonEvictableTxs = new Set<string>();
 
     this.#archivedTxs = archive.openMap('archivedTxs');
     this.#archivedTxIndices = archive.openMap('archivedTxIndices');
-    this.#archivedTxLimit = archivedTxLimit;
 
     this.#store = store;
     this.#archive = archive;
-    this.#log = log;
-    this.#metrics = new PoolInstrumentation(telemetry, PoolName.TX_POOL, () => store.estimateSize());
+    this.#worldStateSynchronizer = worldStateSynchronizer;
+    this.#metrics = new PoolInstrumentation(telemetry, PoolName.TX_POOL, this.countTxs, () => store.estimateSize());
   }
 
-  public markAsMined(txHashes: TxHash[], blockNumber: number): Promise<void> {
+  private countTxs: PoolStatsCallback = async () => {
+    const [pending = 0, mined = 0] = await Promise.all([this.getPendingTxCount(), this.getMinedTxCount()]);
+
+    return Promise.resolve({
+      itemCount: {
+        pending,
+        mined,
+      },
+    });
+  };
+
+  public async isEmpty(): Promise<boolean> {
+    for await (const _ of this.#txs.entriesAsync()) {
+      return false;
+    }
+    return true;
+  }
+  /**
+   * Marks transactions as mined in a block and updates the pool state accordingly.
+   * Removes the transactions from the pending set and adds them to the mined set.
+   * Also evicts any transactions that become invalid after the block is mined.
+   * @param txHashes - Array of transaction hashes that were mined
+   * @param blockHeader - The header of the block the transactions were mined in
+   */
+  public async markAsMined(txHashes: TxHash[], blockHeader: BlockHeader): Promise<void> {
     if (txHashes.length === 0) {
       return Promise.resolve();
     }
 
-    let deletedPending = 0;
-    return this.#store.transactionAsync(async () => {
+    const minedNullifiers = new Set<string>();
+    const minedFeePayers = new Set<string>();
+
+    await this.#store.transactionAsync(async () => {
+      let pendingTxSize = (await this.#pendingTxSize.getAsync()) ?? 0;
       for (const hash of txHashes) {
         const key = hash.toString();
-        await this.#minedTxHashToBlock.set(key, blockNumber);
 
-        const tx = await this.getTxByHash(hash);
+        // If this tx was previously soft-deleted, remove it from the deleted sets
+        if (await this.#deletedMinedTxHashes.hasAsync(key)) {
+          const originalBlock = await this.#deletedMinedTxHashes.getAsync(key);
+          await this.#deletedMinedTxHashes.delete(key);
+          // Remove from block-to-hash mapping
+          if (originalBlock !== undefined) {
+            await this.#blockToDeletedMinedTxHash.deleteValue(originalBlock, key);
+          }
+        }
+
+        await this.#minedTxHashToBlock.set(key, blockHeader.globalVariables.blockNumber);
+
+        const tx = await this.getPendingTxByHash(hash);
         if (tx) {
-          deletedPending++;
-          const fee = getPendingTxPriority(tx);
-          await this.#pendingTxPriorityToHash.deleteValue(fee, key);
+          const nullifiers = tx.data.getNonEmptyNullifiers();
+          nullifiers.forEach(nullifier => minedNullifiers.add(nullifier.toString()));
+          minedFeePayers.add(tx.data.feePayer.toString());
+          pendingTxSize -= tx.getSize();
+          await this.removePendingTxIndices(tx, key);
         }
       }
-      this.#metrics.recordAddedObjects(txHashes.length, 'mined');
-      this.#metrics.recordRemovedObjects(deletedPending, 'pending');
+      await this.#pendingTxSize.set(pendingTxSize);
+
+      await this.evictInvalidTxsAfterMining(txHashes, blockHeader, minedNullifiers, minedFeePayers);
     });
+    this.#metrics.transactionsRemoved(txHashes);
+    // We update this after the transaction above. This ensures that the non-evictable transactions are not evicted
+    // until any that have been mined are marked as such.
+    // The non-evictable set is not considered when evicting transactions that are invalid after a block is mined.
+    this.#nonEvictableTxs.clear();
   }
 
-  public markMinedAsPending(txHashes: TxHash[]): Promise<void> {
+  public async markMinedAsPending(txHashes: TxHash[]): Promise<void> {
     if (txHashes.length === 0) {
       return Promise.resolve();
     }
-
-    let markedAsPending = 0;
-    return this.#store.transactionAsync(async () => {
+    await this.#store.transactionAsync(async () => {
+      let pendingTxSize = (await this.#pendingTxSize.getAsync()) ?? 0;
       for (const hash of txHashes) {
         const key = hash.toString();
         await this.#minedTxHashToBlock.delete(key);
 
-        const tx = await this.getTxByHash(hash);
+        // Rehydrate the tx in the in-memory pending txs mapping
+        const tx = await this.getPendingTxByHash(hash);
         if (tx) {
-          await this.#pendingTxPriorityToHash.set(getPendingTxPriority(tx), key);
-          markedAsPending++;
+          await this.addPendingTxIndices(tx, key);
+          pendingTxSize += tx.getSize();
         }
       }
 
-      this.#metrics.recordAddedObjects(markedAsPending, 'pending');
-      this.#metrics.recordRemovedObjects(markedAsPending, 'mined');
+      await this.#pendingTxSize.set(pendingTxSize);
     });
+
+    await this.evictInvalidTxsAfterReorg(txHashes);
+    await this.evictLowPriorityTxs(txHashes);
   }
 
   public async getPendingTxHashes(): Promise<TxHash[]> {
     const vals = await toArray(this.#pendingTxPriorityToHash.valuesAsync({ reverse: true }));
-    return vals.map(x => TxHash.fromString(x));
+    return vals.map(TxHash.fromString);
   }
 
-  public async getMinedTxHashes(): Promise<[TxHash, number][]> {
+  public async getMinedTxHashes(): Promise<[TxHash, BlockNumber][]> {
     const vals = await toArray(this.#minedTxHashToBlock.entriesAsync());
     return vals.map(([txHash, blockNumber]) => [TxHash.fromString(txHash), blockNumber]);
   }
 
-  public async getTxStatus(txHash: TxHash): Promise<'pending' | 'mined' | undefined> {
-    const key = txHash.toString();
-    const [isMined, isKnown] = await Promise.all([this.#minedTxHashToBlock.hasAsync(key), this.#txs.hasAsync(key)]);
+  public async getPendingTxCount(): Promise<number> {
+    return (await this.#pendingTxHashToHeaderHash.sizeAsync()) ?? 0;
+  }
 
-    if (isMined) {
+  public async getMinedTxCount(): Promise<number> {
+    return (await this.#minedTxHashToBlock.sizeAsync()) ?? 0;
+  }
+
+  public async getTxStatus(txHash: TxHash): Promise<'pending' | 'mined' | 'deleted' | undefined> {
+    const key = txHash.toString();
+    const [isMined, isKnown, isDeleted] = await Promise.all([
+      this.#minedTxHashToBlock.hasAsync(key),
+      this.#txs.hasAsync(key),
+      this.#deletedMinedTxHashes.hasAsync(key),
+    ]);
+
+    if (isDeleted) {
+      return 'deleted';
+    } else if (isMined) {
       return 'mined';
     } else if (isKnown) {
       return 'pending';
@@ -146,12 +263,21 @@ export class AztecKVTxPool implements TxPool {
    */
   public async getTxByHash(txHash: TxHash): Promise<Tx | undefined> {
     const buffer = await this.#txs.getAsync(txHash.toString());
-    if (buffer) {
-      const tx = Tx.fromBuffer(buffer);
-      tx.setTxHash(txHash);
-      return tx;
-    }
-    return undefined;
+    return buffer ? Tx.fromBuffer(buffer) : undefined;
+  }
+
+  async getTxsByHash(txHashes: TxHash[]): Promise<(Tx | undefined)[]> {
+    const txs = await Promise.all(txHashes.map(txHash => this.#txs.getAsync(txHash.toString())));
+    return txs.map(buffer => (buffer ? Tx.fromBuffer(buffer) : undefined));
+  }
+
+  async hasTxs(txHashes: TxHash[]): Promise<boolean[]> {
+    return await Promise.all(txHashes.map(txHash => this.#txs.hasAsync(txHash.toString())));
+  }
+
+  async hasTx(txHash: TxHash): Promise<boolean> {
+    const result = await this.hasTxs([txHash]);
+    return result[0];
   }
 
   /**
@@ -161,12 +287,7 @@ export class AztecKVTxPool implements TxPool {
    */
   public async getArchivedTxByHash(txHash: TxHash): Promise<Tx | undefined> {
     const buffer = await this.#archivedTxs.getAsync(txHash.toString());
-    if (buffer) {
-      const tx = Tx.fromBuffer(buffer);
-      tx.setTxHash(txHash);
-      return tx;
-    }
-    return undefined;
+    return buffer ? Tx.fromBuffer(buffer) : undefined;
   }
 
   /**
@@ -174,75 +295,99 @@ export class AztecKVTxPool implements TxPool {
    * @param txs - An array of txs to be added to the pool.
    * @returns Empty promise.
    */
-  public async addTxs(txs: Tx[]): Promise<void> {
-    const hashesAndStats = await Promise.all(
-      txs.map(async tx => ({ txHash: await tx.getTxHash(), txStats: await tx.getStats() })),
-    );
+  public async addTxs(txs: Tx[], opts: { source?: string } = {}): Promise<number> {
+    const addedTxs: Tx[] = [];
+    const hashesAndStats = txs.map(tx => ({ txHash: tx.getTxHash(), txStats: tx.getStats() }));
     await this.#store.transactionAsync(async () => {
-      let pendingCount = 0;
+      let pendingTxSize = (await this.#pendingTxSize.getAsync()) ?? 0;
       await Promise.all(
         txs.map(async (tx, i) => {
           const { txHash, txStats } = hashesAndStats[i];
+          const key = txHash.toString();
+          if (await this.#txs.hasAsync(key)) {
+            this.#log.debug(`Tx ${txHash.toString()} already exists in the pool`);
+            return;
+          }
+
           this.#log.verbose(`Adding tx ${txHash.toString()} to pool`, {
             eventName: 'tx-added-to-pool',
             ...txStats,
           } satisfies TxAddedToPoolStats);
 
-          const key = txHash.toString();
           await this.#txs.set(key, tx.toBuffer());
+          addedTxs.push(tx as Tx);
 
           if (!(await this.#minedTxHashToBlock.hasAsync(key))) {
-            pendingCount++;
-            // REFACTOR: Use an lmdb conditional write to avoid race conditions with this write tx
-            await this.#pendingTxPriorityToHash.set(getPendingTxPriority(tx), key);
+            pendingTxSize += tx.getSize();
+            await this.addPendingTxIndices(tx, key);
             this.#metrics.recordSize(tx);
           }
         }),
       );
 
-      this.#metrics.recordAddedObjects(pendingCount, 'pending');
+      await this.#pendingTxSize.set(pendingTxSize);
+      await this.evictLowPriorityTxs(hashesAndStats.map(({ txHash }) => txHash));
     });
+
+    if (addedTxs.length > 0) {
+      this.#metrics.transactionsAdded(addedTxs);
+      this.emit('txs-added', { ...opts, txs: addedTxs });
+    }
+    return addedTxs.length;
   }
 
   /**
    * Deletes transactions from the pool. Tx hashes that are not present are ignored.
-   * @param txHashes - An array of tx hashes to be removed from the tx pool.
+   * Mined transactions are soft-deleted with a timestamp, pending transactions are permanently deleted.
+   * @param txHashes - An array of tx hashes to be deleted from the tx pool.
    * @returns Empty promise.
    */
-  public deleteTxs(txHashes: TxHash[]): Promise<void> {
-    let pendingDeleted = 0;
-    let minedDeleted = 0;
-
+  public deleteTxs(txHashes: TxHash[], opts: { eviction?: boolean; permanently?: boolean } = {}): Promise<void> {
+    if (txHashes.length === 0) {
+      return Promise.resolve();
+    }
     const deletedTxs: Tx[] = [];
     const poolDbTx = this.#store.transactionAsync(async () => {
+      let pendingTxSize = (await this.#pendingTxSize.getAsync()) ?? 0;
       for (const hash of txHashes) {
         const key = hash.toString();
         const tx = await this.getTxByHash(hash);
 
         if (tx) {
-          const fee = getPendingTxPriority(tx);
-          await this.#pendingTxPriorityToHash.deleteValue(fee, key);
-
-          const isMined = await this.#minedTxHashToBlock.hasAsync(key);
-          if (isMined) {
-            minedDeleted++;
+          const minedBlockNumber = await this.#minedTxHashToBlock.getAsync(key);
+
+          if (minedBlockNumber !== undefined) {
+            await this.#minedTxHashToBlock.delete(key);
+            if (opts.permanently) {
+              // Permanently delete mined transactions if specified
+              this.#log.trace(`Deleting mined tx ${key} from pool`);
+              await this.#txs.delete(key);
+            } else {
+              // Soft-delete mined transactions: remove from mined set but keep in storage
+              this.#log.trace(`Soft-deleting mined tx ${key} from pool`);
+              await this.#deletedMinedTxHashes.set(key, minedBlockNumber);
+              await this.#blockToDeletedMinedTxHash.set(minedBlockNumber, key);
+            }
           } else {
-            pendingDeleted++;
+            // Permanently delete pending transactions
+            this.#log.trace(`Deleting pending tx ${key} from pool`);
+            pendingTxSize -= tx.getSize();
+            await this.removePendingTxIndices(tx, key);
+            await this.#txs.delete(key);
           }
 
-          if (this.#archivedTxLimit) {
+          if (!opts.eviction && this.#archivedTxLimit) {
             deletedTxs.push(tx);
           }
-
-          await this.#txs.delete(key);
-          await this.#minedTxHashToBlock.delete(key);
+        } else {
+          this.#log.trace(`Skipping deletion of missing tx ${key} from pool`);
         }
       }
 
-      this.#metrics.recordRemovedObjects(pendingDeleted, 'pending');
-      this.#metrics.recordRemovedObjects(minedDeleted, 'mined');
+      await this.#pendingTxSize.set(pendingTxSize);
     });
-
+    this.#metrics.transactionsRemoved(txHashes);
+    this.#log.debug(`Deleted ${txHashes.length} txs from pool`, { txHashes });
     return this.#archivedTxLimit ? poolDbTx.then(() => this.archiveTxs(deletedTxs)) : poolDbTx;
   }
 
@@ -251,12 +396,8 @@ export class AztecKVTxPool implements TxPool {
    * @returns Array of tx objects in the order they were added to the pool.
    */
   public async getAllTxs(): Promise<Tx[]> {
-    const vals = await toArray(this.#txs.entriesAsync());
-    return vals.map(([hash, buffer]) => {
-      const tx = Tx.fromBuffer(buffer);
-      tx.setTxHash(TxHash.fromString(hash));
-      return tx;
-    });
+    const vals = await toArray(this.#txs.valuesAsync());
+    return vals.map(buffer => Tx.fromBuffer(buffer));
   }
 
   /**
@@ -268,42 +409,346 @@ export class AztecKVTxPool implements TxPool {
     return vals.map(x => TxHash.fromString(x));
   }
 
+  public updateConfig({ maxTxPoolSize, txPoolOverflowFactor, archivedTxLimit }: TxPoolOptions): void {
+    if (typeof maxTxPoolSize === 'number') {
+      assert(maxTxPoolSize >= 0, 'maxTxPoolSize must be greater or equal to 0');
+      this.#maxTxPoolSize = maxTxPoolSize;
+
+      if (maxTxPoolSize === 0) {
+        this.#log.info(`Disabling maximum tx mempool size. Tx eviction stopped`);
+      } else {
+        this.#log.info(`Setting maximum tx mempool size`, { maxTxPoolSize });
+      }
+    }
+
+    if (typeof txPoolOverflowFactor === 'number') {
+      assert(txPoolOverflowFactor >= 1, 'txPoolOveflowFactor must be greater or equal to 1');
+      this.txPoolOverflowFactor = txPoolOverflowFactor;
+      this.#log.info(`Allowing tx pool size to grow above limit`, { maxTxPoolSize, txPoolOverflowFactor });
+    }
+
+    if (typeof archivedTxLimit === 'number') {
+      assert(archivedTxLimit >= 0, 'archivedTxLimit must be greater or equal to 0');
+      this.#archivedTxLimit = archivedTxLimit;
+    }
+
+    // deletedMinedCleanupThresholdMs is no longer used in block-based cleanup
+  }
+
+  public markTxsAsNonEvictable(txHashes: TxHash[]): Promise<void> {
+    txHashes.forEach(txHash => this.#nonEvictableTxs.add(txHash.toString()));
+    return Promise.resolve();
+  }
+
+  /**
+   * Permanently deletes deleted mined transactions from blocks up to and including the specified block number.
+   * @param blockNumber - Block number threshold. Deleted mined txs from this block or earlier will be permanently deleted.
+   * @returns The number of transactions permanently deleted.
+   */
+  public async cleanupDeletedMinedTxs(blockNumber: BlockNumber): Promise<number> {
+    let deletedCount = 0;
+    const txHashesToDelete: string[] = [];
+    const blocksToDelete: BlockNumber[] = [];
+
+    await this.#store.transactionAsync(async () => {
+      // Iterate through all entries and check block numbers
+      for await (const [block, txHash] of this.#blockToDeletedMinedTxHash.entriesAsync()) {
+        if (block <= blockNumber) {
+          // Permanently delete the transaction
+          await this.#txs.delete(txHash);
+          await this.#deletedMinedTxHashes.delete(txHash);
+          txHashesToDelete.push(txHash);
+          if (!blocksToDelete.includes(block)) {
+            blocksToDelete.push(block);
+          }
+          deletedCount++;
+        }
+      }
+
+      // Clean up block-to-hash mapping - delete all values for each block
+      for (const block of blocksToDelete) {
+        const txHashesForBlock = await toArray(this.#blockToDeletedMinedTxHash.getValuesAsync(block));
+        for (const txHash of txHashesForBlock) {
+          await this.#blockToDeletedMinedTxHash.deleteValue(block, txHash);
+        }
+      }
+    });
+
+    if (deletedCount > 0) {
+      this.#log.debug(`Permanently deleted ${deletedCount} deleted mined txs from blocks up to ${blockNumber}`);
+    }
+    return deletedCount;
+  }
+
+  /**
+   * Creates a GasTxValidator instance.
+   * @param db - DB for the validator to use
+   * @returns A GasTxValidator instance
+   */
+  protected createGasTxValidator(db: MerkleTreeReadOperations): GasTxValidator {
+    return new GasTxValidator(new DatabasePublicStateSource(db), ProtocolContractAddress.FeeJuice, GasFees.empty());
+  }
+
+  /**
+   * Creates an ArchiveCache instance.
+   * @param db - DB for the cache to use
+   * @returns An ArchiveCache instance
+   */
+  protected createArchiveCache(db: MerkleTreeReadOperations): ArchiveCache {
+    return new ArchiveCache(db);
+  }
+
+  /**
+   * Checks if a cached transaction exists in the in-memory pending tx pool and returns it.
+   * Otherwise, it checks the tx pool, updates the pending tx pool, and returns the tx.
+   * @param txHash - The generated tx hash.
+   * @returns The transaction, if found, 'undefined' otherwise.
+   */
+  private async getPendingTxByHash(txHash: TxHash | string): Promise<Tx | undefined> {
+    let key;
+    if (typeof txHash === 'string') {
+      key = txHash;
+      txHash = TxHash.fromString(txHash);
+    } else {
+      key = txHash.toString();
+    }
+
+    if (this.#pendingTxs.has(key)) {
+      return this.#pendingTxs.get(key);
+    }
+    const tx = await this.getTxByHash(txHash);
+    if (tx) {
+      this.#pendingTxs.set(key, tx);
+      return tx;
+    }
+    return undefined;
+  }
+
   /**
    * Archives a list of txs for future reference. The number of archived txs is limited by the specified archivedTxLimit.
    * @param txs - The list of transactions to archive.
    * @returns Empty promise.
    */
   private async archiveTxs(txs: Tx[]): Promise<void> {
-    const txHashes = await Promise.all(txs.map(tx => tx.getTxHash()));
-    await this.#archive.transactionAsync(async () => {
-      // calcualte the head and tail indices of the archived txs by insertion order.
-      let headIdx =
-        ((await this.#archivedTxIndices.entriesAsync({ limit: 1, reverse: true }).next()).value?.[0] ?? -1) + 1;
-      let tailIdx = (await this.#archivedTxIndices.entriesAsync({ limit: 1 }).next()).value?.[0] ?? 0;
-
-      for (let i = 0; i < txs.length; i++) {
-        const tx = txs[i];
-        while (headIdx - tailIdx >= this.#archivedTxLimit) {
-          const txHash = await this.#archivedTxIndices.getAsync(tailIdx);
-          if (txHash) {
-            await this.#archivedTxs.delete(txHash);
-            await this.#archivedTxIndices.delete(tailIdx);
+    if (txs.length === 0) {
+      return;
+    }
+    try {
+      const txHashes = await Promise.all(txs.map(tx => tx.getTxHash()));
+      await this.#archive.transactionAsync(async () => {
+        // calculate the head and tail indices of the archived txs by insertion order.
+        let headIdx =
+          ((await this.#archivedTxIndices.entriesAsync({ limit: 1, reverse: true }).next()).value?.[0] ?? -1) + 1;
+        let tailIdx = (await this.#archivedTxIndices.entriesAsync({ limit: 1 }).next()).value?.[0] ?? 0;
+
+        for (let i = 0; i < txs.length; i++) {
+          const tx = txs[i];
+          while (headIdx - tailIdx >= this.#archivedTxLimit) {
+            const txHash = await this.#archivedTxIndices.getAsync(tailIdx);
+            if (txHash) {
+              await this.#archivedTxs.delete(txHash);
+              await this.#archivedTxIndices.delete(tailIdx);
+            }
+            tailIdx++;
           }
-          tailIdx++;
+
+          const archivedTx: Tx = new Tx(
+            tx.txHash,
+            tx.data,
+            ChonkProof.empty(),
+            tx.contractClassLogFields,
+            tx.publicFunctionCalldata,
+          );
+          const txHash = txHashes[i].toString();
+          await this.#archivedTxs.set(txHash, archivedTx.toBuffer());
+          await this.#archivedTxIndices.set(headIdx, txHash);
+          headIdx++;
+        }
+        this.#log.debug(`Archived ${txs.length} txs`, { txHashes });
+        this.#log.debug(`Total archived txs: ${headIdx - tailIdx}`);
+      });
+    } catch (error) {
+      this.#log.error(`Error archiving txs`, { error });
+    }
+  }
+
+  /**
+   * Evicts pending txs with the lowest priority fees from the pool to accomodate the max tx count and cumulative max tx size
+   * after new txs are added.
+   *
+   * @param newTxHashes - The tx hashes of the new txs added to the pool.
+   * @returns The total number of txs evicted from the pool and the number of new txs that were evicted.
+   */
+  private async evictLowPriorityTxs(
+    newTxHashes: TxHash[],
+  ): Promise<{ numLowPriorityTxsEvicted: number; numNewTxsEvicted: number }> {
+    if (this.#maxTxPoolSize === undefined || this.#maxTxPoolSize === 0) {
+      return { numLowPriorityTxsEvicted: 0, numNewTxsEvicted: 0 };
+    }
+
+    let numNewTxsEvicted = 0;
+    const txsToEvict: TxHash[] = [];
+
+    let pendingTxsSize = (await this.#pendingTxSize.getAsync()) ?? 0;
+    if (pendingTxsSize > this.#maxTxPoolSize * this.txPoolOverflowFactor) {
+      for await (const txHash of this.#pendingTxPriorityToHash.valuesAsync()) {
+        if (this.#nonEvictableTxs.has(txHash.toString())) {
+          continue;
         }
+        const txSize =
+          (await this.#pendingTxHashToSize.getAsync(txHash.toString())) ??
+          (await this.getPendingTxByHash(txHash))?.getSize();
 
-        const archivedTx: Tx = new Tx(
-          tx.data,
-          ClientIvcProof.empty(),
-          tx.contractClassLogs,
-          tx.enqueuedPublicFunctionCalls,
-          tx.publicTeardownFunctionCall,
+        this.#log.verbose(`Evicting tx ${txHash} from pool due to low priority to satisfy max tx size limit`, {
+          txHash,
+          txSize,
+        });
+
+        txsToEvict.push(TxHash.fromString(txHash));
+
+        if (txSize) {
+          pendingTxsSize -= txSize;
+          if (pendingTxsSize <= this.#maxTxPoolSize) {
+            break;
+          }
+        }
+      }
+      numNewTxsEvicted += newTxHashes.filter(txHash => txsToEvict.includes(txHash)).length;
+    }
+
+    if (txsToEvict.length > 0) {
+      await this.deleteTxs(txsToEvict, { eviction: true });
+    }
+    return {
+      numLowPriorityTxsEvicted: txsToEvict.length,
+      numNewTxsEvicted,
+    };
+  }
+
+  /**
+   * Evicts invalid pending txs from the pool after a txs from a block are mined.
+   * Eviction criteria includes:
+   *   - txs with nullifiers that are already included in the mined block
+   *   - txs with an insufficient fee payer balance
+   *   - txs with an expiration timestamp lower than that of the mined block
+   *
+   * @param minedTxHashes - The tx hashes of the txs mined in the block.
+   * @param blockHeader - The header of the mined block.
+   * @returns The total number of txs evicted from the pool.
+   */
+  private async evictInvalidTxsAfterMining(
+    minedTxHashes: TxHash[],
+    blockHeader: BlockHeader,
+    minedNullifiers: Set<string>,
+    minedFeePayers: Set<string>,
+  ): Promise<number> {
+    if (minedTxHashes.length === 0) {
+      return 0;
+    }
+
+    const { blockNumber, timestamp } = blockHeader.globalVariables;
+
+    // Wait for world state to be synced to at least the mined block number
+    await this.#worldStateSynchronizer.syncImmediate(blockNumber);
+
+    const db = this.#worldStateSynchronizer.getCommitted();
+    const gasTxValidator = this.createGasTxValidator(db);
+
+    const txsToEvict: TxHash[] = [];
+    for await (const txHash of this.#pendingTxPriorityToHash.valuesAsync()) {
+      const tx = await this.getPendingTxByHash(txHash);
+      if (!tx) {
+        continue;
+      }
+
+      // Evict pending txs that share nullifiers with mined txs
+      const txNullifiers = tx.data.getNonEmptyNullifiers();
+      if (txNullifiers.some(nullifier => minedNullifiers.has(nullifier.toString()))) {
+        this.#log.verbose(`Evicting tx ${txHash} from pool due to a duplicate nullifier with a mined tx`);
+        txsToEvict.push(TxHash.fromString(txHash));
+        continue;
+      }
+
+      // Evict pending txs with an insufficient fee payer balance
+      if (
+        minedFeePayers.has(tx.data.feePayer.toString()) &&
+        (await gasTxValidator.validateTxFee(tx)).result === 'invalid'
+      ) {
+        this.#log.verbose(`Evicting tx ${txHash} from pool due to an insufficient fee payer balance`);
+        txsToEvict.push(TxHash.fromString(txHash));
+        continue;
+      }
+
+      // Evict pending txs with an expiration timestamp less than or equal to the mined block timestamp
+      const includeByTimestamp = tx.data.includeByTimestamp;
+      if (includeByTimestamp <= timestamp) {
+        this.#log.verbose(
+          `Evicting tx ${txHash} from pool due to the tx being expired (includeByTimestamp: ${includeByTimestamp}, mined block timestamp: ${timestamp})`,
         );
-        const txHash = txHashes[i].toString();
-        await this.#archivedTxs.set(txHash, archivedTx.toBuffer());
-        await this.#archivedTxIndices.set(headIdx, txHash);
-        headIdx++;
+        txsToEvict.push(TxHash.fromString(txHash));
+        continue;
       }
-    });
+    }
+
+    if (txsToEvict.length > 0) {
+      await this.deleteTxs(txsToEvict, { eviction: true });
+    }
+    return txsToEvict.length;
+  }
+
+  /**
+   * Evicts pending txs that no longer have valid archive roots or fee payer balances from the pool after a reorg.
+   *
+   * @param txHashes - The tx hashes of the txs that were moved from mined to pending.
+   * @returns The total number of txs evicted from the pool.
+   */
+  private async evictInvalidTxsAfterReorg(txHashes: TxHash[]): Promise<number> {
+    if (txHashes.length === 0) {
+      return 0;
+    }
+
+    await this.#worldStateSynchronizer.syncImmediate();
+    const db = this.#worldStateSynchronizer.getCommitted();
+    const archiveCache = this.createArchiveCache(db);
+    const gasTxValidator = this.createGasTxValidator(db);
+
+    const txsToEvict: TxHash[] = [];
+
+    for await (const [txHash, headerHash] of this.#pendingTxHashToHeaderHash.entriesAsync()) {
+      const tx = await this.getPendingTxByHash(txHash);
+      if (!tx) {
+        continue;
+      }
+
+      const [index] = await archiveCache.getArchiveIndices([Fr.fromString(headerHash)]);
+      if (index === undefined) {
+        this.#log.verbose(`Evicting tx ${txHash} from pool due to an invalid archive root`);
+        txsToEvict.push(TxHash.fromString(txHash));
+        continue;
+      }
+
+      if ((await gasTxValidator.validateTxFee(tx)).result === 'invalid') {
+        this.#log.verbose(`Evicting tx ${txHash} from pool due to an insufficient fee payer balance`);
+        txsToEvict.push(TxHash.fromString(txHash));
+      }
+    }
+
+    if (txsToEvict.length > 0) {
+      await this.deleteTxs(txsToEvict, { eviction: true });
+    }
+    return txsToEvict.length;
+  }
+
+  private async addPendingTxIndices(tx: Tx, txHash: string): Promise<void> {
+    await this.#pendingTxPriorityToHash.set(getPendingTxPriority(tx), txHash);
+    await this.#pendingTxHashToSize.set(txHash, tx.getSize());
+    await this.#pendingTxHashToHeaderHash.set(txHash, (await tx.data.constants.anchorBlockHeader.hash()).toString());
+  }
+
+  private async removePendingTxIndices(tx: Tx, txHash: string): Promise<void> {
+    await this.#pendingTxPriorityToHash.deleteValue(getPendingTxPriority(tx), txHash);
+    await this.#pendingTxHashToSize.delete(txHash);
+    await this.#pendingTxHashToHeaderHash.delete(txHash);
+    this.#pendingTxs.delete(txHash);
   }
 }