@aztec/p2p 0.0.1-commit.29c6b1a3 → 0.0.1-commit.2e2504e2

package/src/bootstrap/bootstrap.ts

@@ -1,4 +1,4 @@
-import { createLogger } from '@aztec/foundation/log';
+import { type Logger, type LoggerBindings, createLogger } from '@aztec/foundation/log';
 import type { AztecAsyncKVStore } from '@aztec/kv-store';
 import type { P2PBootstrapApi } from '@aztec/stdlib/interfaces/server';
 import { OtelMetricsAdapter, type TelemetryClient } from '@aztec/telemetry-client';
@@ -18,12 +18,15 @@ import { convertToMultiaddr, getPeerIdPrivateKey, getPublicIp } from '../util.js
 export class BootstrapNode implements P2PBootstrapApi {
   private node?: Discv5EventEmitter = undefined;
   private peerId?: PeerId;
+  private logger: Logger;
 
   constructor(
     private store: AztecAsyncKVStore,
     private telemetry: TelemetryClient,
-    private logger = createLogger('p2p:bootstrap'),
-  ) {}
+    bindings?: LoggerBindings,
+  ) {
+    this.logger = createLogger('p2p:bootstrap', bindings);
+  }
 
   /**
    * Starts the bootstrap node.
@@ -65,7 +68,7 @@ export class BootstrapNode implements P2PBootstrapApi {
 
     this.logger.debug(`Starting bootstrap node ${peerId} listening on ${listenAddrUdp.toString()}`);
 
-    const metricsRegistry = new OtelMetricsAdapter(this.telemetry);
+    const metricsRegistry = new OtelMetricsAdapter(this.telemetry, this.logger.getBindings());
     this.node = Discv5.create({
       enr: ourEnr,
       peerId,

package/src/client/factory.ts

@@ -21,6 +21,7 @@ import { DummyP2PService } from '../services/dummy_service.js';
 import { LibP2PService } from '../services/index.js';
 import { TxCollection } from '../services/tx_collection/tx_collection.js';
 import { type TxSource, createNodeRpcTxSources } from '../services/tx_collection/tx_source.js';
+import { TxFileStore } from '../services/tx_file_store/tx_file_store.js';
 import { configureP2PClientAddresses, createLibP2PPeerIdFromPrivateKey, getPeerIdPrivateKey } from '../util.js';
 
 export type P2PClientDeps<T extends P2PClientType> = {
@@ -62,15 +63,11 @@ export async function createP2PClient<T extends P2PClientType>(
     );
   }
 
-  const store = deps.store ?? (await createStore(P2P_STORE_NAME, 2, config, createLogger('p2p:lmdb-v2')));
-  const archive = await createStore(P2P_ARCHIVE_STORE_NAME, 1, config, createLogger('p2p-archive:lmdb-v2'));
-  const peerStore = await createStore(P2P_PEER_STORE_NAME, 1, config, createLogger('p2p-peer:lmdb-v2'));
-  const attestationStore = await createStore(
-    P2P_ATTESTATION_STORE_NAME,
-    1,
-    config,
-    createLogger('p2p-attestation:lmdb-v2'),
-  );
+  const bindings = logger.getBindings();
+  const store = deps.store ?? (await createStore(P2P_STORE_NAME, 2, config, bindings));
+  const archive = await createStore(P2P_ARCHIVE_STORE_NAME, 1, config, bindings);
+  const peerStore = await createStore(P2P_PEER_STORE_NAME, 1, config, bindings);
+  const attestationStore = await createStore(P2P_ATTESTATION_STORE_NAME, 1, config, bindings);
   const l1Constants = await archiver.getL1Constants();
 
   const mempools: MemPools = {
@@ -120,6 +117,8 @@ export async function createP2PClient<T extends P2PClientType>(
     logger.createChild('tx-collection'),
   );
 
+  const txFileStore = await TxFileStore.create(mempools.txPool, config, logger.createChild('tx-file-store'), telemetry);
+
   return new P2PClient(
     clientType,
     store,
@@ -127,6 +126,7 @@ export async function createP2PClient<T extends P2PClientType>(
     mempools,
     p2pService,
     txCollection,
+    txFileStore,
     config,
     dateProvider,
     telemetry,

package/src/client/p2p_client.ts

@@ -41,6 +41,7 @@ import {
 import { chunkTxHashesRequest } from '../services/reqresp/protocols/tx.js';
 import type { P2PBlockReceivedCallback, P2PCheckpointReceivedCallback, P2PService } from '../services/service.js';
 import { TxCollection } from '../services/tx_collection/tx_collection.js';
+import type { TxFileStore } from '../services/tx_file_store/tx_file_store.js';
 import { TxProvider } from '../services/tx_provider.js';
 import { type P2P, P2PClientState, type P2PSyncState } from './interface.js';
 
@@ -90,6 +91,7 @@ export class P2PClient<T extends P2PClientType = P2PClientType.Full>
     mempools: MemPools,
     private p2pService: P2PService,
     private txCollection: TxCollection,
+    private txFileStore: TxFileStore | undefined,
     config: Partial<P2PConfig> = {},
     private _dateProvider: DateProvider = new DateProvider(),
     private telemetry: TelemetryClient = getTelemetryClient(),
@@ -274,6 +276,7 @@ export class P2PClient<T extends P2PClientType = P2PClientType.Full>
 
     this.blockStream!.start();
     await this.txCollection.start();
+    this.txFileStore?.start();
     return this.syncPromise;
   }
 
@@ -306,6 +309,8 @@ export class P2PClient<T extends P2PClientType = P2PClientType.Full>
     this.log.debug('Stopping p2p client...');
     await tryStop(this.txCollection);
     this.log.debug('Stopped tx collection service');
+    await this.txFileStore?.stop();
+    this.log.debug('Stopped tx file store');
     await this.p2pService.stop();
     this.log.debug('Stopped p2p service');
     await this.blockStream?.stop();
@@ -326,8 +331,10 @@ export class P2PClient<T extends P2PClientType = P2PClientType.Full>
     [Attributes.BLOCK_ARCHIVE]: proposal.archive.toString(),
     [Attributes.P2P_ID]: (await proposal.p2pMessageLoggingIdentifier()).toString(),
   }))
-  public broadcastProposal(proposal: BlockProposal): Promise<void> {
+  public async broadcastProposal(proposal: BlockProposal): Promise<void> {
     this.log.verbose(`Broadcasting proposal for slot ${proposal.slotNumber} to peers`);
+    // Store our own proposal so we can respond to req/resp requests for it
+    await this.attestationPool.addBlockProposal(proposal);
     return this.p2pService.propagate(proposal);
   }
 
@@ -336,8 +343,13 @@ export class P2PClient<T extends P2PClientType = P2PClientType.Full>
     [Attributes.BLOCK_ARCHIVE]: proposal.archive.toString(),
     [Attributes.P2P_ID]: (await proposal.p2pMessageLoggingIdentifier()).toString(),
   }))
-  public broadcastCheckpointProposal(proposal: CheckpointProposal): Promise<void> {
+  public async broadcastCheckpointProposal(proposal: CheckpointProposal): Promise<void> {
     this.log.verbose(`Broadcasting checkpoint proposal for slot ${proposal.slotNumber} to peers`);
+    const blockProposal = proposal.getBlockProposal();
+    if (blockProposal) {
+      // Store our own last-block proposal so we can respond to req/resp requests for it.
+      await this.attestationPool.addBlockProposal(blockProposal);
+    }
     return this.p2pService.propagate(proposal);
   }
 

package/src/client/test/tx_proposal_collector/README.md

@@ -24,7 +24,7 @@ The benchmark runs a small simulated network on localhost:
 ```
 ┌─────────────────────────────────────────────────────────────────────┐
 │                        Test Process (Driver)                        │
-│   p2p_client.proposal_tx_collector_bench.test.ts                    │
+│   p2p_client.proposal_tx_collector.bench.test.ts                    │
 │   ┌─────────────────────────────────────────────────────────────┐   │
 │   │            WorkerClientManager                              │   │
 │   │         (src/testbench/worker_client_manager.ts)            │   │
@@ -127,13 +127,13 @@ From the p2p package:
 
 ```bash
 cd yarn-project/p2p
-yarn test src/client/test/tx_proposal_collector/p2p_client.proposal_tx_collector_bench.test.ts
+yarn test src/client/test/tx_proposal_collector/p2p_client.proposal_tx_collector.bench.test.ts
 ```
 
 Or from repo root:
 
 ```bash
-yarn test p2p_client.proposal_tx_collector_bench.test.ts
+yarn test p2p_client.proposal_tx_collector.bench.test.ts
 ```
 
 The benchmark is intentionally long due to spawning many processes and running multiple cases.
@@ -207,7 +207,7 @@ This benchmark does **not** measure:
 
 | File | Purpose |
 |------|---------|
-| `p2p_client.proposal_tx_collector_bench.test.ts` | Test suite (cases, distributions, output formatting) |
+| `p2p_client.proposal_tx_collector.bench.test.ts` | Test suite (cases, distributions, output formatting) |
 | `proposal_tx_collector_worker.ts` | Collector-specific worker implementation |
 | `proposal_tx_collector_worker_protocol.ts` | IPC message types and serialization |
 | `src/testbench/worker_client_manager.ts` | Worker process manager (forking, IPC, orchestration) |

package/src/client/test/tx_proposal_collector/proposal_tx_collector_worker.ts

@@ -104,7 +104,7 @@ async function startClient(config: P2PConfig, clientIndex: number) {
   const worldState = createMockWorldStateSynchronizer();
   const l2BlockSource = new MockL2BlockSource();
   const proofVerifier = new AlwaysTrueCircuitVerifier();
-  kvStore = await openTmpStore(`proposal-bench-${clientIndex}`);
+  kvStore = await openTmpStore(`proposal-bench-${clientIndex}`, true, BENCHMARK_CONSTANTS.KV_STORE_MAP_SIZE_KB);
   logger = createLogger(`p2p:proposal-bench:${clientIndex}`);
 
   const telemetry = getTelemetryClient();

package/src/config.ts

@@ -21,11 +21,17 @@ import {
 } from './services/reqresp/batch-tx-requester/config.js';
 import { type P2PReqRespConfig, p2pReqRespConfigMappings } from './services/reqresp/config.js';
 import { type TxCollectionConfig, txCollectionConfigMappings } from './services/tx_collection/config.js';
+import { type TxFileStoreConfig, txFileStoreConfigMappings } from './services/tx_file_store/config.js';
 
 /**
  * P2P client configuration values.
  */
