@aztec/p2p 0.0.1-commit.358457c → 0.0.1-commit.3750d92a7

package/src/mem_pools/tx_pool_v2/index.ts

@@ -7,6 +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/interfaces.ts

@@ -46,6 +46,8 @@ export type TxPoolV2Config = {
   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;
 };
 
 /**
@@ -57,6 +59,7 @@ export const DEFAULT_TX_POOL_V2_CONFIG: TxPoolV2Config = {
   minTxPoolAgeMs: 2_000,
   evictedTxCacheSize: 10_000,
   dropTransactionsProbability: 0,
+  priceBumpPercentage: 10n,
 };
 
 /**
@@ -69,6 +72,8 @@ export type TxPoolV2Dependencies = {
   worldStateSynchronizer: WorldStateSynchronizer;
   /** Factory that creates a validator for re-validating pool transactions using metadata */
   createTxValidator: () => Promise<TxValidator<TxMetaData>>;
+  /** Checks whether a tx's setup-phase calls are on the allow list. Precomputed at receipt time. */
+  checkAllowedSetupCalls: (tx: Tx) => Promise<boolean>;
 };
 
 /**
@@ -155,10 +160,10 @@ export interface TxPoolV2 extends TypedEventEmitter<TxPoolV2Events> {
   handleMinedBlock(block: L2Block): Promise<void>;
 
   /**
-   * Prepares the pool for a new slot.
-   * Unprotects transactions from earlier slots and validates them before
-   * returning to pending state.
-   * @param slotNumber - The slot number to prepare for
+   * Prepares the pool for a new slot by unprotecting transactions from earlier
+   * slots and re-validating them before returning to pending state.
+   * @param slotNumber - The pipeline slot we are building for (i.e. the slot
+   *   the resulting blocks will target on L1).
    */
   prepareForSlot(slotNumber: SlotNumber): Promise<void>;
 

package/src/mem_pools/tx_pool_v2/tx_metadata.ts

@@ -1,12 +1,12 @@
+import { minBigint } from '@aztec/foundation/bigint';
 import { BlockNumber } from '@aztec/foundation/branded-types';
 import { Fr } from '@aztec/foundation/curves/bn254';
 import { ProtocolContractAddress } from '@aztec/protocol-contracts';
 import { BlockHash, type L2BlockId } from '@aztec/stdlib/block';
 import { Gas } from '@aztec/stdlib/gas';
-import type { Tx } from '@aztec/stdlib/tx';
+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, TxPoolRejectionCode } from './eviction/interfaces.js';
 
 /** Validator-compatible data interface, mirroring the subset of PrivateKernelTailCircuitPublicInputs used by validators. */
@@ -40,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;
 
@@ -64,6 +67,9 @@ export type TxMetaData = {
   /** Timestamp by which the transaction must be included (for expiration checks) */
   readonly expirationTimestamp: bigint;
 
+  /** Whether the tx's setup-phase calls pass the allow list check. Computed at receipt time. */
+  readonly allowedSetupCalls: boolean;
+
   /** Validator-compatible data, providing the same access patterns as Tx.data */
   readonly data: TxMetaValidationData;
 
@@ -81,9 +87,15 @@ 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.
+ *
+ * @param allowedSetupCalls - Whether the tx's setup-phase calls pass the allow list.
+ *   For gossip/RPC txs this is always `true` (already validated by PhasesTxValidator).
+ *   For req/resp txs this should be computed by the caller using the phases validator.
  */
-export async function buildTxMetaData(tx: Tx): Promise<TxMetaData> {
-  const txHash = tx.getTxHash().toString();
+export async function buildTxMetaData(tx: Tx, allowedSetupCalls: boolean = true): Promise<TxMetaData> {
+  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();
@@ -99,6 +111,7 @@ export async function buildTxMetaData(tx: Tx): Promise<TxMetaData> {
 
   return {
     txHash,
+    txHashBigInt,
     anchorBlockHeaderHash,
     priorityFee,
     feePayer,
@@ -106,6 +119,7 @@ export async function buildTxMetaData(tx: Tx): Promise<TxMetaData> {
     feeLimit,
     nullifiers,
     expirationTimestamp,
+    allowedSetupCalls,
     receivedAt: 0,
     estimatedSizeBytes,
     data: {
@@ -134,11 +148,11 @@ const HEX_STRING_BYTES = 98;
 const BIGINT_BYTES = 32;
 const FR_BYTES = 80;
 // Fixed cost: object shell + txHash + anchorBlockHeaderHash + feePayer (3 hex strings)
-// + priorityFee + claimAmount + feeLimit + includeByTimestamp (4 bigints)
+// + 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 + 4 * BIGINT_BYTES + 8 + 8 + OBJECT_OVERHEAD + FR_BYTES + 8;
+  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 {
@@ -146,14 +160,19 @@ function estimateTxMetaDataSize(nullifierCount: number): number {
   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;
 }
 
@@ -162,10 +181,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);
 }
 
 /**
@@ -173,29 +190,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[] = [];
 
@@ -216,19 +250,32 @@ 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: {
           code: TxPoolRejectionCode.NULLIFIER_CONFLICT,
-          message: `Nullifier conflict with existing tx ${conflictingHashStr}`,
+          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,
         },
       };
     }
@@ -244,7 +291,7 @@ export function stubTxMetaValidationData(overrides: { expirationTimestamp?: bigi
     expirationTimestamp: overrides.expirationTimestamp ?? 0n,
     constants: {
       anchorBlockHeader: {
-        hash: () => Promise.resolve(new BlockHash(Fr.ZERO)),
+        hash: () => Promise.resolve(BlockHash.ZERO),
         globalVariables: { blockNumber: BlockNumber(0) },
       },
       txContext: {
@@ -253,3 +300,44 @@ export function stubTxMetaValidationData(overrides: { expirationTimestamp?: bigi
     },
   };
 }
+
+/** 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;
+    allowedSetupCalls?: boolean;
+  } = {},
+): 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,
+    allowedSetupCalls: overrides.allowedSetupCalls ?? true,
+    receivedAt: 0,
+    estimatedSizeBytes: 0,
+    data: stubTxMetaValidationData({ expirationTimestamp }),
+  };
+}
+
+/** Returns the priority fee for a tx, based on the L2 priority fee capped by the max fee per gas. */
+function getTxPriorityFee(tx: Tx): bigint {
+  const { maxPriorityFeesPerGas: priorityFees, maxFeesPerGas } = tx.getGasSettings();
+  return minBigint(maxFeesPerGas.feePerL2Gas, priorityFees.feePerL2Gas);
+}

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> {