@aztec/p2p 3.0.0-rc.5 → 4.0.0-nightly.20260107

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aztec/p2p",
-  "version": "3.0.0-rc.5",
+  "version": "4.0.0-nightly.20260107",
   "type": "module",
   "exports": {
     ".": "./dest/index.js",
@@ -67,17 +67,17 @@
     ]
   },
   "dependencies": {
-    "@aztec/constants": "3.0.0-rc.5",
-    "@aztec/epoch-cache": "3.0.0-rc.5",
-    "@aztec/ethereum": "3.0.0-rc.5",
-    "@aztec/foundation": "3.0.0-rc.5",
-    "@aztec/kv-store": "3.0.0-rc.5",
-    "@aztec/noir-contracts.js": "3.0.0-rc.5",
-    "@aztec/noir-protocol-circuits-types": "3.0.0-rc.5",
-    "@aztec/protocol-contracts": "3.0.0-rc.5",
-    "@aztec/simulator": "3.0.0-rc.5",
-    "@aztec/stdlib": "3.0.0-rc.5",
-    "@aztec/telemetry-client": "3.0.0-rc.5",
+    "@aztec/constants": "4.0.0-nightly.20260107",
+    "@aztec/epoch-cache": "4.0.0-nightly.20260107",
+    "@aztec/ethereum": "4.0.0-nightly.20260107",
+    "@aztec/foundation": "4.0.0-nightly.20260107",
+    "@aztec/kv-store": "4.0.0-nightly.20260107",
+    "@aztec/noir-contracts.js": "4.0.0-nightly.20260107",
+    "@aztec/noir-protocol-circuits-types": "4.0.0-nightly.20260107",
+    "@aztec/protocol-contracts": "4.0.0-nightly.20260107",
+    "@aztec/simulator": "4.0.0-nightly.20260107",
+    "@aztec/stdlib": "4.0.0-nightly.20260107",
+    "@aztec/telemetry-client": "4.0.0-nightly.20260107",
     "@chainsafe/libp2p-gossipsub": "13.0.0",
     "@chainsafe/libp2p-noise": "^15.0.0",
     "@chainsafe/libp2p-yamux": "^6.0.2",
@@ -104,8 +104,8 @@
     "xxhash-wasm": "^1.1.0"
   },
   "devDependencies": {
-    "@aztec/archiver": "3.0.0-rc.5",
-    "@aztec/world-state": "3.0.0-rc.5",
+    "@aztec/archiver": "4.0.0-nightly.20260107",
+    "@aztec/world-state": "4.0.0-nightly.20260107",
     "@jest/globals": "^30.0.0",
     "@types/jest": "^30.0.0",
     "@types/node": "^22.15.17",

package/src/client/factory.ts

@@ -26,7 +26,7 @@ import { configureP2PClientAddresses, createLibP2PPeerIdFromPrivateKey, getPeerI
 export type P2PClientDeps<T extends P2PClientType> = {
   txPool?: TxPool;
   store?: AztecAsyncKVStore;
-  attestationPool?: T extends P2PClientType.Full ? AttestationPool : undefined;
+  attestationPool?: AttestationPool;
   logger?: Logger;
   txCollectionNodeSources?: TxSource[];
   p2pServiceFactory?: (...args: Parameters<(typeof LibP2PService)['new']>) => Promise<LibP2PService<T>>;
@@ -73,19 +73,14 @@ export async function createP2PClient<T extends P2PClientType>(
   );
   const l1Constants = await archiver.getL1Constants();
 
-  const mempools: MemPools<T> = {
+  const mempools: MemPools = {
     txPool:
       deps.txPool ??
       new AztecKVTxPool(store, archive, worldStateSynchronizer, telemetry, {
-        maxTxPoolSize: config.maxTxPoolSize,
+        maxPendingTxCount: config.maxPendingTxCount,
         archivedTxLimit: config.archivedTxLimit,
       }),
-    attestationPool:
-      clientType === P2PClientType.Full
-        ? ((deps.attestationPool ?? new KvAttestationPool(attestationStore, telemetry)) as T extends P2PClientType.Full
-            ? AttestationPool
-            : undefined)
-        : undefined,
+    attestationPool: deps.attestationPool ?? new KvAttestationPool(attestationStore, telemetry),
   };
 
   const p2pService = await createP2PService<T>(
@@ -147,7 +142,7 @@ async function createP2PService<T extends P2PClientType>(
   epochCache: EpochCacheInterface,
   store: AztecAsyncKVStore,
   peerStore: AztecLMDBStoreV2,
-  mempools: MemPools<T>,
+  mempools: MemPools,
   p2pServiceFactory: P2PClientDeps<T>['p2pServiceFactory'],
   packageVersion: string,
   logger: Logger,

package/src/client/p2p_client.ts

@@ -69,7 +69,7 @@ export class P2PClient<T extends P2PClientType = P2PClientType.Full>
   private synchedLatestSlot: AztecAsyncSingleton<bigint>;
 
   private txPool: TxPool;
-  private attestationPool: T extends P2PClientType.Full ? AttestationPool : undefined;
+  private attestationPool: AttestationPool;
 
   private config: P2PConfig;
 
@@ -91,7 +91,7 @@ export class P2PClient<T extends P2PClientType = P2PClientType.Full>
     _clientType: T,
     private store: AztecAsyncKVStore,
     private l2BlockSource: L2BlockSource & ContractDataSource,
-    mempools: MemPools<T>,
+    mempools: MemPools,
     private p2pService: P2PService,
     private txCollection: TxCollection,
     config: Partial<P2PConfig> = {},
@@ -103,7 +103,7 @@ export class P2PClient<T extends P2PClientType = P2PClientType.Full>
 
     this.config = { ...getP2PDefaultConfig(), ...config };
     this.txPool = mempools.txPool;
-    this.attestationPool = mempools.attestationPool!;
+    this.attestationPool = mempools.attestationPool;
 
     this.txProvider = new TxProvider(
       this.txCollection,
@@ -282,10 +282,7 @@ export class P2PClient<T extends P2PClientType = P2PClientType.Full>
     const syncedProvenBlock = (await this.getSyncedProvenBlockNum()) + 1;
     const syncedFinalizedBlock = (await this.getSyncedFinalizedBlockNum()) + 1;
 
-    if (
-      (await this.txPool.isEmpty()) &&
-      (this.attestationPool === undefined || (await this.attestationPool?.isEmpty()))
-    ) {
+    if ((await this.txPool.isEmpty()) && (await this.attestationPool.isEmpty())) {
       // if mempools are empty, we don't care about syncing prior blocks
       this.initBlockStream(BlockNumber(this.latestBlockNumberAtStart));
       this.setCurrentState(P2PClientState.RUNNING);
@@ -389,19 +386,17 @@ export class P2PClient<T extends P2PClientType = P2PClientType.Full>
   }
 
   public async getAttestationsForSlot(slot: SlotNumber, proposalId?: string): Promise<BlockAttestation[]> {
-    return (
-      (await (proposalId
-        ? this.attestationPool?.getAttestationsForSlotAndProposal(slot, proposalId)
-        : this.attestationPool?.getAttestationsForSlot(slot))) ?? []
-    );
+    return await (proposalId
+      ? this.attestationPool.getAttestationsForSlotAndProposal(slot, proposalId)
+      : this.attestationPool.getAttestationsForSlot(slot));
   }
 
   public addAttestations(attestations: BlockAttestation[]): Promise<void> {
-    return this.attestationPool?.addAttestations(attestations) ?? Promise.resolve();
+    return this.attestationPool.addAttestations(attestations);
   }
 
   public deleteAttestation(attestation: BlockAttestation): Promise<void> {
-    return this.attestationPool?.deleteAttestations([attestation]) ?? Promise.resolve();
+    return this.attestationPool.deleteAttestations([attestation]);
   }
 
   // REVIEW: https://github.com/AztecProtocol/aztec-packages/issues/7963
@@ -715,6 +710,7 @@ export class P2PClient<T extends P2PClientType = P2PClientType.Full>
     }
 
     await this.markTxsAsMinedFromBlocks(blocks);
+    await this.txPool.clearNonEvictableTxs();
     await this.startCollectingMissingTxs(blocks);
 
     const lastBlock = blocks.at(-1)!;
@@ -782,7 +778,7 @@ export class P2PClient<T extends P2PClientType = P2PClientType.Full>
     await this.txPool.deleteTxs(txHashes, { permanently: true });
     await this.txPool.cleanupDeletedMinedTxs(lastBlockNum);
 
-    await this.attestationPool?.deleteAttestationsOlderThan(lastBlockSlot);
+    await this.attestationPool.deleteAttestationsOlderThan(lastBlockSlot);
 
     await this.synchedFinalizedBlockNumber.set(lastBlockNum);
     this.log.debug(`Synched to finalized block ${lastBlockNum} at slot ${lastBlockSlot}`);
@@ -833,8 +829,7 @@ export class P2PClient<T extends P2PClientType = P2PClientType.Full>
       this.log.info(`Deleting ${minedTxsFromReorg.length} mined txs from reorg`);
       await this.txPool.deleteTxs(minedTxsFromReorg);
     } else {
-      this.log.info(`Moving ${minedTxsFromReorg.length} mined txs from reorg back to pending`);
-      await this.txPool.markMinedAsPending(minedTxsFromReorg);
+      await this.txPool.markMinedAsPending(minedTxsFromReorg, latestBlock);
     }
 
     await this.synchedLatestBlockNumber.set(latestBlock);

package/src/config.ts

@@ -133,11 +133,8 @@ export interface P2PConfig extends P2PReqRespConfig, ChainConfig, TxCollectionCo
   /** Which calls are allowed in the public setup phase of a tx. */
   txPublicSetupAllowList: AllowedElement[];
 
-  /** The maximum cumulative tx size (in bytes) of pending txs before evicting lower priority txs. */
-  maxTxPoolSize: number;
-
-  /** If the pool is full, it will still accept a few more txs until it reached maxTxPoolOverspillFactor * maxTxPoolSize. Then it will evict */
-  txPoolOverflowFactor: number;
+  /** The maximum number of pending txs before evicting lower priority txs. */
+  maxPendingTxCount: number;
 
   /** The node's seen message ID cache size */
   seenMessageCacheSize: number;
@@ -375,15 +372,12 @@ export const p2pConfigMappings: ConfigMappingsType<P2PConfig> = {
     printDefault: () =>
       'AuthRegistry, FeeJuice.increase_public_balance, Token.increase_public_balance, FPC.prepare_fee',
   },
-  maxTxPoolSize: {
-    env: 'P2P_MAX_TX_POOL_SIZE',
-    description: 'The maximum cumulative tx size of pending txs (in bytes) before evicting lower priority txs.',
-    ...numberConfigHelper(100_000_000), // 100MB
-  },
-  txPoolOverflowFactor: {
-    env: 'P2P_TX_POOL_OVERFLOW_FACTOR',
-    description: 'How much the tx pool can overflow before it starts evicting txs. Must be greater than 1',
-    ...floatConfigHelper(1.1), // 10% overflow
+  maxPendingTxCount: {
+    env: 'P2P_MAX_PENDING_TX_COUNT',
+    description: 'The maximum number of pending txs before evicting lower priority txs.',
+    // Worst case scenario: Uncompressed public/private tx is ~ 156kb
+    // This implies we are using ~156MB of memory for pending pool
+    ...numberConfigHelper(1_000),
   },
   seenMessageCacheSize: {
     env: 'P2P_SEEN_MSG_CACHE_SIZE',

package/src/mem_pools/instrumentation.ts

@@ -1,4 +1,5 @@
 import type { Gossipable } from '@aztec/stdlib/p2p';
+import type { Tx } from '@aztec/stdlib/tx';
 import {
   Attributes,
   type BatchObservableResult,
@@ -22,6 +23,7 @@ type MetricsLabels = {
   objectInMempool: MetricsType;
   objectSize: MetricsType;
   itemsAdded: MetricsType;
+  itemMinedDelay: MetricsType;
 };
 
 /**
@@ -35,12 +37,14 @@ function getMetricsLabels(name: PoolName): MetricsLabels {
       objectInMempool: Metrics.MEMPOOL_TX_COUNT,
       objectSize: Metrics.MEMPOOL_TX_SIZE,
       itemsAdded: Metrics.MEMPOOL_TX_ADDED_COUNT,
+      itemMinedDelay: Metrics.MEMPOOL_TX_MINED_DELAY,
     };
   } else if (name === PoolName.ATTESTATION_POOL) {
     return {
       objectInMempool: Metrics.MEMPOOL_ATTESTATIONS_COUNT,
       objectSize: Metrics.MEMPOOL_ATTESTATIONS_SIZE,
       itemsAdded: Metrics.MEMPOOL_ATTESTATIONS_ADDED_COUNT,
+      itemMinedDelay: Metrics.MEMPOOL_ATTESTATIONS_MINED_DELAY,
     };
   }
 
@@ -60,12 +64,16 @@ export class PoolInstrumentation<PoolObject extends Gossipable> {
   private addObjectCounter: UpDownCounter;
   /** Tracks tx size */
   private objectSize: Histogram;
+  /** Track delay between transaction added and evicted */
+  private minedDelay: Histogram;
 
   private dbMetrics: LmdbMetrics;
 
   private defaultAttributes;
   private meter: Meter;
 
+  private txAddedTimestamp: Map<bigint, number> = new Map<bigint, number>();
+
   constructor(
     telemetry: TelemetryClient,
     name: PoolName,
@@ -98,6 +106,10 @@ export class PoolInstrumentation<PoolObject extends Gossipable> {
       description: 'The number of transactions added to the mempool',
     });
 
+    this.minedDelay = this.meter.createHistogram(metricsLabels.itemMinedDelay, {
+      description: 'Delay between transaction added and evicted from the mempool',
+    });
+
     this.meter.addBatchObservableCallback(this.observeStats, [this.objectsInMempool]);
   }
 
@@ -109,6 +121,27 @@ export class PoolInstrumentation<PoolObject extends Gossipable> {
     this.addObjectCounter.add(count);
   }
 
+  public transactionsAdded(transactions: Tx[]) {
+    const timestamp = Date.now();
+    for (const transaction of transactions) {
+      this.txAddedTimestamp.set(transaction.txHash.toBigInt(), timestamp);
+    }
+  }
+
+  public transactionsRemoved(hashes: Iterable<bigint> | Iterable<string>) {
+    const timestamp = Date.now();
+    for (const hash of hashes) {
+      const key = BigInt(hash);
+      const addedAt = this.txAddedTimestamp.get(key);
+      if (addedAt !== undefined) {
+        this.txAddedTimestamp.delete(key);
+        if (addedAt < timestamp) {
+          this.minedDelay.record(timestamp - addedAt);
+        }
+      }
+    }
+  }
+
   private observeStats = async (observer: BatchObservableResult) => {
     const { itemCount } = await this.poolStats();
     if (typeof itemCount === 'number') {

package/src/mem_pools/interface.ts

@@ -1,12 +1,10 @@
-import type { P2PClientType } from '@aztec/stdlib/p2p';
-
 import type { AttestationPool } from './attestation_pool/attestation_pool.js';
 import type { TxPool } from './tx_pool/tx_pool.js';
 
 /**
  * A interface the combines all mempools
  */
-export type MemPools<T extends P2PClientType = P2PClientType.Full> = {
+export type MemPools = {
   txPool: TxPool;
-  attestationPool?: T extends P2PClientType.Full ? AttestationPool : undefined;
+  attestationPool: AttestationPool;
 };

package/src/mem_pools/tx_pool/README.md

@@ -0,0 +1,255 @@
+# Transaction Pool (Mempool)
+
+This module implements the transaction pool (mempool) for the Aztec P2P network. The mempool holds unconfirmed transactions awaiting inclusion in a block.
+
+## Overview
+
+The transaction pool serves as a staging area for transactions before they are included in blocks. It manages the lifecycle of transactions from initial submission through mining, handling duplicates, priority ordering, and eviction of invalid or low-priority transactions.
+
+## Interface: `TxPool`
+
+The [`TxPool`](tx_pool.ts) interface defines the contract that all transaction pool implementations must fulfill:
+
+### Transaction Lifecycle
+
+The lifecycle of transactions in the pool is summarised in the following table:
+
+| State | Meaning | Possible Future States |
+| --- | --- | --- |
+| Pending | Available to be added to a block, can be evicted | Protected, Mined, Soft Deleted |
+| Protected | Added to a proposal, must not be evicted | Mined, Pending |
+| Mined | Confirmed as added to a block | Soft Deleted, Pending |
+| Soft Deleted | Awaiting full deletion once state has been finalised on L1 | Pending, Deleted |
+| Deleted | Removed from the pool | N/A |
+
+**Note on why Soft Delete:**
+Mined transactions are soft-deleted rather than permanently removed to support:
+1. Reorg handling — If a chain reorganization occurs, soft-deleted transactions are still available in the mempool 
+2. Slash condition detection — The epoch prune watcher needs access to transactions from pruned epochs to correctly identify data withholding slash conditions. Without soft-delete, transactions invalidated by reorgs (e.g., built on removed blocks) would be lost, causing false positives for data withholding violations.
+
+Mined transactions are permanently deleted via `cleanupDeletedMinedTxs()` once their original block is finalized on L1, ensuring theyremain available during the uncertainty window.
+Alternatively, mined transactions can be permanently deleted immediately by passing the `permanent: true` option to `deleteTxs()`.
+
+#### Transaction Lifecycle Methods
+
+| Method | Description |
+|--------|-------------|
+| `addTxs(txs, opts?)` | Adds transactions to the pool. Duplicates are ignored. Returns count of newly added txs. |
+| `deleteTxs(txHashes, opts?)` | Removes transactions from the pool. Supports soft-delete for mined txs. |
+| `markAsMined(txHashes, blockHeader)` | Marks transactions as included in a block. |
+| `markMinedAsPending(txHashes, blockNumber)` | Reverts mined transactions to pending (used during reorgs). |
+| `getArchivedTxByHash(txHash)` | Retrieves archived (historical) transactions. |
+| `getTxStatus(txHash)` | Returns status: `'pending'`, `'mined'`, `'deleted'`, or `undefined`. |
+
+### Transaction Fetching
+
+| Method | Description |
+|--------|-------------|
+| `hasTx(txHash)` / `hasTxs(txHashes)` | Checks if transaction(s) exist in the pool. |
+| `getTxByHash(txHash)` | Retrieves a transaction by its hash. |
+| `getTxsByHash(txHashes)` | Batch retrieval of transactions by hash. |
+| `getAllTxs()` / `getAllTxHashes()` | Returns all transactions or their hashes. |
+| `getPendingTxHashes()` | Returns pending tx hashes **sorted by priority** (highest first). |
+| `getPendingTxCount()` | Returns count of pending transactions. |
+| `getMinedTxHashes()` | Returns mined tx hashes with their block numbers. |
+
+### Pool Management
+
+| Method | Description |
+|--------|-------------|
+| `updateConfig(config)` | Updates pool configuration (max size, archive limit). |
+| `markTxsAsNonEvictable(txHashes)` | Protects transactions from eviction. |
+| `clearNonEvictableTxs()` | Clears non-evictable flag from all transactions. |
+| `cleanupDeletedMinedTxs(blockNumber)` | Permanently removes soft-deleted txs from blocks ≤ blockNumber. |
+| `isEmpty()` | Checks if the pool has no transactions. |
+
+### Events
+
+The pool emits a `txs-added` event when new transactions are successfully added, allowing subscribers to react to pool changes.
+
+## `AztecKVTxPool`
+
+The [`AztecKVTxPool`](aztec_kv_tx_pool.ts) is the production-grade implementation backed by a persistent key-value store. It provides:
+
+- **Persistent storage** via `AztecAsyncKVStore`
+- **Multiple indexes** for efficient queries
+- **Automatic eviction** of invalid and low-priority transactions
+- **Transaction archival** for historical lookups
+- **Soft-delete semantics** for mined transactions
+
+#### Storage Structure
+
+The pool maintains several KV maps and indexes:
+
+| Store | Purpose |
+|-------|---------|
+| `#txs` | Primary storage: tx hash → serialized tx buffer |
+| `#minedTxHashToBlock` | Index of mined txs: tx hash → block number |
+| `#pendingTxPriorityToHash` | Priority-ordered index of pending txs |
+| `#deletedMinedTxHashes` | Soft-deleted mined txs: tx hash → original block number |
+| `#blockToDeletedMinedTxHash` | Reverse index for cleanup: block → deleted tx hashes |
+| `#txHashToHistoricalBlockHeaderHash` | Anchor block reference for each tx |
+| `#historicalHeaderToTxHash` | Index from historical block → tx hashes |
+| `#feePayerToTxHash` | Index from fee payer address → tx hashes |
+| `#archivedTxs` | Archived transactions for historical lookup |
+
+#### In-Memory Caches
+
+| Cache | Purpose |
+|-------|---------|
+| `#pendingTxs` | Hydrated pending transactions for fast access |
+| `#nonEvictableTxs` | Set of tx hashes protected from eviction |
+
+## Transaction Priority
+
+Transactions are prioritized based on their **total priority fees** (see [`priority.ts`](priority.ts)):
+
+```typescript
+priorityFee = maxPriorityFeesPerGas.feePerDaGas + maxPriorityFeesPerGas.feePerL2Gas
+```
+
+The priority is stored as a hex string derived from a 32-byte buffer representation of the fee amount, enabling lexicographic ordering in the KV store. Pending transactions are returned in **descending priority order** (highest fees first).
+
+## Transaction Lifecycle in AztecKVTxPool
+
+### 1. Adding Transactions
+
+When `addTxs()` is called:
+
+1. Check for duplicates (skip if tx already exists)
+2. Store the serialized tx in `#txs`
+3. Index the tx by its anchor block hash
+4. If not already mined, add to pending indexes:
+   - Priority-to-hash index (for ordering)
+   - Historical header index (for reorg handling)
+   - Fee payer index (for balance validation)
+5. Record metrics
+6. Trigger eviction rules for `TXS_ADDED` event
+7. Emit `txs-added` event
+
+### 2. Marking as Mined
+
+When a block is finalized, `markAsMined()`:
+
+1. Move tx from pending to mined status
+2. If previously soft-deleted, restore to mined status
+3. Trigger eviction rules for `BLOCK_MINED` event
+
+### 3. Handling Reorgs
+
+When blocks are pruned, `markMinedAsPending()`:
+
+1. Remove tx from mined index
+2. Rehydrate pending indexes
+3. Trigger eviction rules for `CHAIN_PRUNED` event
+
+### 4. Deleting Transactions
+
+The `deleteTxs()` method handles two cases:
+
+- **Pending transactions**: Permanently deleted (transactions and all indexes to the transaction)
+- **Mined transactions**: Soft-deleted by default (moved to `#deletedMinedTxHashes`), with option for permanent deletion
+
+Soft-deleted mined transactions are retained for potential future reference and can be permanently cleaned up later via `cleanupDeletedMinedTxs()`.
+
+## Eviction System
+
+The eviction system automatically removes invalid or low-priority transactions based on configurable rules. See the [`eviction/`](eviction/) subdirectory for implementation details.
+
+### Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                      EvictionManager                            │
+│  Orchestrates eviction rules based on pool events               │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐  │
+│  │EvictionRule #1  │  │EvictionRule #2  │  │EvictionRule #N  │  │
+│  └─────────────────┘  └─────────────────┘  └─────────────────┘  │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+                    ┌─────────────────┐
+                    │ TxPoolOperations│
+                    │   (interface)   │
+                    └─────────────────┘
+```
+
+The [`EvictionManager`](eviction/eviction_manager.ts) coordinates eviction by:
+
+1. Registering multiple `EvictionRule` implementations
+2. Calling each rule when tx pool events occur
+3. Propagating configuration updates to all rules
+
+### Eviction Events
+
+| Event | Trigger | Purpose |
+|-------|---------|---------|
+| `TXS_ADDED` | New transactions added | Enforce pool size limits |
+| `BLOCK_MINED` | Block finalized | Remove invalidated transactions |
+| `CHAIN_PRUNED` | Chain reorganization | Remove txs referencing pruned blocks |
+
+### Eviction Rules
+
+#### 1. `InvalidTxsAfterMiningRule`
+
+**Triggers on:** `BLOCK_MINED`
+
+Evicts transactions that become invalid after a block is mined:
+
+- Duplicate nullifiers: Txs with nullifiers already included in the mined block
+- Expired transactions: Txs with `includeByTimestamp` ≤ mined block timestamp
+
+#### 2. `InvalidTxsAfterReorgRule`
+
+**Triggers on:** `CHAIN_PRUNED`
+
+Evicts transactions that reference blocks no longer in the canonical chain:
+
+- Checks each pending tx's anchor block hash against the archive tree
+- Removes txs whose anchor blocks are not found (pruned)
+
+#### 3. `InsufficientFeePayerBalanceRule`
+
+**Triggers on:** `BLOCK_MINED`, `CHAIN_PRUNED`
+
+Evicts transactions whose fee payer no longer has sufficient balance:
+
+- Uses `GasTxValidator` to check fee payer balances against current world state
+
+#### 4. `LowPriorityEvictionRule`
+
+**Triggers on:** `TXS_ADDED`
+
+Enforces maximum pool size by evicting lowest-priority (by fee) transactions:
+
+- Configured via `maxPendingTxCount` option (0 = disabled)
+- Uses `getLowestPriorityEvictable()` to find txs to evict
+
+### Non-Evictable Transactions
+
+Transactions can be marked as non-evictable via `markTxsAsNonEvictable()`. This protects them from all eviction rules, typically used during block building to ensure transactions being processed aren't evicted mid-operation. The flag is cleared after block processing via `clearNonEvictableTxs()`.
+The `clearNonEvictableTxs` is called upon getting new L2 block.
+
+## Configuration
+
+The pool accepts configuration via `TxPoolOptions`:
+
+```typescript
+type TxPoolOptions = {
+  maxPendingTxCount?: number;  // Max pending txs (0 = unlimited)
+  archivedTxLimit?: number;    // Number of archived txs to retain
+};
+```
+
+Configuration can be updated at runtime via `updateConfig()`.
+
+## Telemetry
+
+The pool integrates with the telemetry system to report:
+
+- Transaction counts (pending vs mined)
+- Transaction sizes
+- Store size estimates