-export interface P2PConfig extends P2PReqRespConfig, BatchTxRequesterConfig, ChainConfig, TxCollectionConfig {
+export interface P2PConfig
+  extends P2PReqRespConfig,
+    BatchTxRequesterConfig,
+    ChainConfig,
+    TxCollectionConfig,
+    TxFileStoreConfig {
   /** A flag dictating whether the P2P subsystem should be enabled. */
   p2pEnabled: boolean;
 
@@ -439,6 +445,7 @@ export const p2pConfigMappings: ConfigMappingsType<P2PConfig> = {
   ...batchTxRequesterConfigMappings,
   ...chainConfigMappings,
   ...txCollectionConfigMappings,
+  ...txFileStoreConfigMappings,
 };
 
 /**

package/src/mem_pools/instrumentation.ts

@@ -12,6 +12,7 @@ import {
   type ObservableGauge,
   type TelemetryClient,
   type UpDownCounter,
+  createUpDownCounterWithDefault,
 } from '@aztec/telemetry-client';
 
 export enum PoolName {
@@ -97,7 +98,7 @@ export class PoolInstrumentation<PoolObject extends Gossipable> {
       dbStats,
     );
 
-    this.addObjectCounter = this.meter.createUpDownCounter(metricsLabels.itemsAdded);
+    this.addObjectCounter = createUpDownCounterWithDefault(this.meter, metricsLabels.itemsAdded);
 
     this.minedDelay = this.meter.createHistogram(metricsLabels.itemMinedDelay);
 

package/src/mem_pools/tx_pool_v2/README.md

@@ -0,0 +1,188 @@
+# TxPoolV2
+
+Transaction pool implementation with explicit state management and pluggable eviction rules.
+
+## Overview
+
+TxPoolV2 manages transactions through a state machine with clear transitions:
+
+```
+              addPendingTxs()
+                    │
+                    ▼
+┌─────────────────────────────────────┐
+│              PENDING                │◄──────────────────┐
+│   (awaiting block inclusion)        │                   │
+└─────────────────────────────────────┘                   │
+        │                                                 │
+        │ protectTxs() / addProtectedTxs()               │
+        ▼                                                 │
+┌─────────────────────────────────────┐                   │
+│            PROTECTED                │───────────────────┘
+│   (in a block proposal)             │  prepareForSlot()
+└─────────────────────────────────────┘  (slot passed without mining)
+        │                                                 │
+        │ handleMinedBlock()                              │
+        ▼                                                 │
+┌─────────────────────────────────────┐                   │
+│              MINED                  │───────────────────┘
+│   (included in a block)             │  handlePrunedBlocks()
+└─────────────────────────────────────┘  (reorg)
+        │
+        │ handleFinalizedBlock()
+        ▼
+┌─────────────────────────────────────┐
+│             DELETED                 │
+│   (optionally archived)             │
+└─────────────────────────────────────┘
+```
+
+## Key Components
+
+### TxPoolV2 (`tx_pool_v2.ts`)
+
+The public API wrapper that serializes all operations through a queue to prevent race conditions. Delegates to `TxPoolV2Impl` for actual logic.
+
+### TxPoolV2Impl (`tx_pool_v2_impl.ts`)
+
+Core implementation containing:
+- KV store persistence for transactions and metadata
+- In-memory indices for fast lookups (by nullifier, fee payer, priority)
+- State transition logic
+- Pre-add rule execution
+- Post-event eviction rule execution
+
+### TxMetaData (`tx_metadata.ts`)
+
+Lightweight metadata stored alongside each transaction:
+- `txHash`: Transaction identifier
+- `state`: Current state (pending, protected, mined)
+- `priorityFee`: For priority ordering
+- `feePayer`: For balance-based eviction
+- `nullifiers`: For conflict detection
+- `estimatedTxFee`: For balance calculations
+- `blockId`: Block info when mined
+- `protectedSlot`: Slot number when protected
+
+## Eviction Rules
+
+The pool uses a pluggable rule system for managing transactions.
+
+### Pre-Add Rules
+
+Checked before adding a transaction to the pending pool:
+
+| Rule | Purpose |
+|------|---------|
+| `NullifierConflictRule` | Handles transactions with conflicting nullifiers. Higher priority tx wins. |
+| `FeePayerBalancePreAddRule` | Ensures fee payer has sufficient balance for all their pending txs. |
+| `LowPriorityPreAddRule` | Rejects txs when pool is full and new tx has lowest priority. |
+
+### Post-Event Eviction Rules
+
+Run after events to clean up the pool:
+
+| Rule | Trigger | Purpose |
+|------|---------|---------|
+| `LowPriorityEvictionRule` | `txs_added` | Evicts lowest priority txs when pool exceeds limit. |
+| `FeePayerBalanceEvictionRule` | `block_mined` | Evicts txs when fee payer balance decreases. |
+| `InvalidTxsAfterMiningRule` | `block_mined` | Evicts pending txs with nullifiers that were just mined. |
+| `InvalidTxsAfterReorgRule` | `chain_pruned` | Evicts txs with invalid anchor blocks after reorg. |
+
+## Usage
+
+### Creating a Pool
+
+```typescript
+import { AztecKVTxPoolV2 } from './tx_pool_v2.js';
+
+const pool = new AztecKVTxPoolV2(txStore, archiveStore, {
+  l2BlockSource: archiver,
+  worldStateSynchronizer: worldState,
+  pendingTxValidator: validator,
+});
+
+await pool.start();
+```
+
+### Adding Transactions
+
+```typescript
+// Add to pending pool (validates and runs pre-add rules)
+const result = await pool.addPendingTxs(txs, { source: 'gossip' });
+// result: { accepted: TxHash[], ignored: TxHash[], rejected: TxHash[] }
+
+// Check without modifying pool
+const canAdd = await pool.canAddPendingTx(tx);
+// canAdd: 'accepted' | 'ignored' | 'rejected'
+```
+
+### Block Building Flow
+
+```typescript
+// 1. Proposer protects txs for their block
+await pool.protectTxs(selectedTxHashes, blockHeader);
+
+// 2. On successful mining
+await pool.handleMinedBlock(minedTxHashes, blockHeader);
+
+// 3. If slot passes without mining
+await pool.prepareForSlot(nextSlotNumber);
+
+// 4. On finalization
+await pool.handleFinalizedBlock(finalizedBlockHeader);
+```
+
+### Handling Reorgs
+
+```typescript
+// When blocks are pruned, un-mine affected transactions
+await pool.handlePrunedBlocks(latestValidBlockId);
+```
+
+## Configuration
+
+```typescript
+await pool.updateConfig({
+  maxPendingTxCount: 10000,  // 0 = unlimited
+  archivedTxLimit: 1000,     // 0 = disabled
+});
+```
+
+## Return Values
+
+### AddTxsResult
+
+When adding pending transactions, each tx is categorized:
+
+| Status | Meaning |
+|--------|---------|
+| `accepted` | Successfully added to the pool |
+| `ignored` | Valid but not added (duplicate, lost nullifier conflict, insufficient balance) |
+| `rejected` | Failed validation (invalid proof, expired, etc.) |
+
+## Archive
+
+Finalized transactions can optionally be archived for historical queries:
+
+```typescript
+const archivedTx = await pool.getArchivedTxByHash(txHash);
+```
+
+The archive uses FIFO eviction when `archivedTxLimit` is reached.
+
+## Testing
+
+```bash
+# Unit tests (131 tests)
+yarn test src/mem_pools/tx_pool_v2/tx_pool_v2.test.ts
+
+# Compatibility tests (25 tests)
+yarn test src/mem_pools/tx_pool_v2/tx_pool_v2.compat.test.ts
+
+# Eviction rule tests
+yarn test src/mem_pools/tx_pool_v2/eviction/
+
+# Benchmarks
+yarn test src/mem_pools/tx_pool_v2/tx_pool_v2_bench.test.ts
+```

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

@@ -0,0 +1 @@
+export { TxArchive } from './tx_archive.js';

package/src/mem_pools/tx_pool_v2/archive/tx_archive.ts

@@ -0,0 +1,120 @@
+import { type Logger, createLogger } from '@aztec/foundation/log';
+import type { AztecAsyncKVStore, AztecAsyncMap } from '@aztec/kv-store';
+import { ChonkProof } from '@aztec/stdlib/proofs';
+import { Tx, TxHash } from '@aztec/stdlib/tx';
+
+/**
+ * Manages archived transactions with FIFO eviction.
+ * Archived transactions have their proofs stripped to save space.
+ */
+export class TxArchive {
+  #store: AztecAsyncKVStore;
+  #txs: AztecAsyncMap<string, Buffer>;
+  #indices: AztecAsyncMap<number, string>;
+  #limit: number;
+  #log: Logger;
+
+  constructor(store: AztecAsyncKVStore, limit: number, log?: Logger) {
+    this.#store = store;
+    this.#txs = store.openMap('archivedTxs');
+    this.#indices = store.openMap('archivedTxIndices');
+    this.#limit = limit;
+    this.#log = log ?? createLogger('p2p:tx_pool_v2:archive');
+  }
+
+  /**
+   * Updates the maximum number of archived transactions.
+   */
+  updateLimit(limit: number): void {
+    this.#limit = limit;
+  }
+
+  /**
+   * Gets the current archive limit.
+   */
+  getLimit(): number {
+    return this.#limit;
+  }
+
+  /**
+   * Checks if archiving is enabled.
+   */
+  isEnabled(): boolean {
+    return this.#limit > 0;
+  }
+
+  /**
+   * Archives transactions, stripping their proofs.
+   * Evicts oldest transactions if the limit is exceeded.
+   */
+  async archiveTxs(txs: Tx[]): Promise<void> {
+    if (!this.isEnabled() || txs.length === 0) {
+      return;
+    }
+
+    try {
+      await this.#store.transactionAsync(async () => {
+        // Get current head and tail indices
+        let headIdx = await this.getHeadIndex();
+        let tailIdx = await this.getTailIndex();
+
+        for (const tx of txs) {
+          // Evict oldest entries if at capacity
+          while (headIdx - tailIdx >= this.#limit) {
+            const txHashToEvict = await this.#indices.getAsync(tailIdx);
+            if (txHashToEvict) {
+              await this.#txs.delete(txHashToEvict);
+              await this.#indices.delete(tailIdx);
+            }
+            tailIdx++;
+          }
+
+          // Archive the transaction with stripped proof
+          const archivedTx = this.stripProof(tx);
+          const txHash = tx.getTxHash().toString();
+          await this.#txs.set(txHash, archivedTx.toBuffer());
+          await this.#indices.set(headIdx, txHash);
+          headIdx++;
+        }
+
+        this.#log.debug(`Archived ${txs.length} txs, total: ${headIdx - tailIdx}`);
+      });
+    } catch (error) {
+      this.#log.error('Error archiving transactions', { error });
+    }
+  }
+
+  /**
+   * Retrieves an archived transaction by its hash.
+   */
+  async getTxByHash(txHash: TxHash): Promise<Tx | undefined> {
+    const buffer = await this.#txs.getAsync(txHash.toString());
+    return buffer ? Tx.fromBuffer(buffer) : undefined;
+  }
+
+  /**
+   * Gets the current count of archived transactions.
+   */
+  async getCount(): Promise<number> {
+    const head = await this.getHeadIndex();
+    const tail = await this.getTailIndex();
+    return head - tail;
+  }
+
+  /**
+   * Strips the proof from a transaction for archival.
+   */
+  private stripProof(tx: Tx): Tx {
+    return new Tx(tx.txHash, tx.data, ChonkProof.empty(), tx.contractClassLogFields, tx.publicFunctionCalldata);
+  }
+
+  private async getHeadIndex(): Promise<number> {
+    const entry = await this.#indices.entriesAsync({ limit: 1, reverse: true }).next();
+    return (entry.value?.[0] ?? -1) + 1;
+  }
+
+  private async getTailIndex(): Promise<number> {
+    const entry = await this.#indices.entriesAsync({ limit: 1 }).next();
+    return entry.value?.[0] ?? 0;
+  }
+}

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

