@aztec/p2p 0.0.0-test.1 → 0.0.1-commit.1142ef1

package/dest/mem_pools/tx_pool/aztec_kv_tx_pool.js

@@ -1,21 +1,38 @@
+import { insertIntoSortedArray } from '@aztec/foundation/array';
+import { Fr } from '@aztec/foundation/curves/bn254';
 import { toArray } from '@aztec/foundation/iterable';
 import { createLogger } from '@aztec/foundation/log';
-import { ClientIvcProof } from '@aztec/stdlib/proofs';
+import { ChonkProof } from '@aztec/stdlib/proofs';
 import { Tx, TxHash } from '@aztec/stdlib/tx';
 import { getTelemetryClient } from '@aztec/telemetry-client';
+import assert from 'assert';
+import EventEmitter from 'node:events';
+import { ArchiveCache } from '../../msg_validators/tx_validator/archive_cache.js';
 import { PoolInstrumentation, PoolName } from '../instrumentation.js';
+import { EvictionManager } from './eviction/eviction_manager.js';
+import { InsufficientFeePayerBalanceRule } from './eviction/insufficient_fee_payer_balance_rule.js';
+import { InvalidTxsAfterMiningRule } from './eviction/invalid_txs_after_mining_rule.js';
+import { InvalidTxsAfterReorgRule } from './eviction/invalid_txs_after_reorg_rule.js';
+import { LowPriorityEvictionRule } from './eviction/low_priority_eviction_rule.js';
 import { getPendingTxPriority } from './priority.js';
 /**
  * KV implementation of the Transaction Pool.
- */ export class AztecKVTxPool {
+ */ export class AztecKVTxPool extends EventEmitter {
     #store;
     /** Our tx pool, stored as a Map, with K: tx hash and V: the transaction. */ #txs;
+    /** Holds the historical block for each tx */ #pendingTxHashToHistoricalBlockHeaderHash;
     /** Index from tx hash to the block number in which they were mined, filtered by mined txs. */ #minedTxHashToBlock;
     /** Index from tx priority (stored as hex) to its tx hash, filtered by pending txs. */ #pendingTxPriorityToHash;
+    /** Map from tx hash to the block number it was originally mined in (for soft-deleted txs). */ #deletedMinedTxHashes;
+    /** MultiMap from block number to deleted mined tx hashes for efficient cleanup. */ #blockToDeletedMinedTxHash;
+    #historicalHeaderToTxHash;
+    #feePayerToTxHash;
+    /** In-memory set of txs that should not be evicted from the pool. */ #nonEvictableTxs;
     /** KV store for archived txs. */ #archive;
     /** Archived txs map for future lookup. */ #archivedTxs;
     /** Indexes of the archived txs by insertion order. */ #archivedTxIndices;
-    /** Number of txs to archive. */ #archivedTxLimit;
+    /** Number of txs to archive. */ #archivedTxLimit = 0;
+    #evictionManager;
     #log;
     #metrics;
     /**
@@ -25,83 +42,122 @@ import { getPendingTxPriority } from './priority.js';
    * @param telemetry - A telemetry client.
    * @param archivedTxLimit - The number of txs to archive.
    * @param log - A logger.
-   */ constructor(store, archive, telemetry = getTelemetryClient(), archivedTxLimit = 0, log = createLogger('p2p:tx_pool')){
+   */ constructor(store, archive, worldState, telemetry = getTelemetryClient(), config = {}, log = createLogger('p2p:tx_pool')){
+        super();
+        this.#log = log;
+        this.#evictionManager = new EvictionManager(this);
+        this.#evictionManager.registerRule(new InvalidTxsAfterMiningRule());
+        this.#evictionManager.registerRule(new InvalidTxsAfterReorgRule(worldState));
+        this.#evictionManager.registerRule(new InsufficientFeePayerBalanceRule(worldState));
+        this.#evictionManager.registerRule(new LowPriorityEvictionRule({
+            //NOTE: 0 effectively disables low priority eviction
+            maxPoolSize: config.maxPendingTxCount ?? 0
+        }));
+        this.updateConfig(config);
         this.#txs = store.openMap('txs');
         this.#minedTxHashToBlock = store.openMap('txHashToBlockMined');
         this.#pendingTxPriorityToHash = store.openMultiMap('pendingTxFeeToHash');
+        this.#deletedMinedTxHashes = store.openMap('deletedMinedTxHashes');
+        this.#blockToDeletedMinedTxHash = store.openMultiMap('blockToDeletedMinedTxHash');
+        this.#pendingTxHashToHistoricalBlockHeaderHash = store.openMap('txHistoricalBlock');
+        this.#historicalHeaderToTxHash = store.openMultiMap('historicalHeaderToPendingTxHash');
+        this.#feePayerToTxHash = store.openMultiMap('feePayerToPendingTxHash');
+        this.#nonEvictableTxs = new Set();
         this.#archivedTxs = archive.openMap('archivedTxs');
         this.#archivedTxIndices = archive.openMap('archivedTxIndices');
-        this.#archivedTxLimit = archivedTxLimit;
         this.#store = store;
         this.#archive = archive;
-        this.#log = log;
-        this.#metrics = new PoolInstrumentation(telemetry, PoolName.TX_POOL, ()=>store.estimateSize());
+        this.#metrics = new PoolInstrumentation(telemetry, PoolName.TX_POOL, this.countTxs, ()=>store.estimateSize());
+    }
+    countTxs = async ()=>{
+        const [pending = 0, mined = 0] = await Promise.all([
+            this.getPendingTxCount(),
+            this.getMinedTxCount()
+        ]);
+        return Promise.resolve({
+            itemCount: {
+                pending,
+                mined
+            }
+        });
+    };
+    async isEmpty() {
+        for await (const _ of this.#txs.entriesAsync()){
+            return false;
+        }
+        return true;
     }
