@aztec/p2p 0.0.1-commit.24de95ac → 0.0.1-commit.2e2504e2

package/src/mem_pools/tx_pool_v2/tx_metadata.ts

@@ -0,0 +1,160 @@
+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 { getFeePayerBalanceDelta } from '../../msg_validators/tx_validator/fee_payer_balance.js';
+import { getTxPriorityFee } from '../tx_pool/priority.js';
+import type { PreAddResult } from './eviction/interfaces.js';
+
+/**
+ * Lightweight in-memory representation of a transaction.
+ * Stored for every tx in the pool to enable efficient queries and challenges
+ * without deserializing full transaction data.
+ *
+ * Uses strings for txHash and nullifiers to enable fast Map/Set lookups
+ * without repeated .toString() conversions.
+ */
+export type TxMetaData = {
+  /** The transaction hash as hex string */
+  readonly txHash: string;
+
+  /** Block ID (number and hash) in which the transaction was mined (undefined if not mined) */
+  minedL2BlockId?: L2BlockId;
+
+  /** Hash of the block header the transaction uses as its anchor (hex string) */
+  readonly anchorBlockHeaderHash: string;
+
+  /** The total priority fee (used for ordering and challenges) */
+  readonly priorityFee: bigint;
+
+  /** The fee payer address as hex string */
+  readonly feePayer: string;
+
+  /** The claim amount for the fee payer */
+  readonly claimAmount: bigint;
+
+  /** The fee limit */
+  readonly feeLimit: bigint;
+
+  /** Non-empty nullifiers emitted by the transaction (hex strings) */
+  readonly nullifiers: readonly string[];
+
+  /** Timestamp by which the transaction must be included (for expiration checks) */
+  readonly includeByTimestamp: bigint;
+};
+
+/** Transaction state derived from TxMetaData fields and pool protection status */
+export type TxState = 'pending' | 'protected' | 'mined';
+
+/**
+ * Builds TxMetaData from a full Tx object.
+ * Extracts all relevant fields for efficient in-memory storage and querying.
+ */
+export async function buildTxMetaData(tx: Tx): Promise<TxMetaData> {
+  const txHash = tx.getTxHash().toString();
+  const anchorBlockHeaderHash = (await tx.data.constants.anchorBlockHeader.hash()).toString();
+  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);
+
+  return {
+    txHash,
+    anchorBlockHeaderHash,
+    priorityFee,
+    feePayer,
+    claimAmount,
+    feeLimit,
+    nullifiers,
+    includeByTimestamp,
+  };
+}
+
+/** Minimal fields required for priority comparison. */
+type PriorityComparable = Pick<TxMetaData, 'txHash' | '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 {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+/**
+ * Compares two tx hashes in ascending order.
+ * 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);
+}
+
+/**
+ * Compares two transactions by priority fee, with txHash as tiebreaker.
+ * 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 {
+  const feeComparison = compareFee(a.priorityFee, b.priorityFee);
+  if (feeComparison !== 0) {
+    return feeComparison;
+  }
+  return compareTxHash(a.txHash, b.txHash);
+}
+
+/**
+ * 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
+ *
+ * @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
+ */
+export function checkNullifierConflict(
+  incomingMeta: TxMetaData,
+  getTxHashByNullifier: (nullifier: string) => string | undefined,
+  getMetadata: (txHash: string) => TxMetaData | undefined,
+): PreAddResult {
+  const txHashesToEvict: string[] = [];
+
+  for (const nullifier of incomingMeta.nullifiers) {
+    const conflictingHashStr = getTxHashByNullifier(nullifier);
+
+    if (!conflictingHashStr || conflictingHashStr === incomingMeta.txHash) {
+      continue;
+    }
+
+    // Skip if already marked for eviction
+    if (txHashesToEvict.includes(conflictingHashStr)) {
+      continue;
+    }
+
+    const conflictingMeta = getMetadata(conflictingHashStr);
+    if (!conflictingMeta) {
+      continue;
+    }
+
+    // If incoming tx has strictly higher priority, mark for eviction
+    // Otherwise, ignore incoming tx (ties go to existing tx)
+    if (incomingMeta.priorityFee > conflictingMeta.priorityFee) {
+      txHashesToEvict.push(conflictingHashStr);
+    } else {
+      return {
+        shouldIgnore: true,
+        txHashesToEvict: [],
+        reason: `nullifier conflict with ${conflictingHashStr}`,
+      };
+    }
+  }
+
+  return { shouldIgnore: false, txHashesToEvict };
+}

