@aztec/p2p 0.0.1-commit.2eb6648a → 0.0.1-commit.343b43af6

package/src/mem_pools/tx_pool_v2/eviction/low_priority_eviction_rule.ts

@@ -5,7 +5,7 @@ import { EvictionEvent } from './interfaces.js';
 
 /**
  * Eviction rule that removes low-priority transactions when the pool exceeds configured limits.
- * Only triggers on TXS_ADDED events.
+ * Triggers on TXS_ADDED and CHAIN_PRUNED events.
  */
 export class LowPriorityEvictionRule implements EvictionRule {
   public readonly name = 'LowPriorityEviction';
@@ -18,7 +18,7 @@ export class LowPriorityEvictionRule implements EvictionRule {
   }
 
   async evict(context: EvictionContext, pool: PoolOperations): Promise<EvictionResult> {
-    if (context.event !== EvictionEvent.TXS_ADDED) {
+    if (context.event !== EvictionEvent.TXS_ADDED && context.event !== EvictionEvent.CHAIN_PRUNED) {
       return {
         reason: 'low_priority',
         success: true,
@@ -48,19 +48,24 @@ export class LowPriorityEvictionRule implements EvictionRule {
         };
       }
 
-      this.log.verbose(
-        `Evicting low priority txs. Pending tx count above limit: ${currentTxCount} > ${this.maxPoolSize}`,
-      );
+      this.log.info(`Evicting low priority txs. Pending tx count above limit: ${currentTxCount} > ${this.maxPoolSize}`);
       const numberToEvict = currentTxCount - this.maxPoolSize;
       const txsToEvict = pool.getLowestPriorityPending(numberToEvict);
 
       if (txsToEvict.length > 0) {
-        await pool.deleteTxs(txsToEvict);
+        if (context.event === EvictionEvent.TXS_ADDED) {
+          const toEvictSet = new Set(txsToEvict);
+          const numNewTxsEvicted = context.newTxHashes.filter(newTxHash => toEvictSet.has(newTxHash)).length;
+          this.log.info(`Evicted ${txsToEvict.length} low priority txs, including ${numNewTxsEvicted} newly added txs`);
+        } else {
+          this.log.info(`Evicted ${txsToEvict.length} low priority txs after chain prune`);
+        }
+        await pool.deleteTxs(txsToEvict, this.name);
       }
 
-      const numNewTxsEvicted = context.newTxHashes.filter(newTxHash => txsToEvict.includes(newTxHash)).length;
-
-      this.log.verbose(`Evicted ${txsToEvict.length} low priority txs, including ${numNewTxsEvicted} newly added txs`);
+      this.log.debug(`Evicted ${txsToEvict.length} low priority txs`, {
+        txHashes: txsToEvict,
+      });
 
       return {
         reason: 'low_priority',

package/src/mem_pools/tx_pool_v2/eviction/low_priority_pre_add_rule.ts

@@ -1,7 +1,14 @@
 import { createLogger } from '@aztec/foundation/log';
 
-import type { TxMetaData } from '../tx_metadata.js';
-import type { EvictionConfig, PreAddPoolAccess, PreAddResult, PreAddRule } from './interfaces.js';
+import { type TxMetaData, comparePriority, getMinimumPriceBumpFee } from '../tx_metadata.js';
+import {
+  type EvictionConfig,
+  type PreAddContext,
+  type PreAddPoolAccess,
+  type PreAddResult,
+  type PreAddRule,
+  TxPoolRejectionCode,
+} from './interfaces.js';
 
 /**
  * Pre-add rule that checks if the pool is at capacity and handles low-priority eviction.
@@ -20,7 +27,7 @@ export class LowPriorityPreAddRule implements PreAddRule {
     this.maxPoolSize = config.maxPoolSize;
   }
 
-  check(incomingMeta: TxMetaData, poolAccess: PreAddPoolAccess): Promise<PreAddResult> {
+  check(incomingMeta: TxMetaData, poolAccess: PreAddPoolAccess, context?: PreAddContext): Promise<PreAddResult> {
     // Skip if max pool size is disabled (0 = unlimited)
     if (this.maxPoolSize === 0) {
       return Promise.resolve({ shouldIgnore: false, txHashesToEvict: [] });
@@ -40,8 +47,18 @@ export class LowPriorityPreAddRule implements PreAddRule {
       return Promise.resolve({ shouldIgnore: false, txHashesToEvict: [] });
     }
 
-    // If incoming tx has strictly higher priority, evict the lowest priority tx
-    if (incomingMeta.priorityFee > lowestPriorityMeta.priorityFee) {
+    // Compare incoming tx against lowest priority tx.
+    // feeOnly mode (RPC): use strict fee comparison only — avoids churn from hash ordering.
+    // When price bump is also set, require the bumped fee threshold.
+    // Default (gossip): use full comparePriority (fee + tx hash tiebreaker) for determinism.
+    const isHigherPriority = context?.feeComparisonOnly
+      ? context.priceBumpPercentage !== undefined
+        ? incomingMeta.priorityFee >=
+          getMinimumPriceBumpFee(lowestPriorityMeta.priorityFee, context.priceBumpPercentage)
+        : incomingMeta.priorityFee > lowestPriorityMeta.priorityFee
+      : comparePriority(incomingMeta, lowestPriorityMeta) > 0;
+
+    if (isHigherPriority) {
       this.log.debug(
         `Pool at capacity (${currentCount}/${this.maxPoolSize}), evicting ${lowestPriorityMeta.txHash} ` +
           `(priority ${lowestPriorityMeta.priorityFee}) for ${incomingMeta.txHash} (priority ${incomingMeta.priorityFee})`,
@@ -53,6 +70,11 @@ export class LowPriorityPreAddRule implements PreAddRule {
     }
 
     // Incoming tx has equal or lower priority - ignore it (it would be evicted anyway)
+    const minimumFee =
+      context?.feeComparisonOnly && context.priceBumpPercentage !== undefined
+        ? getMinimumPriceBumpFee(lowestPriorityMeta.priorityFee, context.priceBumpPercentage)
+        : lowestPriorityMeta.priorityFee + 1n;
+
     this.log.debug(
       `Pool at capacity (${currentCount}/${this.maxPoolSize}), ignoring ${incomingMeta.txHash} ` +
         `(priority ${incomingMeta.priorityFee}) - lower than existing minimum (priority ${lowestPriorityMeta.priorityFee})`,
@@ -60,7 +82,12 @@ export class LowPriorityPreAddRule implements PreAddRule {
     return Promise.resolve({
       shouldIgnore: true,
       txHashesToEvict: [],
-      reason: `pool at capacity and tx has lower priority than existing transactions`,
+      reason: {
+        code: TxPoolRejectionCode.LOW_PRIORITY_FEE,
+        message: `Tx does not meet minimum priority fee. Required: ${minimumFee}, got: ${incomingMeta.priorityFee}`,
+        minimumPriorityFee: minimumFee,
+        txPriorityFee: incomingMeta.priorityFee,
+      },
     });
   }
 

package/src/mem_pools/tx_pool_v2/eviction/nullifier_conflict_rule.ts

@@ -1,7 +1,7 @@
 import { createLogger } from '@aztec/foundation/log';
 
 import { type TxMetaData, checkNullifierConflict } from '../tx_metadata.js';
-import type { PreAddPoolAccess, PreAddResult, PreAddRule } from './interfaces.js';
+import type { PreAddContext, PreAddPoolAccess, PreAddResult, PreAddRule } from './interfaces.js';
 
 /**
  * Pre-add rule that checks for nullifier conflicts between incoming and existing transactions.
@@ -15,15 +15,16 @@ export class NullifierConflictRule implements PreAddRule {
 
   private log = createLogger('p2p:tx_pool_v2:nullifier_conflict_rule');
 
-  check(incomingMeta: TxMetaData, poolAccess: PreAddPoolAccess): Promise<PreAddResult> {
+  check(incomingMeta: TxMetaData, poolAccess: PreAddPoolAccess, context?: PreAddContext): Promise<PreAddResult> {
     const result = checkNullifierConflict(
       incomingMeta,
       nullifier => poolAccess.getTxHashByNullifier(nullifier),
       txHash => poolAccess.getMetadata(txHash),
+      context?.priceBumpPercentage,
     );
 
     if (result.shouldIgnore) {
-      this.log.debug(`Ignoring tx ${incomingMeta.txHash}: ${result.reason}`);
+      this.log.debug(`Ignoring tx ${incomingMeta.txHash}: ${result.reason?.message}`);
     }
 
     return Promise.resolve(result);

package/src/mem_pools/tx_pool_v2/index.ts

@@ -7,5 +7,6 @@ export {
   type PoolReadAccess,
   DEFAULT_TX_POOL_V2_CONFIG,
 } from './interfaces.js';
-export { type TxMetaData, type TxState, buildTxMetaData, comparePriority } from './tx_metadata.js';
+export { type TxMetaData, type TxState, buildTxMetaData, comparePriority, stubTxMetaData } from './tx_metadata.js';
 export { TxArchive } from './archive/index.js';
+export { DeletedPool } from './deleted_pool.js';

package/src/mem_pools/tx_pool_v2/instrumentation.ts

@@ -0,0 +1,69 @@
+import {
+  Attributes,
+  type Meter,
+  Metrics,
+  type ObservableGauge,
+  type ObservableResult,
+  type TelemetryClient,
+  type UpDownCounter,
+  createUpDownCounterWithDefault,
+} from '@aztec/telemetry-client';
+
+/** Callback that returns the current estimated metadata memory in bytes. */
+export type MetadataMemoryCallback = () => number;
+
+/** Instrumentation for TxPoolV2Impl internal operations. */
+export class TxPoolV2Instrumentation {
+  #evictedCounter: UpDownCounter;
+  #ignoredCounter: UpDownCounter;
+  #rejectedCounter: UpDownCounter;
+  #softDeletedHitsCounter: UpDownCounter;
+  #missingOnProtectCounter: UpDownCounter;
+  #missingPreviouslyEvictedCounter: UpDownCounter;
+  #metadataMemoryGauge: ObservableGauge;
+
+  constructor(telemetry: TelemetryClient, metadataMemoryCallback: MetadataMemoryCallback) {
+    const meter: Meter = telemetry.getMeter('TxPoolV2Impl');
+
+    this.#evictedCounter = createUpDownCounterWithDefault(meter, Metrics.MEMPOOL_TX_POOL_V2_EVICTED_COUNT);
+    this.#ignoredCounter = createUpDownCounterWithDefault(meter, Metrics.MEMPOOL_TX_POOL_V2_IGNORED_COUNT);
+    this.#rejectedCounter = createUpDownCounterWithDefault(meter, Metrics.MEMPOOL_TX_POOL_V2_REJECTED_COUNT);
+    this.#softDeletedHitsCounter = createUpDownCounterWithDefault(meter, Metrics.MEMPOOL_TX_POOL_V2_SOFT_DELETED_HITS);
+    this.#missingOnProtectCounter = createUpDownCounterWithDefault(
+      meter,
+      Metrics.MEMPOOL_TX_POOL_V2_MISSING_ON_PROTECT,
+    );
+    this.#missingPreviouslyEvictedCounter = createUpDownCounterWithDefault(
+      meter,
+      Metrics.MEMPOOL_TX_POOL_V2_MISSING_PREVIOUSLY_EVICTED,
+    );
+    this.#metadataMemoryGauge = meter.createObservableGauge(Metrics.MEMPOOL_TX_POOL_V2_METADATA_MEMORY);
+    this.#metadataMemoryGauge.addCallback((result: ObservableResult) => {
+      result.observe(metadataMemoryCallback());
+    });
+  }
+
+  recordEvictions(count: number, reason: string) {
+    this.#evictedCounter.add(count, { [Attributes.TX_POOL_EVICTION_REASON]: reason });
+  }
+
+  recordIgnored(count: number) {
+    this.#ignoredCounter.add(count);
+  }
+
+  recordRejected(count: number) {
+    this.#rejectedCounter.add(count);
+  }
+
+  recordSoftDeletedHits(count: number) {
+    this.#softDeletedHitsCounter.add(count);
+  }
+
+  recordMissingOnProtect(count: number) {
+    this.#missingOnProtectCounter.add(count);
+  }
+
+  recordMissingPreviouslyEvicted(count: number) {
+    this.#missingPreviouslyEvictedCounter.add(count);
+  }
+}

package/src/mem_pools/tx_pool_v2/interfaces.ts

@@ -4,6 +4,7 @@ import type { L2Block, L2BlockId, L2BlockSource } from '@aztec/stdlib/block';
 import type { WorldStateSynchronizer } from '@aztec/stdlib/interfaces/server';
 import type { BlockHeader, Tx, TxHash, TxValidator } from '@aztec/stdlib/tx';
 
+import type { TxPoolRejectionError } from './eviction/interfaces.js';
 import type { TxMetaData, TxState } from './tx_metadata.js';
 
 /**
@@ -17,6 +18,8 @@ export type AddTxsResult = {
   ignored: TxHash[];
   /** Transactions rejected because they failed validation (e.g., invalid proof, expired timestamp) */
   rejected: TxHash[];
+  /** Optional rejection errors, only present when there are rejections with structured errors. */
+  errors?: Map<string, TxPoolRejectionError>;
 };
 
 /**
@@ -37,6 +40,14 @@ export type TxPoolV2Config = {
   maxPendingTxCount: number;
   /** Maximum number of archived transactions to retain (0 = disabled) */
   archivedTxLimit: number;
