@aztec/p2p 0.0.1-commit.96dac018d → 0.0.1-commit.993d240

package/src/mem_pools/tx_pool_v2/tx_pool_indices.ts

@@ -1,7 +1,8 @@
+import { insertIntoSortedArray, removeFromSortedArray } from '@aztec/foundation/array';
 import { SlotNumber } from '@aztec/foundation/branded-types';
 import type { L2BlockId } from '@aztec/stdlib/block';
 
-import { type TxMetaData, type TxState, compareFee, compareTxHash } from './tx_metadata.js';
+import { type PriorityComparable, type TxMetaData, type TxState, comparePriority } from './tx_metadata.js';
 
 /**
  * Manages in-memory indices for the transaction pool.
@@ -22,8 +23,8 @@ export class TxPoolIndices {
   #nullifierToTxHash: Map<string, string> = new Map();
   /** Fee payer to txHashes index (pending txs only) */
   #feePayerToTxHashes: Map<string, Set<string>> = new Map();
-  /** Pending txHashes grouped by priority fee */
-  #pendingByPriority: Map<bigint, Set<string>> = new Map();
+  /** Pending transactions sorted ascending by priority fee, ties broken by txHash */
+  #pendingByPriority: PriorityComparable[] = [];
   /** Protected transactions: txHash -> slotNumber */
   #protectedTransactions: Map<string, SlotNumber> = new Map();
 