@@ -0,0 +1,147 @@
+import type { BlockNumber } from '@aztec/foundation/branded-types';
+import type { Logger } from '@aztec/foundation/log';
+import type { BlockHeader } from '@aztec/stdlib/tx';
+
+import type { TxMetaData } from '../tx_metadata.js';
+import {
+  type EvictionConfig,
+  type EvictionContext,
+  EvictionEvent,
+  type EvictionRule,
+  type PoolOperations,
+  type PreAddPoolAccess,
+  type PreAddResult,
+  type PreAddRule,
+} from './interfaces.js';
+
+/**
+ * Manages eviction rules for the transaction pool.
+ * Coordinates pre-add rules (run during addPendingTxs) and post-event rules (run after events).
+ */
+export class EvictionManager {
+  private preAddRules: PreAddRule[] = [];
+  private postEventRules: EvictionRule[] = [];
+
+  constructor(
+    private pool: PoolOperations,
+    private log: Logger,
+  ) {}
+
+  /**
+   * Registers a pre-add rule that runs during transaction addition.
+   */
+  registerPreAddRule(rule: PreAddRule): void {
+    this.preAddRules.push(rule);
+    this.log.debug(`Registered pre-add rule: ${rule.name}`);
+  }
+
+  /**
+   * Registers a post-event eviction rule that runs after events.
+   */
+  registerRule(rule: EvictionRule): void {
+    this.postEventRules.push(rule);
+    this.log.debug(`Registered eviction rule: ${rule.name}`);
+  }
+
+  /**
+   * Runs all pre-add rules for an incoming transaction.
+   * Returns combined result of all rules.
+   */
+  async runPreAddRules(incomingMeta: TxMetaData, poolAccess: PreAddPoolAccess): Promise<PreAddResult> {
+    const allTxHashesToEvict: string[] = [];
+
+    for (const rule of this.preAddRules) {
+      try {
+        const result = await rule.check(incomingMeta, poolAccess);
+
+        if (result.shouldIgnore) {
+          return result;
+        }
+
+        // Collect txs to evict from all rules
+        for (const txHash of result.txHashesToEvict) {
+          if (!allTxHashesToEvict.includes(txHash)) {
+            allTxHashesToEvict.push(txHash);
+          }
+        }
+      } catch (err) {
+        this.log.error(`Error running pre-add rule ${rule.name}`, { err, txHash: incomingMeta.txHash });
+        // On error, ignore the transaction to be safe
+        return {
+          shouldIgnore: true,
+          txHashesToEvict: [],
+          reason: `pre-add rule ${rule.name} error: ${err}`,
+        };
+      }
+    }
+
+    return {
+      shouldIgnore: false,
+      txHashesToEvict: allTxHashesToEvict,
+    };
+  }
+
+  /**
+   * Runs post-event eviction after new transactions are added.
+   */
+  async evictAfterNewTxs(newTxHashes: string[], feePayers: string[]): Promise<void> {
+    const context: EvictionContext = {
+      event: EvictionEvent.TXS_ADDED,
+      newTxHashes,
+      feePayers,
+    };
+
+    await this.runPostEventRules(context);
+  }
+
+  /**
+   * Runs post-event eviction after a block is mined.
+   */
+  async evictAfterNewBlock(block: BlockHeader, newNullifiers: string[], feePayers: string[]): Promise<void> {
+    const context: EvictionContext = {
+      event: EvictionEvent.BLOCK_MINED,
+      block,
+      newNullifiers,
+      feePayers,
+    };
+
+    await this.runPostEventRules(context);
+  }
+
+  /**
+   * Runs post-event eviction after a chain prune (reorg).
+   */
+  async evictAfterChainPrune(blockNumber: BlockNumber): Promise<void> {
+    const context: EvictionContext = {
+      event: EvictionEvent.CHAIN_PRUNED,
+      blockNumber,
+    };
+
+    await this.runPostEventRules(context);
+  }
+
+  /**
+   * Updates configuration for all rules.
+   */
+  updateConfig(config: EvictionConfig): void {
+    for (const rule of this.preAddRules) {
+      rule.updateConfig?.(config);
+    }
+    for (const rule of this.postEventRules) {
+      rule.updateConfig?.(config);
+    }
+  }
+
+  private async runPostEventRules(context: EvictionContext): Promise<void> {
+    for (const rule of this.postEventRules) {
+      try {
+        const result = await rule.evict(context, this.pool);
+        if (!result.success) {
+          this.log.warn(`Eviction rule ${rule.name} failed`, { error: result.error });
+        }
+      } catch (err) {
+        this.log.error(`Error running eviction rule ${rule.name}`, { err });
+      }
+    }
+  }
+}