+  /** Minimum age (ms) a transaction must have been in the pool before it's eligible for block building */
+  minTxPoolAgeMs: number;
+  /** Maximum number of evicted tx hashes to remember for metrics tracking */
+  evictedTxCacheSize: number;
+  /** The probability (0-1) that a transaction is discarded. 0 disables dropping. For testing purposes only. */
+  dropTransactionsProbability: number;
+  /** Minimum percentage fee increase required to replace an existing tx via RPC (0 = no bump). */
+  priceBumpPercentage: bigint;
 };
 
 /**
@@ -45,6 +56,10 @@ export type TxPoolV2Config = {
 export const DEFAULT_TX_POOL_V2_CONFIG: TxPoolV2Config = {
   maxPendingTxCount: 0, // 0 = disabled
   archivedTxLimit: 0, // 0 = disabled
+  minTxPoolAgeMs: 2_000,
+  evictedTxCacheSize: 10_000,
+  dropTransactionsProbability: 0,
+  priceBumpPercentage: 10n,
 };
 
 /**
@@ -55,8 +70,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>>;
 };
 
 /**
@@ -95,15 +110,15 @@ export interface TxPoolV2 extends TypedEventEmitter<TxPoolV2Events> {
    * @param opts - Optional metadata (e.g., source for logging)
    * @returns Result categorizing each transaction as accepted, rejected, or ignored
    */