@@ -73,20 +74,14 @@ export class TxPoolIndices {
    * @param order - 'desc' for highest priority first, 'asc' for lowest priority first
    */
   *iteratePendingByPriority(order: 'asc' | 'desc', filter?: (hash: string) => boolean): Generator<string> {
-    // Use compareFee from tx_metadata, swap args for descending order
-    const feeCompareFn = order === 'desc' ? (a: bigint, b: bigint) => compareFee(b, a) : compareFee;
-    const hashCompareFn = order === 'desc' ? (a: string, b: string) => compareTxHash(b, a) : compareTxHash;
-
-    const sortedFees = [...this.#pendingByPriority.keys()].sort(feeCompareFn);
-
-    for (const fee of sortedFees) {
-      const hashesAtFee = this.#pendingByPriority.get(fee)!;
-      // Use compareTxHash from tx_metadata, swap args for descending order
-      const sortedHashes = [...hashesAtFee].sort(hashCompareFn);
-      for (const hash of sortedHashes) {
-        if (filter === undefined || filter(hash)) {
-          yield hash;
-        }
+    const arr = this.#pendingByPriority;
+    const start = order === 'asc' ? 0 : arr.length - 1;
+    const step = order === 'asc' ? 1 : -1;
+    const inBounds = order === 'asc' ? (i: number) => i < arr.length : (i: number) => i >= 0;
+
+    for (let i = start; inBounds(i); i += step) {
+      if (filter === undefined || filter(arr[i].txHash)) {
+        yield arr[i].txHash;
       }
     }
   }
@@ -227,11 +222,7 @@ export class TxPoolIndices {
 
   /** Gets the count of pending transactions */
   getPendingTxCount(): number {
-    let count = 0;
-    for (const hashes of this.#pendingByPriority.values()) {
-      count += hashes.size;
-    }
-    return count;
+    return this.#pendingByPriority.length;
   }
 
   /** Gets the lowest priority pending transaction hashes (up to limit) */
@@ -264,12 +255,10 @@ export class TxPoolIndices {
   /** Gets all pending transactions */
   getPendingTxs(): TxMetaData[] {
     const result: TxMetaData[] = [];
-    for (const hashSet of this.#pendingByPriority.values()) {
-      for (const txHash of hashSet) {
-        const meta = this.#metadata.get(txHash);
-        if (meta) {
-          result.push(meta);
-        }
+    for (const entry of this.#pendingByPriority) {
+      const meta = this.#metadata.get(entry.txHash);
+      if (meta) {
+        result.push(meta);
       }
     }
     return result;
@@ -408,13 +397,12 @@ export class TxPoolIndices {
     }
     feePayerSet.add(meta.txHash);
 
-    // Add to priority bucket
-    let prioritySet = this.#pendingByPriority.get(meta.priorityFee);
-    if (!prioritySet) {
-      prioritySet = new Set();
-      this.#pendingByPriority.set(meta.priorityFee, prioritySet);
-    }
-    prioritySet.add(meta.txHash);
+    insertIntoSortedArray(
+      this.#pendingByPriority,
+      { txHash: meta.txHash, priorityFee: meta.priorityFee, txHashBigInt: meta.txHashBigInt },
+      comparePriority,
+      false,
+    );
   }
 
   #removeFromPendingIndices(meta: TxMetaData): void {
@@ -432,13 +420,11 @@ export class TxPoolIndices {
       }
     }
 
-    // Remove from priority map
-    const hashSet = this.#pendingByPriority.get(meta.priorityFee);
-    if (hashSet) {
-      hashSet.delete(meta.txHash);
-      if (hashSet.size === 0) {
-        this.#pendingByPriority.delete(meta.priorityFee);
-      }
-    }
+    // Remove from priority array
+    removeFromSortedArray(
+      this.#pendingByPriority,
+      { txHash: meta.txHash, priorityFee: meta.priorityFee, txHashBigInt: meta.txHashBigInt },
+      comparePriority,
+    );
   }
 }

package/src/mem_pools/tx_pool_v2/tx_pool_v2.ts

@@ -11,7 +11,14 @@ import { type TelemetryClient, getTelemetryClient } from '@aztec/telemetry-clien
 import EventEmitter from 'node:events';
 
 import { PoolInstrumentation, PoolName } from '../instrumentation.js';
-import type { AddTxsResult, TxPoolV2, TxPoolV2Config, TxPoolV2Dependencies, TxPoolV2Events } from './interfaces.js';
+import type {
+  AddTxsResult,
+  PoolReadAccess,
+  TxPoolV2,
+  TxPoolV2Config,
+  TxPoolV2Dependencies,
+  TxPoolV2Events,
+} from './interfaces.js';
 import type { TxState } from './tx_metadata.js';
 import { TxPoolV2Impl } from './tx_pool_v2_impl.js';
 
@@ -58,6 +65,9 @@ export class AztecKVTxPoolV2 extends (EventEmitter as new () => TypedEventEmitte
         const hashes = txHashes.map(h => (typeof h === 'string' ? TxHash.fromString(h) : TxHash.fromBigInt(h)));
         this.emit('txs-removed', { txHashes: hashes });
       },
+      onTxsMined: (txHashes: string[]) => {
+        this.#metrics?.transactionsRemoved(txHashes);
+      },
     };
 
     // Create the implementation
@@ -162,6 +172,11 @@ export class AztecKVTxPoolV2 extends (EventEmitter as new () => TypedEventEmitte
     return this.#queue.put(() => Promise.resolve(this.#impl.getLowestPriorityPending(limit)));
   }
 
+  /** Returns read-only access to the pool. Used for testing. */
+  getPoolReadAccess(): PoolReadAccess {
+    return this.#impl.getPoolReadAccess();
+  }
+
   // === Configuration ===
 
   updateConfig(config: Partial<TxPoolV2Config>): Promise<void> {

package/src/mem_pools/tx_pool_v2/tx_pool_v2_impl.ts

@@ -1,4 +1,5 @@
 import { BlockNumber, SlotNumber } from '@aztec/foundation/branded-types';
+import { FifoSet } from '@aztec/foundation/fifo-set';
 import type { Logger } from '@aztec/foundation/log';
 import type { DateProvider } from '@aztec/foundation/timer';
 import type { AztecAsyncKVStore, AztecAsyncMap } from '@aztec/kv-store';
@@ -17,6 +18,7 @@ import {
   EvictionManager,
   FeePayerBalanceEvictionRule,
   FeePayerBalancePreAddRule,
+  InsufficientFeePerGasEvictionRule,
   InvalidTxsAfterMiningRule,
   InvalidTxsAfterReorgRule,
   LowPriorityEvictionRule,
@@ -39,12 +41,20 @@ import {
 import { type TxMetaData, type TxState, buildTxMetaData, checkNullifierConflict } from './tx_metadata.js';
 import { TxPoolIndices } from './tx_pool_indices.js';
 
+/**
+ * Maximum number of full transactions to load into memory at once when finalizing a block.
+ * Bounds peak memory while archiving and hard-deleting mined txs (~23k txs/epoch at 10 TPS would
+ * otherwise OOM the node).
+ */
+const FINALIZE_BLOCK_CHUNK_SIZE = 100;
+
 /**
  * Callbacks for the implementation to notify the outer class about events and metrics.
  */
 export interface TxPoolV2Callbacks {
   onTxsAdded: (txs: Tx[], opts: { source?: string }) => void;
   onTxsRemoved: (txHashes: string[] | bigint[]) => void;
+  onTxsMined: (txHashes: string[]) => void;
 }
 
 /**
@@ -61,6 +71,7 @@ export class TxPoolV2Impl {
   #l2BlockSource: L2BlockSource;
   #worldStateSynchronizer: WorldStateSynchronizer;
   #createTxValidator: TxPoolV2Dependencies['createTxValidator'];
+  #checkAllowedSetupCalls: TxPoolV2Dependencies['checkAllowedSetupCalls'];
 
   // === In-Memory Indices ===
   #indices: TxPoolIndices = new TxPoolIndices();
@@ -72,7 +83,7 @@ export class TxPoolV2Impl {
   #evictionManager: EvictionManager;
   #dateProvider: DateProvider;
   #instrumentation: TxPoolV2Instrumentation;
-  #evictedTxHashes: Set<string> = new Set();
+  #evictedTxHashes: FifoSet<string>;
   #log: Logger;
   #callbacks: TxPoolV2Callbacks;
 
@@ -92,8 +103,10 @@ export class TxPoolV2Impl {
     this.#l2BlockSource = deps.l2BlockSource;
     this.#worldStateSynchronizer = deps.worldStateSynchronizer;
     this.#createTxValidator = deps.createTxValidator;
+    this.#checkAllowedSetupCalls = deps.checkAllowedSetupCalls;
 
     this.#config = { ...DEFAULT_TX_POOL_V2_CONFIG, ...config };
+    this.#evictedTxHashes = FifoSet.withLimit<string>(this.#config.evictedTxCacheSize);
     this.#archive = new TxArchive(archiveStore, this.#config.archivedTxLimit, log);
     this.#deletedPool = new DeletedPool(store, this.#txsDB, log);
     this.#dateProvider = dateProvider;
@@ -113,6 +126,7 @@ export class TxPoolV2Impl {
 
     // Post-event eviction rules (run after events to check ALL pending txs)
     this.#evictionManager.registerRule(new InvalidTxsAfterMiningRule());
+    this.#evictionManager.registerRule(new InsufficientFeePerGasEvictionRule(deps.blockMinFeesProvider));
     this.#evictionManager.registerRule(new InvalidTxsAfterReorgRule(deps.worldStateSynchronizer));
     this.#evictionManager.registerRule(new FeePayerBalanceEvictionRule(deps.worldStateSynchronizer));
     // LowPriorityEvictionRule handles cases where txs become pending via prepareForSlot (unprotect)
@@ -135,39 +149,67 @@ export class TxPoolV2Impl {
     // Step 0: Hydrate deleted pool state
     await this.#deletedPool.hydrateFromDatabase();
 
-    // Step 1: Load all transactions from DB (excluding soft-deleted)
-    const { loaded, errors: deserializationErrors } = await this.#loadAllTxsFromDb();
+    // Step 1: Stream txs from DB, building metadata and mined status one at a time.
+    const minedMetas: TxMetaData[] = [];
+    const pendingMetas: TxMetaData[] = [];
+    const deserializationErrors: string[] = [];
+
+    for await (const [txHashStr, buffer] of this.#txsDB.entriesAsync()) {
+      // Skip soft-deleted transactions - they stay in DB but not in indices
+      if (this.#deletedPool.isSoftDeleted(txHashStr)) {
+        continue;
+      }
+
+      let meta: TxMetaData;
+      let txEffect: Awaited<ReturnType<L2BlockSource['getTxEffect']>>;
+      try {
+        const tx = Tx.fromBuffer(buffer);
+        // Resolve allowed-setup-calls and the tx effect concurrently
+        // getTxEffect failures are non-fatal (we just treat the tx as not-yet-mined), so
+        // its rejection is swallowed before the Promise.all so it can't fail-fast the batch.
+        const txEffectPromise = this.#l2BlockSource.getTxEffect(tx.getTxHash()).catch(err => {
+          this.#log.warn(`Failed to check mined status for tx ${txHashStr}`, { err });
+          return undefined;
+        });
+        const [allowedSetupCalls, fetchedTxEffect] = await Promise.all([
+          this.#checkAllowedSetupCalls(tx),
+          txEffectPromise,
+        ]);
+        meta = await buildTxMetaData(tx, allowedSetupCalls);
+        txEffect = fetchedTxEffect;
+      } catch (err) {
+        this.#log.warn(`Failed to deserialize tx ${txHashStr}, deleting`, { err });
+        deserializationErrors.push(txHashStr);
+        continue;
+      }
 
-    // Step 2: Check mined status for each tx
-    await this.#markMinedStatusBatch(loaded.map(l => l.meta));
+      if (txEffect) {
+        meta.minedL2BlockId = {
+          number: txEffect.l2BlockNumber,
+          hash: txEffect.l2BlockHash.toString(),
+        };
+      }
 
-    // Step 3: Partition by mined status
-    const mined: TxMetaData[] = [];
-    const nonMined: { tx: Tx; meta: TxMetaData }[] = [];
-    for (const entry of loaded) {
-      if (entry.meta.minedL2BlockId !== undefined) {
-        mined.push(entry.meta);
+      if (meta.minedL2BlockId !== undefined) {
+        minedMetas.push(meta);
       } else {
-        nonMined.push(entry);
+        pendingMetas.push(meta);
       }
     }
 
-    // Step 4: Validate non-mined transactions
-    const { valid, invalid } = await this.#revalidateMetadata(
-      nonMined.map(e => e.meta),
-      'on startup',
-    );
+    // Step 2: Validate non-mined transactions
+    const { valid, invalid } = await this.#revalidateMetadata(pendingMetas, 'on startup');
 
-    // Step 5: Populate mined indices (these don't need conflict resolution)
-    for (const meta of mined) {
+    // Step 3: Populate mined indices (these don't need conflict resolution)
+    for (const meta of minedMetas) {
       this.#indices.addMined(meta);
     }
 
-    // Step 6: Rebuild pending pool by running pre-add rules for each tx
+    // Step 4: Rebuild pending pool by running pre-add rules for each tx
     // This resolves nullifier conflicts, fee payer balance issues, and pool size limits
     const { rejected } = await this.#rebuildPendingPool(valid);
 
-    // Step 7: Delete invalid and rejected txs from DB only (indices were never populated for these)
+    // Step 5: Delete invalid and rejected txs from DB only (indices were never populated for these)
     const toDelete = [...deserializationErrors, ...invalid, ...rejected];
     if (toDelete.length === 0) {
       return;
@@ -187,9 +229,35 @@ export class TxPoolV2Impl {
     const errors = new Map<string, TxPoolRejectionError>();
     const acceptedPending = new Set<string>();
 
+    // Phase 1: Pre-compute all throwable I/O outside the transaction.
+    // If any pre-computation throws, the entire call fails before mutations happen.
+    const precomputed = new Map<string, { meta: TxMetaData; minedBlockId: L2BlockId | undefined; isValid: boolean }>();
+
+    const validator = await this.#createTxValidator();
+
+    for (const tx of txs) {
+      const txHash = tx.getTxHash();
+      const txHashStr = txHash.toString();
+
+      const meta = await buildTxMetaData(tx);
+      const minedBlockId = await this.#getMinedBlockId(txHash);
+
+      // Validate non-mined txs (mined and pre-protected txs bypass validation inside the transaction)
+      let isValid = true;
+      if (!minedBlockId) {
+        isValid = await this.#validateMeta(meta, validator);
+      }
+
+      precomputed.set(txHashStr, { meta, minedBlockId, isValid });
+    }
+
+    // Phase 2: Apply mutations inside the transaction using only pre-computed results,
+    // in-memory reads, and buffered DB writes. Nothing here can throw an unhandled exception.
     const poolAccess = this.#createPreAddPoolAccess();
     const preAddContext: PreAddContext | undefined =
-      opts.feeComparisonOnly !== undefined ? { feeComparisonOnly: opts.feeComparisonOnly } : undefined;
+      opts.feeComparisonOnly !== undefined
+        ? { feeComparisonOnly: opts.feeComparisonOnly, priceBumpPercentage: this.#config.priceBumpPercentage }
+        : undefined;
 
     await this.#store.transactionAsync(async () => {
       for (const tx of txs) {
@@ -202,22 +270,25 @@ export class TxPoolV2Impl {
           continue;
         }
 
-        // Check mined status first (applies to all paths)
-        const minedBlockId = await this.#getMinedBlockId(txHash);
+        const { meta, minedBlockId, isValid } = precomputed.get(txHashStr)!;
         const preProtectedSlot = this.#indices.getProtectionSlot(txHashStr);
 
         if (minedBlockId) {
           // Already mined - add directly (protection already set if pre-protected)
-          await this.#addTx(tx, { mined: minedBlockId }, opts);
+          await this.#addTx(tx, { mined: minedBlockId }, opts, meta);
           accepted.push(txHash);
         } else if (preProtectedSlot !== undefined) {
           // Pre-protected and not mined - add as protected (bypass validation)
-          await this.#addTx(tx, { protected: preProtectedSlot }, opts);
+          await this.#addTx(tx, { protected: preProtectedSlot }, opts, meta);
           accepted.push(txHash);
+        } else if (!isValid) {
+          // Failed pre-computed validation
+          rejected.push(txHash);
         } else {
-          // Regular pending tx - validate and run pre-add rules
+          // Regular pending tx - run pre-add rules using pre-computed metadata
           const result = await this.#tryAddRegularPendingTx(
             tx,
+            meta,
             opts,
             poolAccess,
             acceptedPending,
@@ -227,8 +298,6 @@ export class TxPoolV2Impl {
           );
           if (result.status === 'accepted') {
             acceptedPending.add(txHashStr);
-          } else if (result.status === 'rejected') {
-            rejected.push(txHash);
           } else {
             ignored.push(txHash);
           }
@@ -259,27 +328,21 @@ export class TxPoolV2Impl {
     return { accepted, ignored, rejected, ...(errors.size > 0 ? { errors } : {}) };
   }
 
-  /** Validates and adds a regular pending tx. Returns status. */
+  /** Adds a validated pending tx, running pre-add rules and evicting conflicts. */
   async #tryAddRegularPendingTx(
     tx: Tx,
+    precomputedMeta: TxMetaData,
     opts: { source?: string },
     poolAccess: PreAddPoolAccess,
     acceptedPending: Set<string>,
     ignored: TxHash[],
     errors: Map<string, TxPoolRejectionError>,
     preAddContext?: PreAddContext,
-  ): Promise<{ status: 'accepted' | 'ignored' | 'rejected' }> {
-    const txHash = tx.getTxHash();
-    const txHashStr = txHash.toString();
-
-    // Build metadata and validate using metadata
-    const meta = await buildTxMetaData(tx);
-    if (!(await this.#validateMeta(meta))) {
-      return { status: 'rejected' };
-    }
+  ): Promise<{ status: 'accepted' | 'ignored' }> {
+    const txHashStr = tx.getTxHash().toString();
 
     // Run pre-add rules
-    const preAddResult = await this.#evictionManager.runPreAddRules(meta, poolAccess, preAddContext);
+    const preAddResult = await this.#evictionManager.runPreAddRules(precomputedMeta, poolAccess, preAddContext);
 
     if (preAddResult.shouldIgnore) {
       this.#log.debug(`Ignoring tx ${txHashStr}: ${preAddResult.reason?.message ?? 'unknown reason'}`);
@@ -323,7 +386,7 @@ export class TxPoolV2Impl {
     }
 
     // Add the transaction
-    await this.#addTx(tx, 'pending', opts);
+    await this.#addTx(tx, 'pending', opts, precomputedMeta);
     return { status: 'accepted' };
   }
 
@@ -332,6 +395,7 @@ export class TxPoolV2Impl {
 
     // Check if already in pool
     if (this.#indices.has(txHashStr)) {
+      this.#log.verbose(`canAddPendingTx: tx ${txHashStr} already in pool`);
       return 'ignored';
     }
 
@@ -340,26 +404,37 @@ export class TxPoolV2Impl {
     const poolAccess = this.#createPreAddPoolAccess();
     const preAddResult = await this.#evictionManager.runPreAddRules(meta, poolAccess);
 
-    return preAddResult.shouldIgnore ? 'ignored' : 'accepted';
+    if (preAddResult.shouldIgnore) {
+      this.#log.verbose(`canAddPendingTx: tx ${txHashStr} ignored by pre-add rule`, {
+        reason: preAddResult.reason?.message ?? 'no reason provided',
+      });
+      return 'ignored';
+    }
+    return 'accepted';
   }
 
   async addProtectedTxs(txs: Tx[], block: BlockHeader, opts: { source?: string }): Promise<void> {
     const slotNumber = block.globalVariables.slotNumber;
 
+    // Precompute setup-call allow-list flags outside the store transaction
+    const allowedFlags = await Promise.all(txs.map(tx => this.#checkAllowedSetupCalls(tx)));
+
     await this.#store.transactionAsync(async () => {
-      for (const tx of txs) {
+      for (let i = 0; i < txs.length; i++) {
+        const tx = txs[i];
         const txHash = tx.getTxHash();
         const txHashStr = txHash.toString();
         const isNew = !this.#indices.has(txHashStr);
         const minedBlockId = await this.#getMinedBlockId(txHash);
 
         if (isNew) {
+          const meta = await buildTxMetaData(tx, allowedFlags[i]);
           // New tx - add as mined or protected (callback emitted by #addTx)
           if (minedBlockId) {
-            await this.#addTx(tx, { mined: minedBlockId }, opts);
+            await this.#addTx(tx, { mined: minedBlockId }, opts, meta);
             this.#indices.setProtection(txHashStr, slotNumber);
           } else {
-            await this.#addTx(tx, { protected: slotNumber }, opts);
+            await this.#addTx(tx, { protected: slotNumber }, opts, meta);
           }
         } else {
           // Existing tx - update protection and mined status
@@ -479,6 +554,10 @@ export class TxPoolV2Impl {
       await this.#evictionManager.evictAfterNewBlock(block.header, nullifiers, feePayers);
     });
 
+    if (found.length > 0) {
+      this.#callbacks.onTxsMined(found.map(m => m.txHash));
+    }
+
     this.#log.info(`Marked ${found.length} txs as mined in block ${blockId.number}`);
   }
 
@@ -598,28 +677,29 @@ export class TxPoolV2Impl {
     // Step 1: Find mined txs at or before finalized block
     const minedTxsToFinalize = this.#indices.findTxsMinedAtOrBefore(blockNumber);
 
-    await this.#store.transactionAsync(async () => {
-      // Step 2: Collect mined txs for archiving (before deletion)
-      const txsToArchive: Tx[] = [];
-      if (this.#archive.isEnabled()) {
-        for (const txHashStr of minedTxsToFinalize) {
+    // Step 2: Archive in chunks if archiving is enabled. Hydrating an entire epoch's worth of
+    // mined txs at once would OOM under load. When archiving is disabled there is no need to hydrate the txs at all.
+    if (this.#archive.isEnabled()) {
+      for (let i = 0; i < minedTxsToFinalize.length; i += FINALIZE_BLOCK_CHUNK_SIZE) {
+        const chunk = minedTxsToFinalize.slice(i, i + FINALIZE_BLOCK_CHUNK_SIZE);
+        const txsToArchive: Tx[] = [];
+        for (const txHashStr of chunk) {
           const buffer = await this.#txsDB.getAsync(txHashStr);
           if (buffer) {
             txsToArchive.push(Tx.fromBuffer(buffer));
           }
         }
+        if (txsToArchive.length > 0) {
+          await this.#archive.archiveTxs(txsToArchive);
+        }
       }
+    }
 
-      // Step 3: Delete mined txs from active pool
+    // Step 3: Delete mined txs from the active pool and finalize soft-deleted txs in one
+    // transaction. Only tx hashes are touched here, so memory is bounded and atomicity is preserved.
+    await this.#store.transactionAsync(async () => {
       await this.#deleteTxsBatch(minedTxsToFinalize);
-
-      // Step 4: Finalize soft-deleted txs
       await this.#deletedPool.finalizeBlock(blockNumber);
-
-      // Step 5: Archive mined txs
-      if (txsToArchive.length > 0) {
-        await this.#archive.archiveTxs(txsToArchive);
-      }
     });
 
     if (minedTxsToFinalize.length > 0) {
@@ -765,9 +845,10 @@ export class TxPoolV2Impl {
     tx: Tx,
     state: 'pending' | { protected: SlotNumber } | { mined: L2BlockId },
     opts: { source?: string } = {},
+    precomputedMeta?: TxMetaData,
   ): Promise<TxMetaData> {
     const txHashStr = tx.getTxHash().toString();
-    const meta = await buildTxMetaData(tx);
+    const meta = precomputedMeta ?? (await buildTxMetaData(tx));
     meta.receivedAt = this.#dateProvider.now();
 
     await this.#txsDB.set(txHashStr, tx.toBuffer());
@@ -824,21 +905,11 @@ export class TxPoolV2Impl {
     this.#instrumentation.recordEvictions(txHashes.length, reason);
     for (const txHashStr of txHashes) {
       this.#log.debug(`Evicting tx ${txHashStr}`, { txHash: txHashStr, reason });
-      this.#addToEvictedCache(txHashStr);
+      this.#evictedTxHashes.add(txHashStr);
     }
     await this.#deleteTxsBatch(txHashes);
   }
 
-  /** Adds a tx hash to the bounded evicted cache, evicting the oldest entry if at capacity. */
-  #addToEvictedCache(txHashStr: string): void {
-    if (this.#evictedTxHashes.size >= this.#config.evictedTxCacheSize) {
-      // FIFO eviction: remove the first (oldest) entry
-      const oldest = this.#evictedTxHashes.values().next().value!;
-      this.#evictedTxHashes.delete(oldest);
-    }
-    this.#evictedTxHashes.add(txHashStr);
-  }
-
   // ============================================================================
   // PRIVATE HELPERS - Validation & Conflict Resolution
   // ============================================================================
@@ -933,50 +1004,6 @@ export class TxPoolV2Impl {
     };
   }
 
-  /** Loads all transactions from the database, returning loaded txs and deserialization errors */
-  async #loadAllTxsFromDb(): Promise<{
-    loaded: { tx: Tx; meta: TxMetaData }[];
-    errors: string[];
-  }> {
-    const loaded: { tx: Tx; meta: TxMetaData }[] = [];
-    const errors: string[] = [];
-
-    for await (const [txHashStr, buffer] of this.#txsDB.entriesAsync()) {
-      // Skip soft-deleted transactions - they stay in DB but not in indices
-      if (this.#deletedPool.isSoftDeleted(txHashStr)) {
-        continue;
-      }
-
-      try {
-        const tx = Tx.fromBuffer(buffer);
-        const meta = await buildTxMetaData(tx);
-        loaded.push({ tx, meta });
-      } catch (err) {
-        this.#log.warn(`Failed to deserialize tx ${txHashStr}, deleting`, { err });
-        errors.push(txHashStr);
-      }
-    }
-
-    return { loaded, errors };
-  }
-
-  /** Queries block source and marks mined status on transaction metadata */
-  async #markMinedStatusBatch(metas: TxMetaData[]): Promise<void> {
-    for (const meta of metas) {
-      try {
-        const txEffect = await this.#l2BlockSource.getTxEffect(TxHash.fromString(meta.txHash));
-        if (txEffect) {
-          meta.minedL2BlockId = {
-            number: txEffect.l2BlockNumber,
-            hash: txEffect.l2BlockHash.toString(),
-          };
-        }
-      } catch (err) {
-        this.#log.warn(`Failed to check mined status for tx ${meta.txHash}`, { err });
-      }
-    }
-  }
-
   /**
    * Rebuilds the pending pool by processing each tx through pre-add rules.
    * Starts with an empty pending pool and adds txs one by one, resolving conflicts.

package/src/msg_validators/attestation_validator/README.md

@@ -0,0 +1,49 @@
+# Attestation Validation
+
+This module validates `CheckpointAttestation` gossipsub messages. Attestations are signatures from committee members endorsing a checkpoint proposal.
+
+**Topic**: `checkpoint_attestation` | **Snappy size limit**: 5 KB
+
+## Stage 1: AttestationValidator (Gossipsub Validation)
+
+| # | Rule | Consequence | Severity | File |
+|---|------|-------------|----------|------|
+| 1 | **Slot timeliness**: `currentSlot` or `nextSlot`. Previous slot within 500ms: IGNORE. Older: REJECT. | REJECT or IGNORE | HighToleranceError | `attestation_validator.ts` |
+| 2 | **Attester signature**: `getSender()` must recover valid address | REJECT | LowToleranceError | same |
+| 3 | **Attester in committee**: recovered address in committee for slot | REJECT | HighToleranceError | same |
+| 4 | **Proposer exists**: `getProposerAttesterAddressInSlot` must return defined | REJECT | HighToleranceError | same |
+| 5 | **Proposer signature**: `getProposer()` must recover valid address | REJECT | LowToleranceError | same |
+| 6 | **Proposer matches expected**: recovered proposer = expected for slot | REJECT | HighToleranceError | same |
+| 7 | **NoCommitteeError**: committee unavailable | REJECT | LowToleranceError | same |
+
+**Fisherman mode extension** (`FishermanAttestationValidator`): if a checkpoint proposal for the same archive exists in pool, the attestation's `ConsensusPayload` must `.equals()` the stored proposal's payload. On mismatch: REJECT + LowToleranceError.
+
+## Stage 2: Pool Admission
+
+| # | Rule | Consequence |
+|---|------|-------------|
+| 8 | Sender recoverable (pool-side) | Silent drop |
+| 9 | Not a duplicate (same slot + proposalId + signer) | IGNORE |
+| 10 | Per-signer cap: `MAX_ATTESTATIONS_PER_SLOT_AND_SIGNER` = 2 | IGNORE |
+
+Own attestations added via `addOwnCheckpointAttestations` bypass the per-signer cap.
+
+## Stage 3: Equivocation Detection
+
+When a signer's attestation count for a slot reaches exactly 2 (different proposals): `duplicateAttestationCallback` fires -> `WANT_TO_SLASH_EVENT` with `OffenseType.DUPLICATE_ATTESTATION`. Attestation still ACCEPTED and rebroadcast. Callback fires once (not again at count 3+).
+
+## Validation at L1 Checkpoint Submission (Archiver)
+
+| Rule | Consequence | File |
+|------|-------------|------|
+| Each attestation must have recoverable signature (or address-only is allowed but does not count toward quorum) | Checkpoint rejected as invalid | `archiver/src/modules/validation.ts` |
+| Attestation at index `i` must correspond to committee member at index `i` | Checkpoint rejected as invalid | same |
+| Valid attestation count >= floor(committee * 2/3) + 1 | Checkpoint rejected as invalid | same |
+| No committee / escape hatch open | Accepted unconditionally | same |
+
+Note: `skipValidateCheckpointAttestations` config flag bypasses all archiver attestation validation.
+
+## Gossipsub Topic Scoring
+
+P3 enabled with expected messages per slot = `targetCommitteeSize`. Conservative threshold (30% of convergence value). Max P3 penalty = -34 per topic.
+