-    markAsMined(txHashes, blockNumber) {
+    /**
+   * Marks transactions as mined in a block and updates the pool state accordingly.
+   * Removes the transactions from the pending set and adds them to the mined set.
+   * Also evicts any transactions that become invalid after the block is mined.
+   * @param txHashes - Array of transaction hashes that were mined
+   * @param blockHeader - The header of the block the transactions were mined in
+   */ async markAsMined(txHashes, blockHeader) {
         if (txHashes.length === 0) {
             return Promise.resolve();
         }
-        let deletedPending = 0;
-        return this.#store.transactionAsync(async ()=>{
-            for (const hash of txHashes){
-                const key = hash.toString();
-                await this.#minedTxHashToBlock.set(key, blockNumber);
-                const tx = await this.getTxByHash(hash);
-                if (tx) {
-                    deletedPending++;
-                    const fee = getPendingTxPriority(tx);
-                    await this.#pendingTxPriorityToHash.deleteValue(fee, key);
+        const uniqueMinedNullifiers = [];
+        const uniqueMinedFeePayers = [];
+        try {
+            await this.#store.transactionAsync(async ()=>{
+                for (const hash of txHashes){
+                    const key = hash.toString();
+                    await this.#minedTxHashToBlock.set(key, blockHeader.globalVariables.blockNumber);
+                    const tx = await this.getPendingTxByHash(hash);
+                    if (tx) {
+                        const nullifiers = tx.data.getNonEmptyNullifiers();
+                        nullifiers.forEach((nullifier)=>insertIntoSortedArray(uniqueMinedNullifiers, nullifier, Fr.cmp, false));
+                        insertIntoSortedArray(uniqueMinedFeePayers, tx.data.feePayer, (a, b)=>a.toField().cmp(b.toField()), false);
+                        await this.removePendingTxIndicesInDbTx(tx, key);
+                    }
+                    // If this tx was previously soft-deleted, remove it from the deleted sets
+                    if (await this.#deletedMinedTxHashes.hasAsync(key)) {
+                        const originalBlock = await this.#deletedMinedTxHashes.getAsync(key);
+                        await this.#deletedMinedTxHashes.delete(key);
+                        // Remove from block-to-hash mapping
+                        if (originalBlock !== undefined) {
+                            await this.#blockToDeletedMinedTxHash.deleteValue(originalBlock, key);
+                        }
+                    }
                 }
-            }
-            this.#metrics.recordAddedObjects(txHashes.length, 'mined');
-            this.#metrics.recordRemovedObjects(deletedPending, 'pending');
-        });
+            });
+            await this.#evictionManager.evictAfterNewBlock(blockHeader, uniqueMinedNullifiers, uniqueMinedFeePayers);
+            this.#metrics.transactionsRemoved(txHashes.map((hash)=>hash.toBigInt()));
+        } catch (err) {
+            this.#log.warn('Unexpected error when marking txs as mined', {
+                err
+            });
+        }
     }
