@aztec/p2p 0.0.1-commit.aada20e3 → 0.0.1-commit.b1c78909e

package/src/mem_pools/attestation_pool/index.ts

@@ -1,2 +1,9 @@
-export * from './attestation_pool.js';
-export * from './memory_attestation_pool.js';
+export {
+  AttestationPool,
+  type AttestationPoolApi,
+  type TryAddResult,
+  createTestAttestationPool,
+  MAX_CHECKPOINT_PROPOSALS_PER_SLOT,
+  MAX_BLOCK_PROPOSALS_PER_POSITION,
+  MAX_ATTESTATIONS_PER_SLOT_AND_SIGNER,
+} from './attestation_pool.js';

package/src/mem_pools/attestation_pool/mocks.ts

@@ -34,9 +34,10 @@ export const mockCheckpointAttestation = (
   slot: number = 0,
   archive: Fr = Fr.random(),
   header?: CheckpointHeader,
+  feeAssetPriceModifier: bigint = 0n,
 ): CheckpointAttestation => {
   header = header ?? CheckpointHeader.random({ slotNumber: SlotNumber(slot) });
-  const payload = new ConsensusPayload(header, archive);
+  const payload = new ConsensusPayload(header, archive, feeAssetPriceModifier);
 
   const attestationHash = getHashedSignaturePayloadEthSignedMessage(
     payload,

package/src/mem_pools/index.ts

@@ -1,3 +1,6 @@
-export { type AttestationPool } from './attestation_pool/attestation_pool.js';
+export { AttestationPool, type AttestationPoolApi } from './attestation_pool/attestation_pool.js';
 export { type MemPools } from './interface.js';
+// Old TxPool exports - kept temporarily for external consumers
 export { type TxPool } from './tx_pool/tx_pool.js';
+// New TxPoolV2 exports
+export { type TxPoolV2, type TxPoolV2Config, type TxPoolV2Events, type AddTxsResult } from './tx_pool_v2/index.js';

package/src/mem_pools/instrumentation.ts

@@ -73,7 +73,7 @@ export class PoolInstrumentation<PoolObject extends Gossipable> {
   private defaultAttributes;
   private meter: Meter;
 
-  private txAddedTimestamp: Map<bigint, number> = new Map<bigint, number>();
+  private mempoolItemAddedTimestamp: Map<bigint | string, number> = new Map<bigint | string, number>();
 
   constructor(
     telemetry: TelemetryClient,
@@ -114,22 +114,26 @@ export class PoolInstrumentation<PoolObject extends Gossipable> {
   }
 
   public transactionsAdded(transactions: Tx[]) {
-    const timestamp = Date.now();
-    for (const transaction of transactions) {
-      this.txAddedTimestamp.set(transaction.txHash.toBigInt(), timestamp);
-    }
+    transactions.forEach(tx => this.trackMempoolItemAdded(tx.txHash.toBigInt()));
   }
 
   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);
-        }
+      this.trackMempoolItemRemoved(BigInt(hash));
+    }
+  }
+
+  public trackMempoolItemAdded(key: bigint | string): void {
+    this.mempoolItemAddedTimestamp.set(key, Date.now());
+  }
+
+  public trackMempoolItemRemoved(key: bigint | string): void {
+    const timestamp = Date.now();
+    const addedAt = this.mempoolItemAddedTimestamp.get(key);
+    if (addedAt !== undefined) {
+      this.mempoolItemAddedTimestamp.delete(key);
+      if (addedAt < timestamp) {
+        this.minedDelay.record(timestamp - addedAt);
       }
     }
   }

package/src/mem_pools/interface.ts

@@ -1,10 +1,10 @@
-import type { AttestationPool } from './attestation_pool/attestation_pool.js';
-import type { TxPool } from './tx_pool/tx_pool.js';
+import type { AttestationPoolApi } from './attestation_pool/attestation_pool.js';
+import type { TxPoolV2 } from './tx_pool_v2/interfaces.js';
 
 /**
  * A interface the combines all mempools
  */
 export type MemPools = {
-  txPool: TxPool;
-  attestationPool: AttestationPool;
+  txPool: TxPoolV2;
+  attestationPool: AttestationPoolApi;
 };

package/src/mem_pools/tx_pool/README.md

@@ -213,7 +213,7 @@ The [`EvictionManager`](eviction/eviction_manager.ts) coordinates eviction by:
 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
