@aztec/p2p 0.0.1-commit.f2ce05ee → 0.0.1-commit.f8ca9b2f3

package/src/mem_pools/tx_pool_v2/README.md

@@ -28,13 +28,21 @@ 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
+        ▼                                     ▼
+┌─────────────────────────────────────┐  ┌─────────────────────────────────────┐
+│             DELETED                 │  │         SOFT-DELETED                │
+│   (hard-deleted or archived)        │  │   (kept in DB for debugging)        │
+└─────────────────────────────────────┘  └─────────────────────────────────────┘
+                                                  │
+                                                  │ handleFinalizedBlock()
+                                                  │ (mined block finalized)
+                                                  ▼
+                                         ┌─────────────────────────────────────┐
+                                         │          HARD-DELETED               │
+                                         │   (permanently removed from DB)     │
+                                         └─────────────────────────────────────┘
 ```
 
 ## Key Components
@@ -52,6 +60,16 @@ Core implementation containing:
 - 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:
@@ -68,8 +86,37 @@ Lightweight metadata stored alongside each transaction:
 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`):
@@ -120,7 +167,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();
@@ -195,9 +242,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,234 @@
+import { BlockNumber } from '@aztec/foundation/branded-types';
+import type { Logger } from '@aztec/foundation/log';
+import type { AztecAsyncKVStore, AztecAsyncMap } 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 "soft deleted" - removed from indices but kept
+ *   in the database for later re-execution
+ * - Transactions NOT from pruned blocks are "hard deleted" - completely removed from DB
+ *
+ * When a block is finalized, soft-deleted transactions that were originally mined at or
+ * before that block number are permanently (hard) deleted.
+ */
+export class DeletedPool {
+  /** Persisted map: txHash -> DeletedTxState (serialized) */
+  #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();
+
+  #log: Logger;
+
+  constructor(store: AztecAsyncKVStore, txsDB: AztecAsyncMap<string, Buffer>, log: Logger) {
+    this.#deletedTxsDB = store.openMap('deleted_txs');
+    this.#txsDB = txsDB;
+    this.#log = log;
+  }
+
+  /**
+   * Loads state from the database on startup.
+   */
+  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`);
+    }
+  }
+
+  /**
+   * 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.debug(`Marked ${count} transactions from pruned blocks`);
+    }
+  }
+
+  /**
+   * Deletes a transaction. This is the single entry point for ALL deletions.
+   *
+   * - If the tx is from a pruned block: soft-delete (keep in DB, mark as deleted)
+   * - If the tx is NOT from a pruned block: hard-delete (remove from DB)
+   *
+   * @returns 'soft' if soft-deleted, 'hard' if hard-deleted
+   */
+  async deleteTx(txHash: string): Promise<'soft' | 'hard'> {
+    const existing = this.#state.get(txHash);
+    if (existing !== undefined) {
+      // Soft delete - keep in DB
+      const state: DeletedTxState = {
+        minedAtBlock: existing.minedAtBlock,
+        softDeleted: true,
+      };
+      this.#state.set(txHash, state);
+      await this.#deletedTxsDB.set(txHash, serializeState(state));
+      return 'soft';
+    } else {
+      // Hard delete - remove from DB
+      await this.#txsDB.delete(txHash);
+      return 'hard';
+    }
+  }
+
+  /**
+   * 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.
+   */
+  isSoftDeleted(txHash: string): boolean {
+    return this.#state.get(txHash)?.softDeleted ?? false;
+  }
+
+  /**
+   * 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}`);
+    return toHardDelete;
+  }
+
+  /**
+   * Gets the count of transactions from pruned blocks.
+   */
+  getCount(): number {
+    return this.#state.size;
+  }
+
+  /**
+   * Gets all transaction hashes from pruned blocks.
+   */
+  getPrunedTxHashes(): string[] {
+    return Array.from(this.#state.keys());
+  }
+}

package/src/mem_pools/tx_pool_v2/index.ts

@@ -9,3 +9,4 @@ export {
 } from './interfaces.js';
 export { type TxMetaData, type TxState, buildTxMetaData, comparePriority } from './tx_metadata.js';
 export { TxArchive } from './archive/index.js';
+export { DeletedPool } from './deleted_pool.js';

package/src/mem_pools/tx_pool_v2/interfaces.ts