-    markMinedAsPending(txHashes) {
+    async markMinedAsPending(txHashes, latestBlock) {
         if (txHashes.length === 0) {
             return Promise.resolve();
         }
-        let markedAsPending = 0;
-        return this.#store.transactionAsync(async ()=>{
-            for (const hash of txHashes){
-                const key = hash.toString();
-                await this.#minedTxHashToBlock.delete(key);
-                const tx = await this.getTxByHash(hash);
-                if (tx) {
-                    await this.#pendingTxPriorityToHash.set(getPendingTxPriority(tx), key);
-                    markedAsPending++;
+        try {
+            await this.#store.transactionAsync(async ()=>{
+                for (const hash of txHashes){
+                    const key = hash.toString();
+                    await this.#minedTxHashToBlock.delete(key);
+                    // Rehydrate the tx in the in-memory pending txs mapping
+                    const tx = await this.getPendingTxByHash(hash);
+                    if (tx) {
+                        await this.addPendingTxIndicesInDbTx(tx, key);
+                    }
                 }
-            }
-            this.#metrics.recordAddedObjects(markedAsPending, 'pending');
-            this.#metrics.recordRemovedObjects(markedAsPending, 'mined');
-        });
+            });
+            await this.#evictionManager.evictAfterChainPrune(latestBlock);
+        } catch (err) {
+            this.#log.warn('Unexpected error when marking mined txs as pending', {
+                err
+            });
+        }
     }
     async getPendingTxHashes() {
         const vals = await toArray(this.#pendingTxPriorityToHash.valuesAsync({
             reverse: true
         }));