package/src/mem_pools/tx_pool_v2/tx_pool_bench_metrics.ts

@@ -0,0 +1,77 @@
+/**
+ * Metrics types for tx pool benchmarks.
+ */
+
+export enum TxPoolOperation {
+  ADD_PENDING_TXS = 'addPendingTxs',
+  CAN_ADD_PENDING_TX = 'canAddPendingTx',
+  GET_PENDING_TX_HASHES = 'getPendingTxHashes',
+  GET_TX_BY_HASH = 'getTxByHash',
+  GET_TXS_BY_HASH = 'getTxsByHash',
+  HAS_TXS = 'hasTxs',
+  HANDLE_MINED_BLOCK = 'handleMinedBlock',
+  PREPARE_FOR_SLOT = 'prepareForSlot',
+  HANDLE_PRUNED_BLOCKS = 'handlePrunedBlocks',
+  GET_LOWEST_PRIORITY_PENDING = 'getLowestPriorityPending',
+  HYDRATE_FROM_DATABASE = 'hydrateFromDatabase',
+}
+
+type OperationMetric = {
+  operation: TxPoolOperation;
+  poolSize: number;
+  batchSize: number;
+  value: number;
+};
+
+/**
+ * Collects and formats tx pool benchmark metrics.
+ */
+export class TxPoolBenchMetrics {
+  private metrics: OperationMetric[] = [];
+
+  public addMetric(operation: TxPoolOperation, poolSize: number, batchSize: number, value: number) {
+    this.metrics.push({ operation, poolSize, batchSize, value });
+  }
+
+  public toPrettyString(): string {
+    let pretty = 'TxPool Benchmark Metrics:\n';
+    pretty += '='.repeat(60) + '\n';
+
+    // Group by operation
+    const byOperation = new Map<TxPoolOperation, OperationMetric[]>();
+    for (const metric of this.metrics) {
+      if (!byOperation.has(metric.operation)) {
+        byOperation.set(metric.operation, []);
+      }
+      byOperation.get(metric.operation)!.push(metric);
+    }
+
+    for (const [operation, opMetrics] of byOperation) {
+      pretty += `\n${operation}:\n`;
+      for (const metric of opMetrics) {
+        const poolSizeStr = metric.poolSize > 0 ? `pool=${metric.poolSize}` : '';
+        const batchSizeStr = metric.batchSize > 0 ? `batch=${metric.batchSize}` : '';
+        const params = [poolSizeStr, batchSizeStr].filter(Boolean).join(', ');
+        pretty += `  ${params ? `(${params})` : ''}: ${metric.value.toFixed(3)} ms\n`;
+      }
+    }
+
+    return pretty;
+  }
+
+  public toGithubActionBenchmarkJSON(indent = 2): string {
+    const data = this.metrics.map(metric => {
+      const poolSizeStr = metric.poolSize > 0 ? `${metric.poolSize} txs in pool` : '';
+      const batchSizeStr = metric.batchSize > 0 ? `batch of ${metric.batchSize}` : '';
+      const params = [poolSizeStr, batchSizeStr].filter(Boolean).join('/');
+
+      return {
+        name: `TxPool/${metric.operation}${params ? `/${params}` : ''}`,
+        value: metric.value,
+        unit: 'ms',
+      };
+    });
+
+    return JSON.stringify(data, null, indent);
+  }
+}

package/src/mem_pools/tx_pool_v2/tx_pool_v2.ts

