@aztec/p2p 0.0.1-commit.d431d1c → 0.0.1-commit.d58ff9d0

package/dest/mem_pools/tx_pool_v2/tx_pool_indices.js

@@ -0,0 +1,368 @@
+import { insertIntoSortedArray, removeFromSortedArray } from '@aztec/foundation/array';
+import { comparePriority } from './tx_metadata.js';
+/**
+ * Manages in-memory indices for the transaction pool.
+ *
+ * Tracks transaction metadata and maintains several indices for efficient querying:
+ * - Metadata by txHash (primary store)
+ * - Nullifier to txHash mapping (pending txs only)
+ * - Fee payer to txHashes mapping (pending txs only)
+ * - Priority-ordered pending txs
+ * - Protected transaction tracking
+ *
+ * Key invariant: Only pending txs appear in nullifier/feePayer/priority indices.
+ */ export class TxPoolIndices {
+    /** Primary metadata store: txHash -> TxMetaData */ #metadata = new Map();
+    /** Nullifier to txHash index (pending txs only) */ #nullifierToTxHash = new Map();
+    /** Fee payer to txHashes index (pending txs only) */ #feePayerToTxHashes = new Map();
+    /** Pending transactions sorted ascending by priority fee, ties broken by txHash */ #pendingByPriority = [];
+    /** Protected transactions: txHash -> slotNumber */ #protectedTransactions = new Map();
+    // ============================================================================
+    // STATE QUERIES
+    // ============================================================================
+    /**
+   * Derives the transaction state from its metadata and protection status.
+   * A transaction is:
+   * - 'mined' if it has a minedL2BlockId
+   * - 'protected' if it's in the protectedTransactions map (but not mined)
+   * - 'pending' otherwise
+   */ getTxState(meta) {
+        if (meta.minedL2BlockId !== undefined) {
+            return 'mined';
+        } else if (this.#protectedTransactions.has(meta.txHash)) {
+            return 'protected';
+        } else {
+            return 'pending';
+        }
+    }
+    getMetadata(txHash) {
+        return this.#metadata.get(txHash);
+    }
+    has(txHash) {
+        return this.#metadata.has(txHash);
+    }
+    isEmpty() {
+        return this.#metadata.size === 0;
+    }
+    getTxCount() {
+        return this.#metadata.size;
+    }
+    // ============================================================================
+    // ITERATION
+    // ============================================================================
+    /**
+   * Iterates pending transaction hashes in priority order.
+   * @param order - 'desc' for highest priority first, 'asc' for lowest priority first
+   */ *iteratePendingByPriority(order, filter) {
+        const arr = this.#pendingByPriority;
+        const start = order === 'asc' ? 0 : arr.length - 1;
+        const step = order === 'asc' ? 1 : -1;
+        const inBounds = order === 'asc' ? (i)=>i < arr.length : (i)=>i >= 0;
+        for(let i = start; inBounds(i); i += step){
+            if (filter === undefined || filter(arr[i].txHash)) {
+                yield arr[i].txHash;
+            }
+        }
+    }
+    /**
+   * Iterates pending transaction hashes in priority order, skipping txs received after maxReceivedAt.
+   * @param order - 'desc' for highest priority first, 'asc' for lowest priority first
+   * @param maxReceivedAt - Only yield txs with receivedAt <= this value
+   */ *iterateEligiblePendingByPriority(order, maxReceivedAt) {
+        const filter = (hash)=>{
+            const meta = this.#metadata.get(hash);
+            return meta !== undefined && meta.receivedAt <= maxReceivedAt;
+        };
+        yield* this.iteratePendingByPriority(order, filter);
+    }
+    /** Iterates all metadata entries */ *iterateMetadata() {
+        yield* this.#metadata;
+    }
+    // ============================================================================
+    // INDEX MODIFICATIONS
+    // ============================================================================
+    /** Adds a new pending transaction to all indices */ addPending(meta) {
+        this.#metadata.set(meta.txHash, meta);
+        this.#addToPendingIndices(meta);
+    }
+    /** Adds a new protected transaction (not added to pending indices) */ addProtected(meta, slot) {
+        this.#metadata.set(meta.txHash, meta);
+        this.#protectedTransactions.set(meta.txHash, slot);
+    }
+    /** Adds a new mined transaction (not added to pending indices) */ addMined(meta) {
+        this.#metadata.set(meta.txHash, meta);
+    }
+    /** Marks an existing transaction as mined and removes from pending indices */ markAsMined(meta, blockId) {
+        meta.minedL2BlockId = blockId;
+        // Safe to call unconditionally - removeFromPendingIndices is idempotent
+        this.#removeFromPendingIndices(meta);
+        // A mined tx supersedes any protection: drop the stale entry so it can't linger in the map and
+        // be matched by later protection scans.
+        this.#protectedTransactions.delete(meta.txHash);
+    }
+    /** Clears the mined status from a transaction */ markAsUnmined(meta) {
+        meta.minedL2BlockId = undefined;
+    }
+    /**
+   * Updates protection status for an existing transaction.
+   * Removes from pending indices if transitioning from pending to protected.
+   */ updateProtection(txHash, slotNumber) {
+        const currentSlot = this.#protectedTransactions.get(txHash);
+        // Only update if not already protected at an equal or later slot
+        if (currentSlot !== undefined && currentSlot >= slotNumber) {
+            return;
+        }
+        // Remove from pending indices if transitioning from pending to protected
+        if (currentSlot === undefined) {
+            const meta = this.#metadata.get(txHash);
+            if (meta) {
+                this.#removeFromPendingIndices(meta);
+            }
+        }
+        this.#protectedTransactions.set(txHash, slotNumber);
+    }
+    /** Sets protection for a txHash that may not have metadata yet */ setProtection(txHash, slotNumber) {
+        this.#protectedTransactions.set(txHash, slotNumber);
+    }
+    /** Gets the protection slot for a txHash, if protected */ getProtectionSlot(txHash) {
+        return this.#protectedTransactions.get(txHash);
+    }
+    /** Removes protection from tx hashes */ clearProtection(txHashes) {
+        for (const txHash of txHashes){
+            this.#protectedTransactions.delete(txHash);
+        }
+    }
+    /** Removes a transaction from all indices */ remove(txHash) {
+        const meta = this.#metadata.get(txHash);
+        if (!meta) {
+            return;
+        }
+        this.#metadata.delete(txHash);
+        this.#protectedTransactions.delete(txHash);
+        this.#removeFromPendingIndices(meta);
+    }
+    /** Removes a transaction from pending indices only (not metadata) */ removeFromPendingIndices(meta) {
+        this.#removeFromPendingIndices(meta);
+    }
+    /** Adds a transaction to pending indices (used during conflict resolution) */ addToPendingIndices(meta) {
+        this.#addToPendingIndices(meta);
+    }
+    // ============================================================================
+    // QUERIES FOR EVICTION RULES
+    // ============================================================================
+    /** Gets all pending transactions for a given fee payer */ getFeePayerPendingTxs(feePayer) {
+        const txHashes = this.#feePayerToTxHashes.get(feePayer);
+        if (!txHashes) {
+            return [];
+        }
+        const result = [];
+        for (const txHash of txHashes){
+            const meta = this.#metadata.get(txHash);
+            if (meta && this.getTxState(meta) === 'pending') {
+                result.push(meta);
+            }
+        }
+        return result;
+    }
+    /** Gets the count of pending transactions */ getPendingTxCount() {
+        return this.#pendingByPriority.length;
+    }
+    /**
+   * Returns whether at least `minCount` pending transactions were received at or before maxReceivedAt,
+   * i.e. are old enough to be eligible for block building. Stops as soon as the threshold is met, so it
+   * does not scan the whole pool when only a handful of eligible txs are needed. The total pending count
+   * is an upper bound on the eligible count, so a pool with fewer than `minCount` pending can never
+   * satisfy the threshold and short-circuits without scanning.
+   */ hasEligiblePendingTxs(maxReceivedAt, minCount) {
+        if (minCount <= 0) {
+            return true;
+        }
+        if (this.#pendingByPriority.length < minCount) {
+            return false;
+        }
+        let count = 0;
+        for (const _ of this.iterateEligiblePendingByPriority('desc', maxReceivedAt)){
+            if (++count >= minCount) {
+                return true;
+            }
+        }
+        return false;
+    }
+    /** Gets the lowest priority pending transaction hashes (up to limit) */ getLowestPriorityPending(limit) {
+        if (limit <= 0) {
+            return [];
+        }
+        const result = [];
+        for (const hash of this.iteratePendingByPriority('asc')){
+            result.push(hash);
+            if (result.length >= limit) {
+                break;
+            }
+        }
+        return result;
+    }
+    /** Gets the lowest priority pending transaction */ getLowestPriorityPendingTx() {
+        for (const txHash of this.iteratePendingByPriority('asc')){
+            const meta = this.#metadata.get(txHash);
+            if (meta) {
+                return meta;
+            }
+        }
+        return undefined;
+    }
+    /** Gets all pending transactions */ getPendingTxs() {
+        const result = [];
+        for (const entry of this.#pendingByPriority){
+            const meta = this.#metadata.get(entry.txHash);
+            if (meta) {
+                result.push(meta);
+            }
+        }
+        return result;
+    }
+    /** Gets all fee payers with pending transactions */ getPendingFeePayers() {
+        return Array.from(this.#feePayerToTxHashes.keys());
+    }
+    /** Gets the txHash that uses a given nullifier (pending txs only) */ getTxHashByNullifier(nullifier) {
+        return this.#nullifierToTxHash.get(nullifier);
+    }
+    /** Gets txHashes for a fee payer */ getTxHashesByFeePayer(feePayer) {
+        return this.#feePayerToTxHashes.get(feePayer);
+    }
+    // ============================================================================
+    // FIND/FILTER OPERATIONS
+    // ============================================================================
+    /** Finds all transactions mined in blocks after the given block number */ findTxsMinedAfter(blockNumber) {
+        const result = [];
+        for (const meta of this.#metadata.values()){
+            if (meta.minedL2BlockId !== undefined && meta.minedL2BlockId.number > blockNumber) {
+                result.push(meta);
+            }
+        }
+        return result;
+    }
+    /** Finds tx hashes mined at or before the given block number */ findTxsMinedAtOrBefore(blockNumber) {
+        const result = [];
+        for (const [txHash, meta] of this.#metadata){
+            if (meta.minedL2BlockId !== undefined && meta.minedL2BlockId.number <= blockNumber) {
+                result.push(txHash);
+            }
+        }
+        return result;
+    }
+    /** Finds protected tx hashes from slots earlier than the given slot number */ findExpiredProtectedTxs(slotNumber) {
+        const result = [];
+        for (const [txHash, protectedSlot] of this.#protectedTransactions){
+            if (protectedSlot < slotNumber) {
+                result.push(txHash);
+            }
+        }
+        return result;
+    }
+    /**
+   * From the given hashes, returns those whose protection is recorded at exactly the given slot.
+   * Used to release the protections a single block proposal created without disturbing entries a
+   * later proposal raised to a higher slot via updateProtection.
+   */ findProtectedTxsAtSlot(txHashes, slotNumber) {
+        return txHashes.filter((txHash)=>this.#protectedTransactions.get(txHash) === slotNumber);
+    }
+    /** Filters out transactions that are currently protected */ filterUnprotected(txs) {
+        return txs.filter((meta)=>!this.#protectedTransactions.has(meta.txHash));
+    }
+    /** Filters to transactions that have metadata and are not mined */ filterRestorable(txHashes) {
+        const result = [];
+        for (const txHash of txHashes){
+            const meta = this.#metadata.get(txHash);
+            if (meta && meta.minedL2BlockId === undefined) {
+                result.push(meta);
+            }
+        }
+        return result;
+    }
+    // ============================================================================
+    // METRICS
+    // ============================================================================
+    /** Counts transactions by state and estimates total metadata memory usage */ countTxs() {
+        let pending = 0;
+        let protected_ = 0;
+        let mined = 0;
+        let totalMetadataBytes = 0;
+        for (const meta of this.#metadata.values()){
+            totalMetadataBytes += meta.estimatedSizeBytes;
+            const state = this.getTxState(meta);
+            if (state === 'pending') {
+                pending++;
+            } else if (state === 'protected') {
+                protected_++;
+            } else if (state === 'mined') {
+                mined++;
+            }
+        }
+        return {
+            pending,
+            protected: protected_,
+            mined,
+            totalMetadataBytes
+        };
+    }
+    /** Returns the estimated total memory consumed by all metadata objects */ getTotalMetadataBytes() {
+        let total = 0;
+        for (const meta of this.#metadata.values()){
+            total += meta.estimatedSizeBytes;
+        }
+        return total;
+    }
+    /** Gets all mined transactions with their block IDs */ getMinedTxs() {
+        const result = [];
+        for (const [txHash, meta] of this.#metadata){
+            if (meta.minedL2BlockId !== undefined) {
+                result.push([
+                    txHash,
+                    meta.minedL2BlockId
+                ]);
+            }
+        }
+        return result;
+    }
+    // ============================================================================
+    // PRIVATE HELPERS
+    // ============================================================================
+    #addToPendingIndices(meta) {
+        // Add to nullifier index
+        for (const nullifier of meta.nullifiers){
+            this.#nullifierToTxHash.set(nullifier, meta.txHash);
+        }
+        // Add to fee payer index
+        let feePayerSet = this.#feePayerToTxHashes.get(meta.feePayer);
+        if (!feePayerSet) {
+            feePayerSet = new Set();
+            this.#feePayerToTxHashes.set(meta.feePayer, feePayerSet);
+        }
+        feePayerSet.add(meta.txHash);
+        insertIntoSortedArray(this.#pendingByPriority, {
+            txHash: meta.txHash,
+            priorityFee: meta.priorityFee,
+            txHashBigInt: meta.txHashBigInt
+        }, comparePriority, false);
+    }
+    #removeFromPendingIndices(meta) {
+        // Remove from nullifier index
+        for (const nullifier of meta.nullifiers){
+            this.#nullifierToTxHash.delete(nullifier);
+        }
+        // Remove from fee payer index
+        const feePayerSet = this.#feePayerToTxHashes.get(meta.feePayer);
+        if (feePayerSet) {
+            feePayerSet.delete(meta.txHash);
+            if (feePayerSet.size === 0) {
+                this.#feePayerToTxHashes.delete(meta.feePayer);
+            }
+        }
+        // Remove from priority array
+        removeFromSortedArray(this.#pendingByPriority, {
+            txHash: meta.txHash,
+            priorityFee: meta.priorityFee,
+            txHashBigInt: meta.txHashBigInt
+        }, comparePriority);
+    }
+}

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

