@aztec/p2p 4.0.0-nightly.20250907 → 4.0.0-nightly.20260107

package/src/mem_pools/attestation_pool/memory_attestation_pool.ts

@@ -1,14 +1,20 @@
+import type { SlotNumber } from '@aztec/foundation/branded-types';
 import { createLogger } from '@aztec/foundation/log';
 import type { BlockAttestation, BlockProposal } from '@aztec/stdlib/p2p';
 import { type TelemetryClient, getTelemetryClient } from '@aztec/telemetry-client';
 
 import { PoolInstrumentation, PoolName, type PoolStatsCallback } from '../instrumentation.js';
 import type { AttestationPool } from './attestation_pool.js';
+import { ATTESTATION_CAP_BUFFER, MAX_PROPOSALS_PER_SLOT } from './kv_attestation_pool.js';
 
 export class InMemoryAttestationPool implements AttestationPool {
   private metrics: PoolInstrumentation<BlockAttestation>;
 
-  private attestations: Map</*slot=*/ bigint, Map</*proposalId*/ string, Map</*address=*/ string, BlockAttestation>>>;
+  // eslint-disable-next-line aztec-custom/no-non-primitive-in-collections
+  private attestations: Map<
+    /*slot=*/ SlotNumber,
+    Map</*proposalId*/ string, Map</*address=*/ string, BlockAttestation>>
+  >;
   private proposals: Map<string, BlockProposal>;
 
   constructor(
@@ -30,7 +36,7 @@ export class InMemoryAttestationPool implements AttestationPool {
     return Promise.resolve(this.attestations.size === 0);
   }
 
-  public getAttestationsForSlot(slot: bigint): Promise<BlockAttestation[]> {
+  public getAttestationsForSlot(slot: SlotNumber): Promise<BlockAttestation[]> {
     return Promise.resolve(
       Array.from(this.attestations.get(slot)?.values() ?? []).flatMap(proposalAttestationMap =>
         Array.from(proposalAttestationMap.values()),
@@ -38,7 +44,7 @@ export class InMemoryAttestationPool implements AttestationPool {
     );
   }
 
-  public getAttestationsForSlotAndProposal(slot: bigint, proposalId: string): Promise<BlockAttestation[]> {
+  public getAttestationsForSlotAndProposal(slot: SlotNumber, proposalId: string): Promise<BlockAttestation[]> {
     const slotAttestationMap = this.attestations.get(slot);
     if (slotAttestationMap) {
       const proposalAttestationMap = slotAttestationMap.get(proposalId);
@@ -55,16 +61,26 @@ export class InMemoryAttestationPool implements AttestationPool {
       const slotNumber = attestation.payload.header.slotNumber;
 
       const proposalId = attestation.archive.toString();
-      const address = attestation.getSender();
+      const sender = attestation.getSender();
 
-      const slotAttestationMap = getSlotOrDefault(this.attestations, slotNumber.toBigInt());
+      // Skip attestations with invalid signatures
+      if (!sender) {
+        this.log.warn(`Skipping attestation with invalid signature for slot ${slotNumber}`, {
+          signature: attestation.signature.toString(),
+          slotNumber,
+          proposalId,
+        });
+        continue;
+      }
+
+      const slotAttestationMap = getSlotOrDefault(this.attestations, slotNumber);
       const proposalAttestationMap = getProposalOrDefault(slotAttestationMap, proposalId);
-      proposalAttestationMap.set(address.toString(), attestation);
+      proposalAttestationMap.set(sender.toString(), attestation);
 
-      this.log.verbose(`Added attestation for slot ${slotNumber.toBigInt()} from ${address}`, {
+      this.log.verbose(`Added attestation for slot ${slotNumber} from ${sender}`, {
         signature: attestation.signature.toString(),
         slotNumber,
-        address,
+        address: sender,
         proposalId,
       });
     }
@@ -72,7 +88,7 @@ export class InMemoryAttestationPool implements AttestationPool {
     return Promise.resolve();
   }
 
-  #getNumberOfAttestationsInSlot(slot: bigint): number {
+  #getNumberOfAttestationsInSlot(slot: SlotNumber): number {
     let total = 0;
     const slotAttestationMap = getSlotOrDefault(this.attestations, slot);
 
@@ -84,7 +100,7 @@ export class InMemoryAttestationPool implements AttestationPool {
     return total;
   }
 
-  public async deleteAttestationsOlderThan(oldestSlot: bigint): Promise<void> {
+  public async deleteAttestationsOlderThan(oldestSlot: SlotNumber): Promise<void> {
     const olderThan = [];
 
     // Entries are iterated in insertion order, so we can break as soon as we find a slot that is older than the oldestSlot.
@@ -105,7 +121,7 @@ export class InMemoryAttestationPool implements AttestationPool {
     return Promise.resolve();
   }
 
-  public deleteAttestationsForSlot(slot: bigint): Promise<void> {
+  public deleteAttestationsForSlot(slot: SlotNumber): Promise<void> {
     // We count the number of attestations we are removing
     const numberOfAttestations = this.#getNumberOfAttestationsInSlot(slot);
     const proposalIdsToDelete = this.attestations.get(slot)?.keys();
@@ -123,7 +139,7 @@ export class InMemoryAttestationPool implements AttestationPool {
     return Promise.resolve();
   }
 
-  public deleteAttestationsForSlotAndProposal(slot: bigint, proposalId: string): Promise<void> {
+  public deleteAttestationsForSlotAndProposal(slot: SlotNumber, proposalId: string): Promise<void> {
     const slotAttestationMap = getSlotOrDefault(this.attestations, slot);
     if (slotAttestationMap) {
       if (slotAttestationMap.has(proposalId)) {
@@ -142,24 +158,54 @@ export class InMemoryAttestationPool implements AttestationPool {
   public deleteAttestations(attestations: BlockAttestation[]): Promise<void> {
     for (const attestation of attestations) {
       const slotNumber = attestation.payload.header.slotNumber;
-      const slotAttestationMap = this.attestations.get(slotNumber.toBigInt());
+      const slotAttestationMap = this.attestations.get(slotNumber);
       if (slotAttestationMap) {
         const proposalId = attestation.archive.toString();
         const proposalAttestationMap = getProposalOrDefault(slotAttestationMap, proposalId);
         if (proposalAttestationMap) {
-          const address = attestation.getSender();
-          proposalAttestationMap.delete(address.toString());
-          this.log.debug(`Deleted attestation for slot ${slotNumber} from ${address}`);
+          const sender = attestation.getSender();
+
+          // Skip attestations with invalid signatures
+          if (!sender) {
+            this.log.warn(`Skipping deletion of attestation with invalid signature for slot ${slotNumber}`);
+            continue;
+          }
+
+          proposalAttestationMap.delete(sender.toString());
+          this.log.debug(`Deleted attestation for slot ${slotNumber} from ${sender}`);
         }
       }
     }
     return Promise.resolve();
   }
 
+  public hasAttestation(attestation: BlockAttestation): Promise<boolean> {
+    const slotNumber = attestation.payload.header.slotNumber;
+    const proposalId = attestation.archive.toString();
+    const sender = attestation.getSender();
+
+    // Attestations with invalid signatures are never in the pool
+    if (!sender) {
+      return Promise.resolve(false);
+    }
+
+    const slotAttestationMap = this.attestations.get(slotNumber);
+    if (!slotAttestationMap) {
+      return Promise.resolve(false);
+    }
+
+    const proposalAttestationMap = slotAttestationMap.get(proposalId);
+    if (!proposalAttestationMap) {
+      return Promise.resolve(false);
+    }
+
+    return Promise.resolve(proposalAttestationMap.has(sender.toString()));
+  }
+
   public addBlockProposal(blockProposal: BlockProposal): Promise<void> {
     // We initialize slot-proposal mapping if it does not exist
     // This is important to ensure we can delete this proposal if there were not attestations for it
-    const slotProposalMapping = getSlotOrDefault(this.attestations, blockProposal.slotNumber.toBigInt());
+    const slotProposalMapping = getSlotOrDefault(this.attestations, blockProposal.slotNumber);
     slotProposalMapping.set(blockProposal.payload.archive.toString(), new Map<string, BlockAttestation>());
 
     this.proposals.set(blockProposal.payload.archive.toString(), blockProposal);
@@ -169,6 +215,38 @@ export class InMemoryAttestationPool implements AttestationPool {
   public getBlockProposal(id: string): Promise<BlockProposal | undefined> {
     return Promise.resolve(this.proposals.get(id));
   }
+
+  public hasBlockProposal(idOrProposal: string | BlockProposal): Promise<boolean> {
+    const id = typeof idOrProposal === 'string' ? idOrProposal : idOrProposal.payload.archive.toString();
+    return Promise.resolve(this.proposals.has(id));
+  }
+
+  public hasReachedProposalCap(slot: SlotNumber): Promise<boolean> {
+    const slotAttestationMap = this.attestations.get(slot);
+    const proposalCount = slotAttestationMap?.size ?? 0;
+    return Promise.resolve(proposalCount >= MAX_PROPOSALS_PER_SLOT);
+  }
+
+  public hasReachedAttestationCap(slot: SlotNumber, proposalId: string, committeeSize: number): Promise<boolean> {
+    const limit = committeeSize + ATTESTATION_CAP_BUFFER;
+    const count = this.attestations.get(slot)?.get(proposalId)?.size ?? 0;
+    return Promise.resolve(limit <= 0 || count >= limit);
+  }
+
+  public async canAddProposal(block: BlockProposal): Promise<boolean> {
+    return this.proposals.has(block.archive.toString()) || !(await this.hasReachedProposalCap(block.slotNumber));
+  }
+
+  public async canAddAttestation(attestation: BlockAttestation, committeeSize: number): Promise<boolean> {
+    const sender = attestation.getSender();
+    const slot = attestation.payload.header.slotNumber;
+    const pid = attestation.archive.toString();
+    return (
+      !!sender &&
+      ((this.attestations.get(slot)?.get(pid)?.has(sender.toString()) ?? false) ||
+        !(await this.hasReachedAttestationCap(slot, pid, committeeSize)))
+    );
+  }
 }
 
 /**
@@ -180,8 +258,9 @@ export class InMemoryAttestationPool implements AttestationPool {
  * @returns The slot mapping
  */
 function getSlotOrDefault(
-  map: Map<bigint, Map<string, Map<string, BlockAttestation>>>,
-  slot: bigint,
+  // eslint-disable-next-line aztec-custom/no-non-primitive-in-collections
+  map: Map<SlotNumber, Map<string, Map<string, BlockAttestation>>>,
+  slot: SlotNumber,
 ): Map<string, Map<string, BlockAttestation>> {
   if (!map.has(slot)) {
     map.set(slot, new Map<string, Map<string, BlockAttestation>>());

package/src/mem_pools/attestation_pool/mocks.ts

@@ -1,12 +1,12 @@
-import type { Secp256k1Signer } from '@aztec/foundation/crypto';
-import { Fr } from '@aztec/foundation/fields';
+import type { Secp256k1Signer } from '@aztec/foundation/crypto/secp256k1-signer';
+import { Fr } from '@aztec/foundation/curves/bn254';
 import {
   BlockAttestation,
   ConsensusPayload,
   SignatureDomainSeparator,
   getHashedSignaturePayloadEthSignedMessage,
 } from '@aztec/stdlib/p2p';
-import { makeHeader } from '@aztec/stdlib/testing';
+import { makeL2BlockHeader } from '@aztec/stdlib/testing';
 
 import { type LocalAccount, generatePrivateKey, privateKeyToAccount } from 'viem/accounts';
 
@@ -32,11 +32,14 @@ export const mockAttestation = (
   archive: Fr = Fr.random(),
 ): BlockAttestation => {
   // Use arbitrary numbers for all other than slot
-  const header = makeHeader(1, 2, slot);
-  const payload = new ConsensusPayload(header.toPropose(), archive, header.state);
+  const header = makeL2BlockHeader(1, 2, slot);
+  const payload = new ConsensusPayload(header.toCheckpointHeader(), archive);
 
-  const hash = getHashedSignaturePayloadEthSignedMessage(payload, SignatureDomainSeparator.blockAttestation);
-  const signature = signer.sign(hash);
+  const attestationHash = getHashedSignaturePayloadEthSignedMessage(payload, SignatureDomainSeparator.blockAttestation);
+  const attestationSignature = signer.sign(attestationHash);
 
-  return new BlockAttestation(header.globalVariables.blockNumber, payload, signature);
+  const proposalHash = getHashedSignaturePayloadEthSignedMessage(payload, SignatureDomainSeparator.blockProposal);
+  const proposerSignature = signer.sign(proposalHash);
+
+  return new BlockAttestation(payload, attestationSignature, proposerSignature);
 };

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,
@@ -10,6 +11,7 @@ import {
   type MetricsType,
   type ObservableGauge,
   type TelemetryClient,
+  type UpDownCounter,
 } from '@aztec/telemetry-client';
 
 export enum PoolName {
@@ -20,6 +22,8 @@ export enum PoolName {
 type MetricsLabels = {
   objectInMempool: MetricsType;
   objectSize: MetricsType;
+  itemsAdded: MetricsType;
+  itemMinedDelay: MetricsType;
 };
 
 /**
@@ -32,11 +36,15 @@ function getMetricsLabels(name: PoolName): MetricsLabels {
     return {
       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,
     };
   }
 
@@ -53,14 +61,19 @@ export type PoolStatsCallback = () => Promise<{
 export class PoolInstrumentation<PoolObject extends Gossipable> {
   /** The number of txs in the mempool */
   private objectsInMempool: ObservableGauge;
+  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,
@@ -89,6 +102,14 @@ export class PoolInstrumentation<PoolObject extends Gossipable> {
       dbStats,
     );
 
+    this.addObjectCounter = this.meter.createUpDownCounter(metricsLabels.itemsAdded, {
+      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]);
   }
 
@@ -96,6 +117,31 @@ export class PoolInstrumentation<PoolObject extends Gossipable> {
     this.objectSize.record(poolObject.getSize());
   }
 
+  public incrementAddedObjects(count: number) {
+    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