-        return vals.map((x)=>TxHash.fromString(x));
-    }
-    async getMinedTxHashes() {
-        const vals = await toArray(this.#minedTxHashToBlock.entriesAsync());
-        return vals.map(([txHash, blockNumber])=>[
-                TxHash.fromString(txHash),
-                blockNumber
-            ]);
-    }
-    async getTxStatus(txHash) {
-        const key = txHash.toString();
-        const [isMined, isKnown] = await Promise.all([
-            this.#minedTxHashToBlock.hasAsync(key),
-            this.#txs.hasAsync(key)
-        ]);
-        if (isMined) {
-            return 'mined';
-        } else if (isKnown) {
-            return 'pending';
-        } else {
-            return undefined;
-        }
+        return vals.map(TxHash.fromString);
     }
     /**
    * Checks if a transaction exists in the pool and returns it.
@@ -109,12 +165,20 @@ import { getPendingTxPriority } from './priority.js';
    * @returns The transaction, if found, 'undefined' otherwise.
    */ async getTxByHash(txHash) {
         const buffer = await this.#txs.getAsync(txHash.toString());
-        if (buffer) {
-            const tx = Tx.fromBuffer(buffer);
-            tx.setTxHash(txHash);
-            return tx;
-        }
-        return undefined;
+        return buffer ? Tx.fromBuffer(buffer) : undefined;
+    }
+    async getTxsByHash(txHashes) {
+        const txs = await Promise.all(txHashes.map((txHash)=>this.#txs.getAsync(txHash.toString())));
+        return txs.map((buffer)=>buffer ? Tx.fromBuffer(buffer) : undefined);
+    }
+    async hasTxs(txHashes) {
+        return await Promise.all(txHashes.map((txHash)=>this.#txs.hasAsync(txHash.toString())));
+    }
+    async hasTx(txHash) {
+        const result = await this.hasTxs([
+            txHash
+        ]);
+        return result[0];
     }
     /**
    * Checks if an archived tx exists and returns it.
@@ -122,85 +186,120 @@ import { getPendingTxPriority } from './priority.js';
    * @returns The transaction metadata, if found, 'undefined' otherwise.
    */ async getArchivedTxByHash(txHash) {
         const buffer = await this.#archivedTxs.getAsync(txHash.toString());
-        if (buffer) {
-            const tx = Tx.fromBuffer(buffer);
-            tx.setTxHash(txHash);
-            return tx;
-        }
-        return undefined;
+        return buffer ? Tx.fromBuffer(buffer) : undefined;
     }
     /**
    * Adds a list of transactions to the pool. Duplicates are ignored.
    * @param txs - An array of txs to be added to the pool.
-   * @returns Empty promise.
-   */ async addTxs(txs) {
-        const hashesAndStats = await Promise.all(txs.map(async (tx)=>({
-                txHash: await tx.getTxHash(),
-                txStats: await tx.getStats()
-            })));
-        await this.#store.transactionAsync(async ()=>{
-            let pendingCount = 0;
-            await Promise.all(txs.map(async (tx, i)=>{
-                const { txHash, txStats } = hashesAndStats[i];
-                this.#log.verbose(`Adding tx ${txHash.toString()} to pool`, {
-                    eventName: 'tx-added-to-pool',
-                    ...txStats
-                });
-                const key = txHash.toString();
-                await this.#txs.set(key, tx.toBuffer());
-                if (!await this.#minedTxHashToBlock.hasAsync(key)) {
-                    pendingCount++;
-                    // REFACTOR: Use an lmdb conditional write to avoid race conditions with this write tx
-                    await this.#pendingTxPriorityToHash.set(getPendingTxPriority(tx), key);
-                    this.#metrics.recordSize(tx);
-                }
+   * @returns count of added transactions
+   */ async addTxs(txs, opts = {}) {
+        if (txs.length === 0) {
+            return Promise.resolve(0);
+        }
+        const addedTxs = [];
+        const hashesAndStats = txs.map((tx)=>({
+                txHash: tx.getTxHash(),
+                txStats: tx.getStats()
             }));
-            this.#metrics.recordAddedObjects(pendingCount, 'pending');
-        });
+        try {
+            await this.#store.transactionAsync(async ()=>{
+                await Promise.all(txs.map(async (tx, i)=>{
+                    const { txHash, txStats } = hashesAndStats[i];
+                    const key = txHash.toString();
+                    if (await this.#txs.hasAsync(key)) {
+                        this.#log.debug(`Tx ${txHash.toString()} already exists in the pool`);
+                        return;
+                    }
+                    this.#log.verbose(`Adding tx ${txHash.toString()} to pool`, {
+                        eventName: 'tx-added-to-pool',
+                        ...txStats
+                    });
+                    await this.#txs.set(key, tx.toBuffer());
+                    addedTxs.push(tx);
+                    await this.#pendingTxHashToHistoricalBlockHeaderHash.set(key, (await tx.data.constants.anchorBlockHeader.hash()).toString());
+                    if (!await this.#minedTxHashToBlock.hasAsync(key)) {
+                        await this.addPendingTxIndicesInDbTx(tx, key);
+                        this.#metrics.recordSize(tx);
+                    }
+                }));
+            });
+            await this.#evictionManager.evictAfterNewTxs(addedTxs.map(({ txHash })=>txHash));
+        } catch (err) {
+            this.#log.warn('Unexpected error when adding txs', {
+                err
+            });
+        }
+        if (addedTxs.length > 0) {
+            this.#metrics.transactionsAdded(addedTxs);
+            this.emit('txs-added', {
+                ...opts,
+                txs: addedTxs
+            });
+        }
+        return addedTxs.length;
     }
     /**
    * Deletes transactions from the pool. Tx hashes that are not present are ignored.
-   * @param txHashes - An array of tx hashes to be removed from the tx pool.
+   * Mined transactions are soft-deleted with a timestamp, pending transactions are permanently deleted.
+   * @param txHashes - An array of tx hashes to be deleted from the tx pool.
    * @returns Empty promise.
-   */ deleteTxs(txHashes) {
-        let pendingDeleted = 0;
-        let minedDeleted = 0;
+   */ deleteTxs(txHashes, opts) {
+        if (txHashes.length === 0) {
+            return Promise.resolve();
+        }
         const deletedTxs = [];
         const poolDbTx = this.#store.transactionAsync(async ()=>{
             for (const hash of txHashes){
                 const key = hash.toString();
                 const tx = await this.getTxByHash(hash);
-                if (tx) {
-                    const fee = getPendingTxPriority(tx);
-                    await this.#pendingTxPriorityToHash.deleteValue(fee, key);
-                    const isMined = await this.#minedTxHashToBlock.hasAsync(key);
-                    if (isMined) {
-                        minedDeleted++;
-                    } else {
-                        pendingDeleted++;
-                    }
-                    if (this.#archivedTxLimit) {
+                if (!tx) {
+                    this.#log.trace(`Skipping deletion of missing tx ${key} from pool`);
+                    continue;
+                }
+                const minedBlockNumber = await this.#minedTxHashToBlock.getAsync(key);
+                const txIsPending = minedBlockNumber === undefined;
+                if (txIsPending) {
+                    await this.deletePendingTx(tx, key);
+                } else {
+                    await this.deleteMinedTx(key, minedBlockNumber, opts?.permanently ?? false);
+                    const shouldArchiveTx = this.#archivedTxLimit && !opts?.permanently;
+                    if (shouldArchiveTx) {
                         deletedTxs.push(tx);
                     }
-                    await this.#txs.delete(key);
-                    await this.#minedTxHashToBlock.delete(key);
                 }
             }
-            this.#metrics.recordRemovedObjects(pendingDeleted, 'pending');
-            this.#metrics.recordRemovedObjects(minedDeleted, 'mined');
+        });
+        this.#metrics.transactionsRemoved(txHashes.map((hash)=>hash.toBigInt()));
+        this.#log.debug(`Deleted ${txHashes.length} txs from pool`, {
+            txHashes
         });
         return this.#archivedTxLimit ? poolDbTx.then(()=>this.archiveTxs(deletedTxs)) : poolDbTx;
     }
