@aztec/p2p 0.0.1-commit.c7c42ec → 0.0.1-commit.f295ac2

package/src/mem_pools/tx_pool/aztec_kv_tx_pool.ts

@@ -5,7 +5,7 @@ import { toArray } from '@aztec/foundation/iterable';
 import { type Logger, createLogger } from '@aztec/foundation/log';
 import type { TypedEventEmitter } from '@aztec/foundation/types';
 import type { AztecAsyncKVStore, AztecAsyncMap, AztecAsyncMultiMap } from '@aztec/kv-store';
-import type { AztecAddress } from '@aztec/stdlib/aztec-address';
+import { AztecAddress } from '@aztec/stdlib/aztec-address';
 import type { MerkleTreeReadOperations, ReadonlyWorldStateAccess } from '@aztec/stdlib/interfaces/server';
 import { ChonkProof } from '@aztec/stdlib/proofs';
 import type { TxAddedToPoolStats } from '@aztec/stdlib/stats';
@@ -18,11 +18,18 @@ import EventEmitter from 'node:events';
 import { ArchiveCache } from '../../msg_validators/tx_validator/archive_cache.js';
 import { PoolInstrumentation, PoolName, type PoolStatsCallback } from '../instrumentation.js';
 import { EvictionManager } from './eviction/eviction_manager.js';
-import type { PendingTxInfo, TxBlockReference, TxPoolOperations } from './eviction/eviction_strategy.js';
-import { InsufficientFeePayerBalanceRule } from './eviction/insufficient_fee_payer_balance_rule.js';
+import {
+  FeePayerTxInfo,
+  type PendingTxInfo,
+  type PreAddPoolAccess,
+  type TxBlockReference,
+  type TxPoolOperations,
+} from './eviction/eviction_strategy.js';
+import { FeePayerBalanceEvictionRule } from './eviction/fee_payer_balance_eviction_rule.js';
 import { InvalidTxsAfterMiningRule } from './eviction/invalid_txs_after_mining_rule.js';
 import { InvalidTxsAfterReorgRule } from './eviction/invalid_txs_after_reorg_rule.js';
 import { LowPriorityEvictionRule } from './eviction/low_priority_eviction_rule.js';
+import { NullifierConflictPreAddRule } from './eviction/nullifier_conflict_pre_add_rule.js';
 import { getPendingTxPriority } from './priority.js';
 import type { TxPool, TxPoolEvents, TxPoolOptions } from './tx_pool.js';
 
@@ -55,7 +62,10 @@ export class AztecKVTxPool
 
   #historicalHeaderToTxHash: AztecAsyncMultiMap<string, string>;
 
-  #feePayerToTxHash: AztecAsyncMultiMap<string, string>;
+  #feePayerToBalanceEntry: AztecAsyncMultiMap<string, Buffer>;
+
+  /** Index from nullifier to pending tx hash */
+  #pendingNullifierToTxHash: AztecAsyncMap<string, string>;
 
   /** In-memory set of txs that should not be evicted from the pool. */
   #nonEvictableTxs: Set<string>;
@@ -101,13 +111,14 @@ export class AztecKVTxPool
     this.#evictionManager = new EvictionManager(this);
     this.#evictionManager.registerRule(new InvalidTxsAfterMiningRule());
     this.#evictionManager.registerRule(new InvalidTxsAfterReorgRule(worldState));
-    this.#evictionManager.registerRule(new InsufficientFeePayerBalanceRule(worldState));
+    this.#evictionManager.registerRule(new FeePayerBalanceEvictionRule(worldState));
     this.#evictionManager.registerRule(
       new LowPriorityEvictionRule({
         //NOTE: 0 effectively disables low priority eviction
         maxPoolSize: config.maxPendingTxCount ?? 0,
       }),
     );
+    this.#evictionManager.registerPreAddRule(new NullifierConflictPreAddRule());
 
     this.updateConfig(config);
 
@@ -119,7 +130,8 @@ export class AztecKVTxPool
 
     this.#pendingTxHashToHistoricalBlockHeaderHash = store.openMap('txHistoricalBlock');
     this.#historicalHeaderToTxHash = store.openMultiMap('historicalHeaderToPendingTxHash');
-    this.#feePayerToTxHash = store.openMultiMap('feePayerToPendingTxHash');
+    this.#feePayerToBalanceEntry = store.openMultiMap('feePayerToBalanceEntry');
+    this.#pendingNullifierToTxHash = store.openMap('pendingNullifierToTxHash');
 
     this.#nonEvictableTxs = new Set<string>();
 