@@ -55,8 +55,8 @@ export type TxPoolV2Dependencies = {
   l2BlockSource: L2BlockSource;
   /** World state synchronizer for validating transactions after chain prunes */
   worldStateSynchronizer: WorldStateSynchronizer;
-  /** Validator for transactions entering the pending pool */
-  pendingTxValidator: TxValidator<Tx>;
+  /** Factory that creates a validator for re-validating pool transactions using metadata */
+  createTxValidator: () => Promise<TxValidator<TxMetaData>>;
 };
 
 /**

package/src/mem_pools/tx_pool_v2/tx_metadata.ts

@@ -1,12 +1,27 @@
+import { BlockNumber } from '@aztec/foundation/branded-types';
 import { Fr } from '@aztec/foundation/curves/bn254';
 import { ProtocolContractAddress } from '@aztec/protocol-contracts';
-import type { L2BlockId } from '@aztec/stdlib/block';
+import { BlockHash, type L2BlockId } from '@aztec/stdlib/block';
 import type { Tx } from '@aztec/stdlib/tx';
 
 import { getFeePayerBalanceDelta } from '../../msg_validators/tx_validator/fee_payer_balance.js';
 import { getTxPriorityFee } from '../tx_pool/priority.js';
 import type { PreAddResult } from './eviction/interfaces.js';
 
+/** Validator-compatible data interface, mirroring the subset of PrivateKernelTailCircuitPublicInputs used by validators. */
+export type TxMetaValidationData = {
+  getNonEmptyNullifiers(): Fr[];
+  includeByTimestamp: bigint;
+  constants: {
+    anchorBlockHeader: {
+      hash(): Promise<BlockHash>;
+      globalVariables: {
+        blockNumber: BlockNumber;
+      };
+    };
+  };
+};
+
 /**
  * Lightweight in-memory representation of a transaction.
  * Stored for every tx in the pool to enable efficient queries and challenges
@@ -42,22 +57,29 @@ export type TxMetaData = {
 
   /** Timestamp by which the transaction must be included (for expiration checks) */
   readonly includeByTimestamp: bigint;
+
+  /** Validator-compatible data, providing the same access patterns as Tx.data */
+  readonly data: TxMetaValidationData;
 };
 
 /** Transaction state derived from TxMetaData fields and pool protection status */
-export type TxState = 'pending' | 'protected' | 'mined';
+export type TxState = 'pending' | 'protected' | 'mined' | 'deleted';
 
 /**
  * Builds TxMetaData from a full Tx object.
  * Extracts all relevant fields for efficient in-memory storage and querying.
+ * Fr values are captured in closures for zero-cost re-validation.
  */
 export async function buildTxMetaData(tx: Tx): Promise<TxMetaData> {
   const txHash = tx.getTxHash().toString();
-  const anchorBlockHeaderHash = (await tx.data.constants.anchorBlockHeader.hash()).toString();
+  const nullifierFrs = tx.data.getNonEmptyNullifiers();
+  const nullifiers = nullifierFrs.map(n => n.toString());
+  const anchorBlockHeaderHashFr = await tx.data.constants.anchorBlockHeader.hash();
+  const anchorBlockHeaderHash = anchorBlockHeaderHashFr.toString();
+  const includeByTimestamp = tx.data.includeByTimestamp;
+  const anchorBlockNumber = tx.data.constants.anchorBlockHeader.globalVariables.blockNumber;
   const priorityFee = getTxPriorityFee(tx);
   const feePayer = tx.data.feePayer.toString();
-  const nullifiers = tx.data.getNonEmptyNullifiers().map(n => n.toString());
-  const includeByTimestamp = tx.data.includeByTimestamp;
 
   const { feeLimit, claimAmount } = await getFeePayerBalanceDelta(tx, ProtocolContractAddress.FeeJuice);
 
@@ -70,6 +92,16 @@ export async function buildTxMetaData(tx: Tx): Promise<TxMetaData> {
     feeLimit,
     nullifiers,
     includeByTimestamp,
+    data: {
+      getNonEmptyNullifiers: () => nullifierFrs,
+      includeByTimestamp,
+      constants: {
+        anchorBlockHeader: {
+          hash: () => Promise.resolve(anchorBlockHeaderHashFr),
+          globalVariables: { blockNumber: anchorBlockNumber },
+        },
+      },
+    },
   };
 }
 
@@ -159,3 +191,17 @@ export function checkNullifierConflict(
 
   return { shouldIgnore: false, txHashesToEvict };
 }
+
+/** Creates a stub TxMetaValidationData for tests that don't exercise validators. */
+export function stubTxMetaValidationData(overrides: { includeByTimestamp?: bigint } = {}): TxMetaValidationData {
+  return {
+    getNonEmptyNullifiers: () => [],
+    includeByTimestamp: overrides.includeByTimestamp ?? 0n,
+    constants: {
+      anchorBlockHeader: {
+        hash: () => Promise.resolve(new BlockHash(Fr.ZERO)),
+        globalVariables: { blockNumber: BlockNumber(0) },
+      },
+    },
+  };
+}