+    async deleteMinedTx(txHash, minedBlockNumber, permanently) {
+        await this.#minedTxHashToBlock.delete(txHash);
+        if (permanently) {
+            this.#log.trace(`Deleting mined tx ${txHash} from pool`);
+            await this.#txs.delete(txHash);
+            return;
+        }
+        // Soft-delete mined transactions: remove from mined set but keep in storage
+        this.#log.trace(`Soft-deleting mined tx ${txHash} from pool`);
+        await this.#deletedMinedTxHashes.set(txHash, minedBlockNumber);
+        await this.#blockToDeletedMinedTxHash.set(minedBlockNumber, txHash);
+    }
+    async deletePendingTx(tx, txHash) {
+        // We always permanently delete pending transactions
+        this.#log.trace(`Deleting pending tx ${txHash} from pool`);
+        await this.removePendingTxIndices(tx, txHash);
+        await this.#txs.delete(txHash);
+        await this.#pendingTxHashToHistoricalBlockHeaderHash.delete(txHash);
+    }
     /**
    * Gets all the transactions stored in the pool.
    * @returns Array of tx objects in the order they were added to the pool.
    */ async getAllTxs() {
-        const vals = await toArray(this.#txs.entriesAsync());
-        return vals.map(([hash, buffer])=>{
-            const tx = Tx.fromBuffer(buffer);
-            tx.setTxHash(TxHash.fromString(hash));
-            return tx;
-        });
+        const vals = await toArray(this.#txs.valuesAsync());
+        return vals.map((buffer)=>Tx.fromBuffer(buffer));
     }
     /**
    * Gets the hashes of all transactions currently in the tx pool.
@@ -209,37 +308,248 @@ import { getPendingTxPriority } from './priority.js';
         const vals = await toArray(this.#txs.keysAsync());
         return vals.map((x)=>TxHash.fromString(x));
     }
+    async getPendingTxInfos() {
+        const vals = await toArray(this.#pendingTxPriorityToHash.valuesAsync());
+        const results = await Promise.all(vals.map((val)=>this.getPendingTxInfo(TxHash.fromString(val))));
+        return results.filter((info)=>info !== undefined);
+    }
+    async getPendingTxInfo(txHash) {
+        let historicalBlockHash = await this.#pendingTxHashToHistoricalBlockHeaderHash.getAsync(txHash.toString());
+        // Not all tx might have this index created.
+        if (!historicalBlockHash) {
+            const tx = await this.getPendingTxByHash(txHash);
+            if (!tx) {
+                this.#log.warn(`PendingTxInfo:tx ${txHash} not found`);
+                return undefined;
+            }
+            historicalBlockHash = (await tx.data.constants.anchorBlockHeader.hash()).toString();
+            await this.#pendingTxHashToHistoricalBlockHeaderHash.set(txHash.toString(), historicalBlockHash);
+        }
+        return {
+            txHash,
+            blockHash: Fr.fromString(historicalBlockHash),
+            isEvictable: !this.#nonEvictableTxs.has(txHash.toString())
+        };
+    }
+    async getPendingTxsReferencingBlocks(blockHashes) {
+        const result = [];
+        for (const blockHash of blockHashes){
+            const chunk = await toArray(this.#historicalHeaderToTxHash.getValuesAsync(blockHash.toString()));
+            result.push(...chunk.map((txHash)=>({
+                    txHash: TxHash.fromString(txHash),
+                    blockHash,
+                    isEvictable: !this.#nonEvictableTxs.has(txHash)
+                })));
+        }
+        return result;
+    }
+    async getPendingTxsWithFeePayer(feePayers) {
+        const result = [];
+        for (const feePayer of feePayers){
+            const chunk = await toArray(this.#feePayerToTxHash.getValuesAsync(feePayer.toString()));
+            const infos = await Promise.all(chunk.map((txHash)=>this.getPendingTxInfo(TxHash.fromString(txHash))));
+            result.push(...infos.filter((info)=>info !== undefined));
+        }
+        return result;
+    }
+    async getMinedTxHashes() {
+        const vals = await toArray(this.#minedTxHashToBlock.entriesAsync());
+        return vals.map(([txHash, blockNumber])=>[
+                TxHash.fromString(txHash),
+                blockNumber
+            ]);
+    }
+    async getPendingTxCount() {
+        return await this.#pendingTxPriorityToHash.sizeAsync() ?? 0;
+    }
+    async getMinedTxCount() {
+        return await this.#minedTxHashToBlock.sizeAsync() ?? 0;
+    }
+    async getTxStatus(txHash) {
+        const key = txHash.toString();
+        const [isMined, isKnown, isDeleted] = await Promise.all([
+            this.#minedTxHashToBlock.hasAsync(key),
+            this.#txs.hasAsync(key),
+            this.#deletedMinedTxHashes.hasAsync(key)
+        ]);
+        if (isDeleted) {
+            return 'deleted';
+        } else if (isMined) {
+            return 'mined';
+        } else if (isKnown) {
+            return 'pending';
+        } else {
+            return undefined;
+        }
+    }
+    updateConfig(cfg) {
+        if (typeof cfg.archivedTxLimit === 'number') {
+            assert(cfg.archivedTxLimit >= 0, 'archivedTxLimit must be greater or equal to 0');
+            this.#archivedTxLimit = cfg.archivedTxLimit;
+        }
+        if (this.#evictionManager) {
+            this.#evictionManager.updateConfig(cfg);
+        }
+    }
+    markTxsAsNonEvictable(txHashes) {
+        txHashes.forEach((txHash)=>this.#nonEvictableTxs.add(txHash.toString()));
+        return Promise.resolve();
+    }
+    clearNonEvictableTxs() {
+        // Clear the non-evictable set after completing the DB updates above.
+        // This ensures pinned (non-evictable) txs are protected while we mark mined txs,
+        // but they won't remain pinned indefinitely across blocks. Note that eviction rules
+        // (including post-mining invalidation) respect the non-evictable flag while it is set.
+        this.#nonEvictableTxs.clear();
+        return Promise.resolve();
+    }
+    /**
+   * Permanently deletes deleted mined transactions from blocks up to and including the specified block number.
+   * @param blockNumber - Block number threshold. Deleted mined txs from this block or earlier will be permanently deleted.
+   * @returns The number of transactions permanently deleted.
+   */ async cleanupDeletedMinedTxs(blockNumber) {
+        let deletedCount = 0;
+        await this.#store.transactionAsync(async ()=>{
+            const txHashesToDelete = [];
+            const blocksToDelete = [];
+            // Iterate through all entries and check block numbers
+            for await (const [block, txHash] of this.#blockToDeletedMinedTxHash.entriesAsync()){
+                if (block <= blockNumber) {
+                    // Permanently delete the transaction
+                    await this.#txs.delete(txHash);
+                    await this.#deletedMinedTxHashes.delete(txHash);
+                    txHashesToDelete.push(txHash);
+                    if (!blocksToDelete.includes(block)) {
+                        blocksToDelete.push(block);
+                    }
+                    deletedCount++;
+                }
+            }
+            this.#metrics.transactionsRemoved(txHashesToDelete);
+            // Clean up block-to-hash mapping - delete all values for each block
+            for (const block of blocksToDelete){
+                const txHashesForBlock = await toArray(this.#blockToDeletedMinedTxHash.getValuesAsync(block));
+                for (const txHash of txHashesForBlock){
+                    await this.#blockToDeletedMinedTxHash.deleteValue(block, txHash);
+                }
+            }
+        });
+        if (deletedCount > 0) {
+            this.#log.debug(`Permanently deleted ${deletedCount} deleted mined txs from blocks up to ${blockNumber}`);
+        }
+        return deletedCount;
+    }
+    /**
+   * Creates an ArchiveCache instance.
+   * @param db - DB for the cache to use
+   * @returns An ArchiveCache instance
+   */ createArchiveCache(db) {
+        return new ArchiveCache(db);
+    }
+    /**
+   * Checks if a cached transaction exists in the in-memory pending tx pool and returns it.
+   * Otherwise, it checks the tx pool, updates the pending tx pool, and returns the tx.
+   * @param txHash - The generated tx hash.
+   * @returns The transaction, if found, 'undefined' otherwise.
+   */ async getPendingTxByHash(txHash) {
+        if (typeof txHash === 'string') {
+            txHash = TxHash.fromString(txHash);
+        }
+        const tx = await this.getTxByHash(txHash);
+        if (tx) {
+            return tx;
+        }
+        return undefined;
+    }
     /**
    * Archives a list of txs for future reference. The number of archived txs is limited by the specified archivedTxLimit.
+   * Note: Pending txs should not be archived, only finalized txs
    * @param txs - The list of transactions to archive.
    * @returns Empty promise.
    */ async archiveTxs(txs) {
-        const txHashes = await Promise.all(txs.map((tx)=>tx.getTxHash()));
-        await this.#archive.transactionAsync(async ()=>{
-            // calcualte the head and tail indices of the archived txs by insertion order.
-            let headIdx = ((await this.#archivedTxIndices.entriesAsync({
-                limit: 1,
-                reverse: true
-            }).next()).value?.[0] ?? -1) + 1;
-            let tailIdx = (await this.#archivedTxIndices.entriesAsync({
-                limit: 1
-            }).next()).value?.[0] ?? 0;
-            for(let i = 0; i < txs.length; i++){
-                const tx = txs[i];
-                while(headIdx - tailIdx >= this.#archivedTxLimit){
-                    const txHash = await this.#archivedTxIndices.getAsync(tailIdx);
-                    if (txHash) {
-                        await this.#archivedTxs.delete(txHash);
-                        await this.#archivedTxIndices.delete(tailIdx);
+        if (txs.length === 0) {
+            return;
+        }
+        if (this.#archivedTxLimit === 0) {
+            return;
+        }
+        try {
+            const txHashes = await Promise.all(txs.map((tx)=>tx.getTxHash()));
+            await this.#archive.transactionAsync(async ()=>{
+                // calculate the head and tail indices of the archived txs by insertion order.
+                let headIdx = ((await this.#archivedTxIndices.entriesAsync({
+                    limit: 1,
+                    reverse: true
+                }).next()).value?.[0] ?? -1) + 1;
+                let tailIdx = (await this.#archivedTxIndices.entriesAsync({
+                    limit: 1
+                }).next()).value?.[0] ?? 0;
+                for(let i = 0; i < txs.length; i++){
+                    const tx = txs[i];
+                    while(headIdx - tailIdx >= this.#archivedTxLimit){
+                        const txHash = await this.#archivedTxIndices.getAsync(tailIdx);
+                        if (txHash) {
+                            await this.#archivedTxs.delete(txHash);
+                            await this.#archivedTxIndices.delete(tailIdx);
+                        }
+                        tailIdx++;
                     }
-                    tailIdx++;
+                    const archivedTx = new Tx(tx.txHash, tx.data, ChonkProof.empty(), tx.contractClassLogFields, tx.publicFunctionCalldata);
+                    const txHash = txHashes[i].toString();
+                    await this.#archivedTxs.set(txHash, archivedTx.toBuffer());
+                    await this.#archivedTxIndices.set(headIdx, txHash);
+                    headIdx++;
                 }