@@ -171,7 +183,7 @@ export class AztecKVTxPool
           const key = hash.toString();
           await this.#minedTxHashToBlock.set(key, blockHeader.globalVariables.blockNumber);
 
-          const tx = await this.getPendingTxByHash(hash);
+          const tx = await this.getTxByHash(hash);
           if (tx) {
             const nullifiers = tx.data.getNonEmptyNullifiers();
 
@@ -216,8 +228,16 @@ export class AztecKVTxPool
           const key = hash.toString();
           await this.#minedTxHashToBlock.delete(key);
 
+          // Clear soft-delete metadata if this tx was previously soft-deleted,
+          // so cleanupDeletedMinedTxs won't later hard-delete it while it's pending
+          const deletedBlock = await this.#deletedMinedTxHashes.getAsync(key);
+          if (deletedBlock !== undefined) {
+            await this.#deletedMinedTxHashes.delete(key);
+            await this.#blockToDeletedMinedTxHash.deleteValue(deletedBlock, key);
+          }
+
           // Rehydrate the tx in the in-memory pending txs mapping
-          const tx = await this.getPendingTxByHash(hash);
+          const tx = await this.getTxByHash(hash);
           if (tx) {
             await this.addPendingTxIndicesInDbTx(tx, key);
           }
@@ -271,6 +291,8 @@ export class AztecKVTxPool
 
   /**
    * Adds a list of transactions to the pool. Duplicates are ignored.
+   * Handles nullifier deduplication: if an incoming tx has a nullifier conflict with
+   * existing pending txs, it will either replace them (if higher fee) or be rejected.
    * @param txs - An array of txs to be added to the pool.
    * @returns count of added transactions
    */
@@ -280,43 +302,69 @@ export class AztecKVTxPool
     }
 
     const addedTxs: Tx[] = [];
+    const uniqueFeePayers: AztecAddress[] = [];
+    const replacedTxHashes: TxHash[] = [];
     const hashesAndStats = txs.map(tx => ({ txHash: tx.getTxHash(), txStats: tx.getStats() }));
     try {
       await this.#store.transactionAsync(async () => {
-        await Promise.all(
-          txs.map(async (tx, i) => {
-            const { txHash, txStats } = hashesAndStats[i];
-            const key = txHash.toString();
-            if (await this.#txs.hasAsync(key)) {
-              this.#log.debug(`Tx ${txHash.toString()} already exists in the pool`);
-              return;
+        for (let i = 0; i < txs.length; i++) {
+          const tx = txs[i];
+          const { txHash, txStats } = hashesAndStats[i];
+          const key = txHash.toString();
+          if (await this.#txs.hasAsync(key)) {
+            this.#log.debug(`Tx ${key} already exists in the pool`);
+            continue;
+          }
+
+          const poolAccess = this.getPreAddPoolAccess();
+          const { shouldReject, txHashesToEvict } = await this.#evictionManager.runPreAddRules(tx, poolAccess);
+          if (shouldReject) {
+            continue;
+          }
+
+          for (const txHashToEvict of txHashesToEvict) {
+            const txToDelete = await this.getTxByHash(txHashToEvict);
+            if (txToDelete) {
+              const evictedKey = txHashToEvict.toString();
+              await this.deletePendingTxInDbTx(txToDelete, evictedKey);
+              replacedTxHashes.push(txHashToEvict);
+              this.#log.verbose(`Evicted tx ${evictedKey} due to higher-fee tx ${key}`);
             }
+          }
 
-            this.#log.verbose(`Adding tx ${txHash.toString()} to pool`, {
-              eventName: 'tx-added-to-pool',
-              ...txStats,
-            } satisfies TxAddedToPoolStats);
+          this.#log.verbose(`Adding tx ${key} to pool`, {
+            eventName: 'tx-added-to-pool',
+            ...txStats,
+          } satisfies TxAddedToPoolStats);
 
-            await this.#txs.set(key, tx.toBuffer());
-            addedTxs.push(tx as Tx);
-            await this.#pendingTxHashToHistoricalBlockHeaderHash.set(
-              key,
-              (await tx.data.constants.anchorBlockHeader.hash()).toString(),
-            );
+          await this.#txs.set(key, tx.toBuffer());
+          addedTxs.push(tx);
+          insertIntoSortedArray(uniqueFeePayers, tx.data.feePayer, (a, b) => a.toField().cmp(b.toField()), false);
 
-            if (!(await this.#minedTxHashToBlock.hasAsync(key))) {
-              await this.addPendingTxIndicesInDbTx(tx, key);
-              this.#metrics.recordSize(tx);
-            }
-          }),
-        );
+          await this.#pendingTxHashToHistoricalBlockHeaderHash.set(
+            key,
+            (await tx.data.constants.anchorBlockHeader.hash()).toString(),
+          );
+
+          if (!(await this.#minedTxHashToBlock.hasAsync(key))) {
+            await this.addPendingTxIndicesInDbTx(tx, key);
+            this.#metrics.recordSize(tx);
+          }
+        }
       });
 
