@aztec/p2p 0.0.1-commit.e61ad554 → 0.0.1-commit.ec5f612

package/src/mem_pools/tx_pool_v2/tx_metadata.ts

@@ -0,0 +1,297 @@
+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, 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. */
+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.
+ * 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;
+
+  /** 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;
+
+  /** 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 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' | '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 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 { feeLimit, claimAmount } = await getFeePayerBalanceDelta(tx, ProtocolContractAddress.FeeJuice);
+
+  const estimatedSizeBytes = estimateTxMetaDataSize(nullifiers.length);
+
+  return {
+    txHash,
+    txHashBigInt,
+    anchorBlockHeaderHash,
+    priorityFee,
+    feePayer,
+    claimAmount,
+    feeLimit,
+    nullifiers,
+    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, '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 {
+  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: bigint, b: bigint): number {
+  return Fr.cmpAsBigInt(a, b);
+}
+
+/**
+ * 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.txHashBigInt, b.txHashBigInt);
+}
+
+/**
+ * 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)
+    // Use comparePriority for deterministic ordering (includes txHash as tiebreaker)
+    if (comparePriority(incomingMeta, conflictingMeta) > 0) {
+      txHashesToEvict.push(conflictingHashStr);
+    } else {
+      return {
+        shouldIgnore: true,
+        txHashesToEvict: [],
+        reason: {
+          code: TxPoolRejectionCode.NULLIFIER_CONFLICT,
+          message: `Nullifier conflict with existing tx ${conflictingHashStr}`,
+          conflictingTxHash: conflictingHashStr,
+        },
+      };
+    }
+  }
+
+  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 }),
+  };
+}

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);
+  }
+}