-                const archivedTx = new Tx(tx.data, ClientIvcProof.empty(), tx.contractClassLogs, tx.enqueuedPublicFunctionCalls, tx.publicTeardownFunctionCall);
-                const txHash = txHashes[i].toString();
-                await this.#archivedTxs.set(txHash, archivedTx.toBuffer());
-                await this.#archivedTxIndices.set(headIdx, txHash);
-                headIdx++;
-            }
+                this.#log.debug(`Archived ${txs.length} txs`, {
+                    txHashes
+                });
+                this.#log.debug(`Total archived txs: ${headIdx - tailIdx}`);
+            });
+        } catch (error) {
+            this.#log.error(`Error archiving txs`, {
+                error
+            });
+        }
+    }
+    // Assumes being called within a DB transaction
+    async addPendingTxIndicesInDbTx(tx, txHash) {
+        await this.#pendingTxPriorityToHash.set(getPendingTxPriority(tx), txHash);
+        await this.#historicalHeaderToTxHash.set((await tx.data.constants.anchorBlockHeader.hash()).toString(), txHash);
+        await this.#feePayerToTxHash.set(tx.data.feePayer.toString(), txHash);
+    }
+    async addPendingTxIndices(tx, txHash) {
+        return await this.#store.transactionAsync(async ()=>{
+            await this.addPendingTxIndicesInDbTx(tx, txHash);
         });
     }