-      await this.#evictionManager.evictAfterNewTxs(addedTxs.map(({ txHash }) => txHash));
+      await this.#evictionManager.evictAfterNewTxs(
+        addedTxs.map(({ txHash }) => txHash),
+        uniqueFeePayers,
+      );
     } catch (err) {
       this.#log.warn('Unexpected error when adding txs', { err });
     }
 
+    if (replacedTxHashes.length > 0) {
+      this.#metrics.transactionsRemoved(replacedTxHashes.map(hash => hash.toBigInt()));
+    }
+
     if (addedTxs.length > 0) {
       this.#metrics.transactionsAdded(addedTxs);
       this.emit('txs-added', { ...opts, txs: addedTxs });
@@ -348,7 +396,7 @@ export class AztecKVTxPool
         const minedBlockNumber = await this.#minedTxHashToBlock.getAsync(key);
         const txIsPending = minedBlockNumber === undefined;
         if (txIsPending) {
-          await this.deletePendingTx(tx, key);
+          await this.deletePendingTxInDbTx(tx, key);
         } else {
           await this.deleteMinedTx(key, minedBlockNumber!, opts?.permanently ?? false);
           const shouldArchiveTx = this.#archivedTxLimit && !opts?.permanently;
@@ -378,10 +426,11 @@ export class AztecKVTxPool
     await this.#blockToDeletedMinedTxHash.set(minedBlockNumber, txHash);
   }
 
-  private async deletePendingTx(tx: Tx, txHash: `0x${string}`) {
+  // Assumes being called within a DB transaction
+  private async deletePendingTxInDbTx(tx: Tx, txHash: `0x${string}`) {
     // We always permanently delete pending transactions
     this.#log.trace(`Deleting pending tx ${txHash} from pool`);
-    await this.removePendingTxIndices(tx, txHash);
+    await this.removePendingTxIndicesInDbTx(tx, txHash);
     await this.#txs.delete(txHash);
     await this.#pendingTxHashToHistoricalBlockHeaderHash.delete(txHash);
   }
@@ -414,7 +463,7 @@ export class AztecKVTxPool
     let historicalBlockHash = await this.#pendingTxHashToHistoricalBlockHeaderHash.getAsync(txHash.toString());
     // Not all tx might have this index created.
     if (!historicalBlockHash) {
-      const tx = await this.getPendingTxByHash(txHash);
+      const tx = await this.getTxByHash(txHash);
       if (!tx) {
         this.#log.warn(`PendingTxInfo:tx ${txHash} not found`);
         return undefined;
@@ -447,15 +496,21 @@ export class AztecKVTxPool
     return result;
   }
 
-  public async getPendingTxsWithFeePayer(feePayers: AztecAddress[]): Promise<PendingTxInfo[]> {
-    const result: PendingTxInfo[] = [];
-    for (const feePayer of feePayers) {
-      const chunk = await toArray(this.#feePayerToTxHash.getValuesAsync(feePayer.toString()));
-      const infos = await Promise.all(chunk.map(txHash => this.getPendingTxInfo(TxHash.fromString(txHash))));
-      result.push(...infos.filter((info): info is PendingTxInfo => info !== undefined));
+  public async getPendingFeePayers(): Promise<AztecAddress[]> {
+    const feePayers: AztecAddress[] = [];
+    for await (const feePayer of this.#feePayerToBalanceEntry.keysAsync()) {
+      const address = AztecAddress.fromString(feePayer);
+      insertIntoSortedArray(feePayers, address, (a, b) => a.toField().cmp(b.toField()), false);
     }
+    return feePayers;
+  }
 
-    return result;
+  public async *getFeePayerTxInfos(feePayer: AztecAddress): AsyncIterable<FeePayerTxInfo> {
+    for await (const value of this.#feePayerToBalanceEntry.getValuesAsync(feePayer.toString())) {
+      const info = FeePayerTxInfo.decode(value);
+      info.isEvictable = !this.#nonEvictableTxs.has(info.txHash.toString());
+      yield info;
+    }
   }
 
   public async getMinedTxHashes(): Promise<[TxHash, BlockNumber][]> {
@@ -565,24 +620,6 @@ export class AztecKVTxPool
     return new ArchiveCache(db);
   }
 
-  /**
-   * Checks if a cached transaction exists in the in-memory pending tx pool and returns it.
-   * Otherwise, it checks the tx pool, updates the pending tx pool, and returns the tx.
-   * @param txHash - The generated tx hash.
-   * @returns The transaction, if found, 'undefined' otherwise.
-   */
-  private async getPendingTxByHash(txHash: TxHash | string): Promise<Tx | undefined> {
-    if (typeof txHash === 'string') {
-      txHash = TxHash.fromString(txHash);
-    }
-
-    const tx = await this.getTxByHash(txHash);
-    if (tx) {
-      return tx;
-    }
-    return undefined;
-  }
-
   /**
    * Archives a list of txs for future reference. The number of archived txs is limited by the specified archivedTxLimit.
    * Note: Pending txs should not be archived, only finalized txs
@@ -640,13 +677,13 @@ export class AztecKVTxPool
   private async addPendingTxIndicesInDbTx(tx: Tx, txHash: string): Promise<void> {
     await this.#pendingTxPriorityToHash.set(getPendingTxPriority(tx), txHash);
     await this.#historicalHeaderToTxHash.set((await tx.data.constants.anchorBlockHeader.hash()).toString(), txHash);
-    await this.#feePayerToTxHash.set(tx.data.feePayer.toString(), txHash);
-  }
+    await this.#feePayerToBalanceEntry.set(tx.data.feePayer.toString(), await FeePayerTxInfo.encode(tx, txHash));
 
-  private async addPendingTxIndices(tx: Tx, txHash: string): Promise<void> {
-    return await this.#store.transactionAsync(async () => {
-      await this.addPendingTxIndicesInDbTx(tx, txHash);
-    });
+    // Add nullifier entries for conflict detection
+    const nullifiers = tx.data.getNonEmptyNullifiers();
+    for (const nullifier of nullifiers) {
+      await this.#pendingNullifierToTxHash.set(nullifier.toString(), txHash);
+    }
   }
 
   // Assumes being called within a DB transaction
@@ -656,13 +693,16 @@ export class AztecKVTxPool
       (await tx.data.constants.anchorBlockHeader.hash()).toString(),
       txHash,
     );
-    await this.#feePayerToTxHash.deleteValue(tx.data.feePayer.toString(), txHash);
-  }
+    await this.#feePayerToBalanceEntry.deleteValue(
+      tx.data.feePayer.toString(),
+      await FeePayerTxInfo.encode(tx, txHash),
+    );
 
-  private async removePendingTxIndices(tx: Tx, txHash: string): Promise<void> {
-    return await this.#store.transactionAsync(async () => {
-      await this.removePendingTxIndicesInDbTx(tx, txHash);
-    });
+    // Remove nullifier entries
+    const nullifiers = tx.data.getNonEmptyNullifiers();
+    for (const nullifier of nullifiers) {
+      await this.#pendingNullifierToTxHash.delete(nullifier.toString());
+    }
   }
 
   /**
@@ -688,4 +728,19 @@ export class AztecKVTxPool
 
     return txsToEvict;
   }
+
+  /**
+   * Creates a PreAddPoolAccess object for use by pre-add eviction rules.
+   * Provides read-only access to pool state during addTxs transaction.
+   */
+  private getPreAddPoolAccess(): PreAddPoolAccess {
+    return {
+      getTxHashByNullifier: async nullifier => {
+        const hashStr = await this.#pendingNullifierToTxHash.getAsync(nullifier.toString());
+        return hashStr ? TxHash.fromString(hashStr) : undefined;
+      },
+      getPendingTxByHash: this.getTxByHash.bind(this),
+      getTxPriority: getPendingTxPriority,
+    };
+  }
 }

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

@@ -1,23 +1,36 @@
+import { findIndexInSortedArray, insertIntoSortedArray } from '@aztec/foundation/array';
 import { Fr } from '@aztec/foundation/curves/bn254';
 import { createLogger } from '@aztec/foundation/log';
 import type { AztecAddress } from '@aztec/stdlib/aztec-address';
-import { BlockHeader, TxHash } from '@aztec/stdlib/tx';
+import { BlockHeader, Tx, TxHash } from '@aztec/stdlib/tx';
 
 import type { TxPoolOptions } from '../tx_pool.js';
-import { type EvictionContext, EvictionEvent, type EvictionRule, type TxPoolOperations } from './eviction_strategy.js';
+import {
+  type EvictionContext,
+  EvictionEvent,
+  type EvictionRule,
+  type PreAddEvictionResult,
+  type PreAddEvictionRule,
+  type PreAddPoolAccess,
+  type TxPoolOperations,
+} from './eviction_strategy.js';
 
 export class EvictionManager {
   private rules: EvictionRule[] = [];
 
+  /** Pre-add eviction rules (run inside addTxs transaction) */
+  private preAddRules: PreAddEvictionRule[] = [];
+
   constructor(
     private txPool: TxPoolOperations,
     private log = createLogger('p2p:mempool:tx_pool:eviction_manager'),
   ) {}
 
-  public async evictAfterNewTxs(newTxs: TxHash[]): Promise<void> {
+  public async evictAfterNewTxs(newTxs: TxHash[], feePayers: AztecAddress[]): Promise<void> {
     const ctx: EvictionContext = {
       event: EvictionEvent.TXS_ADDED,
       newTxs,
+      feePayers,
     };
     await this.runEvictionRules(ctx);
   }
@@ -31,7 +44,7 @@ export class EvictionManager {
       event: EvictionEvent.BLOCK_MINED,
       block,
       newNullifiers,
-      minedFeePayers,
+      feePayers: minedFeePayers,
     };
 
     await this.runEvictionRules(ctx);
@@ -45,14 +58,61 @@ export class EvictionManager {
     await this.runEvictionRules(ctx);
   }
 
+  /**
+   * Runs pre-add eviction rules to determine if an incoming tx should be added
+   * and which existing txs should be evicted.
+   * Called from inside the addTxs database transaction for atomicity.
+   *
+   * @param tx - The incoming transaction
+   * @param poolAccess - Read-only access to pool state
+   * @returns Combined result from all pre-add rules
+   */
+  public async runPreAddRules(tx: Tx, poolAccess: PreAddPoolAccess): Promise<PreAddEvictionResult> {
+    const allTxHashesToEvict: TxHash[] = [];
+    const cmpTxHash = (a: TxHash, b: TxHash) => Fr.cmp(a.hash, b.hash);
+
+    for (const rule of this.preAddRules) {
+      try {
+        const result = await rule.check(tx, poolAccess);
+
+        if (result.shouldReject) {
+          return { shouldReject: true, txHashesToEvict: [], reason: result.reason };
+        }
+
+        for (const txHashToEvict of result.txHashesToEvict) {
+          // Only add if not already present (dedup)
+          if (findIndexInSortedArray(allTxHashesToEvict, txHashToEvict, cmpTxHash) === -1) {
+            insertIntoSortedArray(allTxHashesToEvict, txHashToEvict, cmpTxHash);
+          }
+        }
+      } catch (err) {
+        this.log.warn(`Pre-add eviction rule ${rule.name} unexpected error: ${String(err)}`, {
+          err,
+          preAddRule: rule.name,
+        });
+        // On error, reject the tx to be safe
+        return { shouldReject: true, txHashesToEvict: [], reason: `rule error: ${String(err)}` };
+      }
+    }
+
+    return { shouldReject: false, txHashesToEvict: allTxHashesToEvict };
+  }
+
   public registerRule(rule: EvictionRule) {
     this.rules.push(rule);
   }
 
+  public registerPreAddRule(rule: PreAddEvictionRule) {
+    this.preAddRules.push(rule);
+  }
+
   public updateConfig(config: TxPoolOptions): void {
     for (const rule of this.rules) {
       rule.updateConfig(config);
     }
+    for (const rule of this.preAddRules) {
+      rule.updateConfig?.(config);
+    }
   }
 
   private async runEvictionRules(ctx: EvictionContext): Promise<void> {

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

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