@aztec/p2p 0.0.1-commit.7d4e6cd → 0.0.1-commit.858058eac

package/src/mem_pools/tx_pool/eviction/eviction_strategy.ts

@@ -1,7 +1,12 @@
+import type { BlockNumber } from '@aztec/foundation/branded-types';
+import { Buffer32 } from '@aztec/foundation/buffer';
 import { Fr } from '@aztec/foundation/curves/bn254';
+import { ProtocolContractAddress } from '@aztec/protocol-contracts';
 import type { AztecAddress } from '@aztec/stdlib/aztec-address';
-import type { BlockHeader, Tx, TxHash } from '@aztec/stdlib/tx';
+import { type BlockHeader, type Tx, TxHash } from '@aztec/stdlib/tx';
 
+import { getFeePayerBalanceDelta } from '../../../msg_validators/tx_validator/fee_payer_balance.js';
+import { getTxPriorityFee } from '../priority.js';
 import type { TxPoolOptions } from '../tx_pool.js';
 
 export const EvictionEvent = {
@@ -16,16 +21,17 @@ export type EvictionContext =
   | {
       event: typeof EvictionEvent.TXS_ADDED;
       newTxs: TxHash[];
+      feePayers: AztecAddress[];
     }
   | {
       event: typeof EvictionEvent.CHAIN_PRUNED;
-      blockNumber: number;
+      blockNumber: BlockNumber;
     }
   | {
       event: typeof EvictionEvent.BLOCK_MINED;
       block: BlockHeader;
       newNullifiers: Fr[];
-      minedFeePayers: AztecAddress[];
+      feePayers: AztecAddress[];
     };
 
 /**
@@ -63,7 +69,8 @@ export interface TxPoolOperations {
   getTxByHash(txHash: TxHash): Promise<Tx | undefined>;
   getPendingTxInfos(): Promise<PendingTxInfo[]>;
   getPendingTxsReferencingBlocks(blockHashes: Fr[]): Promise<TxBlockReference[]>;
-  getPendingTxsWithFeePayer(feePayer: AztecAddress[]): Promise<PendingTxInfo[]>;
+  getPendingFeePayers(): Promise<AztecAddress[]>;
+  getFeePayerTxInfos(feePayer: AztecAddress): AsyncIterable<FeePayerTxInfo>;
   /** Cheap count of current pending transactions. */
   getPendingTxCount(): Promise<number>;
   /**
@@ -91,3 +98,111 @@ export interface EvictionRule {
    */
   updateConfig(config: TxPoolOptions): void;
 }