@@ -0,0 +1,68 @@
+import { SlotNumber } from '@aztec/foundation/branded-types';
+import { type Logger } from '@aztec/foundation/log';
+import { DateProvider } from '@aztec/foundation/timer';
+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 } from '@aztec/telemetry-client';
+import type { AddTxsResult, PoolReadAccess, TxPoolV2, TxPoolV2Config, TxPoolV2Dependencies, TxPoolV2Events } from './interfaces.js';
+import type { TxState } from './tx_metadata.js';
+declare const AztecKVTxPoolV2_base: new () => TypedEventEmitter<TxPoolV2Events>;
+/**
+ * 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 declare class AztecKVTxPoolV2 extends AztecKVTxPoolV2_base implements TxPoolV2 {
+    #private;
+    constructor(store: AztecAsyncKVStore, archiveStore: AztecAsyncKVStore, deps: TxPoolV2Dependencies, telemetry?: TelemetryClient, config?: Partial<TxPoolV2Config>, dateProvider?: DateProvider, log?: Logger);
+    addPendingTxs(txs: Tx[], opts?: {
+        source?: string;
+        feeComparisonOnly?: boolean;
+    }): Promise<AddTxsResult>;
+    canAddPendingTx(tx: Tx): Promise<'accepted' | 'ignored'>;
+    addProtectedTxs(txs: Tx[], block: BlockHeader, opts?: {
+        source?: string;
+    }): Promise<void>;
+    protectTxs(txHashes: TxHash[], block: BlockHeader): Promise<TxHash[]>;
+    addMinedTxs(txs: Tx[], block: BlockHeader, opts?: {
+        source?: string;
+    }): Promise<void>;
+    handleMinedBlock(block: L2Block): Promise<void>;
+    prepareForSlot(slotNumber: SlotNumber): Promise<void>;
+    unprotectTxs(txHashes: TxHash[], slotNumber: SlotNumber): Promise<void>;
+    handlePrunedBlocks(latestBlock: L2BlockId, options?: {
+        deleteAllTxs?: boolean;
+    }): Promise<void>;
+    handleFailedExecution(txHashes: TxHash[]): Promise<void>;
+    handleFinalizedBlock(block: BlockHeader): Promise<void>;
+    getTxByHash(txHash: TxHash, opts?: {
+        includeProof?: boolean;
+    }): Promise<Tx | undefined>;
+    getTxsByHash(txHashes: TxHash[], opts?: {
+        includeProof?: boolean;
+    }): Promise<(Tx | undefined)[]>;
+    hasTxs(txHashes: TxHash[]): Promise<boolean[]>;
+    getTxStatus(txHash: TxHash): Promise<TxState | 'deleted' | undefined>;
+    getPendingTxHashes(): Promise<TxHash[]>;
+    getEligiblePendingTxHashes(): Promise<TxHash[]>;
+    getPendingTxCount(): Promise<number>;
+    hasEligiblePendingTxs(minCount: number): Promise<boolean>;
+    getMinedTxHashes(): Promise<[TxHash, L2BlockId][]>;
+    getMinedTxCount(): Promise<number>;
+    isEmpty(): Promise<boolean>;
+    getArchivedTxByHash(txHash: TxHash): Promise<Tx | undefined>;
+    getLowestPriorityPending(limit: number): Promise<TxHash[]>;
+    /** Returns read-only access to the pool. Used for testing. */
+    getPoolReadAccess(): PoolReadAccess;
+    updateConfig(config: Partial<TxPoolV2Config>): Promise<void>;
+    /**
+     * Starts the pool and initializes state from persistence.
+     */
+    start(): Promise<void>;
+    stop(): Promise<void>;
+}
+export {};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidHhfcG9vbF92Mi5kLnRzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vLi4vc3JjL21lbV9wb29scy90eF9wb29sX3YyL3R4X3Bvb2xfdjIudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxFQUFFLFVBQVUsRUFBRSxNQUFNLGlDQUFpQyxDQUFDO0FBQzdELE9BQU8sRUFBRSxLQUFLLE1BQU0sRUFBZ0IsTUFBTSx1QkFBdUIsQ0FBQztBQUVsRSxPQUFPLEVBQUUsWUFBWSxFQUFFLE1BQU0seUJBQXlCLENBQUM7QUFDdkQsT0FBTyxLQUFLLEVBQUUsaUJBQWlCLEVBQUUsTUFBTSx5QkFBeUIsQ0FBQztBQUNqRSxPQUFPLEtBQUssRUFBRSxpQkFBaUIsRUFBRSxNQUFNLGlCQUFpQixDQUFDO0FBQ3pELE9BQU8sS0FBSyxFQUFFLE9BQU8sRUFBRSxTQUFTLEVBQUUsTUFBTSxxQkFBcUIsQ0FBQztBQUM5RCxPQUFPLEVBQUUsV0FBVyxFQUFFLEVBQUUsRUFBRSxNQUFNLEVBQUUsTUFBTSxrQkFBa0IsQ0FBQztBQUMzRCxPQUFPLEVBQUUsS0FBSyxlQUFlLEVBQXNCLE1BQU0seUJBQXlCLENBQUM7QUFLbkYsT0FBTyxLQUFLLEVBQ1YsWUFBWSxFQUNaLGNBQWMsRUFDZCxRQUFRLEVBQ1IsY0FBYyxFQUNkLG9CQUFvQixFQUNwQixjQUFjLEVBQ2YsTUFBTSxpQkFBaUIsQ0FBQztBQUN6QixPQUFPLEtBQUssRUFBRSxPQUFPLEVBQUUsTUFBTSxrQkFBa0IsQ0FBQzs7QUFJaEQ7Ozs7O0dBS0c7QUFDSCxxQkFBYSxlQUFnQixTQUFRLG9CQUE4RCxZQUFXLFFBQVE7O0lBU3BILFlBQ0UsS0FBSyxFQUFFLGlCQUFpQixFQUN4QixZQUFZLEVBQUUsaUJBQWlCLEVBQy9CLElBQUksRUFBRSxvQkFBb0IsRUFDMUIsU0FBUyxHQUFFLGVBQXNDLEVBQ2pELE1BQU0sR0FBRSxPQUFPLENBQUMsY0FBYyxDQUFNLEVBQ3BDLFlBQVksR0FBRSxZQUFp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

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

