@aztec/p2p 0.0.1-commit.993d52e → 0.0.1-commit.9a89641

package/src/mem_pools/instrumentation.ts

@@ -1,5 +1,4 @@
 import type { Gossipable } from '@aztec/stdlib/p2p';
-import type { Tx } from '@aztec/stdlib/tx';
 import {
   Attributes,
   type BatchObservableResult,
@@ -73,7 +72,7 @@ export class PoolInstrumentation<PoolObject extends Gossipable> {
   private defaultAttributes;
   private meter: Meter;
 
-  private txAddedTimestamp: Map<bigint, number> = new Map<bigint, number>();
+  private mempoolItemAddedTimestamp: Map<bigint | string, number> = new Map<bigint | string, number>();
 
   constructor(
     telemetry: TelemetryClient,
@@ -100,7 +99,11 @@ export class PoolInstrumentation<PoolObject extends Gossipable> {
 
     this.addObjectCounter = createUpDownCounterWithDefault(this.meter, metricsLabels.itemsAdded);
 
-    this.minedDelay = this.meter.createHistogram(metricsLabels.itemMinedDelay);
+    this.minedDelay = this.meter.createHistogram(metricsLabels.itemMinedDelay, {
+      advice: {
+        explicitBucketBoundaries: [100, 500, 1000, 5000, 10000, 30000, 60000, 300000, 600000, 1800000, 3600000],
+      },
+    });
 
     this.meter.addBatchObservableCallback(this.observeStats, [this.objectsInMempool]);
   }
@@ -113,27 +116,34 @@ export class PoolInstrumentation<PoolObject extends Gossipable> {
     this.addObjectCounter.add(count);
   }
 
-  public transactionsAdded(transactions: Tx[]) {
-    const timestamp = Date.now();
-    for (const transaction of transactions) {
-      this.txAddedTimestamp.set(transaction.txHash.toBigInt(), timestamp);
-    }
+  public trackMempoolItemAdded(key: bigint | string): void {
+    this.mempoolItemAddedTimestamp.set(key, Date.now());
   }
 
-  public transactionsRemoved(hashes: Iterable<bigint> | Iterable<string>) {
+  public trackMempoolItemRemoved(key: bigint | string): void {
     const timestamp = Date.now();
-    for (const hash of hashes) {
-      const key = BigInt(hash);
-      const addedAt = this.txAddedTimestamp.get(key);
-      if (addedAt !== undefined) {
-        this.txAddedTimestamp.delete(key);
-        if (addedAt < timestamp) {
-          this.minedDelay.record(timestamp - addedAt);
-        }
+    const addedAt = this.mempoolItemAddedTimestamp.get(key);
+    if (addedAt !== undefined) {
+      this.mempoolItemAddedTimestamp.delete(key);
+      if (addedAt < timestamp) {
+        this.minedDelay.record(timestamp - addedAt);
       }
     }
   }
 
+  /**
+   * Records a pre-computed pending-to-mined delay directly, bypassing the
+   * `mempoolItemAddedTimestamp` map. Used by the tx pool, which derives the
+   * delay from the persisted `receivedAt` on tx metadata at the mined
+   * transition — more accurate than the add/remove map (which also fires on
+   * eviction) and resilient to the caller not having tracked the add.
+   */
+  public recordMinedDelay(delayMs: number): void {
+    if (delayMs > 0) {
+      this.minedDelay.record(delayMs);
+    }
+  }
+
   private observeStats = async (observer: BatchObservableResult) => {
     const { itemCount } = await this.poolStats();
     if (typeof itemCount === 'number') {

package/src/mem_pools/tx_pool_v2/archive/tx_archive.ts

@@ -1,6 +1,5 @@
 import { type Logger, createLogger } from '@aztec/foundation/log';
 import type { AztecAsyncKVStore, AztecAsyncMap } from '@aztec/kv-store';
-import { ChonkProof } from '@aztec/stdlib/proofs';
 import { Tx, TxHash } from '@aztec/stdlib/tx';
 
 /**
@@ -70,7 +69,7 @@ export class TxArchive {
           }
 
           // Archive the transaction with stripped proof
-          const archivedTx = this.stripProof(tx);
+          const archivedTx = tx.withoutProof();
           const txHash = tx.getTxHash().toString();
           await this.#txs.set(txHash, archivedTx.toBuffer());
           await this.#indices.set(headIdx, txHash);
@@ -101,13 +100,6 @@ export class TxArchive {
     return head - tail;
   }
 
-  /**
-   * Strips the proof from a transaction for archival.
-   */
-  private stripProof(tx: Tx): Tx {
-    return new Tx(tx.txHash, tx.data, ChonkProof.empty(), tx.contractClassLogFields, tx.publicFunctionCalldata);
-  }
-
   private async getHeadIndex(): Promise<number> {
     const entry = await this.#indices.entriesAsync({ limit: 1, reverse: true }).next();
     return (entry.value?.[0] ?? -1) + 1;

package/src/mem_pools/tx_pool_v2/deleted_pool.ts

@@ -52,8 +52,8 @@ export class DeletedPool {
   /** Persisted map: txHash -> DeletedTxState (serialized) - for prune-based soft deletions */
   #deletedTxsDB: AztecAsyncMap<string, Buffer>;
 
-  /** Reference to the main txs database for hard deletion */
-  #txsDB: AztecAsyncMap<string, Buffer>;
+  /** Hard-deletes a tx's stored data (tx blob and proof) from the pool's stores. */
+  #deleteTxData: (txHash: string) => Promise<void>;
 
   /** In-memory state for transactions from pruned blocks */
   #state: Map<string, DeletedTxState> = new Map();
@@ -69,10 +69,10 @@ export class DeletedPool {
 
   #log: Logger;
 
-  constructor(store: AztecAsyncKVStore, txsDB: AztecAsyncMap<string, Buffer>, log: Logger) {
+  constructor(store: AztecAsyncKVStore, deleteTxData: (txHash: string) => Promise<void>, log: Logger) {
     this.#deletedTxsDB = store.openMap('deleted_txs');
     this.#slotDeletedDB = store.openSet('slot_deleted_txs');
-    this.#txsDB = txsDB;
+    this.#deleteTxData = deleteTxData;
     this.#log = log;
   }
 
@@ -100,7 +100,7 @@ export class DeletedPool {
     // Slot-deleted txs are stale after restart - hard-delete them all
     let slotDeletedCount = 0;
     for await (const txHash of this.#slotDeletedDB.entriesAsync()) {
-      await this.#txsDB.delete(txHash);
+      await this.#deleteTxData(txHash);
       await this.#slotDeletedDB.delete(txHash);
       slotDeletedCount++;
     }
@@ -234,7 +234,7 @@ export class DeletedPool {
     for (const txHash of toHardDelete) {
       this.#state.delete(txHash);
       await this.#deletedTxsDB.delete(txHash);
-      await this.#txsDB.delete(txHash);
+      await this.#deleteTxData(txHash);
     }
 
     this.#log.debug(`Finalized ${toHardDelete.length} txs from pruned blocks at block ${finalizedBlockNumber}`, {
@@ -266,7 +266,7 @@ export class DeletedPool {
     for (const txHash of toHardDelete) {
       this.#slotDeletedTxs.delete(txHash);
       await this.#slotDeletedDB.delete(txHash);
-      await this.#txsDB.delete(txHash);
+      await this.#deleteTxData(txHash);
     }
 
     this.#log.debug(

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

@@ -29,7 +29,8 @@ export class FeePayerBalanceEvictionRule implements EvictionRule {
 
       if (context.event === EvictionEvent.BLOCK_MINED) {
         const blockNumber = context.block.getBlockNumber();
-        await this.worldState.syncImmediate(blockNumber);
+        const blockHash = await context.block.hash();
+        await this.worldState.syncImmediate(blockNumber, blockHash);
         return await this.evictForFeePayers(context.feePayers, this.worldState.getSnapshot(blockNumber), pool);
       }
 
@@ -68,9 +69,7 @@ export class FeePayerBalanceEvictionRule implements EvictionRule {
 
     if (txsToEvict.length > 0) {
       await pool.deleteTxs(txsToEvict, this.name);
-      this.log.debug(`Evicted ${txsToEvict.length} txs due to insufficient fee payer balance`, {
-        txHashes: txsToEvict,
-      });
+      this.log.info(`Evicted ${txsToEvict.length} txs due to insufficient fee payer balance`, { txsToEvict });
     }
 
     return {
@@ -85,7 +84,7 @@ export class FeePayerBalanceEvictionRule implements EvictionRule {
     publicStateSource: DatabasePublicStateSource,
     pool: PoolOperations,
   ): Promise<string[]> {
-    const feePayer = AztecAddress.fromString(feePayerStr);
+    const feePayer = AztecAddress.fromStringUnsafe(feePayerStr);
     const initialBalance = (
       await publicStateSource.storageRead(
         ProtocolContractAddress.FeeJuice,

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

@@ -112,8 +112,9 @@ export class FeePayerBalancePreAddRule implements PreAddRule {
     }
 
     if (txsToEvict.length > 0) {
-      this.log.debug(
-        `Accepting tx ${incomingMeta.txHash}, evicting ${txsToEvict.length} lower-priority txs due to fee payer balance`,
+      this.log.info(
+        `Accepting tx ${incomingMeta.txHash} and evicting ${txsToEvict.length} lower-priority txs due to fee payer balance`,
+        { txsToEvict },
       );
     }
 

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

@@ -21,6 +21,7 @@ export { FeePayerBalancePreAddRule } from './fee_payer_balance_pre_add_rule.js';
 export { LowPriorityPreAddRule } from './low_priority_pre_add_rule.js';
 
 // Post-event eviction rules
+export { InsufficientFeePerGasEvictionRule } from './insufficient_fee_per_gas_eviction_rule.js';
 export { InvalidTxsAfterMiningRule } from './invalid_txs_after_mining_rule.js';
 export { InvalidTxsAfterReorgRule } from './invalid_txs_after_reorg_rule.js';
 export { FeePayerBalanceEvictionRule } from './fee_payer_balance_eviction_rule.js';

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

@@ -0,0 +1,67 @@
+import { createLogger } from '@aztec/foundation/log';
+import type { BlockMinFeesProvider } from '@aztec/stdlib/gas';
+
+import type { EvictionContext, EvictionResult, EvictionRule, PoolOperations } from './interfaces.js';
+import { EvictionEvent } from './interfaces.js';
+
+/**
+ * Eviction rule that removes transactions whose maxFeesPerGas no longer meets
+ * the projected minimum gas fees after a new block is mined.
+ * Uses the BlockMinFeesProvider (forward-looking) to get the projected minimum fees.
+ * Only triggers on BLOCK_MINED events.
+ */
+export class InsufficientFeePerGasEvictionRule implements EvictionRule {
+  public readonly name = 'InsufficientFeePerGas';
+
+  private log = createLogger('p2p:tx_pool_v2:insufficient_fee_per_gas_eviction_rule');
+
+  constructor(private blockMinFeesProvider: BlockMinFeesProvider) {}
+
+  async evict(context: EvictionContext, pool: PoolOperations): Promise<EvictionResult> {
+    if (context.event !== EvictionEvent.BLOCK_MINED) {
+      return {
+        reason: 'insufficient_fee_per_gas',
+        success: true,
+        txsEvicted: [],
+      };
+    }
+
+    try {
+      const gasFees = await this.blockMinFeesProvider.getCurrentMinFees();
+      const txsToEvict: string[] = [];
+      const pendingTxs = pool.getPendingTxs();
+
+      for (const meta of pendingTxs) {
+        const maxFeesPerGas = meta.data.constants.txContext.gasSettings.maxFeesPerGas;
+        if (maxFeesPerGas.feePerDaGas < gasFees.feePerDaGas || maxFeesPerGas.feePerL2Gas < gasFees.feePerL2Gas) {
+          this.log.verbose(`Evicting tx ${meta.txHash} from pool due to insufficient fee per gas`, {
+            txMaxFeesPerGas: maxFeesPerGas.toInspect(),
+            blockGasFees: gasFees.toInspect(),
+          });
+          txsToEvict.push(meta.txHash);
+        }
+      }
+
+      if (txsToEvict.length > 0) {
+        this.log.info(`Evicted ${txsToEvict.length} txs with insufficient fee per gas after block mined`, {
+          txsToEvict,
+        });
+        await pool.deleteTxs(txsToEvict, this.name);
+      }
+
+      return {
+        reason: 'insufficient_fee_per_gas',
+        success: true,
+        txsEvicted: txsToEvict,
+      };
+    } catch (err) {
+      this.log.error('Failed to evict transactions with insufficient fee per gas', { err });
+      return {
+        reason: 'insufficient_fee_per_gas',
+        success: false,
+        txsEvicted: [],
+        error: new Error('Failed to evict txs with insufficient fee per gas', { cause: err }),
+      };
+    }
+  }
+}

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

@@ -50,12 +50,10 @@ export class InvalidTxsAfterMiningRule implements EvictionRule {
       }
 
       if (txsToEvict.length > 0) {
-        this.log.info(`Evicted ${txsToEvict.length} invalid txs after block mined`);
+        this.log.info(`Evicted ${txsToEvict.length} invalid txs after block mined`, { txsToEvict });
         await pool.deleteTxs(txsToEvict, this.name);
       }
 
-      this.log.debug(`Evicted ${txsToEvict.length} invalid txs after block mined`, { txHashes: txsToEvict });
-
       return {
         reason: 'block_mined_invalid_txs',
         success: true,

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

@@ -1,5 +1,5 @@
-import { Fr } from '@aztec/foundation/curves/bn254';
 import { createLogger } from '@aztec/foundation/log';
+import { BlockHash } from '@aztec/stdlib/block';
 import type { WorldStateSynchronizer } from '@aztec/stdlib/interfaces/server';
 import { MerkleTreeId } from '@aztec/stdlib/trees';
 
@@ -33,14 +33,14 @@ export class InvalidTxsAfterReorgRule implements EvictionRule {
       const pendingTxs = pool.getPendingTxs();
 
       // Deduplicate block hashes to reduce redundant DB lookups
-      const uniqueBlockHashes = new Map<string, Fr>();
+      const uniqueBlockHashes = new Map<string, BlockHash>();
       const txsByBlockHash = new Map<string, string[]>();
 
       for (const meta of pendingTxs) {
         const blockHashStr = meta.anchorBlockHeaderHash;
         if (!txsByBlockHash.has(blockHashStr)) {
           txsByBlockHash.set(blockHashStr, []);
-          uniqueBlockHashes.set(blockHashStr, Fr.fromHexString(blockHashStr));
+          uniqueBlockHashes.set(blockHashStr, BlockHash.fromString(blockHashStr));
         }
         txsByBlockHash.get(blockHashStr)!.push(meta.txHash);
       }
@@ -72,17 +72,15 @@ export class InvalidTxsAfterReorgRule implements EvictionRule {
       }
 
       if (txsToEvict.length > 0) {
-        this.log.info(`Evicting ${txsToEvict.length} txs from pool due to referencing pruned blocks`);
+        this.log.info(`Evicting ${txsToEvict.length} txs from pool referencing pruned blocks`, { txsToEvict });
         await pool.deleteTxs(txsToEvict, this.name);
       }
 
       const keptCount = pendingTxs.length - txsToEvict.length;
       if (keptCount > 0) {
-        this.log.verbose(`Kept ${keptCount} txs that did not reference pruned blocks`);
+        this.log.debug(`Kept ${keptCount} txs that did not reference pruned blocks`);
       }
 
-      this.log.debug(`Evicted ${txsToEvict.length} invalid txs after reorg`, { txHashes: txsToEvict });
-
       return {
         reason: 'reorg_invalid_txs',
         success: true,

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

@@ -56,17 +56,16 @@ export class LowPriorityEvictionRule implements EvictionRule {
         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`);
+          this.log.info(
+            `Evicted ${txsToEvict.length} low priority txs, including ${numNewTxsEvicted} newly added txs`,
+            { txsToEvict },
+          );
         } else {
-          this.log.info(`Evicted ${txsToEvict.length} low priority txs after chain prune`);
+          this.log.info(`Evicted ${txsToEvict.length} low priority txs after chain prune`, { txsToEvict });
         }
         await pool.deleteTxs(txsToEvict, this.name);
       }
 
-      this.log.debug(`Evicted ${txsToEvict.length} low priority txs`, {
-        txHashes: txsToEvict,
-      });
-
       return {
         reason: 'low_priority',
         success: true,

package/src/mem_pools/tx_pool_v2/interfaces.ts

@@ -1,6 +1,7 @@
 import type { SlotNumber } from '@aztec/foundation/branded-types';
 import type { TypedEventEmitter } from '@aztec/foundation/types';
 import type { L2Block, L2BlockId, L2BlockSource } from '@aztec/stdlib/block';
+import type { BlockMinFeesProvider } from '@aztec/stdlib/gas';
 import type { WorldStateSynchronizer } from '@aztec/stdlib/interfaces/server';
 import type { BlockHeader, Tx, TxHash, TxValidator } from '@aztec/stdlib/tx';
 
@@ -44,8 +45,15 @@ export type TxPoolV2Config = {
   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;
+  /**
+   * Number of slots behind the finalized tip to keep finalized txs for before deleting them. 0 deletes
+   * at the finalized tip (default).
+   */
+  keepFinalizedTxsForSlots: number;
 };
 
 /**
@@ -56,7 +64,9 @@ export const DEFAULT_TX_POOL_V2_CONFIG: TxPoolV2Config = {
   archivedTxLimit: 0, // 0 = disabled
   minTxPoolAgeMs: 2_000,
   evictedTxCacheSize: 10_000,
+  dropTransactionsProbability: 0,
   priceBumpPercentage: 10n,
+  keepFinalizedTxsForSlots: 0,
 };
 
 /**
@@ -69,6 +79,10 @@ 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>;
+  /** Provides projected minimum fees for the next block. Used by eviction rules instead of stale block header fees. */
+  blockMinFeesProvider: BlockMinFeesProvider;
 };
 
 /**
@@ -155,13 +169,24 @@ 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>;
 
+  /**
+   * Releases the protections a failed block proposal created and restores the txs to pending.
+   * Only clears protection entries still recorded at exactly the given slot: a tx that another,
+   * still-live proposal raised to a higher slot via {@link protectTxs} keeps its protection, and
+   * mined txs (which carry no protection entry) are left untouched. Restored txs are re-validated
+   * and resolved against nullifier conflicts before re-entering the pending indices.
+   * @param txHashes - Hashes of the proposal's txs to release.
+   * @param slotNumber - The slot the failed proposal targeted; protection is released only for this slot.
+   */
+  unprotectTxs(txHashes: TxHash[], slotNumber: SlotNumber): Promise<void>;
+
   /**
    * Handles pruned blocks during a reorg.
    * Un-mines all transactions mined in blocks beyond the given latest block
@@ -184,11 +209,11 @@ export interface TxPoolV2 extends TypedEventEmitter<TxPoolV2Events> {
    */
   handleFinalizedBlock(block: BlockHeader): Promise<void>;
 
-  /** Gets a transaction by its hash */
-  getTxByHash(txHash: TxHash): Promise<Tx | undefined>;
+  /** Gets a transaction by its hash. Set `includeProof: false` to skip loading the proof from the DB. */
+  getTxByHash(txHash: TxHash, opts?: { includeProof?: boolean }): Promise<Tx | undefined>;
 
-  /** Gets multiple transactions by their hashes */
-  getTxsByHash(txHashes: TxHash[]): Promise<(Tx | undefined)[]>;
+  /** Gets multiple transactions by their hashes. Set `includeProof: false` to skip loading proofs from the DB. */
+  getTxsByHash(txHashes: TxHash[], opts?: { includeProof?: boolean }): Promise<(Tx | undefined)[]>;
 
   /** Checks if transactions exist in the pool */
   hasTxs(txHashes: TxHash[]): Promise<boolean[]>;
@@ -205,6 +230,13 @@ export interface TxPoolV2 extends TypedEventEmitter<TxPoolV2Events> {
   /** Gets the count of pending transactions */
   getPendingTxCount(): Promise<number>;
 
+  /**
+   * Returns whether at least `minCount` pending transactions are old enough per minTxPoolAgeMs to be eligible
+   * for block building. Stops scanning once the threshold is reached, so it is cheaper than counting all
+   * eligible txs when only a few are needed.
+   */
+  hasEligiblePendingTxs(minCount: number): Promise<boolean>;
+
   /** Gets mined transaction hashes with their block IDs */
   getMinedTxHashes(): Promise<[TxHash, L2BlockId][]>;
 

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 { Gas, GasFees } 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, TxPoolRejectionCode } from './eviction/interfaces.js';
 
 /** Validator-compatible data interface, mirroring the subset of PrivateKernelTailCircuitPublicInputs used by validators. */
@@ -23,7 +23,7 @@ export type TxMetaValidationData = {
       };
     };
     txContext: {
-      gasSettings: { gasLimits: Gas };
+      gasSettings: { gasLimits: Gas; maxFeesPerGas: GasFees };
     };
   };
 };
@@ -67,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;
 
@@ -84,8 +87,12 @@ 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> {
+export async function buildTxMetaData(tx: Tx, allowedSetupCalls: boolean = true): Promise<TxMetaData> {
   const txHashObj = tx.getTxHash();
   const txHash = txHashObj.toString();
   const txHashBigInt = txHashObj.toBigInt();
@@ -112,6 +119,7 @@ export async function buildTxMetaData(tx: Tx): Promise<TxMetaData> {
     feeLimit,
     nullifiers,
     expirationTimestamp,
+    allowedSetupCalls,
     receivedAt: 0,
     estimatedSizeBytes,
     data: {
@@ -124,7 +132,10 @@ export async function buildTxMetaData(tx: Tx): Promise<TxMetaData> {
           globalVariables: { blockNumber: anchorBlockNumber },
         },
         txContext: {
-          gasSettings: { gasLimits: tx.data.constants.txContext.gasSettings.gasLimits },
+          gasSettings: {
+            gasLimits: tx.data.constants.txContext.gasSettings.gasLimits,
+            maxFeesPerGas: tx.data.constants.txContext.gasSettings.maxFeesPerGas,
+          },
         },
       },
     },
@@ -158,13 +169,13 @@ export function txHashFromBigInt(value: bigint): string {
 }
 
 /** Minimal fields required for priority comparison. */
-type PriorityComparable = Pick<TxMetaData, 'txHashBigInt' | '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;
 }
 
@@ -173,7 +184,7 @@ 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: bigint, b: bigint): number {
+export function compareTxHash(a: bigint, b: bigint): -1 | 0 | 1 {
   return Fr.cmpAsBigInt(a, b);
 }
 
@@ -182,7 +193,7 @@ export function compareTxHash(a: bigint, b: bigint): 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;
@@ -277,17 +288,19 @@ export function checkNullifierConflict(
 }
 
 /** Creates a stub TxMetaValidationData for tests that don't exercise validators. */
-export function stubTxMetaValidationData(overrides: { expirationTimestamp?: bigint } = {}): TxMetaValidationData {
+export function stubTxMetaValidationData(
+  overrides: { expirationTimestamp?: bigint; maxFeesPerGas?: GasFees } = {},
+): TxMetaValidationData {
   return {
     getNonEmptyNullifiers: () => [],
     expirationTimestamp: overrides.expirationTimestamp ?? 0n,
     constants: {
       anchorBlockHeader: {
-        hash: () => Promise.resolve(new BlockHash(Fr.ZERO)),
+        hash: () => Promise.resolve(BlockHash.ZERO),
         globalVariables: { blockNumber: BlockNumber(0) },
       },
       txContext: {
-        gasSettings: { gasLimits: Gas.empty() },
+        gasSettings: { gasLimits: Gas.empty(), maxFeesPerGas: overrides.maxFeesPerGas ?? GasFees.empty() },
       },
     },
   };
@@ -304,6 +317,8 @@ export function stubTxMetaData(
     nullifiers?: string[];
     expirationTimestamp?: bigint;
     anchorBlockHeaderHash?: string;
+    allowedSetupCalls?: boolean;
+    maxFeesPerGas?: GasFees;
   } = {},
 ): TxMetaData {
   const txHashBigInt = Fr.fromHexString(txHash).toBigInt();
@@ -320,8 +335,15 @@ export function stubTxMetaData(
     feeLimit: overrides.feeLimit ?? 100n,
     nullifiers: overrides.nullifiers ?? [`0x${normalizedTxHash.slice(2)}null1`],
     expirationTimestamp,
+    allowedSetupCalls: overrides.allowedSetupCalls ?? true,
     receivedAt: 0,
     estimatedSizeBytes: 0,
-    data: stubTxMetaValidationData({ expirationTimestamp }),
+    data: stubTxMetaValidationData({ expirationTimestamp, maxFeesPerGas: overrides.maxFeesPerGas }),
   };
 }
+
+/** 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);
+}