@aztec/p2p 0.0.0-test.0 → 0.0.1-commit.001888fc

package/src/mem_pools/tx_pool/tx_pool_test_suite.ts

@@ -1,7 +1,8 @@
+import { BlockNumber } from '@aztec/foundation/branded-types';
 import { unfreeze } from '@aztec/foundation/types';
 import { GasFees } from '@aztec/stdlib/gas';
 import { mockTx } from '@aztec/stdlib/testing';
-import type { Tx } from '@aztec/stdlib/tx';
+import { BlockHeader, GlobalVariables, type Tx } from '@aztec/stdlib/tx';
 
 import type { TxPool } from './tx_pool.js';
 
@@ -12,79 +13,123 @@ import type { TxPool } from './tx_pool.js';
 export function describeTxPool(getTxPool: () => TxPool) {
   let pool: TxPool;
 
+  const minedBlockHeader = BlockHeader.empty({
+    globalVariables: GlobalVariables.empty({ blockNumber: BlockNumber(1), timestamp: 0n }),
+  });
+
   beforeEach(() => {
     pool = getTxPool();
   });
 
-  it('Adds txs to the pool as pending', async () => {
-    const tx1 = await mockTx();
+  afterEach(() => {
+    pool.removeAllListeners('txs-added');
+  });
+
+  it('adds txs to the pool as pending', async () => {
+    const tx1 = await mockTx(1);
 
     await pool.addTxs([tx1]);
-    const poolTx = await pool.getTxByHash(await tx1.getTxHash());
-    expect(await poolTx!.getTxHash()).toEqual(await tx1.getTxHash());
-    await expect(pool.getTxStatus(await tx1.getTxHash())).resolves.toEqual('pending');
-    await expect(pool.getPendingTxHashes()).resolves.toEqual([await tx1.getTxHash()]);
+    const poolTx = await pool.getTxByHash(tx1.getTxHash());
+    expect(poolTx!.getTxHash()).toEqual(tx1.getTxHash());
+    await expect(pool.getTxStatus(tx1.getTxHash())).resolves.toEqual('pending');
+    await expect(pool.getPendingTxHashes()).resolves.toEqual([tx1.getTxHash()]);
+    await expect(pool.getPendingTxCount()).resolves.toEqual(1);
   });
 
-  it('Removes txs from the pool', async () => {
-    const tx1 = await mockTx();
+  it('emits txs-added event with new txs', async () => {
+    const tx1 = await mockTx(1); // existing and pending
+    const tx2 = await mockTx(2); // mined but not known
+    const tx3 = await mockTx(3); // brand new
 
     await pool.addTxs([tx1]);
-    await pool.deleteTxs([await tx1.getTxHash()]);
+    await pool.markAsMined([tx2.getTxHash()], minedBlockHeader);
+
+    let txsFromEvent: Tx[] | undefined = undefined;
+    pool.once('txs-added', ({ txs }) => {
+      txsFromEvent = txs;
+    });
 
-    await expect(pool.getTxByHash(await tx1.getTxHash())).resolves.toBeFalsy();
-    await expect(pool.getTxStatus(await tx1.getTxHash())).resolves.toBeUndefined();
+    await pool.addTxs([tx1, tx2, tx3]);
+    expect(txsFromEvent).toBeDefined();
+    expect(txsFromEvent).toHaveLength(2);
+    const eventHashes = txsFromEvent!.map(tx => tx.getTxHash());
+    expect(eventHashes).toEqual(expect.arrayContaining([tx2.getTxHash(), tx3.getTxHash()]));
   });
 
-  it('Marks txs as mined', async () => {
+  it('removes txs from the pool', async () => {
+    const pendingTx = await mockTx(1);
+    const minedTx = await mockTx(2);
+
+    await pool.addTxs([pendingTx, minedTx]);
+    await pool.markAsMined([minedTx.getTxHash()], minedBlockHeader);
+
+    // Delete a pending tx - should be permanently deleted
+    await pool.deleteTxs([pendingTx.getTxHash()]);
+    await expect(pool.getTxByHash(pendingTx.getTxHash())).resolves.toBeUndefined();
+    await expect(pool.getTxStatus(pendingTx.getTxHash())).resolves.toBeUndefined();
+
+    // Delete a mined tx - should be soft-deleted (still in storage)
+    await pool.deleteTxs([minedTx.getTxHash()]);
+    await expect(pool.getTxByHash(minedTx.getTxHash())).resolves.toBeDefined();
+    await expect(pool.getTxStatus(minedTx.getTxHash())).resolves.toEqual('deleted');
+    await expect(pool.getMinedTxHashes()).resolves.toEqual([]);
+
+    await expect(pool.getPendingTxCount()).resolves.toEqual(0);
+  });
+
+  it('marks txs as mined', async () => {
     const tx1 = await mockTx(1);
     const tx2 = await mockTx(2);
 
     await pool.addTxs([tx1, tx2]);
-    await pool.markAsMined([await tx1.getTxHash()], 1);
+    await pool.markAsMined([tx1.getTxHash()], minedBlockHeader);
 
-    await expect(pool.getTxByHash(await tx1.getTxHash())).resolves.toEqual(tx1);
-    await expect(pool.getTxStatus(await tx1.getTxHash())).resolves.toEqual('mined');
-    await expect(pool.getMinedTxHashes()).resolves.toEqual([[await tx1.getTxHash(), 1]]);
-    await expect(pool.getPendingTxHashes()).resolves.toEqual([await tx2.getTxHash()]);
+    const retrievedTx = await pool.getTxByHash(tx1.getTxHash());
+    expect(retrievedTx?.getTxHash()).toEqual(tx1.getTxHash());
+    await expect(pool.getTxStatus(tx1.getTxHash())).resolves.toEqual('mined');
+    await expect(pool.getMinedTxHashes()).resolves.toEqual([[tx1.getTxHash(), 1]]);
+    await expect(pool.getPendingTxHashes()).resolves.toEqual([tx2.getTxHash()]);
+    await expect(pool.getPendingTxCount()).resolves.toEqual(1);
   });
 
-  it('Marks txs as pending after being mined', async () => {
+  it('marks txs as pending after being mined', async () => {
     const tx1 = await mockTx(1);
     const tx2 = await mockTx(2);
 
     await pool.addTxs([tx1, tx2]);
-    await pool.markAsMined([await tx1.getTxHash()], 1);
+    await pool.markAsMined([tx1.getTxHash()], minedBlockHeader);
 
-    await pool.markMinedAsPending([await tx1.getTxHash()]);
+    await pool.markMinedAsPending([tx1.getTxHash()], BlockNumber(1));
     await expect(pool.getMinedTxHashes()).resolves.toEqual([]);
     const pending = await pool.getPendingTxHashes();
     expect(pending).toHaveLength(2);
-    expect(pending).toEqual(expect.arrayContaining([await tx1.getTxHash(), await tx2.getTxHash()]));
+    expect(pending).toEqual(expect.arrayContaining([tx1.getTxHash(), tx2.getTxHash()]));
+    await expect(pool.getPendingTxCount()).resolves.toEqual(2);
   });
 
-  it('Only marks txs as pending if they are known', async () => {
+  it('only marks txs as pending if they are known', async () => {
     const tx1 = await mockTx(1);
     // simulate a situation where not all peers have all the txs
     const tx2 = await mockTx(2);
-    const someTxHashThatThisPeerDidNotSee = await tx2.getTxHash();
+    const someTxHashThatThisPeerDidNotSee = tx2.getTxHash();
     await pool.addTxs([tx1]);
     // this peer knows that tx2 was mined, but it does not have the tx object
-    await pool.markAsMined([await tx1.getTxHash(), someTxHashThatThisPeerDidNotSee], 1);
+    await pool.markAsMined([tx1.getTxHash(), someTxHashThatThisPeerDidNotSee], minedBlockHeader);
     expect(await pool.getMinedTxHashes()).toEqual(
       expect.arrayContaining([
-        [await tx1.getTxHash(), 1],
+        [tx1.getTxHash(), 1],
         [someTxHashThatThisPeerDidNotSee, 1],
       ]),
     );
 
     // reorg: both txs should now become available again
-    await pool.markMinedAsPending([await tx1.getTxHash(), someTxHashThatThisPeerDidNotSee]);
+    await pool.markMinedAsPending([tx1.getTxHash(), someTxHashThatThisPeerDidNotSee], BlockNumber(1));
     await expect(pool.getMinedTxHashes()).resolves.toEqual([]);
-    await expect(pool.getPendingTxHashes()).resolves.toEqual([await tx1.getTxHash()]); // tx2 is not in the pool
+    await expect(pool.getPendingTxHashes()).resolves.toEqual([tx1.getTxHash()]); // tx2 is not in the pool
+    await expect(pool.getPendingTxCount()).resolves.toEqual(1);
   });
 
-  it('Returns all transactions in the pool', async () => {
+  it('returns all transactions in the pool', async () => {
     const tx1 = await mockTx(1);
     const tx2 = await mockTx(2);
     const tx3 = await mockTx(3);
@@ -93,10 +138,12 @@ export function describeTxPool(getTxPool: () => TxPool) {
 
     const poolTxs = await pool.getAllTxs();
     expect(poolTxs).toHaveLength(3);
-    expect(poolTxs).toEqual(expect.arrayContaining([tx1, tx2, tx3]));
+    const poolHashes = poolTxs.map(tx => tx.getTxHash());
+    expect(poolHashes).toEqual(expect.arrayContaining([tx1.getTxHash(), tx2.getTxHash(), tx3.getTxHash()]));
+    await expect(pool.getPendingTxCount()).resolves.toEqual(3);
   });
 
-  it('Returns all txHashes in the pool', async () => {
+  it('returns all txHashes in the pool', async () => {
     const tx1 = await mockTx(1);
     const tx2 = await mockTx(2);
     const tx3 = await mockTx(3);
@@ -104,15 +151,62 @@ export function describeTxPool(getTxPool: () => TxPool) {
     await pool.addTxs([tx1, tx2, tx3]);
 
     const poolTxHashes = await pool.getAllTxHashes();
+    const expectedHashes = [tx1, tx2, tx3].map(tx => tx.getTxHash());
     expect(poolTxHashes).toHaveLength(3);
-    expect(poolTxHashes).toEqual(
-      expect.arrayContaining([await tx1.getTxHash(), await tx2.getTxHash(), await tx3.getTxHash()]),
-    );
+    expect(poolTxHashes).toEqual(expect.arrayContaining(expectedHashes));
+    await expect(pool.getPendingTxCount()).resolves.toEqual(3);
   });
 
-  it('Returns pending tx hashes sorted by priority', async () => {
+  it('returns txs by their hash', async () => {
+    const tx1 = await mockTx(1);
+    const tx2 = await mockTx(2);
+    const tx3 = await mockTx(3);
+
+    await pool.addTxs([tx1, tx2, tx3]);
+
+    const requestedTxs = await pool.getTxsByHash([tx1.getTxHash(), tx3.getTxHash()]);
+    expect(requestedTxs).toHaveLength(2);
+    const requestedHashes = requestedTxs.map(tx => tx!.getTxHash());
+    expect(requestedHashes).toEqual(expect.arrayContaining([tx1.getTxHash(), tx3.getTxHash()]));
+  });
+
+  it('returns a large number of transactions by their hash', async () => {
+    const numTxs = 1_000;
+    const txs = await Promise.all(Array.from({ length: numTxs }, (_, i) => mockTx(i)));
+    const hashes = txs.map(tx => tx.getTxHash());
+    await pool.addTxs(txs);
+    const requestedTxs = await pool.getTxsByHash(hashes);
+    expect(requestedTxs).toHaveLength(numTxs);
+    const requestedHashes = requestedTxs.map(tx => tx!.getTxHash());
+    expect(requestedHashes).toEqual(expect.arrayContaining(hashes));
+  });
+
+  it('returns whether or not txs exist', async () => {
+    const tx1 = await mockTx(1);
+    const tx2 = await mockTx(2);
+    const tx3 = await mockTx(3);
+
+    await pool.addTxs([tx1, tx2, tx3]);
+
+    const tx4 = await mockTx(4);
+    const tx5 = await mockTx(5);
+
+    const availability = await pool.hasTxs([
+      tx1.getTxHash(),
+      tx2.getTxHash(),
+      tx3.getTxHash(),
+      tx4.getTxHash(),
+      tx5.getTxHash(),
+    ]);
+    expect(availability).toHaveLength(5);
+    expect(availability).toEqual(expect.arrayContaining([true, true, true, false, false]));
+  });
+
+  it('returns pending tx hashes sorted by priority', async () => {
     const withPriorityFee = (tx: Tx, fee: number) => {
-      unfreeze(tx.data.constants.txContext.gasSettings).maxPriorityFeesPerGas = new GasFees(fee, fee);
+      const gs = unfreeze(tx.data.constants.txContext.gasSettings);
+      gs.maxPriorityFeesPerGas = new GasFees(fee, fee);
+      gs.maxFeesPerGas = new GasFees(fee, fee);
       return tx;
     };
 
@@ -125,6 +219,103 @@ export function describeTxPool(getTxPool: () => TxPool) {
 
     const poolTxHashes = await pool.getPendingTxHashes();
     expect(poolTxHashes).toHaveLength(4);
-    expect(poolTxHashes).toEqual(await Promise.all([tx4, tx1, tx3, tx2].map(tx => tx.getTxHash())));
+    expect(poolTxHashes).toEqual([tx4, tx1, tx3, tx2].map(tx => tx.getTxHash()));
+  });
+
+  describe('soft-delete', () => {
+    it('soft-deletes mined txs and keeps them in storage', async () => {
+      const txs = await Promise.all([mockTx(1), mockTx(2), mockTx(3)]);
+      await pool.addTxs(txs);
+
+      // Mark first tx as mined
+      await pool.markAsMined([txs[0].getTxHash()], minedBlockHeader);
+
+      // Verify initial state
+      await expect(pool.getPendingTxCount()).resolves.toBe(2);
+      await expect(pool.getTxByHash(txs[0].getTxHash())).resolves.toBeDefined();
+      await expect(pool.getTxByHash(txs[1].getTxHash())).resolves.toBeDefined();
+
+      // Delete mined tx - should be soft-deleted
+      await pool.deleteTxs([txs[0].getTxHash()]);
+
+      // Delete pending tx - should be permanently deleted
+      await pool.deleteTxs([txs[1].getTxHash()]);
+
+      // Verify mined tx still exists in storage but has 'deleted' status
+      await expect(pool.getTxByHash(txs[0].getTxHash())).resolves.toBeDefined();
+      await expect(pool.getTxStatus(txs[0].getTxHash())).resolves.toEqual('deleted');
+
+      // Verify pending tx is permanently deleted
+      await expect(pool.getTxByHash(txs[1].getTxHash())).resolves.toBeUndefined();
+      await expect(pool.getTxStatus(txs[1].getTxHash())).resolves.toBeUndefined();
+
+      // Verify remaining pending count
+      await expect(pool.getPendingTxCount()).resolves.toBe(1);
+
+      // Verify pending hashes don't include deleted txs
+      const pendingHashes = await pool.getPendingTxHashes();
+      expect(pendingHashes).toHaveLength(1);
+      expect(pendingHashes.map(h => h.toString())).toContain(txs[2].getTxHash().toString());
+    });
+
+    it('cleans up old deleted mined transactions', async () => {
+      const txs = await Promise.all([mockTx(1), mockTx(2), mockTx(3)]);
+      await pool.addTxs(txs);
+
+      // Mark first two as mined in block 1
+      await pool.markAsMined([txs[0].getTxHash(), txs[1].getTxHash()], minedBlockHeader);
+
+      // Soft-delete mined transactions
+      await pool.deleteTxs([txs[0].getTxHash(), txs[1].getTxHash()]);
+
+      // Clean up deleted mined txs from block 1 and earlier
+      const deletedCount = await pool.cleanupDeletedMinedTxs(BlockNumber(1));
+
+      // Verify old transactions are permanently deleted
+      expect(deletedCount).toBe(2);
+      await expect(pool.getTxByHash(txs[0].getTxHash())).resolves.toBeUndefined();
+      await expect(pool.getTxByHash(txs[1].getTxHash())).resolves.toBeUndefined();
+      await expect(pool.getTxByHash(txs[2].getTxHash())).resolves.toBeDefined();
+    });
+
+    it('does not clean up recent deleted mined transactions', async () => {
+      const txs = await Promise.all([mockTx(1), mockTx(2)]);
+      await pool.addTxs(txs);
+
+      // Mark as mined in block 2
+      const laterBlockHeader = BlockHeader.empty({
+        globalVariables: GlobalVariables.empty({ blockNumber: BlockNumber(2), timestamp: 0n }),
+      });
+      await pool.markAsMined([txs[0].getTxHash()], laterBlockHeader);
+
+      // Soft-delete a mined transaction
+      await pool.deleteTxs([txs[0].getTxHash()]);
+
+      // Try to clean up with block 1 (before the mined block)
+      const deletedCount = await pool.cleanupDeletedMinedTxs(BlockNumber(1));
+
+      // Verify no transactions were cleaned up
+      expect(deletedCount).toBe(0);
+      await expect(pool.getTxByHash(txs[0].getTxHash())).resolves.toBeDefined();
+    });
+
+    it('restores deleted mined tx when it is mined again', async () => {
+      const tx = await mockTx(1);
+      await pool.addTxs([tx]);
+
+      // Mark as mined
+      await pool.markAsMined([tx.getTxHash()], minedBlockHeader);
+
+      // Soft-delete it
+      await pool.deleteTxs([tx.getTxHash()]);
+      await expect(pool.getTxStatus(tx.getTxHash())).resolves.toEqual('deleted');
+
+      // Mark as mined again (e.g., after a reorg)
+      await pool.markAsMined([tx.getTxHash()], minedBlockHeader);
+
+      // Should be back to mined status
+      await expect(pool.getTxStatus(tx.getTxHash())).resolves.toEqual('mined');
+      await expect(pool.getTxByHash(tx.getTxHash())).resolves.toBeDefined();
+    });
   });
 }

package/src/mem_pools/tx_pool_v2/README.md

@@ -0,0 +1,283 @@
+# 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
+        │ / eviction / failed exec            │ (validation failure)
+        ▼                                     ▼
+┌─────────────────────────────────────┐  ┌─────────────────────────────────────┐
+│       SLOT-SOFT-DELETED             │  │       PRUNE-SOFT-DELETED            │
+│  (kept in DB until next slot)       │  │  (kept in DB until finalized)       │
+└─────────────────────────────────────┘  └─────────────────────────────────────┘
+        │                                        │
+        │ prepareForSlot()                       │ handleFinalizedBlock()
+        │ (slot advanced)                        │ (mined block finalized)
+        ▼                                        ▼
+┌─────────────────────────────────────┐  ┌─────────────────────────────────────┐
+│          HARD-DELETED               │  │          HARD-DELETED               │
+│   (permanently removed from DB)     │  │   (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 all transaction deletions in the pool with two soft-deletion mechanisms:
+- **Slot-based**: Non-pruned txs are kept in DB until the next slot, allowing other nodes to fetch them via reqresp
+- **Prune-based**: Txs from pruned blocks are kept in DB until their original mined block is finalized
+
+All deletions go through `DeletedPool.deleteTx()`, which routes to the appropriate path based on whether the tx is tracked as being from a pruned block.
+
+### 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
+- `expirationTimestamp`: 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 (slot-based or prune-based, evicted but kept in DB)
+- `pending` otherwise
+
+## Soft Deletion
+
+Deleted transactions are kept in the database for a grace period before being permanently removed. There are two soft-deletion mechanisms:
+
+### Slot-Based Soft Deletion
+
+When a transaction is deleted from the pool (eviction, validation failure, failed execution) and is **not** from a pruned block, it is "slot-soft-deleted":
+
+1. **Soft Delete**: The tx is removed from indices but kept in the database, tagged with the current slot number
+2. **Retrieval**: Slot-soft-deleted txs can still be retrieved via `getTxByHash` and return status `'deleted'` from `getTxStatus`
+3. **Hard Delete**: When `prepareForSlot` advances to a new slot, txs deleted in earlier slots are permanently removed
+4. **Re-addition**: If a slot-soft-deleted tx is re-added to the pool, the slot-deleted tracking is cleared
+
+This allows other nodes to still fetch recently-deleted transactions via reqresp during the current slot.
+
+### Prune-Based Soft Deletion
+
+When a chain reorganization occurs, transactions that were mined in pruned blocks are handled with longer retention:
+
+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 "prune-soft-deleted" - removed from indices but kept in the database
+3. **Retrieval**: Prune-soft-deleted txs can still be retrieved via `getTxByHash` 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
+5. **Re-addition**: If a prune-soft-deleted tx is re-added, the `softDeleted` flag is reset to `false` but the prune tracking is preserved, so a subsequent deletion still uses the prune path
+
+Prune-soft-deleted transactions are **not** affected by slot cleanup - they survive across slot boundaries until finalized.
+
+**Prune example:**
+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 prune-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
+
+### Hydration
+
+On node restart, slot-soft-deleted transactions are immediately hard-deleted (they are stale by definition). Prune-soft-deleted transactions are loaded from the database and tracked normally.
+
+## 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. For RPC submissions, a configurable price bump percentage is required. |
+| `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
+});
+```
+
+### Price Bump (RPC Transaction Replacement)
+
+When a transaction is submitted via RPC and clashes on nullifiers with an existing pool transaction, the incoming tx must pay at least `priceBumpPercentage`% more in priority fee (i.e. `>= existingFee + existingFee * bump / 100`) to replace it. This prevents spam via small fee increments. The same bump applies when the pool is full and the incoming tx needs to evict the lowest-priority tx.
+
+- **Env var**: `P2P_RPC_PRICE_BUMP_PERCENTAGE` (default: 10)
+- **Scope**: RPC submissions only. P2P gossip uses `comparePriority` (fee + hash tiebreaker) with no bump.
+- Even with a 0% bump, a replacement tx must pay at least 1 unit more than the existing fee.
+
+## 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';