-  addPendingTxs(txs: Tx[], opts?: { source?: string }): Promise<AddTxsResult>;
+  addPendingTxs(txs: Tx[], opts?: { source?: string; feeComparisonOnly?: boolean }): Promise<AddTxsResult>;
 
   /**
-   * Checks if a transaction can be added without modifying the pool.
-   * Performs the same validation as addPendingTxs but doesn't persist changes.
+   * Checks if the pool would accept a transaction without modifying state.
+   * Used as a pre-check before expensive proof verification.
    * @param tx - Transaction to check
-   * @returns Result: 'accepted', 'ignored' (if already in pool or undesirable), or 'rejected' (if validation fails)
+   * @returns 'accepted' if the pool would accept, 'ignored' if already in pool or undesirable
    */
-  canAddPendingTx(tx: Tx): Promise<'accepted' | 'ignored' | 'rejected'>;
+  canAddPendingTx(tx: Tx): Promise<'accepted' | 'ignored'>;
 
   /**
    * Adds transactions as immediately protected for a given slot.
@@ -156,7 +171,7 @@ export interface TxPoolV2 extends TypedEventEmitter<TxPoolV2Events> {
    * and validates them before returning to pending.
    * @param latestBlock - The latest valid block ID after the prune
    */
-  handlePrunedBlocks(latestBlock: L2BlockId): Promise<void>;
+  handlePrunedBlocks(latestBlock: L2BlockId, options?: { deleteAllTxs?: boolean }): Promise<void>;
 
   /**
    * Handles failed transaction execution.
@@ -187,6 +202,9 @@ export interface TxPoolV2 extends TypedEventEmitter<TxPoolV2Events> {
   /** Gets pending transaction hashes sorted by priority (highest first) */
   getPendingTxHashes(): Promise<TxHash[]>;
 