@@ -0,0 +1,209 @@
+import { SlotNumber } from '@aztec/foundation/branded-types';
+import { type Logger, createLogger } from '@aztec/foundation/log';
+import { SerialQueue } from '@aztec/foundation/queue';
+import type { TypedEventEmitter } from '@aztec/foundation/types';
+import type { AztecAsyncKVStore } from '@aztec/kv-store';
+import type { L2Block, L2BlockId } from '@aztec/stdlib/block';
+import { BlockHeader, Tx, TxHash } from '@aztec/stdlib/tx';
+import { type TelemetryClient, getTelemetryClient } from '@aztec/telemetry-client';
+
+import EventEmitter from 'node:events';
+
+import { PoolInstrumentation, PoolName } from '../instrumentation.js';
+import type { AddTxsResult, TxPoolV2, TxPoolV2Config, TxPoolV2Dependencies, TxPoolV2Events } from './interfaces.js';
+import type { TxState } from './tx_metadata.js';
+import { TxPoolV2Impl } from './tx_pool_v2_impl.js';
+
+/**
+ * Implementation of TxPoolV2 with explicit state management.
+ *
+ * This class is a thin wrapper that manages the serial queue and delegates
+ * all operations to TxPoolV2Impl.
+ */
+export class AztecKVTxPoolV2 extends (EventEmitter as new () => TypedEventEmitter<TxPoolV2Events>) implements TxPoolV2 {
+  #queue: SerialQueue;
+  #impl: TxPoolV2Impl;
+  #metrics?: PoolInstrumentation<Tx>;
+  #store: AztecAsyncKVStore;
+  #telemetry: TelemetryClient;
+  #log: Logger;
+  #started = false;
+
+  constructor(
+    store: AztecAsyncKVStore,
+    archiveStore: AztecAsyncKVStore,
+    deps: TxPoolV2Dependencies,
+    telemetry: TelemetryClient = getTelemetryClient(),
+    config: Partial<TxPoolV2Config> = {},
+    log = createLogger('p2p:tx_pool_v2'),
+  ) {
+    super();
+
+    this.#store = store;
+    this.#telemetry = telemetry;
+    this.#log = log;
+    this.#queue = new SerialQueue();
+
+    // Create callbacks that the impl uses to notify us about events and metrics
+    const callbacks = {
+      onTxsAdded: (txs: Tx[], opts: { source?: string }) => {
+        this.#metrics?.transactionsAdded(txs);
+        this.emit('txs-added', { txs, ...opts });
+      },
+      onTxsRemoved: (txHashes: string[] | bigint[]) => {
+        this.#metrics?.transactionsRemoved(txHashes);
+      },
+    };
+
+    // Create the implementation
+    this.#impl = new TxPoolV2Impl(store, archiveStore, deps, callbacks, config, log);
+  }
+
+  // ============================================================================
+  // PUBLIC API - All methods queue to the implementation
+  // ============================================================================
+
+  // === Core Operations ===
+
+  addPendingTxs(txs: Tx[], opts: { source?: string } = {}): Promise<AddTxsResult> {
+    return this.#queue.put(() => this.#impl.addPendingTxs(txs, opts));
+  }
+
+  canAddPendingTx(tx: Tx): Promise<'accepted' | 'ignored' | 'rejected'> {
+    return this.#queue.put(() => this.#impl.canAddPendingTx(tx));
+  }
+
+  addProtectedTxs(txs: Tx[], block: BlockHeader, opts: { source?: string } = {}): Promise<void> {
+    return this.#queue.put(() => this.#impl.addProtectedTxs(txs, block, opts));
+  }
+
+  protectTxs(txHashes: TxHash[], block: BlockHeader): Promise<TxHash[]> {
+    return this.#queue.put(() => Promise.resolve(this.#impl.protectTxs(txHashes, block)));
+  }
+
+  addMinedTxs(txs: Tx[], block: BlockHeader, opts: { source?: string } = {}): Promise<void> {
+    return this.#queue.put(() => this.#impl.addMinedTxs(txs, block, opts));
+  }
+
+  // === State Transition Handlers ===
+
+  handleMinedBlock(block: L2Block): Promise<void> {
+    return this.#queue.put(() => this.#impl.handleMinedBlock(block));
+  }
+
+  prepareForSlot(slotNumber: SlotNumber): Promise<void> {
+    return this.#queue.put(() => this.#impl.prepareForSlot(slotNumber));
+  }
+
+  handlePrunedBlocks(latestBlock: L2BlockId): Promise<void> {
+    return this.#queue.put(() => this.#impl.handlePrunedBlocks(latestBlock));
+  }
+
+  handleFailedExecution(txHashes: TxHash[]): Promise<void> {
+    return this.#queue.put(() => this.#impl.handleFailedExecution(txHashes));
+  }
+
+  handleFinalizedBlock(block: BlockHeader): Promise<void> {
+    return this.#queue.put(() => this.#impl.handleFinalizedBlock(block));
+  }
+
+  // === Queries ===
+
+  getTxByHash(txHash: TxHash): Promise<Tx | undefined> {
+    return this.#queue.put(() => this.#impl.getTxByHash(txHash));
+  }
+
+  getTxsByHash(txHashes: TxHash[]): Promise<(Tx | undefined)[]> {
+    return this.#queue.put(() => this.#impl.getTxsByHash(txHashes));
+  }
+
+  hasTxs(txHashes: TxHash[]): Promise<boolean[]> {
+    return this.#queue.put(() => this.#impl.hasTxs(txHashes));
+  }
+
+  getTxStatus(txHash: TxHash): Promise<TxState | 'deleted' | undefined> {
+    return this.#queue.put(() => Promise.resolve(this.#impl.getTxStatus(txHash)));
+  }
+
+  getPendingTxHashes(): Promise<TxHash[]> {
+    return this.#queue.put(() => Promise.resolve(this.#impl.getPendingTxHashes()));
+  }
+
+  getPendingTxCount(): Promise<number> {
+    return this.#queue.put(() => Promise.resolve(this.#impl.getPendingTxCount()));
+  }
+
+  getMinedTxHashes(): Promise<[TxHash, L2BlockId][]> {
+    return this.#queue.put(() => Promise.resolve(this.#impl.getMinedTxHashes()));
+  }
+
+  getMinedTxCount(): Promise<number> {
+    return this.#queue.put(() => Promise.resolve(this.#impl.getMinedTxCount()));
+  }
+
+  isEmpty(): Promise<boolean> {
+    return this.#queue.put(() => Promise.resolve(this.#impl.isEmpty()));
+  }
+
+  getArchivedTxByHash(txHash: TxHash): Promise<Tx | undefined> {
+    return this.#queue.put(() => this.#impl.getArchivedTxByHash(txHash));
+  }
+
+  getLowestPriorityPending(limit: number): Promise<TxHash[]> {
+    return this.#queue.put(() => Promise.resolve(this.#impl.getLowestPriorityPending(limit)));
+  }
+
+  // === Configuration ===
+
+  updateConfig(config: Partial<TxPoolV2Config>): Promise<void> {
+    return this.#queue.put(() => {
+      this.#impl.updateConfig(config);
+      return Promise.resolve();
+    });
+  }
+
+  // === Lifecycle ===
+
+  /**
+   * Starts the pool and initializes state from persistence.
+   */
+  async start(): Promise<void> {
+    if (this.#started) {
+      return;
+    }
+
+    this.#log.info('Starting transaction pool...');
+
+    // Start the serial queue
+    this.#queue.start();
+    this.#started = true;
+
+    // Setup metrics - created after queue is started so callbacks can safely queue
+    this.#metrics = new PoolInstrumentation(
+      this.#telemetry,
+      PoolName.TX_POOL,
+      () =>
+        this.#queue.put(() => {
+          const counts = this.#impl.countTxs();
+          return Promise.resolve({
+            itemCount: { pending: counts.pending, protected: counts.protected, mined: counts.mined },
+          });
+        }),
+      () => this.#store.estimateSize(),
+    );
+
+    // Hydrate state from persistence (runs in queue)
+    await this.#queue.put(() => this.#impl.hydrateFromDatabase());
+
+    this.#log.info(
+      `Transaction pool started with ${this.#impl.getTxCount()} transactions (${this.#impl.getPendingTxCount()} pending, ${this.#impl.getMinedTxCount()} mined)`,
+    );
+  }
+
+  async stop(): Promise<void> {
+    if (this.#started) {
+      await this.#queue.end();
+      this.#started = false;
+    }
+  }
+}