+- Expired transactions: Txs with `expirationTimestamp` ≤ mined block timestamp
 
 #### 2. `InvalidTxsAfterReorgRule`
 

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

@@ -68,10 +68,10 @@ export class InvalidTxsAfterMiningRule implements EvictionRule {
         }
 
         // Evict pending txs with an expiration timestamp less than or equal to the mined block timestamp
-        const includeByTimestamp = tx.data.includeByTimestamp;
-        if (includeByTimestamp <= timestamp) {
+        const expirationTimestamp = tx.data.expirationTimestamp;
+        if (expirationTimestamp <= timestamp) {
           this.log.verbose(
-            `Evicting tx ${txHash} from pool due to the tx being expired (includeByTimestamp: ${includeByTimestamp}, mined block timestamp: ${timestamp})`,
+            `Evicting tx ${txHash} from pool due to the tx being expired (expirationTimestamp: ${expirationTimestamp}, mined block timestamp: ${timestamp})`,
           );
           txsToEvict.push(txHash);
           continue;

package/src/mem_pools/tx_pool/priority.ts

@@ -1,3 +1,4 @@
+import { minBigint } from '@aztec/foundation/bigint';
 import { Buffer32 } from '@aztec/foundation/buffer';
 import type { Tx } from '@aztec/stdlib/tx';
 
@@ -11,10 +12,12 @@ export function getPendingTxPriority(tx: Tx): string {
 }
 
 /**
- * Returns the priority of a tx.
+ * Returns the priority of a tx based on the priority fees, capped by the max fees per gas.
  */
 export function getTxPriorityFee(tx: Tx): bigint {
-  const priorityFees = tx.getGasSettings().maxPriorityFeesPerGas;
-  const totalFees = priorityFees.feePerDaGas + priorityFees.feePerL2Gas;
+  const { maxPriorityFeesPerGas: priorityFees, maxFeesPerGas } = tx.getGasSettings();
+  const totalFees =
+    minBigint(maxFeesPerGas.feePerDaGas, priorityFees.feePerDaGas) +
+    minBigint(maxFeesPerGas.feePerL2Gas, priorityFees.feePerL2Gas);
   return totalFees;
 }

package/src/mem_pools/tx_pool/tx_pool_test_suite.ts

@@ -204,7 +204,9 @@ export function describeTxPool(getTxPool: () => TxPool) {
 
   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;
     };
 

package/src/mem_pools/tx_pool_v2/README.md

@@ -28,13 +28,22 @@ TxPoolV2 manages transactions through a state machine with clear transitions:
 │              MINED                  │───────────────────┘
 │   (included in a block)             │  handlePrunedBlocks()
 └─────────────────────────────────────┘  (reorg)
-        │
-        │ handleFinalizedBlock()
-        ▼
-┌─────────────────────────────────────┐
-│             DELETED                 │
-│   (optionally archived)             │
-└─────────────────────────────────────┘
+        │                                     │
+        │ 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
@@ -52,17 +61,92 @@ Core implementation containing:
 - 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
-- `state`: Current state (pending, protected, mined)
-- `priorityFee`: For priority ordering
+- `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
-- `estimatedTxFee`: For balance calculations
-- `blockId`: Block info when mined
-- `protectedSlot`: Slot number when protected
+- `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
 
@@ -74,7 +158,7 @@ Checked before adding a transaction to the pending pool:
 
 | Rule | Purpose |
 |------|---------|
-| `NullifierConflictRule` | Handles transactions with conflicting nullifiers. Higher priority tx wins. |
+| `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. |
 
@@ -85,8 +169,8 @@ Run after events to clean up the pool:
 | Rule | Trigger | Purpose |
 |------|---------|---------|
 | `LowPriorityEvictionRule` | `txs_added` | Evicts lowest priority txs when pool exceeds limit. |
-| `FeePayerBalanceEvictionRule` | `block_mined` | Evicts txs when fee payer balance decreases. |
-| `InvalidTxsAfterMiningRule` | `block_mined` | Evicts pending txs with nullifiers that were just mined. |
+| `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
@@ -99,7 +183,7 @@ import { AztecKVTxPoolV2 } from './tx_pool_v2.js';
 const pool = new AztecKVTxPoolV2(txStore, archiveStore, {
   l2BlockSource: archiver,
   worldStateSynchronizer: worldState,
-  pendingTxValidator: validator,
+  createTxValidator: () => validator,
 });
 
 await pool.start();
@@ -149,6 +233,14 @@ await pool.updateConfig({
 });
 ```
 
+### 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
@@ -174,9 +266,12 @@ The archive uses FIFO eviction when `archivedTxLimit` is reached.
 ## Testing
 
 ```bash
-# Unit tests (131 tests)
+# 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
 

package/src/mem_pools/tx_pool_v2/deleted_pool.ts

@@ -0,0 +1,321 @@
+import { BlockNumber, SlotNumber } from '@aztec/foundation/branded-types';
+import type { Logger } from '@aztec/foundation/log';
+import type { AztecAsyncKVStore, AztecAsyncMap, AztecAsyncSet } from '@aztec/kv-store';
+
+/**
+ * State stored for each transaction from a pruned block.
+ */
+type DeletedTxState = {
+  /** Block number in which the transaction was originally mined (before being un-mined by a prune) */
+  minedAtBlock: BlockNumber;
+  /** Whether the transaction has been soft-deleted (removed from indices) */
+  softDeleted: boolean;
+};
+
+/**
+ * Serializes DeletedTxState to a Buffer.
+ * Format: 4 bytes for blockNumber (uint32) + 1 byte for softDeleted (0 or 1)
+ */
+function serializeState(state: DeletedTxState): Buffer {
+  const buffer = Buffer.alloc(5);
+  buffer.writeUInt32BE(Number(state.minedAtBlock), 0);
+  buffer.writeUInt8(state.softDeleted ? 1 : 0, 4);
+  return buffer;
+}
+
+/**
+ * Deserializes a Buffer to DeletedTxState.
+ */
+function deserializeState(buffer: Buffer): DeletedTxState {
+  return {
+    minedAtBlock: BlockNumber(buffer.readUInt32BE(0)),
+    softDeleted: buffer.readUInt8(4) === 1,
+  };
+}
+
+/**
+ * Manages all transaction deletions in the pool.
+ *
+ * When a chain prune (reorg) happens, transactions from pruned blocks are tracked here.
+ * This class is responsible for ALL deletion decisions:
+ *
+ * - Transactions from pruned blocks are "prune-soft-deleted" - removed from indices but kept
+ *   in the database for later re-execution until their mined block is finalized
+ * - Transactions NOT from pruned blocks are "slot-soft-deleted" - kept in the database
+ *   until the next slot, so other nodes can still fetch them via reqresp
+ *
+ * When a block is finalized, prune-soft-deleted transactions that were originally mined at or
+ * before that block number are permanently (hard) deleted. Slot-soft-deleted transactions
+ * are hard-deleted when `prepareForSlot` advances to a new slot.
+ */
+export class DeletedPool {
+  /** Persisted map: txHash -> DeletedTxState (serialized) - for prune-based soft deletions */
+  #deletedTxsDB: AztecAsyncMap<string, Buffer>;
+
+  /** Reference to the main txs database for hard deletion */
+  #txsDB: AztecAsyncMap<string, Buffer>;
+
+  /** In-memory state for transactions from pruned blocks */
+  #state: Map<string, DeletedTxState> = new Map();
+
+  /** In-memory tracking: txHash -> slot at which the tx was deleted */
+  #slotDeletedTxs: Map<string, SlotNumber> = new Map();
+
+  /** Persisted set tracking which txs are slot-deleted, for hydration cleanup. */
+  #slotDeletedDB: AztecAsyncSet<string>;
+
+  /** Current slot number, updated by cleanupSlotDeleted */
+  #currentSlot: SlotNumber = SlotNumber(0);
+
+  #log: Logger;
+
+  constructor(store: AztecAsyncKVStore, txsDB: AztecAsyncMap<string, Buffer>, log: Logger) {
+    this.#deletedTxsDB = store.openMap('deleted_txs');
+    this.#slotDeletedDB = store.openSet('slot_deleted_txs');
+    this.#txsDB = txsDB;
+    this.#log = log;
+  }
+
+  /**
+   * Loads state from the database on startup.
+   * Slot-deleted txs are stale after restart and are immediately hard-deleted.
+   */
+  async hydrateFromDatabase(): Promise<void> {
+    let prunedCount = 0;
+    let softDeletedCount = 0;
+
+    for await (const [txHash, buffer] of this.#deletedTxsDB.entriesAsync()) {
+      const state = deserializeState(buffer);
+      this.#state.set(txHash, state);
+      prunedCount++;
+      if (state.softDeleted) {
+        softDeletedCount++;
+      }
+    }
+
+    if (prunedCount > 0 || softDeletedCount > 0) {
+      this.#log.info(`Loaded ${prunedCount} txs from pruned blocks, ${softDeletedCount} soft-deleted`);
+    }
+
+    // Slot-deleted txs are stale after restart - hard-delete them all
+    let slotDeletedCount = 0;
+    for await (const txHash of this.#slotDeletedDB.entriesAsync()) {
+      await this.#txsDB.delete(txHash);
+      await this.#slotDeletedDB.delete(txHash);
+      slotDeletedCount++;
+    }
+
+    if (slotDeletedCount > 0) {
+      this.#log.info(`Hard-deleted ${slotDeletedCount} stale slot-deleted txs on startup`);
+    }
+  }
+
+  /**
+   * Marks transactions as being from a pruned block.
+   * Called during handlePrunedBlocks for ALL transactions that were un-mined.
+   *
+   * If a tx was previously tracked (e.g., mined at block 4, pruned, re-mined at block 5,
+   * pruned again), updates to the higher block number. This ensures the tx is kept until
+   * its most recent mined block is finalized.
+   *
+   * @param txs - Array of {txHash, minedAtBlock} pairs, where minedAtBlock is the block
+   *              number in which the tx was mined before being un-mined
+   */
+  async markFromPrunedBlock(txs: { txHash: string; minedAtBlock: BlockNumber }[]): Promise<void> {
+    if (txs.length === 0) {
+      return;
+    }
+
+    let count = 0;
+    for (const { txHash, minedAtBlock } of txs) {
+      const existing = this.#state.get(txHash);
+      // Update if not tracked, or if this is a higher mined block (tx was re-mined then pruned again)
+      if (existing === undefined || minedAtBlock > existing.minedAtBlock) {
+        const state: DeletedTxState = {
+          minedAtBlock,
+          softDeleted: existing?.softDeleted ?? false,
+        };
+        this.#state.set(txHash, state);
+        await this.#deletedTxsDB.set(txHash, serializeState(state));
+        count++;
+      }
+    }
+
+    if (count > 0) {
+      this.#log.info(`Marked ${count} transactions from pruned blocks`);
+    }
+  }
+
+  /**
+   * Deletes a transaction. This is the single entry point for ALL deletions.
+   * The tx is always soft-deleted (kept in DB):
+   *
+   * - If the tx is from a pruned block: prune-soft-delete (kept until finalized)
+   * - If the tx is NOT from a pruned block: slot-soft-delete (kept until next slot)
+   */
+  async deleteTx(txHash: string): Promise<void> {
+    const existing = this.#state.get(txHash);
+    if (existing !== undefined) {
+      // Prune-soft-delete - keep in DB until finalized
+      const state: DeletedTxState = {
+        minedAtBlock: existing.minedAtBlock,
+        softDeleted: true,
+      };
+      this.#state.set(txHash, state);
+      await this.#deletedTxsDB.set(txHash, serializeState(state));
+    } else {
+      // Slot-soft-delete - keep in DB until next slot
+      this.#slotDeletedTxs.set(txHash, this.#currentSlot);
+      await this.#slotDeletedDB.add(txHash);
+    }
+  }
+
+  /**
+   * Clears tracking for a transaction if it re-mines at a block number >= the tracked minedAtBlock.
+   *
+   * When a tx re-mines at a higher (or equal) block, the old high-water mark is no longer needed:
+   * any future prune would re-add the tx with an even higher block number. Clearing keeps
+   * DeletedPool consistent — only txs that are actually un-mined should be tracked here.
+   *
+   * When a tx re-mines at a lower block, we must preserve the existing entry to retain
+   * the high-water mark for re-execution purposes.
+   */
+  async clearIfMinedHigher(txHash: string, minedAtBlock: BlockNumber): Promise<void> {
+    const existing = this.#state.get(txHash);
+    if (existing !== undefined && minedAtBlock >= existing.minedAtBlock) {
+      this.#state.delete(txHash);
+      await this.#deletedTxsDB.delete(txHash);
+      this.#log.debug(
+        `Cleared tracking for tx ${txHash}: re-mined at block ${minedAtBlock} (was ${existing.minedAtBlock})`,
+      );
+    }
+  }
+
+  /**
+   * Checks if a transaction is from a pruned block.
+   */
+  isFromPrunedBlock(txHash: string): boolean {
+    return this.#state.has(txHash);
+  }
+
+  /**
+   * Checks if a transaction is soft-deleted (either prune-based or slot-based).
+   */
+  isSoftDeleted(txHash: string): boolean {
+    return (this.#state.get(txHash)?.softDeleted ?? false) || this.#slotDeletedTxs.has(txHash);
+  }
+
+  /**
+   * Gets the block number in which a transaction was originally mined.
+   */
+  getMinedAtBlock(txHash: string): BlockNumber | undefined {
+    return this.#state.get(txHash)?.minedAtBlock;
+  }
+
+  /**
+   * Finalizes transactions when a block is finalized.
+   * Hard-deletes transactions that were originally mined at or before the finalized block.
+   *
+   * @returns The hashes of transactions that were hard-deleted
+   */
+  async finalizeBlock(finalizedBlockNumber: BlockNumber): Promise<string[]> {
+    const toHardDelete: string[] = [];
+    for (const [txHash, state] of this.#state) {
+      if (state.softDeleted && state.minedAtBlock <= finalizedBlockNumber) {
+        toHardDelete.push(txHash);
+      }
+    }
+
+    if (toHardDelete.length === 0) {
+      return [];
+    }
+
+    // Hard-delete from all stores
+    for (const txHash of toHardDelete) {
+      this.#state.delete(txHash);
+      await this.#deletedTxsDB.delete(txHash);
+      await this.#txsDB.delete(txHash);
+    }
+
+    this.#log.debug(`Finalized ${toHardDelete.length} txs from pruned blocks at block ${finalizedBlockNumber}`, {
+      txHashes: toHardDelete,
+    });
+    return toHardDelete;
+  }
+
+  /**
+   * Cleans up slot-deleted transactions from previous slots.
+   * Called at the start of prepareForSlot. Updates #currentSlot and hard-deletes
+   * any txs that were deleted in an earlier slot.
+   */
+  async cleanupSlotDeleted(currentSlot: SlotNumber): Promise<void> {
+    const previousSlot = this.#currentSlot;
+    this.#currentSlot = currentSlot;
+
+    const toHardDelete: string[] = [];
+    for (const [txHash, deletedAtSlot] of this.#slotDeletedTxs) {
+      if (deletedAtSlot < currentSlot) {
+        toHardDelete.push(txHash);
+      }
+    }
+
+    if (toHardDelete.length === 0) {
+      return;
+    }
+
+    for (const txHash of toHardDelete) {
+      this.#slotDeletedTxs.delete(txHash);
+      await this.#slotDeletedDB.delete(txHash);
+      await this.#txsDB.delete(txHash);
+    }
+
+    this.#log.debug(
+      `Cleaned up ${toHardDelete.length} slot-deleted txs from slot ${previousSlot} (now slot ${currentSlot})`,
+      { txHashes: toHardDelete },
+    );
+  }
+
+  /**
+   * Clears soft-deletion status for a transaction being re-added to the pool.
+   * Removes slot-deleted tracking entirely, and resets the prune-soft-deleted flag
+   * while preserving the prune tracking itself (so a subsequent delete still uses
+   * the prune path).
+   */
+  async clearSoftDeleted(txHash: string): Promise<void> {
+    if (this.#slotDeletedTxs.has(txHash)) {
+      this.#slotDeletedTxs.delete(txHash);
+      await this.#slotDeletedDB.delete(txHash);
+    }
+    const existing = this.#state.get(txHash);
+    if (existing?.softDeleted) {
+      const state: DeletedTxState = { minedAtBlock: existing.minedAtBlock, softDeleted: false };
+      this.#state.set(txHash, state);
+      await this.#deletedTxsDB.set(txHash, serializeState(state));
+    }
+  }
+
+  /**
+   * Gets the count of transactions from pruned blocks.
+   */
+  getCount(): number {
+    return this.#state.size;
+  }
+
+  /** Gets the count of soft-deleted transactions (both prune-based and slot-based). */
+  getSoftDeletedCount(): number {
+    let count = this.#slotDeletedTxs.size;
+    for (const state of this.#state.values()) {
+      if (state.softDeleted) {
+        count++;
+      }
+    }
+    return count;
+  }
+
+  /**
+   * Gets all transaction hashes from pruned blocks.
+   */
+  getPrunedTxHashes(): string[] {
+    return Array.from(this.#state.keys());
+  }
+}