+  /** Gets pending transaction hashes that have been in the pool long enough per minTxPoolAgeMs, sorted by priority (highest first) */
+  getEligiblePendingTxHashes(): Promise<TxHash[]>;
+
   /** Gets the count of pending transactions */
   getPendingTxCount(): Promise<number>;
 

package/src/mem_pools/tx_pool_v2/tx_metadata.ts

@@ -1,11 +1,32 @@
+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 type { Tx } from '@aztec/stdlib/tx';
+import { BlockHash, type L2BlockId } from '@aztec/stdlib/block';
+import { Gas } from '@aztec/stdlib/gas';
+import { type Tx, TxHash } 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';
+import { type PreAddResult, TxPoolRejectionCode } from './eviction/interfaces.js';
+
+/** Validator-compatible data interface, mirroring the subset of PrivateKernelTailCircuitPublicInputs used by validators. */
+export type TxMetaValidationData = {
+  getNonEmptyNullifiers(): Fr[];
+  expirationTimestamp: bigint;
+  /** Whether the tx has public calls. Used to select the correct L2 gas minimum. */
+  forPublic?: unknown;
+  constants: {
+    anchorBlockHeader: {
+      hash(): Promise<BlockHash>;
+      globalVariables: {
+        blockNumber: BlockNumber;
+      };
+    };
+    txContext: {
+      gasSettings: { gasLimits: Gas };
+    };
+  };
+};
 
 /**
  * Lightweight in-memory representation of a transaction.
@@ -19,6 +40,9 @@ export type TxMetaData = {
   /** The transaction hash as hex string */
   readonly txHash: string;
 