+    // Assumes being called within a DB transaction
+    async removePendingTxIndicesInDbTx(tx, txHash) {
+        await this.#pendingTxPriorityToHash.deleteValue(getPendingTxPriority(tx), txHash);
+        await this.#historicalHeaderToTxHash.deleteValue((await tx.data.constants.anchorBlockHeader.hash()).toString(), txHash);
+        await this.#feePayerToTxHash.deleteValue(tx.data.feePayer.toString(), txHash);
+    }
+    async removePendingTxIndices(tx, txHash) {
+        return await this.#store.transactionAsync(async ()=>{
+            await this.removePendingTxIndicesInDbTx(tx, txHash);
+        });
+    }
+    /**
+   * Returns up to `limit` lowest-priority evictable pending tx hashes without hydrating transactions.
+   * Iterates the priority index in ascending order and skips non-evictable txs.
+   */ async getLowestPriorityEvictable(limit) {
+        const txsToEvict = [];
+        if (limit <= 0) {
+            return txsToEvict;
+        }
+        for await (const txHashStr of this.#pendingTxPriorityToHash.valuesAsync()){
+            if (this.#nonEvictableTxs.has(txHashStr)) {
+                continue;
+            }
+            txsToEvict.push(TxHash.fromString(txHashStr));
+            if (txsToEvict.length >= limit) {
+                break;
+            }
+        }
+        return txsToEvict;
+    }
 }