@@ -0,0 +1 @@
+{"version":3,"file":"tx_pool_v2.d.ts","sourceRoot":"","sources":["../../../src/mem_pools/tx_pool_v2/tx_pool_v2.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAC;AAC7D,OAAO,EAAE,KAAK,MAAM,EAAgB,MAAM,uBAAuB,CAAC;AAElE,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AACvD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AACjE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACzD,OAAO,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAC9D,OAAO,EAAE,WAAW,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,EAAE,KAAK,eAAe,EAAsB,MAAM,yBAAyB,CAAC;AAKnF,OAAO,KAAK,EACV,YAAY,EACZ,cAAc,EACd,QAAQ,EACR,cAAc,EACd,oBAAoB,EACpB,cAAc,EACf,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;;AAIhD;;;;;GAKG;AACH,qBAAa,eAAgB,SAAQ,oBAA8D,YAAW,QAAQ;;IASpH,YACE,KAAK,EAAE,iBAAiB,EACxB,YAAY,EAAE,iBAAiB,EAC/B,IAAI,EAAE,oBAAoB,EAC1B,SAAS,GAAE,eAAsC,EACjD,MAAM,GAAE,OAAO,CAAC,cAAc,CAAM,EACpC,YAAY,GAAE,YAAiC,EAC/C,GAAG,SAAiC,EAiCrC;IAQD,aAAa,CAAC,GAAG,EAAE,EAAE,EAAE,EAAE,IAAI,GAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,iBAAiB,CAAC,EAAE,OAAO,CAAA;KAAO,GAAG,OAAO,CAAC,YAAY,CAAC,CAE3G;IAED,eAAe,CAAC,EAAE,EAAE,EAAE,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC,CAEvD;IAED,eAAe,CAAC,GAAG,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,WAAW,EAAE,IAAI,GAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAE5F;IAED,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAEpE;IAED,WAAW,CAAC,GAAG,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,WAAW,EAAE,IAAI,GAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAExF;IAID,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAE9C;IAED,cAAc,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAEpD;IAED,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAEtE;IAED,kBAAkB,CAAC,WAAW,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE;QAAE,YAAY,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAE9F;IAED,qBAAqB,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAEvD;IAED,oBAAoB,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAEtD;IAID,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,YAAY,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,EAAE,GAAG,SAAS,CAAC,CAEtF;IAED,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,IAAI,CAAC,EAAE;QAAE,YAAY,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,CAAC,EAAE,GAAG,SAAS,CAAC,EAAE,CAAC,CAE/F;IAED,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAE7C;IAED,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,SAAS,GAAG,SAAS,CAAC,CAEpE;IAED,kBAAkB,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC,CAEtC;IAED,0BAA0B,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC,CAE9C;IAED,iBAAiB,IAAI,OAAO,CAAC,MAAM,CAAC,CAEnC;IAED,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAExD;IAED,gBAAgB,IAAI,OAAO,CAAC,CAAC,MAAM,EAAE,SAAS,CAAC,EAAE,CAAC,CAEjD;IAED,eAAe,IAAI,OAAO,CAAC,MAAM,CAAC,CAEjC;IAED,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC,CAE1B;IAED,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,EAAE,GAAG,SAAS,CAAC,CAE3D;IAED,wBAAwB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAEzD;IAED,8DAA8D;IAC9D,iBAAiB,IAAI,cAAc,CAElC;IAID,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC,cAAc,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAK3D;IAID;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAoC3B;IAEK,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAK1B;CACF"}

package/dest/mem_pools/tx_pool_v2/tx_pool_v2.js

@@ -0,0 +1,178 @@
+import { createLogger } from '@aztec/foundation/log';
+import { SerialQueue } from '@aztec/foundation/queue';
+import { DateProvider } from '@aztec/foundation/timer';
+import { TxHash } from '@aztec/stdlib/tx';
+import { getTelemetryClient } from '@aztec/telemetry-client';
+import EventEmitter from 'node:events';
+import { PoolInstrumentation, PoolName } from '../instrumentation.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 {
+    #queue;
+    #impl;
+    #metrics;
+    #store;
+    #telemetry;
+    #log;
+    #started = false;
+    constructor(store, archiveStore, deps, telemetry = getTelemetryClient(), config = {}, dateProvider = new DateProvider(), 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, opts)=>{
+                this.emit('txs-added', {
+                    txs,
+                    ...opts
+                });
+            },
+            onTxsRemoved: (txHashes)=>{
+                // Convert to TxHash objects for the event
+                const hashes = txHashes.map((h)=>typeof h === 'string' ? TxHash.fromString(h) : TxHash.fromBigInt(h));
+                this.emit('txs-removed', {
+                    txHashes: hashes
+                });
+            },
+            onTxsMined: (minedTxs)=>{
+                // Pending-to-mined delay is derived from the tx's persisted receivedAt at the mined
+                // transition (see TxPoolV2Impl.handleMinedBlock), not the add/remove timestamp map —
+                // so eviction no longer pollutes MEMPOOL_TX_MINED_DELAY.
+                for (const { minedDelayMs } of minedTxs){
+                    if (minedDelayMs !== undefined) {
+                        this.#metrics?.recordMinedDelay(minedDelayMs);
+                    }
+                }
+            }
+        };
+        // Create the implementation
+        this.#impl = new TxPoolV2Impl(store, archiveStore, deps, callbacks, telemetry, config, dateProvider, log);
+    }
+    // ============================================================================
+    // PUBLIC API - All methods queue to the implementation
+    // ============================================================================
+    // === Core Operations ===
+    addPendingTxs(txs, opts = {}) {
+        return this.#queue.put(()=>this.#impl.addPendingTxs(txs, opts));
+    }
+    canAddPendingTx(tx) {
+        return this.#queue.put(()=>this.#impl.canAddPendingTx(tx));
+    }
+    addProtectedTxs(txs, block, opts = {}) {
+        return this.#queue.put(()=>this.#impl.addProtectedTxs(txs, block, opts));
+    }
+    protectTxs(txHashes, block) {
+        return this.#queue.put(()=>this.#impl.protectTxs(txHashes, block));
+    }
+    addMinedTxs(txs, block, opts = {}) {
+        return this.#queue.put(()=>this.#impl.addMinedTxs(txs, block, opts));
+    }
+    // === State Transition Handlers ===
+    handleMinedBlock(block) {
+        return this.#queue.put(()=>this.#impl.handleMinedBlock(block));
+    }
+    prepareForSlot(slotNumber) {
+        return this.#queue.put(()=>this.#impl.prepareForSlot(slotNumber));
+    }
+    unprotectTxs(txHashes, slotNumber) {
+        return this.#queue.put(()=>this.#impl.unprotectTxs(txHashes, slotNumber));
+    }
+    handlePrunedBlocks(latestBlock, options) {
+        return this.#queue.put(()=>this.#impl.handlePrunedBlocks(latestBlock, options));
+    }
+    handleFailedExecution(txHashes) {
+        return this.#queue.put(()=>this.#impl.handleFailedExecution(txHashes));
+    }
+    handleFinalizedBlock(block) {
+        return this.#queue.put(()=>this.#impl.handleFinalizedBlock(block));
+    }
+    // === Queries ===
+    getTxByHash(txHash, opts) {
+        return this.#queue.put(()=>this.#impl.getTxByHash(txHash, opts));
+    }
+    getTxsByHash(txHashes, opts) {
+        return this.#queue.put(()=>this.#impl.getTxsByHash(txHashes, opts));
+    }
+    hasTxs(txHashes) {
+        return this.#queue.put(()=>this.#impl.hasTxs(txHashes));
+    }
+    getTxStatus(txHash) {
+        return this.#queue.put(()=>Promise.resolve(this.#impl.getTxStatus(txHash)));
+    }
+    getPendingTxHashes() {
+        return this.#queue.put(()=>Promise.resolve(this.#impl.getPendingTxHashes()));
+    }
+    getEligiblePendingTxHashes() {
+        return this.#queue.put(()=>Promise.resolve(this.#impl.getEligiblePendingTxHashes()));
+    }
+    getPendingTxCount() {
+        return this.#queue.put(()=>Promise.resolve(this.#impl.getPendingTxCount()));
+    }
+    hasEligiblePendingTxs(minCount) {
+        return this.#queue.put(()=>Promise.resolve(this.#impl.hasEligiblePendingTxs(minCount)));
+    }
+    getMinedTxHashes() {
+        return this.#queue.put(()=>Promise.resolve(this.#impl.getMinedTxHashes()));
+    }
+    getMinedTxCount() {
+        return this.#queue.put(()=>Promise.resolve(this.#impl.getMinedTxCount()));
+    }
+    isEmpty() {
+        return this.#queue.put(()=>Promise.resolve(this.#impl.isEmpty()));
+    }
+    getArchivedTxByHash(txHash) {
+        return this.#queue.put(()=>this.#impl.getArchivedTxByHash(txHash));
+    }
+    getLowestPriorityPending(limit) {
+        return this.#queue.put(()=>Promise.resolve(this.#impl.getLowestPriorityPending(limit)));
+    }
+    /** Returns read-only access to the pool. Used for testing. */ getPoolReadAccess() {
+        return this.#impl.getPoolReadAccess();
+    }
+    // === Configuration ===
+    updateConfig(config) {
+        return this.#queue.put(()=>{
+            this.#impl.updateConfig(config);
+            return Promise.resolve();
+        });
+    }
+    // === Lifecycle ===
+    /**
+   * Starts the pool and initializes state from persistence.
+   */ async start() {
+        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,
+                        softDeleted: counts.softDeleted
+                    }
+                });
+            }), ()=>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() {
+        if (this.#started) {
+            await this.#queue.end();
+            this.#started = false;
+        }
+    }
+}