+  /** The transaction hash as bigint (for efficient Fr conversion in comparisons) */
+  readonly txHashBigInt: bigint;
+
   /** Block ID (number and hash) in which the transaction was mined (undefined if not mined) */
   minedL2BlockId?: L2BlockId;
 
@@ -41,46 +65,106 @@ export type TxMetaData = {
   readonly nullifiers: readonly string[];
 
   /** Timestamp by which the transaction must be included (for expiration checks) */
-  readonly includeByTimestamp: bigint;
+  readonly expirationTimestamp: bigint;
+
+  /** Validator-compatible data, providing the same access patterns as Tx.data */
+  readonly data: TxMetaValidationData;
+
+  /** Timestamp (ms) when the tx was received into the pool. 0 for hydrated txs (always eligible). */
+  receivedAt: number;
+
+  /** Estimated memory footprint of this metadata object in bytes */
+  readonly estimatedSizeBytes: number;
 };
 
 /** 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 txHashObj = tx.getTxHash();
+  const txHash = txHashObj.toString();
+  const txHashBigInt = txHashObj.toBigInt();
+  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 expirationTimestamp = tx.data.expirationTimestamp;
+  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);
 
+  const estimatedSizeBytes = estimateTxMetaDataSize(nullifiers.length);
+
   return {
     txHash,
+    txHashBigInt,
     anchorBlockHeaderHash,
     priorityFee,
     feePayer,
     claimAmount,
     feeLimit,
     nullifiers,
-    includeByTimestamp,
+    expirationTimestamp,
+    receivedAt: 0,
+    estimatedSizeBytes,
+    data: {
+      getNonEmptyNullifiers: () => nullifierFrs,
+      expirationTimestamp,
+      forPublic: !!tx.data.forPublic,
+      constants: {
+        anchorBlockHeader: {
+          hash: () => Promise.resolve(anchorBlockHeaderHashFr),
+          globalVariables: { blockNumber: anchorBlockNumber },
+        },
+        txContext: {
+          gasSettings: { gasLimits: tx.data.constants.txContext.gasSettings.gasLimits },
+        },
+      },
+    },
   };
 }
 
+// V8 JS object overhead (~64 bytes for a plain object with hidden class).
+// String overhead: ~32 bytes header + 1 byte per ASCII char (V8 one-byte strings).
+// Hex string (0x + 64 hex chars = 66 chars): ~98 bytes per string.
+// bigint: ~32 bytes. number: 8 bytes. Fr: ~80 bytes (32 data + object overhead).
+const OBJECT_OVERHEAD = 64;
+const HEX_STRING_BYTES = 98;
+const BIGINT_BYTES = 32;
+const FR_BYTES = 80;
+// Fixed cost: object shell + txHash + anchorBlockHeaderHash + feePayer (3 hex strings)
+// + txHashBigInt + priorityFee + claimAmount + feeLimit + includeByTimestamp (5 bigints)
+// + receivedAt (number, 8 bytes) + estimatedSizeBytes (number, 8 bytes)
+// + data closure object (~OBJECT_OVERHEAD + anchorBlockHeaderHashFr Fr + anchorBlockNumber number)
+const FIXED_METADATA_BYTES =
+  OBJECT_OVERHEAD + 3 * HEX_STRING_BYTES + 5 * BIGINT_BYTES + 8 + 8 + OBJECT_OVERHEAD + FR_BYTES + 8;
+
+/** Estimates the in-memory size of a TxMetaData object based on the number of nullifiers. */
+function estimateTxMetaDataSize(nullifierCount: number): number {
+  // Per nullifier: one hex string in nullifiers[] + one Fr in the captured nullifierFrs[]
+  return FIXED_METADATA_BYTES + nullifierCount * (HEX_STRING_BYTES + FR_BYTES);
+}
+
+/** Converts a txHash bigint back to the canonical 0x-prefixed 64-char hex string. */
+export function txHashFromBigInt(value: bigint): string {
+  return TxHash.fromBigInt(value).toString();
+}
+
 /** Minimal fields required for priority comparison. */
