@aztec/p2p 0.0.1-commit.9d2bcf6d → 0.0.1-commit.aada20e3

package/dest/mem_pools/tx_pool_v2/tx_pool_v2_impl.js

@@ -0,0 +1,1041 @@
+import { ProtocolContractAddress } from '@aztec/protocol-contracts';
+import { computeFeePayerBalanceStorageSlot } from '@aztec/protocol-contracts/fee-juice';
+import { AztecAddress } from '@aztec/stdlib/aztec-address';
+import { DatabasePublicStateSource } from '@aztec/stdlib/trees';
+import { Tx, TxHash } from '@aztec/stdlib/tx';
+import { TxArchive } from './archive/index.js';
+import { EvictionManager, FeePayerBalanceEvictionRule, FeePayerBalancePreAddRule, InvalidTxsAfterMiningRule, InvalidTxsAfterReorgRule, LowPriorityEvictionRule, LowPriorityPreAddRule, NullifierConflictRule } from './eviction/index.js';
+import { DEFAULT_TX_POOL_V2_CONFIG } from './interfaces.js';
+import { buildTxMetaData, checkNullifierConflict, compareFee, compareTxHash } from './tx_metadata.js';
+/**
+ * Implementation of TxPoolV2 logic.
+ *
+ * This class contains all the actual transaction pool logic.
+ */ export class TxPoolV2Impl {
+    // === Persistence ===
+    #store;
+    #txsDB;
+    // === Dependencies ===
+    #l2BlockSource;
+    #worldStateSynchronizer;
+    #pendingTxValidator;
+    // === In-Memory Indices ===
+    /** 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 txHashes grouped by priority fee.
+   * Outer map: priorityFee -> Set of txHashes at that fee level.
+   */ #pendingByPriority = new Map();
+    /** Protected transactions: txHash -> slotNumber. Includes txs we have and txs we expect to receive. */ #protectedTransactions = new Map();
+    // === Config & Services ===
+    #config;
+    #archive;
+    #evictionManager;
+    #log;
+    #callbacks;
+    constructor(store, archiveStore, deps, callbacks, config = {}, log){
+        this.#store = store;
+        this.#txsDB = store.openMap('txs');
+        this.#l2BlockSource = deps.l2BlockSource;
+        this.#worldStateSynchronizer = deps.worldStateSynchronizer;
+        this.#pendingTxValidator = deps.pendingTxValidator;
+        this.#config = {
+            ...DEFAULT_TX_POOL_V2_CONFIG,
+            ...config
+        };
+        this.#archive = new TxArchive(archiveStore, this.#config.archivedTxLimit, log);
+        this.#log = log;
+        this.#callbacks = callbacks;
+        // Setup eviction manager with rules
+        this.#evictionManager = new EvictionManager(this.#createPoolOperations(), log);
+        // Pre-add rules (run during addPendingTxs) - work with TxMetaData
+        this.#evictionManager.registerPreAddRule(new NullifierConflictRule());
+        this.#evictionManager.registerPreAddRule(new FeePayerBalancePreAddRule());
+        this.#evictionManager.registerPreAddRule(new LowPriorityPreAddRule({
+            maxPoolSize: this.#config.maxPendingTxCount
+        }));
+        // Post-event eviction rules (run after events to check ALL pending txs)
+        this.#evictionManager.registerRule(new InvalidTxsAfterMiningRule());
+        this.#evictionManager.registerRule(new InvalidTxsAfterReorgRule(deps.worldStateSynchronizer));
+        this.#evictionManager.registerRule(new FeePayerBalanceEvictionRule(deps.worldStateSynchronizer));
+        // LowPriorityEvictionRule handles cases where txs become pending via prepareForSlot (unprotect)
+        // The pre-add rule handles the addPendingTxs case, but post-event is needed for unprotect
+        this.#evictionManager.registerRule(new LowPriorityEvictionRule({
+            maxPoolSize: this.#config.maxPendingTxCount
+        }));
+    }
+    // ============================================================================
+    // PUBLIC IMPLEMENTATION METHODS
+    // ============================================================================
+    /**
+   * Hydrates the in-memory state from the database on startup.
+   * Pipeline: Load → Check Mined Status → Partition → Validate Non-Mined → Rebuild Pending Pool → Delete Invalid
+   *
+   * Note: Protected status is lost on restart. All non-mined txs are rebuilt as pending
+   * by running pre-add rules to resolve nullifier conflicts, balance checks, and pool size limits.
+   */ async hydrateFromDatabase() {
+        // Step 1: Load all transactions from DB
+        const { loaded, errors: deserializationErrors } = await this.#loadAllTxsFromDb();
+        // Step 2: Check mined status for each tx
+        await this.#markMinedStatusBatch(loaded.map((l)=>l.meta));
+        // Step 3: Partition by mined status
+        const { mined, nonMined } = this.#partitionByMinedStatus(loaded);
+        // Step 4: Validate non-mined transactions
+        const { valid, invalid } = await this.#validateNonMinedTxs(nonMined);
+        // Step 5: Populate mined indices (these don't need conflict resolution)
+        this.#populateMinedIndices(mined);
+        // Step 6: Rebuild pending pool by running pre-add rules for each tx
+        // This resolves nullifier conflicts, fee payer balance issues, and pool size limits
+        const { rejected } = await this.#rebuildPendingPool(valid);
+        // Step 7: Delete invalid and rejected txs from DB
+        const toDelete = [
+            ...deserializationErrors,
+            ...invalid,
+            ...rejected
+        ];
+        if (toDelete.length === 0) {
+            return;
+        }
+        await this.#store.transactionAsync(async ()=>{
+            for (const txHashStr of toDelete){
+                await this.#txsDB.delete(txHashStr);
+            }
+        });
+        this.#log.info(`Deleted ${toDelete.length} invalid/rejected transactions on startup`);
+    }
+    async addPendingTxs(txs, opts) {
+        const accepted = [];
+        const ignored = [];
+        const rejected = [];
+        const newlyAdded = [];
+        const acceptedPending = new Set();
+        const poolAccess = this.#createPreAddPoolAccess();
+        await this.#store.transactionAsync(async ()=>{
+            for (const tx of txs){
+                const txHash = tx.getTxHash();
+                const txHashStr = txHash.toString();
+                // Skip duplicates
+                if (this.#isDuplicateTx(txHashStr)) {
+                    ignored.push(txHash);
+                    continue;
+                }
+                // Check mined status first (applies to all paths)
+                const minedBlockId = await this.#getMinedBlockId(txHash);
+                const preProtectedSlot = this.#protectedTransactions.get(txHashStr);
+                if (minedBlockId) {
+                    // Already mined - add directly (protection already set if pre-protected)
+                    await this.#addNewMinedTx(tx, minedBlockId);
+                    accepted.push(txHash);
+                    newlyAdded.push(tx);
+                } else if (preProtectedSlot !== undefined) {
+                    // Pre-protected and not mined - add as protected (bypass validation)
+                    await this.#addNewProtectedTx(tx, preProtectedSlot);
+                    accepted.push(txHash);
+                    newlyAdded.push(tx);
+                } else {
+                    // Regular pending tx - validate and run pre-add rules
+                    const result = await this.#tryAddRegularPendingTx(tx, poolAccess, acceptedPending, ignored);
+                    if (result.status === 'accepted') {
+                        acceptedPending.add(txHashStr);
+                        newlyAdded.push(tx);
+                    } else if (result.status === 'rejected') {
+                        rejected.push(txHash);
+                    } else {
+                        ignored.push(txHash);
+                    }
+                }
+            }
+        });
+        // Build final accepted list for pending txs (excludes intra-batch evictions)
+        for (const txHashStr of acceptedPending){
+            accepted.push(TxHash.fromString(txHashStr));
+        }
+        // Run post-add eviction rules for pending txs
+        if (acceptedPending.size > 0) {
+            const feePayers = Array.from(acceptedPending).map((txHash)=>this.#metadata.get(txHash).feePayer);
+            const uniqueFeePayers = new Set(feePayers);
+            await this.#evictionManager.evictAfterNewTxs(Array.from(acceptedPending), [
+                ...uniqueFeePayers
+            ]);
+        }
+        // Emit events
+        if (newlyAdded.length > 0) {
+            this.#callbacks.onTxsAdded(newlyAdded, opts);
+        }
+        return {
+            accepted,
+            ignored,
+            rejected
+        };
+    }
+    /** Validates and adds a regular pending tx. Returns status. */ async #tryAddRegularPendingTx(tx, poolAccess, acceptedPending, ignored) {
+        const txHash = tx.getTxHash();
+        const txHashStr = txHash.toString();
+        // Validate transaction
+        const validationResult = await this.#pendingTxValidator.validateTx(tx);
+        if (validationResult.result !== 'valid') {
+            this.#log.info(`Rejecting tx ${txHashStr}: ${validationResult.reason?.join(', ')}`);
+            return {
+                status: 'rejected'
+            };
+        }
+        // Build metadata and run pre-add rules
+        const meta = await buildTxMetaData(tx);
+        const preAddResult = await this.#evictionManager.runPreAddRules(meta, poolAccess);
+        if (preAddResult.shouldIgnore) {
+            this.#log.debug(`Ignoring tx ${txHashStr}: ${preAddResult.reason}`);
+            return {
+                status: 'ignored'
+            };
+        }
+        // Evict conflicts (tracking intra-batch evictions)
+        for (const evictHashStr of preAddResult.txHashesToEvict){
+            await this.#deleteTx(evictHashStr);
+            this.#log.debug(`Evicted tx ${evictHashStr} due to higher-fee tx ${txHashStr}`);
+            if (acceptedPending.has(evictHashStr)) {
+                acceptedPending.delete(evictHashStr);
+                ignored.push(TxHash.fromString(evictHashStr));
+            }
+        }
+        // Add the transaction
+        await this.#addNewPendingTx(tx);
+        return {
+            status: 'accepted'
+        };
+    }
+    async canAddPendingTx(tx) {
+        const txHashStr = tx.getTxHash().toString();
+        // Check if already in pool
+        if (this.#metadata.has(txHashStr)) {
+            return 'ignored';
+        }
+        // Validate transaction
+        const validationResult = await this.#pendingTxValidator.validateTx(tx);
+        if (validationResult.result !== 'valid') {
+            return 'rejected';
+        }
+        // Build metadata and use pre-add rules
+        const meta = await buildTxMetaData(tx);
+        const poolAccess = this.#createPreAddPoolAccess();
+        const preAddResult = await this.#evictionManager.runPreAddRules(meta, poolAccess);
+        return preAddResult.shouldIgnore ? 'ignored' : 'accepted';
+    }
+    async addProtectedTxs(txs, block, opts) {
+        const slotNumber = block.globalVariables.slotNumber;
+        const newlyAdded = [];
+        await this.#store.transactionAsync(async ()=>{
+            for (const tx of txs){
+                const txHash = tx.getTxHash();
+                const txHashStr = txHash.toString();
+                const isNew = !this.#metadata.has(txHashStr);
+                const minedBlockId = await this.#getMinedBlockId(txHash);
+                if (isNew) {
+                    // New tx - add as mined or protected
+                    if (minedBlockId) {
+                        await this.#addNewMinedTx(tx, minedBlockId);
+                        this.#protectedTransactions.set(txHashStr, slotNumber);
+                    } else {
+                        await this.#addNewProtectedTx(tx, slotNumber);
+                    }
+                    newlyAdded.push(tx);
+                } else {
+                    // Existing tx - update protection and mined status
+                    this.#updateProtection(txHashStr, slotNumber);
+                    if (minedBlockId) {
+                        this.#markAsMined(this.#metadata.get(txHashStr), minedBlockId);
+                    }
+                }
+            }
+        });
+        if (newlyAdded.length > 0) {
+            this.#callbacks.onTxsAdded(newlyAdded, opts);
+        }
+    }
+    protectTxs(txHashes, block) {
+        const slotNumber = block.globalVariables.slotNumber;
+        const missing = [];
+        for (const txHash of txHashes){
+            const txHashStr = txHash.toString();
+            if (this.#metadata.has(txHashStr)) {
+                // Step 1a: Update protection for existing tx
+                this.#updateProtection(txHashStr, slotNumber);
+            } else {
+                // Step 1b: Pre-record protection for tx we don't have yet
+                this.#protectedTransactions.set(txHashStr, slotNumber);
+                missing.push(txHash);
+            }
+        }
+        return missing;
+    }
+    async addMinedTxs(txs, block, opts) {
+        // Step 1: Build block ID
+        const blockId = await this.#buildBlockId(block);
+        const newlyAdded = [];
+        await this.#store.transactionAsync(async ()=>{
+            for (const tx of txs){
+                const txHashStr = tx.getTxHash().toString();
+                const existingMeta = this.#metadata.get(txHashStr);
+                if (existingMeta) {
+                    // Step 2a: Mark existing tx as mined
+                    this.#markAsMined(existingMeta, blockId);
+                } else {
+                    // Step 2b: Add new mined tx
+                    await this.#addNewMinedTx(tx, blockId);
+                    newlyAdded.push(tx);
+                }
+            }
+        });
+        // Step 3: Emit events for newly added txs
+        if (newlyAdded.length > 0) {
+            this.#callbacks.onTxsAdded(newlyAdded, opts);
+        }
+    }
+    async handleMinedBlock(block) {
+        // Step 1: Build block ID
+        const blockId = await this.#buildBlockId(block.header);
+        // Step 2: Extract tx hashes and nullifiers directly from the block
+        const txHashes = block.body.txEffects.map((tx)=>tx.txHash);
+        const nullifiers = block.body.txEffects.flatMap((tx)=>tx.nullifiers.map((n)=>n.toString()));
+        // Step 3: Collect fee payers from txs we have in the pool (for balance-based eviction)
+        const feePayers = [];
+        const found = [];
+        for (const txHash of txHashes){
+            const meta = this.#metadata.get(txHash.toString());
+            if (meta) {
+                feePayers.push(meta.feePayer);
+                found.push(meta);
+            }
+        }
+        // Step 4: Mark txs as mined (only those we have in the pool)
+        this.#markTxsAsMined(found, blockId);
+        // Step 5: Run eviction rules (remove pending txs with conflicting nullifiers/expired timestamps)
+        await this.#evictionManager.evictAfterNewBlock(block.header, nullifiers, feePayers);
+        this.#callbacks.onTxsRemoved(txHashes.map((h)=>h.toBigInt()));
+        this.#log.info(`Marked ${found.length} txs as mined in block ${blockId.number}`);
+    }
+    async prepareForSlot(slotNumber) {
+        // Step 1: Find expired protected txs
+        const expiredProtected = this.#findExpiredProtectedTxs(slotNumber);
+        // Step 2: Clear protection for all expired entries (including those without metadata)
+        this.#clearProtection(expiredProtected);
+        // Step 3: Filter to only txs that have metadata and are not mined
+        const txsToRestore = this.#filterRestorable(expiredProtected);
+        if (txsToRestore.length === 0) {
+            return;
+        }
+        this.#log.info(`Preparing for slot ${slotNumber}: unprotecting ${txsToRestore.length} txs`);
+        // Step 4: Validate for pending pool
+        const { valid, invalid } = await this.#validateForPending(txsToRestore);
+        // Step 5: Resolve nullifier conflicts and add winners to pending indices
+        const { added, toEvict } = this.#applyNullifierConflictResolution(valid);
+        // Step 6: Delete invalid and evicted txs
+        await this.#deleteTxsBatch([
+            ...invalid,
+            ...toEvict
+        ]);
+        // Step 7: Run eviction rules (enforce pool size limit)
+        if (added.length > 0) {
+            const feePayers = added.map((meta)=>meta.feePayer);
+            const uniqueFeePayers = new Set(feePayers);
+            await this.#evictionManager.evictAfterNewTxs(added.map((m)=>m.txHash), [
+                ...uniqueFeePayers
+            ]);
+        }
+    }
+    async handlePrunedBlocks(latestBlock) {
+        // Step 1: Find transactions mined after the prune point
+        const txsToUnmine = this.#findTxsMinedAfter(latestBlock.number);
+        if (txsToUnmine.length === 0) {
+            this.#log.debug(`No transactions to un-mine for prune to block ${latestBlock.number}`);
+            return;
+        }
+        this.#log.info(`Handling prune to block ${latestBlock.number}: un-mining ${txsToUnmine.length} txs`);
+        // Step 2: Unmine - clear mined status from metadata
+        this.#unmineTxs(txsToUnmine);
+        // Step 3: Filter out protected txs (they'll be handled by prepareForSlot)
+        const unprotectedTxs = this.#filterUnprotected(txsToUnmine);
+        // Step 4: Validate for pending pool
+        const { valid, invalid } = await this.#validateForPending(unprotectedTxs);
+        // Step 5: Resolve nullifier conflicts and add winners to pending indices
+        const { toEvict } = this.#applyNullifierConflictResolution(valid);
+        // Step 6: Delete invalid and evicted txs
+        await this.#deleteTxsBatch([
+            ...invalid,
+            ...toEvict
+        ]);
+        // Step 7: Run eviction rules for ALL pending txs (not just restored ones)
+        // This handles cases like existing pending txs with invalid fee payer balances
+        await this.#evictionManager.evictAfterChainPrune(latestBlock.number);
+    }
+    async handleFailedExecution(txHashes) {
+        // Step 1: Delete failed txs
+        await this.#deleteTxsBatch(txHashes.map((h)=>h.toString()));
+        this.#log.info(`Deleted ${txHashes.length} failed txs`);
+    }
+    async handleFinalizedBlock(block) {
+        const blockNumber = block.globalVariables.blockNumber;
+        // Step 1: Find txs mined at or before finalized block
+        const txsToFinalize = this.#findTxsMinedAtOrBefore(blockNumber);
+        if (txsToFinalize.length === 0) {
+            return;
+        }
+        // Step 2: Collect txs for archiving (before deletion)
+        const txsToArchive = [];
+        if (this.#archive.isEnabled()) {
+            for (const txHashStr of txsToFinalize){
+                const buffer = await this.#txsDB.getAsync(txHashStr);
+                if (buffer) {
+                    txsToArchive.push(Tx.fromBuffer(buffer));
+                }
+            }
+        }
+        // Step 3: Delete from active pool
+        await this.#deleteTxsBatch(txsToFinalize);
+        // Step 4: Archive
+        if (txsToArchive.length > 0) {
+            await this.#archive.archiveTxs(txsToArchive);
+        }
+        this.#log.info(`Finalized ${txsToFinalize.length} txs from blocks up to ${blockNumber}`);
+    }
+    // === Query Methods ===
+    async getTxByHash(txHash) {
+        const buffer = await this.#txsDB.getAsync(txHash.toString());
+        return buffer ? Tx.fromBuffer(buffer) : undefined;
+    }
+    async getTxsByHash(txHashes) {
+        const results = [];
+        for (const h of txHashes){
+            const buffer = await this.#txsDB.getAsync(h.toString());
+            results.push(buffer ? Tx.fromBuffer(buffer) : undefined);
+        }
+        return results;
+    }
+    hasTxs(txHashes) {
+        return txHashes.map((h)=>this.#metadata.has(h.toString()));
+    }
+    getTxStatus(txHash) {
+        const meta = this.#metadata.get(txHash.toString());
+        if (!meta) {
+            return undefined;
+        }
+        return this.#getTxState(meta);
+    }
+    getPendingTxHashes() {
+        return [
+            ...this.#iteratePendingByPriority('desc')
+        ].map((hash)=>TxHash.fromString(hash));
+    }
+    getPendingTxCount() {
+        let count = 0;
+        for (const hashes of this.#pendingByPriority.values()){
+            count += hashes.size;
+        }
+        return count;
+    }
+    getMinedTxHashes() {
+        const result = [];
+        for (const [txHash, meta] of this.#metadata){
+            if (meta.minedL2BlockId !== undefined) {
+                result.push([
+                    TxHash.fromString(txHash),
+                    meta.minedL2BlockId
+                ]);
+            }
+        }
+        return result;
+    }
+    getMinedTxCount() {
+        let count = 0;
+        for (const meta of this.#metadata.values()){
+            if (meta.minedL2BlockId !== undefined) {
+                count++;
+            }
+        }
+        return count;
+    }
+    isEmpty() {
+        return this.#metadata.size === 0;
+    }
+    getTxCount() {
+        return this.#metadata.size;
+    }
+    getArchivedTxByHash(txHash) {
+        return this.#archive.getTxByHash(txHash);
+    }
+    getLowestPriorityPending(limit) {
+        if (limit <= 0) {
+            return [];
+        }
+        const result = [];
+        for (const hash of this.#iteratePendingByPriority('asc')){
+            result.push(TxHash.fromString(hash));
+            if (result.length >= limit) {
+                break;
+            }
+        }
+        return result;
+    }
+    // === Configuration ===
+    updateConfig(config) {
+        if (config.maxPendingTxCount !== undefined) {
+            this.#config.maxPendingTxCount = config.maxPendingTxCount;
+        }
+        if (config.archivedTxLimit !== undefined) {
+            this.#config.archivedTxLimit = config.archivedTxLimit;
+            this.#archive.updateLimit(config.archivedTxLimit);
+        }
+        // Update eviction rules with new config
+        this.#evictionManager.updateConfig(config);
+    }
+    // === Pool Read Access ===
+    getPoolReadAccess() {
+        return {
+            getMetadata: (txHash)=>this.#metadata.get(txHash),
+            getTxHashByNullifier: (nullifier)=>this.#nullifierToTxHash.get(nullifier),
+            getTxHashesByFeePayer: (feePayer)=>this.#feePayerToTxHashes.get(feePayer),
+            getPendingTxCount: ()=>this.getPendingTxCount()
+        };
+    }
+    // === Metrics ===
+    countTxs() {
+        let pending = 0;
+        let protected_ = 0;
+        let mined = 0;
+        for (const meta of this.#metadata.values()){
+            const state = this.#getTxState(meta);
+            if (state === 'pending') {
+                pending++;
+            } else if (state === 'protected') {
+                protected_++;
+            } else if (state === 'mined') {
+                mined++;
+            }
+        }
+        return {
+            pending,
+            protected: protected_,
+            mined
+        };
+    }
+    // ============================================================================
+    // PRIVATE QUERY IMPLEMENTATIONS
+    // ============================================================================
+    /**
+   * 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';
+        }
+    }
+    /**
+   * Iterates pending transaction hashes in priority order.
+   * @param order - 'desc' for highest priority first, 'asc' for lowest priority first
+   */ *#iteratePendingByPriority(order) {
+        // Use shared comparators, negating for descending order
+        const feeCompareFn = order === 'desc' ? (a, b)=>compareFee(b, a) : (a, b)=>compareFee(a, b);
+        const hashCompareFn = order === 'desc' ? (a, b)=>compareTxHash(b, a) : (a, b)=>compareTxHash(a, b);
+        const sortedFees = [
+            ...this.#pendingByPriority.keys()
+        ].sort(feeCompareFn);
+        for (const fee of sortedFees){
+            const hashesAtFee = this.#pendingByPriority.get(fee);
+            const sortedHashes = [
+                ...hashesAtFee
+            ].sort(hashCompareFn);
+            for (const hash of sortedHashes){
+                yield hash;
+            }
+        }
+    }
+    // ============================================================================
+    // HELPER FUNCTIONS - Pipeline Step Functions
+    // ============================================================================
+    // --- Finding & Filtering Steps ---
+    /** 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 [txHashStr, meta] of this.#metadata){
+            if (meta.minedL2BlockId !== undefined && meta.minedL2BlockId.number <= blockNumber) {
+                result.push(txHashStr);
+            }
+        }
+        return result;
+    }
+    /** Finds protected tx hashes from slots earlier than the given slot number */ #findExpiredProtectedTxs(slotNumber) {
+        const result = [];
+        for (const [txHashStr, protectedSlot] of this.#protectedTransactions){
+            if (protectedSlot < slotNumber) {
+                result.push(txHashStr);
+            }
+        }
+        return result;
+    }
+    /** 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 txHashStr of txHashes){
+            const meta = this.#metadata.get(txHashStr);
+            if (meta && meta.minedL2BlockId === undefined) {
+                result.push(meta);
+            }
+        }
+        return result;
+    }
+    // --- Validation & Conflict Resolution Steps ---
+    /** Validates transactions for pending pool, returning valid and invalid groups */ async #validateForPending(txs) {
+        const valid = [];
+        const invalid = [];
+        for (const meta of txs){
+            const buffer = await this.#txsDB.getAsync(meta.txHash);
+            if (!buffer) {
+                this.#log.warn(`Tx ${meta.txHash} not found in DB during validation`);
+                invalid.push(meta.txHash);
+                continue;
+            }
+            const tx = Tx.fromBuffer(buffer);
+            const result = await this.#pendingTxValidator.validateTx(tx);
+            if (result.result === 'valid') {
+                valid.push(meta);
+            } else {
+                this.#log.info(`Tx ${meta.txHash} failed validation: ${result.reason?.join(', ')}`);
+                invalid.push(meta.txHash);
+            }
+        }
+        return {
+            valid,
+            invalid
+        };
+    }
+    /**
+   * Resolves nullifier conflicts between incoming txs and existing pending txs.
+   * Modifies the pending indices during iteration to maintain consistent state
+   * for subsequent conflict checks within the same batch.
+   */ #applyNullifierConflictResolution(txs) {
+        const added = [];
+        const toEvict = [];
+        for (const meta of txs){
+            const conflict = checkNullifierConflict(meta, (nullifier)=>this.#nullifierToTxHash.get(nullifier), (txHash)=>this.#metadata.get(txHash));
+            if (conflict.shouldIgnore) {
+                // Lower priority than existing - don't add, mark for deletion
+                toEvict.push(meta.txHash);
+            } else {
+                // Higher priority - evict existing conflicts
+                toEvict.push(...conflict.txHashesToEvict);
+                // Remove evicted from indices immediately for subsequent checks
+                for (const evictHash of conflict.txHashesToEvict){
+                    const evictMeta = this.#metadata.get(evictHash);
+                    if (evictMeta) {
+                        this.#removeFromPendingIndices(evictMeta);
+                    }
+                }
+                // Add to pending indices immediately so subsequent txs in the batch see this tx
+                this.#addToPendingIndices(meta);
+                added.push(meta);
+            }
+        }
+        return {
+            added,
+            toEvict
+        };
+    }
+    // --- State Transition Steps ---
+    /** Clears the mined status from transactions, returning them for further processing */ #unmineTxs(txs) {
+        for (const meta of txs){
+            meta.minedL2BlockId = undefined;
+        }
+        return txs;
+    }
+    /** Removes protection from tx hashes and clears them from the protected map */ #clearProtection(txHashes) {
+        for (const txHashStr of txHashes){
+            this.#protectedTransactions.delete(txHashStr);
+        }
+    }
+    // --- Batch Operation Steps ---
+    /** Deletes a batch of transactions permanently */ async #deleteTxsBatch(txHashes) {
+        if (txHashes.length === 0) {
+            return;
+        }
+        await this.#store.transactionAsync(async ()=>{
+            for (const txHashStr of txHashes){
+                await this.#deleteTx(txHashStr);
+            }
+        });
+        this.#callbacks.onTxsRemoved(txHashes);
+    }
+    // --- Block & Tx Info Steps ---
+    /** Builds a block ID from a block header */ async #buildBlockId(block) {
+        return {
+            number: block.globalVariables.blockNumber,
+            hash: (await block.hash()).toString()
+        };
+    }
+    /** Checks if a tx is already mined and returns its block ID if so */ async #getMinedBlockId(txHash) {
+        const txEffect = await this.#l2BlockSource.getTxEffect(txHash);
+        if (!txEffect) {
+            return undefined;
+        }
+        return {
+            number: txEffect.l2BlockNumber,
+            hash: txEffect.l2BlockHash.toString()
+        };
+    }
+    /** Marks a batch of transactions as mined */ #markTxsAsMined(metas, blockId) {
+        for (const meta of metas){
+            this.#markAsMined(meta, blockId);
+        }
+    }
+    // --- Add Transaction Steps ---
+    /** Persists a transaction to the database */ async #persistTx(txHashStr, tx) {
+        await this.#txsDB.set(txHashStr, tx.toBuffer());
+    }
+    /** Adds a new transaction as protected, returning its metadata */ async #addNewProtectedTx(tx, slotNumber) {
+        const txHashStr = tx.getTxHash().toString();
+        const meta = await buildTxMetaData(tx);
+        this.#protectedTransactions.set(txHashStr, slotNumber);
+        await this.#persistTx(txHashStr, tx);
+        this.#metadata.set(txHashStr, meta);
+        // Don't add to pending indices since it's protected
+        this.#log.verbose(`Added protected tx ${txHashStr} for slot ${slotNumber}`);
+        return meta;
+    }
+    /** Adds a new transaction as mined, returning its metadata */ async #addNewMinedTx(tx, blockId) {
+        const txHashStr = tx.getTxHash().toString();
+        const meta = await buildTxMetaData(tx);
+        meta.minedL2BlockId = blockId;
+        await this.#persistTx(txHashStr, tx);
+        this.#metadata.set(txHashStr, meta);
+        // Don't add to pending indices since it's mined
+        this.#log.verbose(`Added mined tx ${txHashStr} from block ${blockId.number}`);
+        return meta;
+    }
+    // --- Hydration Steps ---
+    /** Loads all transactions from the database, returning loaded txs and deserialization errors */ async #loadAllTxsFromDb() {
+        const loaded = [];
+        const errors = [];
+        for await (const [txHashStr, buffer] of this.#txsDB.entriesAsync()){
+            try {
+                const tx = Tx.fromBuffer(buffer);
+                const meta = await buildTxMetaData(tx);
+                loaded.push({
+                    tx,
+                    meta
+                });
+            } catch (err) {
+                this.#log.warn(`Failed to deserialize tx ${txHashStr}, deleting`, {
+                    err
+                });
+                errors.push(txHashStr);
+            }
+        }
+        return {
+            loaded,
+            errors
+        };
+    }
+    /** Queries block source and marks mined status on transaction metadata */ async #markMinedStatusBatch(metas) {
+        for (const meta of metas){
+            try {
+                const txEffect = await this.#l2BlockSource.getTxEffect(TxHash.fromString(meta.txHash));
+                if (txEffect) {
+                    meta.minedL2BlockId = {
+                        number: txEffect.l2BlockNumber,
+                        hash: txEffect.l2BlockHash.toString()
+                    };
+                }
+            } catch (err) {
+                this.#log.warn(`Failed to check mined status for tx ${meta.txHash}`, {
+                    err
+                });
+            }
+        }
+    }
+    /** Partitions transactions by mined status */ #partitionByMinedStatus(txs) {
+        const mined = [];
+        const nonMined = [];
+        for (const entry of txs){
+            if (entry.meta.minedL2BlockId !== undefined) {
+                mined.push(entry.meta);
+            } else {
+                nonMined.push(entry);
+            }
+        }
+        return {
+            mined,
+            nonMined
+        };
+    }
+    /** Validates non-mined transactions, returning valid metadata and invalid hashes */ async #validateNonMinedTxs(txs) {
+        const valid = [];
+        const invalid = [];
+        for (const { tx, meta } of txs){
+            const result = await this.#pendingTxValidator.validateTx(tx);
+            if (result.result === 'valid') {
+                valid.push(meta);
+            } else {
+                this.#log.info(`Removing invalid tx ${meta.txHash} on startup: ${result.reason?.join(', ')}`);
+                invalid.push(meta.txHash);
+            }
+        }
+        return {
+            valid,
+            invalid
+        };
+    }
+    /** Populates metadata index for mined transactions */ #populateMinedIndices(metas) {
+        for (const meta of metas){
+            this.#metadata.set(meta.txHash, meta);
+        }
+    }
+    /**
+   * Rebuilds the pending pool by processing each tx through pre-add rules.
+   * Starts with an empty pending pool and adds txs one by one, resolving conflicts.
+   * Returns the list of accepted and rejected tx hashes.
+   */ async #rebuildPendingPool(metas) {
+        const accepted = new Set();
+        const rejected = [];
+        const poolAccess = this.#createPreAddPoolAccess();
+        for (const meta of metas){
+            // Run pre-add rules against current pending pool state (metadata not yet in pool)
+            const preAddResult = await this.#evictionManager.runPreAddRules(meta, poolAccess);
+            if (preAddResult.shouldIgnore) {
+                // Transaction rejected - mark for deletion from DB
+                rejected.push(meta.txHash);
+                this.#log.debug(`Rejected tx ${meta.txHash} during rebuild: ${preAddResult.reason}`);
+                continue;
+            }
+            // Evict any conflicting txs identified by pre-add rules
+            for (const evictHashStr of preAddResult.txHashesToEvict){
+                const evictMeta = this.#metadata.get(evictHashStr);
+                if (evictMeta) {
+                    this.#removeFromPendingIndices(evictMeta);
+                    this.#metadata.delete(evictHashStr);
+                    rejected.push(evictHashStr);
+                    accepted.delete(evictHashStr);
+                    this.#log.debug(`Evicted tx ${evictHashStr} during rebuild due to conflict with ${meta.txHash}`);
+                }
+            }
+            // Add to metadata and pending indices
+            this.#addToIndices(meta);
+            accepted.add(meta.txHash);
+        }
+        this.#log.info(`Rebuilt pending pool: ${accepted.size} accepted, ${rejected.length} rejected`);
+        return {
+            accepted: [
+                ...accepted
+            ],
+            rejected
+        };
+    }
+    // --- Add Pending Tx Steps ---
+    /** Checks if a tx is a duplicate (already in pool) */ #isDuplicateTx(txHashStr) {
+        return this.#metadata.has(txHashStr);
+    }
+    /** Adds a new pending tx to the pool, returning its metadata */ async #addNewPendingTx(tx) {
+        const txHashStr = tx.getTxHash().toString();
+        const meta = await buildTxMetaData(tx);
+        await this.#persistTx(txHashStr, tx);
+        this.#addToIndices(meta);
+        this.#log.verbose(`Added tx ${txHashStr} to pool`, {
+            eventName: 'tx-added-to-pool',
+            state: this.#getTxState(meta)
+        });
+        return meta;
+    }
+    // ============================================================================
+    // HELPER FUNCTIONS - Index Management
+    // ============================================================================
+    #addToIndices(meta) {
+        this.#metadata.set(meta.txHash, meta);
+        if (this.#getTxState(meta) === 'pending') {
+            this.#addToPendingIndices(meta);
+        }
+    // Protected and mined txs don't go into pending indices
+    }
+    #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);
+        // Add to priority bucket
+        let prioritySet = this.#pendingByPriority.get(meta.priorityFee);
+        if (!prioritySet) {
+            prioritySet = new Set();
+            this.#pendingByPriority.set(meta.priorityFee, prioritySet);
+        }
+        prioritySet.add(meta.txHash);
+    }
+    #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 map
+        const hashSet = this.#pendingByPriority.get(meta.priorityFee);
+        if (hashSet) {
+            hashSet.delete(meta.txHash);
+            if (hashSet.size === 0) {
+                this.#pendingByPriority.delete(meta.priorityFee);
+            }
+        }
+    }
+    #updateProtection(txHashStr, slotNumber) {
+        const currentSlot = this.#protectedTransactions.get(txHashStr);
+        // 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(txHashStr);
+            if (meta) {
+                this.#removeFromPendingIndices(meta);
+            }
+        }
+        this.#protectedTransactions.set(txHashStr, slotNumber);
+    }
+    #markAsMined(meta, blockId) {
+        meta.minedL2BlockId = blockId;
+        // Safe to call unconditionally - removeFromPendingIndices is idempotent
+        this.#removeFromPendingIndices(meta);
+    }
+    async #deleteTx(txHashStr) {
+        const meta = this.#metadata.get(txHashStr);
+        if (!meta) {
+            return;
+        }
+        // Remove from all indices
+        this.#metadata.delete(txHashStr);
+        this.#protectedTransactions.delete(txHashStr);
+        this.#removeFromPendingIndices(meta);
+        // Remove from persistence
+        await this.#txsDB.delete(txHashStr);
+    }
+    // ============================================================================
+    // HELPER FUNCTIONS - Adapters
+    // ============================================================================
+    /** Gets all pending transactions for a given fee payer. */ #getFeePayerPendingTxs(feePayer) {
+        const txHashes = this.#feePayerToTxHashes.get(feePayer);
+        if (!txHashes) {
+            return [];
+        }
+        const result = [];
+        for (const txHashStr of txHashes){
+            const meta = this.#metadata.get(txHashStr);
+            if (meta && this.#getTxState(meta) === 'pending') {
+                result.push(meta);
+            }
+        }
+        return result;
+    }
+    /**
+   * Creates a PoolOperations adapter for use with the eviction manager.
+   */ #createPoolOperations() {
+        return {
+            getPendingTxs: ()=>{
+                const result = [];
+                for (const hashSet of this.#pendingByPriority.values()){
+                    for (const txHashStr of hashSet){
+                        const meta = this.#metadata.get(txHashStr);
+                        if (meta) {
+                            result.push(meta);
+                        }
+                    }
+                }
+                return result;
+            },
+            getPendingFeePayers: ()=>{
+                return Array.from(this.#feePayerToTxHashes.keys());
+            },
+            getFeePayerPendingTxs: (feePayer)=>{
+                return this.#getFeePayerPendingTxs(feePayer);
+            },
+            getPendingTxCount: ()=>{
+                return this.getPendingTxCount();
+            },
+            getLowestPriorityPending: (limit)=>{
+                return this.getLowestPriorityPending(limit).map((h)=>h.toString());
+            },
+            deleteTxs: async (txHashes)=>{
+                await this.#store.transactionAsync(async ()=>{
+                    for (const txHashStr of txHashes){
+                        await this.#deleteTx(txHashStr);
+                    }
+                });
+                this.#callbacks.onTxsRemoved(txHashes);
+            }
+        };
+    }
+    /**
+   * Creates a PreAddPoolAccess adapter for use with pre-add eviction rules.
+   * All methods work with strings and TxMetaData for efficiency.
+   */ #createPreAddPoolAccess() {
+        return {
+            getMetadata: (txHashStr)=>{
+                const meta = this.#metadata.get(txHashStr);
+                if (!meta || this.#getTxState(meta) !== 'pending') {
+                    return undefined;
+                }
+                return meta;
+            },
+            getTxHashByNullifier: (nullifier)=>{
+                return this.#nullifierToTxHash.get(nullifier);
+            },
+            getFeePayerBalance: async (feePayer)=>{
+                const db = this.#worldStateSynchronizer.getCommitted();
+                const publicStateSource = new DatabasePublicStateSource(db);
+                const balance = await publicStateSource.storageRead(ProtocolContractAddress.FeeJuice, await computeFeePayerBalanceStorageSlot(AztecAddress.fromString(feePayer)));
+                return balance.toBigInt();
+            },
+            getFeePayerPendingTxs: (feePayer)=>{
+                return this.#getFeePayerPendingTxs(feePayer);
+            },
+            getPendingTxCount: ()=>{
+                return this.getPendingTxCount();
+            },
+            getLowestPriorityPendingTx: ()=>{
+                // Iterate in ascending order to find the lowest priority
+                for (const txHashStr of this.#iteratePendingByPriority('asc')){
+                    const meta = this.#metadata.get(txHashStr);
+                    if (meta) {
+                        return meta;
+                    }
+                }
+                return undefined;
+            }
+        };
+    }
+}