@aztec/p2p 0.0.1-commit.fcb71a6 → 0.0.1-commit.ff7989d6c

package/dest/mem_pools/tx_pool_v2/interfaces.d.ts

@@ -0,0 +1,211 @@
+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 { 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';
+/**
+ * Result of adding transactions to the pending pool.
+ * Categorizes transactions by their outcome.
+ */
+export type AddTxsResult = {
+    /** Transactions successfully added to the pool */
+    accepted: TxHash[];
+    /** Transactions ignored because they're valid but undesirable (e.g., duplicate, lower priority nullifier conflict) */
+    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>;
+};
+/**
+ * Events emitted by TxPoolV2.
+ */
+export type TxPoolV2Events = {
+    /** Emitted when transactions are successfully added to the pool */
+    'txs-added': (args: {
+        txs: Tx[];
+        source?: string;
+    }) => void;
+    /** Emitted when transactions are removed from the pool */
+    'txs-removed': (args: {
+        txHashes: TxHash[];
+    }) => void;
+};
+/**
+ * Configuration options for TxPoolV2.
+ */
+export type TxPoolV2Config = {
+    /** Maximum number of pending transactions before low-priority eviction */
+    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;
+};
+/**
+ * Default configuration values for TxPoolV2.
+ */
+export declare const DEFAULT_TX_POOL_V2_CONFIG: TxPoolV2Config;
+/**
+ * Dependencies required by TxPoolV2.
+ */
+export type TxPoolV2Dependencies = {
+    /** Block source (Archiver) for checking mined status and verifying pruned blocks */
+    l2BlockSource: L2BlockSource;
+    /** World state synchronizer for validating transactions after chain prunes */
+    worldStateSynchronizer: WorldStateSynchronizer;
+    /** Factory that creates a validator for re-validating pool transactions using metadata */
+    createTxValidator: () => Promise<TxValidator<TxMetaData>>;
+};
+/**
+ * Read-only access to pool state for pre-add checks.
+ * Used by eviction rules to inspect pool state during transaction addition.
+ */
+export interface PoolReadAccess {
+    /** Get metadata for a transaction by its hash (as string) */
+    getMetadata(txHash: string): TxMetaData | undefined;
+    /** Get the transaction hash that uses a specific nullifier (as string) */
+    getTxHashByNullifier(nullifier: string): string | undefined;
+    /** Get all transaction hashes for a fee payer (as string) */
+    getTxHashesByFeePayer(feePayer: string): Set<string> | undefined;
+    /** Get the current pending transaction count */
+    getPendingTxCount(): number;
+}
+/**
+ *
+ * The pool manages transactions through a state machine:
+ * - Pending: Transaction is awaiting inclusion in a block
+ * - Protected: Transaction is being considered for a block proposal
+ * - Mined: Transaction has been included in a block
+ * - Deleted: Transaction has been removed from the pool
+ *
+ * All state-mutating operations are serialized through a handler queue
+ * to prevent race conditions.
+ */
+export interface TxPoolV2 extends TypedEventEmitter<TxPoolV2Events> {
+    /**
+     * Adds transactions to the pending pool with challenge and validation.
+     * Handles nullifier conflicts via the challenge mechanism.
+     * @param txs - Transactions to add
+     * @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;
+        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.
+     * @param tx - Transaction to check
+     * @returns Result: 'accepted', 'ignored' (if already in pool or undesirable), or 'rejected' (if validation fails)
+     */
+    canAddPendingTx(tx: Tx): Promise<'accepted' | 'ignored' | 'rejected'>;
+    /**
+     * Adds transactions as immediately protected for a given slot.
+     * Used when receiving transactions from a block proposal we're validating.
+     * @param txs - Transactions to add as protected
+     * @param block - Block header providing slot context
+     * @param opts - Optional metadata (e.g., source for logging)
+     */
+    addProtectedTxs(txs: Tx[], block: BlockHeader, opts?: {
+        source?: string;
+    }): Promise<void>;
+    /**
+     * Protects existing transactions by hash for a given slot.
+     * Returns hashes of transactions that weren't found in the pool.
+     * Records unknown hashes for automatic protection when received via gossip.
+     * @param txHashes - Hashes of transactions to protect
+     * @param block - Block header providing slot context
+     * @returns Hashes of transactions not found in the pool
+     */
+    protectTxs(txHashes: TxHash[], block: BlockHeader): Promise<TxHash[]>;
+    /**
+     * Adds transactions as already mined.
+     * Used by prover nodes fetching transactions via request/response.
+     * @param txs - Transactions to add as mined
+     * @param block - Block header the transactions were mined in
+     * @param opts - Optional metadata (e.g., source for logging)
+     */
+    addMinedTxs(txs: Tx[], block: BlockHeader, opts?: {
+        source?: string;
+    }): Promise<void>;
+    /**
+     * Handles a mined block - marks transactions as mined and evicts conflicting pending txs.
+     * Uses nullifiers directly from the block to evict pending transactions with conflicts.
+     * @param block - The complete mined block
+     */
+    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
+     */
+    prepareForSlot(slotNumber: SlotNumber): Promise<void>;
+    /**
+     * Handles pruned blocks during a reorg.
+     * Un-mines all transactions mined in blocks beyond the given latest block
+     * and validates them before returning to pending.
+     * @param latestBlock - The latest valid block ID after the prune
+     */
+    handlePrunedBlocks(latestBlock: L2BlockId, options?: {
+        deleteAllTxs?: boolean;
+    }): Promise<void>;
+    /**
+     * Handles failed transaction execution.
+     * Deletes transactions that failed during block building.
+     * @param txHashes - Hashes of transactions that failed
+     */
+    handleFailedExecution(txHashes: TxHash[]): Promise<void>;
+    /**
+     * Handles a finalized block.
+     * Permanently deletes mined transactions and optionally archives them.
+     * @param block - Header of the finalized block
+     */
+    handleFinalizedBlock(block: BlockHeader): Promise<void>;
+    /** Gets a transaction by its hash */
+    getTxByHash(txHash: TxHash): Promise<Tx | undefined>;
+    /** Gets multiple transactions by their hashes */
+    getTxsByHash(txHashes: TxHash[]): Promise<(Tx | undefined)[]>;
+    /** Checks if transactions exist in the pool */
+    hasTxs(txHashes: TxHash[]): Promise<boolean[]>;
+    /** Gets the status of a transaction */
+    getTxStatus(txHash: TxHash): Promise<TxState | 'deleted' | undefined>;
+    /** 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>;
+    /** Gets mined transaction hashes with their block IDs */
+    getMinedTxHashes(): Promise<[TxHash, L2BlockId][]>;
+    /** Gets the count of mined transactions */
+    getMinedTxCount(): Promise<number>;
+    /** Checks if the pool is empty */
+    isEmpty(): Promise<boolean>;
+    /** Gets an archived transaction by its hash */
+    getArchivedTxByHash(txHash: TxHash): Promise<Tx | undefined>;
+    /** Gets the lowest priority pending transactions */
+    getLowestPriorityPending(limit: number): Promise<TxHash[]>;
+    /** Updates the pool configuration */
+    updateConfig(config: Partial<TxPoolV2Config>): Promise<void>;
+    /**
+     * Starts the pool and initializes state from persistence.
+     * Must be called before other operations.
+     * - Reads all transactions from the database
+     * - Checks each against the Archiver to determine mined status
+     * - Validates all non-mined transactions
+     * - Populates in-memory indices
+     */
+    start(): Promise<void>;
+    /** Stops the pool and releases resources */
+    stop(): Promise<void>;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW50ZXJmYWNlcy5kLnRzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vLi4vc3JjL21lbV9wb29scy90eF9wb29sX3YyL2ludGVyZmFjZXMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxLQUFLLEVBQUUsVUFBVSxFQUFFLE1BQU0saUNBQWlDLENBQUM7QUFDbEUsT0FBTyxLQUFLLEVBQUUsaUJBQWlCLEVBQUUsTUFBTSx5QkFBeUIsQ0FBQztBQUNqRSxPQUFPLEtBQUssRUFBRSxPQUFPLEVBQUUsU0FBUyxFQUFFLGFBQWEsRUFBRSxNQUFNLHFCQUFxQixDQUFDO0FBQzdFLE9BQU8sS0FBSyxFQUFFLHNCQUFzQixFQUFFLE1BQU0saUNBQWlDLENBQUM7QUFDOUUsT0FBTyxLQUFLLEVBQUUsV0FBVyxFQUFFLEVBQUUsRUFBRSxNQUFNLEVBQUUsV0FBVyxFQUFFLE1BQU0sa0JBQWtCLENBQUM7QUFFN0UsT0FBTyxLQUFLLEVBQUUsb0JBQW9CLEVBQUUsTUFBTSwwQkFBMEIsQ0FBQztBQUNyRSxPQUFPLEtBQUssRUFBRSxVQUFVLEVBQUUsT0FBTyxFQUFFLE1BQU0sa0JBQWtCLENBQUM7QUFFNUQ7OztHQUdHO0FBQ0gsTUFBTSxNQUFNLFlBQVksR0FBRztJQUN6QixrREFBa0Q7SUFDbEQsUUFBUSxFQUFFLE1BQU0sRUFBRSxDQUFDO0lBQ25CLHNIQUFzSDtJQUN0SCxPQUFPLEVBQUUsTUFBTSxFQUFFLENBQUM7SUFDbEIsb0dBQW9HO0lBQ3BHLFFBQVEsRUFBRSxNQUFNLEVBQUUsQ0FBQztJQUNuQixnR0FBZ0c7SUFDaEcsTUFBTSxDQUFDLEVBQUUsR0FBRyxDQUFDLE1BQU0sRUFBRSxvQkFBb0IsQ0FBQyxDQUFDO0NBQzVDLENBQUM7QUFFRjs7R0FFRztBQUNILE1BQU0sTUFBTSxjQUFjLEdBQUc7SUFDM0IsbUVBQW1FO0lBQ25FLFdBQVcsRUFBRSxDQUFDLElBQUksRUFBRTtRQUFFLEdBQUcsRUFBRSxFQUFFLEVBQUUsQ0FB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

package/dest/mem_pools/tx_pool_v2/interfaces.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interfaces.d.ts","sourceRoot":"","sources":["../../../src/mem_pools/tx_pool_v2/interfaces.ts"],"names":[],"mappings":"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"}

package/dest/mem_pools/tx_pool_v2/interfaces.js

@@ -0,0 +1,9 @@
+/**
+ * Default configuration values for TxPoolV2.
+ */ export const DEFAULT_TX_POOL_V2_CONFIG = {
+    maxPendingTxCount: 0,
+    archivedTxLimit: 0,
+    minTxPoolAgeMs: 2_000,
+    evictedTxCacheSize: 10_000,
+    dropTransactionsProbability: 0
+};

package/dest/mem_pools/tx_pool_v2/tx_metadata.d.ts

@@ -0,0 +1,97 @@
+import { BlockNumber } from '@aztec/foundation/branded-types';
+import { Fr } from '@aztec/foundation/curves/bn254';
+import { BlockHash, type L2BlockId } from '@aztec/stdlib/block';
+import type { Tx } from '@aztec/stdlib/tx';
+import { type PreAddResult } from './eviction/interfaces.js';
+/** Validator-compatible data interface, mirroring the subset of PrivateKernelTailCircuitPublicInputs used by validators. */
+export type TxMetaValidationData = {
+    getNonEmptyNullifiers(): Fr[];
+    expirationTimestamp: bigint;
+    constants: {
+        anchorBlockHeader: {
+            hash(): Promise<BlockHash>;
+            globalVariables: {
+                blockNumber: BlockNumber;
+            };
+        };
+    };
+};
+/**
+ * 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 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 declare function buildTxMetaData(tx: Tx): Promise<TxMetaData>;
+/** 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 declare function compareFee(a: bigint, b: bigint): number;
+/**
+ * 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 declare function compareTxHash(a: string, b: string): number;
+/**
+ * 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 declare function comparePriority(a: PriorityComparable, b: PriorityComparable): number;
+/**
+ * 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 declare function checkNullifierConflict(incomingMeta: TxMetaData, getTxHashByNullifier: (nullifier: string) => string | undefined, getMetadata: (txHash: string) => TxMetaData | undefined): PreAddResult;
+/** Creates a stub TxMetaValidationData for tests that don't exercise validators. */
+export declare function stubTxMetaValidationData(overrides?: {
+    expirationTimestamp?: bigint;
+}): TxMetaValidationData;
+export {};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidHhfbWV0YWRhdGEuZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uLy4uL3NyYy9tZW1fcG9vbHMvdHhfcG9vbF92Mi90eF9tZXRhZGF0YS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEVBQUUsV0FBVyxFQUFFLE1BQU0saUNBQWlDLENBQUM7QUFDOUQsT0FBTyxFQUFFLEVBQUUsRUFBRSxNQUFNLGdDQUFnQyxDQUFDO0FBRXBELE9BQU8sRUFBRSxTQUFTLEVBQUUsS0FBSyxTQUFTLEVBQUUsTUFBTSxxQkFBcUIsQ0FBQztBQUNoRSxPQUFPLEtBQUssRUFBRSxFQUFFLEVBQUUsTUFBTSxrQkFBa0IsQ0FBQztBQUkzQyxPQUFPLEVBQUUsS0FBSyxZQUFZLEVBQXVCLE1BQU0sMEJBQTBCLENBQUM7QUFFbEYsNEhBQTRIO0FBQzVILE1BQU0sTUFBTSxvQkFBb0IsR0FBRztJQUNqQyxxQkFBcUIsSUFBSSxFQUFFLEVBQUUsQ0FBQztJQUM5QixtQkFBbUIsRUFBRSxNQUFNLENBQUM7SUFDNUIsU0FBUyxFQUFFO1FBQ1QsaUJBQWlCLEVBQUU7WUFDakIsSUFBSSxJQUFJLE9BQU8sQ0FBQyxTQUFTLENBQUMsQ0FBQztZQUMzQixlQUFlLEVBQUU7Z0JBQ2YsV0FBVyxFQUFFLFdBQVcsQ0FBQzthQUMxQixDQUFDO1NBQ0gsQ0FBQztLQUNILENBQUM7Q0FDSCxDQUFDO0FBRUY7Ozs7Ozs7R0FPRztBQUNILE1BQU0sTUFBTSxVQUFVLEdBQUc7SUFDdkIseUNBQXlDO0lBQ3pDLFFBQVEsQ0FBQyxNQUFNLEVBQUUsTUFBTSxDQUFDO0lBRXhCLDZGQUE2RjtJQUM3RixjQUFjLENBQUMsRUFBRSxTQUFTLENBQUM7SUFFM0IsK0VBQStFO0lBQy9FLFFBQVEsQ0FBQyxxQkFBcUIsRUFBRSxNQUFNLENBQUM7SUFFdkMsZ0VBQWdFO0lBQ2hFLFFBQVEsQ0FBQyxXQUFXLEVBQUUsTUFBTSxDQUFDO0lBRTdCLDBDQUEwQztJQUMxQyxRQUFRLENBQUMsUUFBUSxFQUFFLE1BQU0sQ0FBQztJQUUxQix5Q0FBeUM7SUFDekMsUUFBUSxDQUFDLFdBQVcsRUFBRSxNQUFNLENBQUM7SUFFN0Isb0JBQW9CO0lBQ3BCLFFBQVEsQ0FBQyxRQUFRLEVBQUUsTUFBTSxDQUFDO0lBRTFCLG9FQUFvRTtJQUNwRSxRQUFRLENBQUMsVUFBVSxFQUFFLFNBQVMsTUFBTSxFQUFFLENBQUM7SUFFdkMsa0ZBQWtGO0lBQ2xGLFFBQVEsQ0FBQyxtQkFBbUIsRUFBRSxNQUFNLENBQUM7SUFFckMsK0VBQStFO0lBQy9FLFFBQVEsQ0FBQyxJQUFJLEVBQUUsb0JBQW9CLENBQUM7SUFFcEMsbUdBQW1HO0lBQ25HLFVBQVUsRUFBRSxNQUFNLENBQUM7SUFFbkIsa0VBQWtFO0lBQ2xFLFFBQVEsQ0FBQyxrQkFBa0IsRUFBRSxNQUFNLENBQUM7Q0FDckMsQ0FBQztBQUVGLGtGQUFrRjtBQUNsRixNQUFNLE1BQU0sT0FBTyxHQUFHLFNBQVMsR0FBRyxXQUFXLEdBQUcsT0FBTyxHQUFHLFNBQVMsQ0FBQztBQUVwRTs7OztHQUlHO0FBQ0gsd0JBQXNCLGVBQWUsQ0FBQyxFQUFFLEVBQUUsRUFBRSxHQUFHLE9BQU8sQ0FBQyxVQUFVLENBQUMsQ0FxQ2pFO0FBdUJELHVEQUF1RDtBQUN2RCxLQUFLLGtCQUFrQixHQUFHLElBQUksQ0FBQyxVQUFVLEVBQUUsUUFBUSxHQUFHLGFBQWEsQ0FBQyxDQUFDO0FBRXJFOzs7R0FHRztBQUNILHdCQUFnQixVQUFVLENBQUMsQ0FBQyxFQUFFLE1BQU0sRUFBRSxDQUFDLEVBQUUsTUFBTSxHQUFHLE1BQU0sQ0FFdkQ7QUFFRDs7OztHQUlHO0FBQ0gsd0JBQWdCLGFBQWEsQ0FBQyxDQUFDLEVBQUUsTUFBTSxFQUFFLENBQUMsRUFBRSxNQUFNLEdBQUcsTUFBTSxDQUkxRDtBQUVEOzs7O0dBSUc7QUFDSCx3QkFBZ0IsZUFBZSxDQUFDLENBQUMsRUFBRSxrQkFBa0IsRUFBRSxDQUFDLEVBQUUsa0JBQWtCLEdBQUcsTUFBTSxDQU1wRjtBQUVEOzs7Ozs7Ozs7O0dBVUc7QUFDSCx3QkFBZ0Isc0JBQXNCLENBQ3BDLFlBQVksRUFBRSxVQUFVLEVBQ3hCLG9CQUFvQixFQUFFLENBQUMsU0FBUyxFQUFFLE1BQU0sS0FBSyxNQUFNLEdBQUcsU0FBUyxFQUMvRCxXQUFXLEVBQUUsQ0FBQyxNQUFNLEVBQUUsTUFBTSxLQUFLLFVBQVUsR0FBRyxTQUFTLEdBQ3RELFlBQVksQ0F1Q2Q7QUFFRCxvRkFBb0Y7QUFDcEYsd0JBQWdCLHdCQUF3QixDQUFDLFNBQVMsR0FBRTtJQUFFLG1CQUFtQixDQUFDLEVBQUUsTUFBTSxDQUFBO0NBQU8sR0FBRyxvQkFBb0IsQ0FXL0cifQ==

package/dest/mem_pools/tx_pool_v2/tx_metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tx_metadata.d.ts","sourceRoot":"","sources":["../../../src/mem_pools/tx_pool_v2/tx_metadata.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,iCAAiC,CAAC;AAC9D,OAAO,EAAE,EAAE,EAAE,MAAM,gCAAgC,CAAC;AAEpD,OAAO,EAAE,SAAS,EAAE,KAAK,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAChE,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,kBAAkB,CAAC;AAI3C,OAAO,EAAE,KAAK,YAAY,EAAuB,MAAM,0BAA0B,CAAC;AAElF,4HAA4H;AAC5H,MAAM,MAAM,oBAAoB,GAAG;IACjC,qBAAqB,IAAI,EAAE,EAAE,CAAC;IAC9B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,SAAS,EAAE;QACT,iBAAiB,EAAE;YACjB,IAAI,IAAI,OAAO,CAAC,SAAS,CAAC,CAAC;YAC3B,eAAe,EAAE;gBACf,WAAW,EAAE,WAAW,CAAC;aAC1B,CAAC;SACH,CAAC;KACH,CAAC;CACH,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,yCAAyC;IACzC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB,6FAA6F;IAC7F,cAAc,CAAC,EAAE,SAAS,CAAC;IAE3B,+EAA+E;IAC/E,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;IAEvC,gEAAgE;IAChE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B,0CAA0C;IAC1C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B,yCAAyC;IACzC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B,oBAAoB;IACpB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B,oEAAoE;IACpE,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IAEvC,kFAAkF;IAClF,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IAErC,+EAA+E;IAC/E,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC;IAEpC,mGAAmG;IACnG,UAAU,EAAE,MAAM,CAAC;IAEnB,kEAAkE;IAClE,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;CACrC,CAAC;AAEF,kFAAkF;AAClF,MAAM,MAAM,OAAO,GAAG,SAAS,GAAG,WAAW,GAAG,OAAO,GAAG,SAAS,CAAC;AAEpE;;;;GAIG;AACH,wBAAsB,eAAe,CAAC,EAAE,EAAE,EAAE,GAAG,OAAO,CAAC,UAAU,CAAC,CAqCjE;AAuBD,uDAAuD;AACvD,KAAK,kBAAkB,GAAG,IAAI,CAAC,UAAU,EAAE,QAAQ,GAAG,aAAa,CAAC,CAAC;AAErE;;;GAGG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAI1D;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,kBAAkB,EAAE,CAAC,EAAE,kBAAkB,GAAG,MAAM,CAMpF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CACpC,YAAY,EAAE,UAAU,EACxB,oBAAoB,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,EAC/D,WAAW,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,UAAU,GAAG,SAAS,GACtD,YAAY,CAuCd;AAED,oFAAoF;AACpF,wBAAgB,wBAAwB,CAAC,SAAS,GAAE;IAAE,mBAAmB,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,oBAAoB,CAW/G"}

package/dest/mem_pools/tx_pool_v2/tx_metadata.js

@@ -0,0 +1,152 @@
+import { BlockNumber } from '@aztec/foundation/branded-types';
+import { Fr } from '@aztec/foundation/curves/bn254';
+import { ProtocolContractAddress } from '@aztec/protocol-contracts';
+import { BlockHash } from '@aztec/stdlib/block';
+import { getFeePayerBalanceDelta } from '../../msg_validators/tx_validator/fee_payer_balance.js';
+import { getTxPriorityFee } from '../tx_pool/priority.js';
+import { TxPoolRejectionCode } from './eviction/interfaces.js';
+/**
+ * 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) {
+    const txHash = tx.getTxHash().toString();
+    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,
+        anchorBlockHeaderHash,
+        priorityFee,
+        feePayer,
+        claimAmount,
+        feeLimit,
+        nullifiers,
+        expirationTimestamp,
+        receivedAt: 0,
+        estimatedSizeBytes,
+        data: {
+            getNonEmptyNullifiers: ()=>nullifierFrs,
+            expirationTimestamp,
+            constants: {
+                anchorBlockHeader: {
+                    hash: ()=>Promise.resolve(anchorBlockHeaderHashFr),
+                    globalVariables: {
+                        blockNumber: anchorBlockNumber
+                    }
+                }
+            }
+        }
+    };
+}
+// 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)
+// + priorityFee + claimAmount + feeLimit + includeByTimestamp (4 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;
+/** Estimates the in-memory size of a TxMetaData object based on the number of nullifiers. */ function estimateTxMetaDataSize(nullifierCount) {
+    // Per nullifier: one hex string in nullifiers[] + one Fr in the captured nullifierFrs[]
+    return FIXED_METADATA_BYTES + nullifierCount * (HEX_STRING_BYTES + FR_BYTES);
+}
+/**
+ * Compares two priority fees in ascending order.
+ * Returns negative if a < b, positive if a > b, 0 if equal.
+ */ export function compareFee(a, b) {
+    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, b) {
+    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, b) {
+    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, getTxHashByNullifier, getMetadata) {
+    const txHashesToEvict = [];
+    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 = {}) {
+    return {
+        getNonEmptyNullifiers: ()=>[],
+        expirationTimestamp: overrides.expirationTimestamp ?? 0n,
+        constants: {
+            anchorBlockHeader: {
+                hash: ()=>Promise.resolve(new BlockHash(Fr.ZERO)),
+                globalVariables: {
+                    blockNumber: BlockNumber(0)
+                }
+            }
+        }
+    };
+}

package/dest/mem_pools/tx_pool_v2/tx_pool_bench_metrics.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Metrics types for tx pool benchmarks.
+ */
+export declare 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"
+}
+/**
+ * Collects and formats tx pool benchmark metrics.
+ */
+export declare class TxPoolBenchMetrics {
+    private metrics;
+    addMetric(operation: TxPoolOperation, poolSize: number, batchSize: number, value: number): void;
+    toPrettyString(): string;
+    toGithubActionBenchmarkJSON(indent?: number): string;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidHhfcG9vbF9iZW5jaF9tZXRyaWNzLmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi9zcmMvbWVtX3Bvb2xzL3R4X3Bvb2xfdjIvdHhfcG9vbF9iZW5jaF9tZXRyaWNzLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOztHQUVHO0FBRUgsb0JBQVksZUFBZTtJQUN6QixlQUFlLGtCQUFrQjtJQUNqQyxrQkFBa0Isb0JBQW9CO0lBQ3RDLHFCQUFxQix1QkFBdUI7SUFDNUMsY0FBYyxnQkFBZ0I7SUFDOUIsZUFBZSxpQkFBaUI7SUFDaEMsT0FBTyxXQUFXO0lBQ2xCLGtCQUFrQixxQkFBcUI7SUFDdkMsZ0JBQWdCLG1CQUFtQjtJQUNuQyxvQkFBb0IsdUJBQXVCO0lBQzNDLDJCQUEyQiw2QkFBNkI7SUFDeEQscUJBQXFCLHdCQUF3QjtDQUM5QztBQVNEOztHQUVHO0FBQ0gscUJBQWEsa0JBQWtCO0lBQzdCLE9BQU8sQ0FBQyxPQUFPLENBQXlCO0lBRWpDLFNBQVMsQ0FBQyxTQUFTLEVBQUUsZUFBZSxFQUFFLFFBQVEsRUFBRSxNQUFNLEVBQUUsU0FBUyxFQUFFLE1BQU0sRUFBRSxLQUFLLEVBQUUsTUFBTSxRQUU5RjtJQUVNLGNBQWMsSUFBSSxNQUFNLENBd0I5QjtJQUVNLDJCQUEyQixDQUFDLE1BQU0sU0FBSSxHQUFHLE1BQU0sQ0FjckQ7Q0FDRiJ9

package/dest/mem_pools/tx_pool_v2/tx_pool_bench_metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tx_pool_bench_metrics.d.ts","sourceRoot":"","sources":["../../../src/mem_pools/tx_pool_v2/tx_pool_bench_metrics.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,oBAAY,eAAe;IACzB,eAAe,kBAAkB;IACjC,kBAAkB,oBAAoB;IACtC,qBAAqB,uBAAuB;IAC5C,cAAc,gBAAgB;IAC9B,eAAe,iBAAiB;IAChC,OAAO,WAAW;IAClB,kBAAkB,qBAAqB;IACvC,gBAAgB,mBAAmB;IACnC,oBAAoB,uBAAuB;IAC3C,2BAA2B,6BAA6B;IACxD,qBAAqB,wBAAwB;CAC9C;AASD;;GAEG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,OAAO,CAAyB;IAEjC,SAAS,CAAC,SAAS,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,QAE9F;IAEM,cAAc,IAAI,MAAM,CAwB9B;IAEM,2BAA2B,CAAC,MAAM,SAAI,GAAG,MAAM,CAcrD;CACF"}

package/dest/mem_pools/tx_pool_v2/tx_pool_bench_metrics.js

@@ -0,0 +1,70 @@
+/**
+ * Metrics types for tx pool benchmarks.
+ */ export var TxPoolOperation = /*#__PURE__*/ function(TxPoolOperation) {
+    TxPoolOperation["ADD_PENDING_TXS"] = "addPendingTxs";
+    TxPoolOperation["CAN_ADD_PENDING_TX"] = "canAddPendingTx";
+    TxPoolOperation["GET_PENDING_TX_HASHES"] = "getPendingTxHashes";
+    TxPoolOperation["GET_TX_BY_HASH"] = "getTxByHash";
+    TxPoolOperation["GET_TXS_BY_HASH"] = "getTxsByHash";
+    TxPoolOperation["HAS_TXS"] = "hasTxs";
+    TxPoolOperation["HANDLE_MINED_BLOCK"] = "handleMinedBlock";
+    TxPoolOperation["PREPARE_FOR_SLOT"] = "prepareForSlot";
+    TxPoolOperation["HANDLE_PRUNED_BLOCKS"] = "handlePrunedBlocks";
+    TxPoolOperation["GET_LOWEST_PRIORITY_PENDING"] = "getLowestPriorityPending";
+    TxPoolOperation["HYDRATE_FROM_DATABASE"] = "hydrateFromDatabase";
+    return TxPoolOperation;
+}({});
+/**
+ * Collects and formats tx pool benchmark metrics.
+ */ export class TxPoolBenchMetrics {
+    metrics = [];
+    addMetric(operation, poolSize, batchSize, value) {
+        this.metrics.push({
+            operation,
+            poolSize,
+            batchSize,
+            value
+        });
+    }
+    toPrettyString() {
+        let pretty = 'TxPool Benchmark Metrics:\n';
+        pretty += '='.repeat(60) + '\n';
+        // Group by operation
+        const byOperation = new Map();
+        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;
+    }
+    toGithubActionBenchmarkJSON(indent = 2) {
+        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);
+    }
+}