-type PriorityComparable = Pick<TxMetaData, 'txHash' | 'priorityFee'>;
+export type PriorityComparable = Pick<TxMetaData, 'txHash' | 'txHashBigInt' | 'priorityFee'>;
 
 /**
  * Compares two priority fees in ascending order.
  * Returns negative if a < b, positive if a > b, 0 if equal.
  */
-export function compareFee(a: bigint, b: bigint): number {
+export function compareFee(a: bigint, b: bigint): -1 | 0 | 1 {
   return a < b ? -1 : a > b ? 1 : 0;
 }
 
@@ -89,10 +173,8 @@ export function compareFee(a: bigint, b: bigint): number {
  * Uses field element comparison for deterministic ordering.
  * Returns negative if a < b, positive if a > b, 0 if equal.
  */
-export function compareTxHash(a: string, b: string): number {
-  const fieldA = Fr.fromHexString(a);
-  const fieldB = Fr.fromHexString(b);
-  return fieldA.cmp(fieldB);
+export function compareTxHash(a: bigint, b: bigint): -1 | 0 | 1 {
+  return Fr.cmpAsBigInt(a, b);
 }
 
 /**
@@ -100,29 +182,46 @@ export function compareTxHash(a: string, b: string): number {
  * Returns negative if a < b, positive if a > b, 0 if equal.
  * Use with sort() for ascending order, or negate/reverse for descending.
  */
-export function comparePriority(a: PriorityComparable, b: PriorityComparable): number {
+export function comparePriority(a: PriorityComparable, b: PriorityComparable): -1 | 0 | 1 {
   const feeComparison = compareFee(a.priorityFee, b.priorityFee);
   if (feeComparison !== 0) {
     return feeComparison;
   }
-  return compareTxHash(a.txHash, b.txHash);
+  return compareTxHash(a.txHashBigInt, b.txHashBigInt);
+}
+
+/**
+ * Returns the minimum fee required to replace an existing tx with the given price bump percentage.
+ * Uses integer arithmetic: `existingFee + existingFee * priceBumpPercentage / 100`.
+ */
+export function getMinimumPriceBumpFee(existingFee: bigint, priceBumpPercentage: bigint): bigint {
+  const bump = (existingFee * priceBumpPercentage) / 100n;
+  // Ensure the minimum bump is at least 1, so that replacement always requires
+  // paying strictly more — even with 0% bump or zero existing fee.
+  const effectiveBump = bump > 0n ? bump : 1n;
+  return existingFee + effectiveBump;
 }
 
 /**
  * Checks for nullifier conflicts between an incoming transaction and existing pool state.
  *
  * When the incoming tx shares nullifiers with existing pending txs:
- * - If the incoming tx has strictly higher priority, mark conflicting txs for eviction
- * - If any conflicting tx has equal or higher priority, ignore the incoming tx
+ * - If the incoming tx meets or exceeds the required priority, mark conflicting txs for eviction
+ * - Otherwise, ignore the incoming tx
+ *
+ * When `priceBumpPercentage` is provided (RPC path), uses fee-only comparison with the
+ * percentage bump instead of `comparePriority`.
  *
  * @param incomingMeta - Metadata for the incoming transaction
  * @param getTxHashByNullifier - Accessor to find which tx uses a nullifier
  * @param getMetadata - Accessor to get metadata for a tx hash
+ * @param priceBumpPercentage - Optional percentage bump required for fee-based replacement
  */
 export function checkNullifierConflict(
   incomingMeta: TxMetaData,
   getTxHashByNullifier: (nullifier: string) => string | undefined,
   getMetadata: (txHash: string) => TxMetaData | undefined,
+  priceBumpPercentage?: bigint,
 ): PreAddResult {
   const txHashesToEvict: string[] = [];
 
@@ -143,19 +242,86 @@ export function checkNullifierConflict(
       continue;
     }
 
-    // If incoming tx has strictly higher priority, mark for eviction
-    // Otherwise, ignore incoming tx (ties go to existing tx)
-    // Use comparePriority for deterministic ordering (includes txHash as tiebreaker)
-    if (comparePriority(incomingMeta, conflictingMeta) > 0) {
+    // When price bump is set (RPC path), require the incoming fee to meet the bumped threshold.
+    // Otherwise (P2P path), use full comparePriority with tx hash tiebreaker.
+    const isHigherPriority =
+      priceBumpPercentage !== undefined
+        ? incomingMeta.priorityFee >= getMinimumPriceBumpFee(conflictingMeta.priorityFee, priceBumpPercentage)
+        : comparePriority(incomingMeta, conflictingMeta) > 0;
+
+    if (isHigherPriority) {
       txHashesToEvict.push(conflictingHashStr);
     } else {
+      const minimumFee =
+        priceBumpPercentage !== undefined
+          ? getMinimumPriceBumpFee(conflictingMeta.priorityFee, priceBumpPercentage)
+          : undefined;
       return {
         shouldIgnore: true,
         txHashesToEvict: [],
-        reason: `nullifier conflict with ${conflictingHashStr}`,
+        reason: {
+          code: TxPoolRejectionCode.NULLIFIER_CONFLICT,
+          message:
+            minimumFee !== undefined
+              ? `Nullifier conflict with existing tx ${conflictingHashStr}. Minimum required fee: ${minimumFee}, got: ${incomingMeta.priorityFee}`
+              : `Nullifier conflict with existing tx ${conflictingHashStr}`,
+          conflictingTxHash: conflictingHashStr,
+          minimumPriceBumpFee: minimumFee,
+          txPriorityFee: minimumFee !== undefined ? incomingMeta.priorityFee : undefined,
+        },
       };
     }
   }
 
   return { shouldIgnore: false, txHashesToEvict };
 }
+
+/** Creates a stub TxMetaValidationData for tests that don't exercise validators. */
+export function stubTxMetaValidationData(overrides: { expirationTimestamp?: bigint } = {}): TxMetaValidationData {
+  return {
+    getNonEmptyNullifiers: () => [],
+    expirationTimestamp: overrides.expirationTimestamp ?? 0n,
+    constants: {
+      anchorBlockHeader: {
+        hash: () => Promise.resolve(new BlockHash(Fr.ZERO)),
+        globalVariables: { blockNumber: BlockNumber(0) },
+      },
+      txContext: {
+        gasSettings: { gasLimits: Gas.empty() },
+      },
+    },
+  };
+}
+
+/** Creates a stub TxMetaData for tests. All fields have sensible defaults and can be overridden. */
+export function stubTxMetaData(
+  txHash: string,
+  overrides: {
+    priorityFee?: bigint;
+    feePayer?: string;
+    claimAmount?: bigint;
+    feeLimit?: bigint;
+    nullifiers?: string[];
+    expirationTimestamp?: bigint;
+    anchorBlockHeaderHash?: string;
+  } = {},
+): TxMetaData {
+  const txHashBigInt = Fr.fromHexString(txHash).toBigInt();
+  // Normalize to canonical zero-padded hex so txHashFromBigInt(txHashBigInt) === normalizedTxHash
+  const normalizedTxHash = txHashFromBigInt(txHashBigInt);
+  const expirationTimestamp = overrides.expirationTimestamp ?? 0n;
+  return {
+    txHash: normalizedTxHash,
+    txHashBigInt,
+    anchorBlockHeaderHash: overrides.anchorBlockHeaderHash ?? '0x1234',
+    priorityFee: overrides.priorityFee ?? 100n,
+    feePayer: overrides.feePayer ?? '0xfeepayer',
+    claimAmount: overrides.claimAmount ?? 0n,
+    feeLimit: overrides.feeLimit ?? 100n,
+    nullifiers: overrides.nullifiers ?? [`0x${normalizedTxHash.slice(2)}null1`],
+    expirationTimestamp,
+    receivedAt: 0,
+    estimatedSizeBytes: 0,
+    data: stubTxMetaValidationData({ expirationTimestamp }),
+  };
+}