+
+/**
+ * Balance-related information about a transaction for a fee payer.
+ */
+export class FeePayerTxInfo {
+  txHash: TxHash;
+  priority: bigint;
+  feeLimit: bigint;
+  claimAmount: bigint;
+  isEvictable: boolean;
+
+  constructor(fields: {
+    txHash: TxHash;
+    priority: bigint;
+    feeLimit: bigint;
+    claimAmount: bigint;
+    isEvictable: boolean;
+  }) {
+    this.txHash = fields.txHash;
+    this.priority = fields.priority;
+    this.feeLimit = fields.feeLimit;
+    this.claimAmount = fields.claimAmount;
+    this.isEvictable = fields.isEvictable;
+  }
+
+  static async encode(tx: Tx, txHash: string | TxHash): Promise<Buffer> {
+    const { feeLimit, claimAmount } = await getFeePayerBalanceDelta(tx, ProtocolContractAddress.FeeJuice);
+    const priority = Buffer32.fromBigInt(getTxPriorityFee(tx)).toBuffer();
+    const hashBuffer = (typeof txHash === 'string' ? TxHash.fromString(txHash) : txHash).toBuffer();
+    const feeLimitBuffer = Buffer32.fromBigInt(feeLimit).toBuffer();
+    const claimAmountBuffer = Buffer32.fromBigInt(claimAmount).toBuffer();
+    return Buffer.concat([priority, hashBuffer, feeLimitBuffer, claimAmountBuffer]);
+  }
+
+  static decode(value: Buffer, isEvictable = true): FeePayerTxInfo {
+    const priority = Buffer32.fromBuffer(value.subarray(0, Buffer32.SIZE)).toBigInt();
+    const hashOffset = Buffer32.SIZE;
+    const feeLimitOffset = hashOffset + TxHash.SIZE;
+    const claimOffset = feeLimitOffset + Buffer32.SIZE;
+
+    return new FeePayerTxInfo({
+      txHash: TxHash.fromBuffer(value.subarray(hashOffset, feeLimitOffset)),
+      priority,
+      feeLimit: Buffer32.fromBuffer(value.subarray(feeLimitOffset, claimOffset)).toBigInt(),
+      claimAmount: Buffer32.fromBuffer(value.subarray(claimOffset, claimOffset + Buffer32.SIZE)).toBigInt(),
+      isEvictable,
+    });
+  }
+}
+
+/**
+ * Read-only access to pool state for pre-add eviction checks.
+ * Passed to pre-add rules during the addTxs transaction.
+ */
+export interface PreAddPoolAccess {
+  /**
+   * Get the pending tx hash that uses a specific nullifier, if any.
+   * Returns undefined if no pending tx uses this nullifier.
+   */
+  getTxHashByNullifier(nullifier: Fr): Promise<TxHash | undefined>;
+
+  /**
+   * Get a pending transaction by its hash.
+   */
+  getPendingTxByHash(hash: TxHash): Promise<Tx | undefined>;
+
+  /**
+   * Get the priority string for a transaction (for fee comparison).
+   */
+  getTxPriority(tx: Tx): string;
+}
+
+/**
+ * Result of a pre-add eviction check for a single transaction.
+ */
+export interface PreAddEvictionResult {
+  /** Whether the incoming tx should be rejected */
+  readonly shouldReject: boolean;
+  /** Sorted array of existing tx hashes that should be evicted if this tx is added */
+  readonly txHashesToEvict: TxHash[];
+  /** Optional reason for rejection */
+  readonly reason?: string;
+}
+
+/**
+ * Strategy interface for pre-add eviction rules.
+ * These run inside the addTxs transaction before a tx is added,
+ * deciding whether to evict existing txs or reject the incoming tx.
+ */
+export interface PreAddEvictionRule {
+  readonly name: string;
+
+  /**
+   * Check if incoming tx should be added and which existing txs to evict.
+   * Called inside the addTxs database transaction for atomicity.
+   *
+   * @param tx - The incoming transaction to check
+   * @param poolAccess - Read-only access to current pool state
+   * @returns Result indicating whether to reject and what to evict
+   */
+  check(tx: Tx, poolAccess: PreAddPoolAccess): Promise<PreAddEvictionResult>;
+
+  /**
+   * Updates the configuration for this rule.
+   * Rules should ignore config options that don't apply to them.
+   */
+  updateConfig?(config: TxPoolOptions): void;
+}

package/src/mem_pools/tx_pool/eviction/fee_payer_balance_eviction_rule.ts

@@ -0,0 +1,162 @@
+import { createLogger } from '@aztec/foundation/log';
+import { ProtocolContractAddress } from '@aztec/protocol-contracts';
+import { computeFeePayerBalanceStorageSlot } from '@aztec/protocol-contracts/fee-juice';
+import type { AztecAddress } from '@aztec/stdlib/aztec-address';
+import type { WorldStateSynchronizer } from '@aztec/stdlib/interfaces/server';
+import { DatabasePublicStateSource, type MerkleTreeReadOperations } from '@aztec/stdlib/trees';
+import type { TxHash } from '@aztec/stdlib/tx';
+
+import type { TxPoolOptions } from '../tx_pool.js';
+import {
+  type EvictionContext,
+  EvictionEvent,
+  type EvictionResult,
+  type EvictionRule,
+  type FeePayerTxInfo,
+  type TxPoolOperations,
+} from './eviction_strategy.js';
+
+export class FeePayerBalanceEvictionRule implements EvictionRule {
+  public readonly name = 'FeePayerBalanceEviction';
+  public readonly reason = 'fee_payer_balance';
+
+  private log = createLogger('p2p:mempool:tx_pool:fee_payer_balance_eviction_rule');
+
+  constructor(private worldState: WorldStateSynchronizer) {}
+
+  async evict(context: EvictionContext, txPool: TxPoolOperations): Promise<EvictionResult> {
+    try {
+      if (context.event === EvictionEvent.TXS_ADDED) {
+        return await this.evictForFeePayers(context.feePayers, this.worldState.getCommitted(), txPool);
+      }
+
+      if (context.event === EvictionEvent.BLOCK_MINED) {
+        const blockNumber = context.block.getBlockNumber();
+        // Ensure world state is synced to this block before accessing the snapshot.
+        // This handles the race where a block is added to the archiver
+        // but the world state hasn't synced it yet.
+        await this.worldState.syncImmediate(blockNumber);
+        return await this.evictForFeePayers(context.feePayers, this.worldState.getSnapshot(blockNumber), txPool);
+      }
+
+      // TODO: fix this edge-case
+      // This can lead to a race condition if we are catching up in the p2p client.
+      // Let's say we have 3 txs for the same fee payer, which get mined in blocks 1, 2, 3.
+      // Tx1 consumes fee juice, tx2 increases it, tx3 consumes it again. We see block1 with tx1 first, run this rule, and evict tx3.
+      // But tx3 was valid (due to tx2) and mined on block3. And we have just removed from the mempool a tx we needed for proving/reexec.
+      //
+      // NOTE: this will happen only in case of that lower-priority-fee tx entered in e.g. block 2, and we have higher-priority-fee tx in block 3
+      // (simply because that was the timing of these txs). But, in case of higher-priority-fee txs being in block 2, the tx3 won't be evicted
+      // -----
+      // Proposed fix: evict only if node is synched
+      if (context.event === EvictionEvent.CHAIN_PRUNED) {
+        // Ensure world state is synced to this block before accessing the snapshot.
+        await this.worldState.syncImmediate(context.blockNumber);
+        const feePayers = await txPool.getPendingFeePayers();
+        return await this.evictForFeePayers(feePayers, this.worldState.getSnapshot(context.blockNumber), txPool);
+      }
+
+      return {
+        reason: this.reason,
+        success: true,
+        txsEvicted: [],
+      };
+    } catch (err) {
+      this.log.error('Failed to evict txs due to fee payer balance', { err });
+      return {
+        reason: this.reason,
+        success: false,
+        txsEvicted: [],
+        error: new Error('Failed to evict txs due to fee payer balance', { cause: err }),
+      };
+    }
+  }
+
+  updateConfig(_config: TxPoolOptions): void {}
+
+  private async evictForFeePayers(
+    feePayers: Array<AztecAddress>, // assumed to be unique
+    db: MerkleTreeReadOperations,
+    txPool: TxPoolOperations,
+  ): Promise<EvictionResult> {
+    const publicStateSource = this.createPublicStateSource(db);
+
+    const txsToEvict = (
+      await Promise.all(feePayers.map(feePayer => this.getEvictionsForFeePayer(feePayer, publicStateSource, txPool)))
+    ).flat();
+
+    if (txsToEvict.length > 0) {
+      await txPool.deleteTxs(txsToEvict);
+    }
+
+    return {
+      reason: this.reason,
+      success: true,
+      txsEvicted: txsToEvict,
+    };
+  }
+
+  private async getEvictionsForFeePayer(
+    feePayer: AztecAddress,
+    publicStateSource: DatabasePublicStateSource,
+    txPool: TxPoolOperations,
+  ): Promise<TxHash[]> {
+    const initialBalance = (
+      await publicStateSource.storageRead(
+        ProtocolContractAddress.FeeJuice,
+        //TODO: cache this LRU-style
+        await computeFeePayerBalanceStorageSlot(feePayer),
+      )
+    ).toBigInt();
+
+    const txs: FeePayerTxInfo[] = [];
+    for await (const entry of txPool.getFeePayerTxInfos(feePayer)) {
+      txs.push(entry);
+    }
+
+    if (txs.length === 0) {
+      return [];
+    }
+
+    const txsToEvict: TxHash[] = [];
+    let balance = initialBalance;
+    let hasNonEvictableOverBalance = false;
+
+    // Evaluate balance in priority order so later claims cannot fund earlier spends.
+    // This sorts so that higher priority txs come first.
+    txs.sort((a, b) => {
+      if (a.priority === b.priority) {
+        return a.txHash.toBigInt() >= b.txHash.toBigInt() ? -1 : 1;
+      }
+
+      return a.priority > b.priority ? -1 : 1;
+    });
+
+    for (const tx of txs) {
+      const available = balance + tx.claimAmount;
+      if (available >= tx.feeLimit) {
+        balance = available - tx.feeLimit;
+        continue;
+      }
+
+      if (tx.isEvictable) {
+        txsToEvict.push(tx.txHash);
+      } else {
+        hasNonEvictableOverBalance = true;
+      }
+    }
+
+    if (hasNonEvictableOverBalance) {
+      this.log.verbose('Fee payer balance cannot be satisfied due to non-evictable txs', {
+        feePayer: feePayer.toString(),
+        balance: initialBalance,
+      });
+    }
+
+    return txsToEvict;
+  }
+
+  private createPublicStateSource(db: MerkleTreeReadOperations): DatabasePublicStateSource {
+    return new DatabasePublicStateSource(db);
+  }
+}

package/src/mem_pools/tx_pool/eviction/invalid_txs_after_reorg_rule.ts

@@ -1,7 +1,7 @@
 import { findIndexInSortedArray, insertIntoSortedArray } from '@aztec/foundation/array';
 import { Fr } from '@aztec/foundation/curves/bn254';
 import { createLogger } from '@aztec/foundation/log';
-import type { ReadonlyWorldStateAccess } from '@aztec/stdlib/interfaces/server';
+import type { WorldStateSynchronizer } from '@aztec/stdlib/interfaces/server';
 import { MerkleTreeId } from '@aztec/stdlib/trees';
 import type { TxHash } from '@aztec/stdlib/tx';
 
@@ -26,7 +26,7 @@ export class InvalidTxsAfterReorgRule implements EvictionRule {
 
   private log = createLogger('p2p:mempool:tx_pool:invalid_txs_after_reorg_rule');
 
-  public constructor(private worldState: ReadonlyWorldStateAccess) {}
+  public constructor(private worldState: WorldStateSynchronizer) {}
 
   async evict(context: EvictionContext, txPool: TxPoolOperations): Promise<EvictionResult> {
     if (context.event !== EvictionEvent.CHAIN_PRUNED) {
@@ -46,6 +46,8 @@ export class InvalidTxsAfterReorgRule implements EvictionRule {
         insertIntoSortedArray(uniqueBlockHashes, blockHash, Fr.cmp, false);
       });
 
+      // Ensure world state is synced to this block before accessing the snapshot.
+      await this.worldState.syncImmediate(context.blockNumber);
       const db = this.worldState.getSnapshot(context.blockNumber);
       const blocksFromDb = await db.findLeafIndices(MerkleTreeId.ARCHIVE, uniqueBlockHashes);
 

package/src/mem_pools/tx_pool/eviction/nullifier_conflict_pre_add_rule.ts

@@ -0,0 +1,75 @@
+import { findIndexInSortedArray, insertIntoSortedArray } from '@aztec/foundation/array';
+import { Fr } from '@aztec/foundation/curves/bn254';
+import { createLogger } from '@aztec/foundation/log';
+import { type Tx, TxHash } from '@aztec/stdlib/tx';
+
+import type { PreAddEvictionResult, PreAddEvictionRule, PreAddPoolAccess } from './eviction_strategy.js';
+
+const cmpTxHash = (a: TxHash, b: TxHash) => Fr.cmp(a.hash, b.hash);
+
+/**
+ * Pre-add eviction rule that checks for nullifier conflicts between incoming and existing transactions.
+ *
+ * When an incoming tx shares nullifiers with existing pending txs:
+ * - If the incoming tx has strictly higher priority fee, evict all conflicting txs
+ * - If any conflicting tx has equal or higher priority fee, reject the incoming tx
+ *
+ * This prevents nullifier spam attacks where an attacker floods the mempool with
+ * transactions spending the same nullifiers.
+ */
+export class NullifierConflictPreAddRule implements PreAddEvictionRule {
+  public readonly name = 'NullifierConflictPreAdd';
+
+  private log = createLogger('p2p:mempool:tx_pool:nullifier_conflict_pre_add_rule');
+
+  /**
+   * Check if the incoming transaction conflicts with existing transactions via nullifiers.
+   *
+   * @param tx - The incoming transaction
+   * @param poolAccess - Read-only access to pool state
+   * @returns Result with rejection status and txs to evict
+   */
+  async check(tx: Tx, poolAccess: PreAddPoolAccess): Promise<PreAddEvictionResult> {
+    const txHash = tx.getTxHash();
+    const nullifiers = tx.data.getNonEmptyNullifiers();
+    const txHashesToEvict: TxHash[] = [];
+    const incomingPriority = poolAccess.getTxPriority(tx);
+
+    for (const nullifier of nullifiers) {
+      const conflictingHash = await poolAccess.getTxHashByNullifier(nullifier);
+
+      if (
+        !conflictingHash ||
+        conflictingHash.equals(txHash) ||
+        findIndexInSortedArray(txHashesToEvict, conflictingHash, cmpTxHash) !== -1
+      ) {
+        continue;
+      }
+
+      // Get the conflicting tx's priority
+      const conflictingTx = await poolAccess.getPendingTxByHash(conflictingHash);
+      if (!conflictingTx) {
+        continue;
+      }
+
+      const conflictingPriority = poolAccess.getTxPriority(conflictingTx);
+
+      // If incoming tx has strictly higher priority, mark for eviction
+      // Otherwise, reject incoming tx (ties go to existing tx)
+      if (incomingPriority > conflictingPriority) {
+        insertIntoSortedArray(txHashesToEvict, conflictingHash, cmpTxHash);
+      } else {
+        this.log.debug(
+          `Rejecting tx ${txHash.toString()}: nullifier conflict with ${conflictingHash.toString()} which has higher or equal fee`,
+        );
+        return {
+          shouldReject: true,
+          txHashesToEvict: [],
+          reason: `nullifier conflict with ${conflictingHash.toString()}`,
+        };
+      }
+    }
+
+    return { shouldReject: false, txHashesToEvict };
+  }
+}

package/src/mem_pools/tx_pool_v2/README.md

@@ -0,0 +1,259 @@
+# 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()              │ eviction after reorg
+        ▼                                     ▼
+┌─────────────────────────────────────┐  ┌─────────────────────────────────────┐
+│             DELETED                 │  │         SOFT-DELETED                │
+│   (hard-deleted or archived)        │  │   (kept in DB for debugging)        │
+└─────────────────────────────────────┘  └─────────────────────────────────────┘
+                                                  │
+                                                  │ handleFinalizedBlock()
+                                                  │ (mined block finalized)
+                                                  ▼
+                                         ┌─────────────────────────────────────┐
+                                         │          HARD-DELETED               │
+                                         │   (permanently removed from DB)     │
+                                         └─────────────────────────────────────┘
+```
+
+## 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
+
+### DeletedPool (`deleted_pool.ts`)
+
+Manages soft deletion of transactions from pruned blocks:
+- When a reorg (chain prune) occurs, transactions from pruned blocks are tracked with their original mined block number
+- When these transactions are later evicted (e.g., failed validation, nullifier conflict), they are "soft-deleted" instead of removed
+- Soft-deleted transactions remain in the database for debugging and potential resubmission
+- When the original mined block is finalized on the new chain, soft-deleted transactions are permanently hard-deleted
+
+This ensures transactions from reorged blocks are kept around until we're certain they won't be needed.
+
+### TxMetaData (`tx_metadata.ts`)
+
+Lightweight metadata stored alongside each transaction:
+- `txHash`: Transaction identifier
+- `anchorBlockHeaderHash`: Hash of the anchor block header
+- `priorityFee`: For priority ordering and challenges
+- `feePayer`: For balance-based eviction
+- `claimAmount`: Fee payer's claim from bridging
+- `feeLimit`: Maximum fee the tx can pay
+- `nullifiers`: For conflict detection
+- `includeByTimestamp`: Expiration timestamp
+- `minedL2BlockId`: Set when mined (undefined otherwise)
+
+State is derived by TxPoolIndices:
+- `mined` if `minedL2BlockId` is set
+- `protected` if in protection map
+- `deleted` if soft-deleted (from a pruned block, evicted but kept in DB)
+- `pending` otherwise
+
+## Soft Deletion
+
+When a chain reorganization occurs, transactions that were mined in pruned blocks are handled specially:
+
+1. **Tracking**: When `handlePrunedBlocks` is called, all un-mined transactions are tracked by their original mined block number
+2. **Soft Delete**: If these transactions are later evicted (failed validation, nullifier conflict, etc.), they are "soft-deleted" - removed from indices but kept in the database
+3. **Retrieval**: Soft-deleted transactions can still be retrieved via `getTxByHash` and `hasTxs`, and return status `'deleted'` from `getTxStatus`
+4. **Hard Delete**: When `handleFinalizedBlock` is called and the finalized block number reaches or exceeds the transaction's original mined block, the transaction is permanently removed
+
+This design allows:
+- Debugging reorg scenarios by keeping transaction data available
+- Potential resubmission of transactions that failed validation after a reorg
+- Clean eventual cleanup once we're certain the transaction won't be needed
+
+**Example scenario:**
+1. Tx mined at block 10
+2. Chain prunes to block 5 (tx becomes un-mined, tracked as minedAtBlock=10)
+3. Tx fails validation and is soft-deleted
+4. Block 9 finalized → tx still in DB (minedAtBlock=10 > finalized=9)
+5. Block 10 finalized → tx hard-deleted (minedAtBlock=10 ≤ finalized=10)
+
+If the tx is re-mined at a higher block before being soft-deleted:
+1. Tx mined at block 10, pruned (tracked as minedAtBlock=10)
+2. Tx re-mined at block 15, pruned again (updated to minedAtBlock=15)
+3. Tx soft-deleted
+4. Block 10 finalized → tx still in DB
+5. Block 15 finalized → tx hard-deleted
+
+## Architecture: Pre-add vs Post-event Rules
+
+**Pre-add rules** (run during `addPendingTxs`):
+- Used for external transactions entering the pool
+- Can reject the incoming tx entirely
+- Can evict lower-priority existing txs to make room
+- Rules: NullifierConflictRule, FeePayerBalancePreAddRule, LowPriorityPreAddRule
+
+**Post-event rules** (run after state transitions):
+- Used for internal state changes (block mined, reorg, slot change)
+- Only evict txs already in the pool
+- Rules: InvalidTxsAfterMiningRule, InvalidTxsAfterReorgRule, FeePayerBalanceEvictionRule, LowPriorityEvictionRule
+
+This design choice means restored txs (from protected/mined states) use post-event rules only, because they were already validated on initial submission.
+
+## 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` | `txs_added`, `block_mined`, `chain_pruned` | Evicts txs when fee payer has insufficient balance. |
+| `InvalidTxsAfterMiningRule` | `block_mined` | Evicts pending txs with: (1) nullifiers in mined block, (2) expired timestamp. |
+| `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,
+  createTxValidator: () => 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 (177 tests)
+yarn test src/mem_pools/tx_pool_v2/tx_pool_v2.test.ts
+
+# Deleted pool tests (17 tests)
+yarn test src/mem_pools/tx_pool_v2/deleted_pool.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';