@aztec/p2p 0.0.1-commit.f295ac2 → 0.0.1-commit.f2ce05ee

package/dest/mem_pools/tx_pool_v2/tx_metadata.js

@@ -0,0 +1,95 @@
+import { Fr } from '@aztec/foundation/curves/bn254';
+import { ProtocolContractAddress } from '@aztec/protocol-contracts';
+import { getFeePayerBalanceDelta } from '../../msg_validators/tx_validator/fee_payer_balance.js';
+import { getTxPriorityFee } from '../tx_pool/priority.js';
+/**
+ * Builds TxMetaData from a full Tx object.
+ * Extracts all relevant fields for efficient in-memory storage and querying.
+ */ export async function buildTxMetaData(tx) {
+    const txHash = tx.getTxHash().toString();
+    const anchorBlockHeaderHash = (await tx.data.constants.anchorBlockHeader.hash()).toString();
+    const priorityFee = getTxPriorityFee(tx);
+    const feePayer = tx.data.feePayer.toString();
+    const nullifiers = tx.data.getNonEmptyNullifiers().map((n)=>n.toString());
+    const includeByTimestamp = tx.data.includeByTimestamp;
+    const { feeLimit, claimAmount } = await getFeePayerBalanceDelta(tx, ProtocolContractAddress.FeeJuice);
+    return {
+        txHash,
+        anchorBlockHeaderHash,
+        priorityFee,
+        feePayer,
+        claimAmount,
+        feeLimit,
+        nullifiers,
+        includeByTimestamp
+    };
+}
+/**
+ * Compares two priority fees in ascending order.
+ * Returns negative if a < b, positive if a > b, 0 if equal.
+ */ export function compareFee(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+/**
+ * Compares two tx hashes in ascending order.
+ * Uses field element comparison for deterministic ordering.
+ * Returns negative if a < b, positive if a > b, 0 if equal.
+ */ export function compareTxHash(a, b) {
+    const fieldA = Fr.fromHexString(a);
+    const fieldB = Fr.fromHexString(b);
+    return fieldA.cmp(fieldB);
+}
+/**
+ * Compares two transactions by priority fee, with txHash as tiebreaker.
+ * Returns negative if a < b, positive if a > b, 0 if equal.
+ * Use with sort() for ascending order, or negate/reverse for descending.
+ */ export function comparePriority(a, b) {
+    const feeComparison = compareFee(a.priorityFee, b.priorityFee);
+    if (feeComparison !== 0) {
+        return feeComparison;
+    }
+    return compareTxHash(a.txHash, b.txHash);
+}
+/**
+ * Checks for nullifier conflicts between an incoming transaction and existing pool state.
+ *
+ * When the incoming tx shares nullifiers with existing pending txs:
+ * - If the incoming tx has strictly higher priority, mark conflicting txs for eviction
+ * - If any conflicting tx has equal or higher priority, ignore the incoming tx
+ *
+ * @param incomingMeta - Metadata for the incoming transaction
+ * @param getTxHashByNullifier - Accessor to find which tx uses a nullifier
+ * @param getMetadata - Accessor to get metadata for a tx hash
+ */ export function checkNullifierConflict(incomingMeta, getTxHashByNullifier, getMetadata) {
+    const txHashesToEvict = [];
+    for (const nullifier of incomingMeta.nullifiers){
+        const conflictingHashStr = getTxHashByNullifier(nullifier);
+        if (!conflictingHashStr || conflictingHashStr === incomingMeta.txHash) {
+            continue;
+        }
+        // Skip if already marked for eviction
+        if (txHashesToEvict.includes(conflictingHashStr)) {
+            continue;
+        }
+        const conflictingMeta = getMetadata(conflictingHashStr);
+        if (!conflictingMeta) {
+            continue;
+        }
+        // If incoming tx has strictly higher priority, mark for eviction
+        // Otherwise, ignore incoming tx (ties go to existing tx)
+        // Use comparePriority for deterministic ordering (includes txHash as tiebreaker)
+        if (comparePriority(incomingMeta, conflictingMeta) > 0) {
+            txHashesToEvict.push(conflictingHashStr);
+        } else {
+            return {
+                shouldIgnore: true,
+                txHashesToEvict: [],
+                reason: `nullifier conflict with ${conflictingHashStr}`
+            };
+        }
+    }
+    return {
+        shouldIgnore: false,
+        txHashesToEvict
+    };
+}

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

@@ -0,0 +1,26 @@
+/**
+ * Metrics types for tx pool benchmarks.
+ */
+export declare enum TxPoolOperation {
+    ADD_PENDING_TXS = "addPendingTxs",
+    CAN_ADD_PENDING_TX = "canAddPendingTx",
+    GET_PENDING_TX_HASHES = "getPendingTxHashes",
+    GET_TX_BY_HASH = "getTxByHash",
+    GET_TXS_BY_HASH = "getTxsByHash",
+    HAS_TXS = "hasTxs",
+    HANDLE_MINED_BLOCK = "handleMinedBlock",
+    PREPARE_FOR_SLOT = "prepareForSlot",
+    HANDLE_PRUNED_BLOCKS = "handlePrunedBlocks",
+    GET_LOWEST_PRIORITY_PENDING = "getLowestPriorityPending",
+    HYDRATE_FROM_DATABASE = "hydrateFromDatabase"
+}
+/**
+ * Collects and formats tx pool benchmark metrics.
+ */
+export declare class TxPoolBenchMetrics {
+    private metrics;
+    addMetric(operation: TxPoolOperation, poolSize: number, batchSize: number, value: number): void;
+    toPrettyString(): string;
+    toGithubActionBenchmarkJSON(indent?: number): string;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidHhfcG9vbF9iZW5jaF9tZXRyaWNzLmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi9zcmMvbWVtX3Bvb2xzL3R4X3Bvb2xfdjIvdHhfcG9vbF9iZW5jaF9tZXRyaWNzLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOztHQUVHO0FBRUgsb0JBQVksZUFBZTtJQUN6QixlQUFlLGtCQUFrQjtJQUNqQyxrQkFBa0Isb0JBQW9CO0lBQ3RDLHFCQUFxQix1QkFBdUI7SUFDNUMsY0FBYyxnQkFBZ0I7SUFDOUIsZUFBZSxpQkFBaUI7SUFDaEMsT0FBTyxXQUFXO0lBQ2xCLGtCQUFrQixxQkFBcUI7SUFDdkMsZ0JBQWdCLG1CQUFtQjtJQUNuQyxvQkFBb0IsdUJBQXVCO0lBQzNDLDJCQUEyQiw2QkFBNkI7SUFDeEQscUJBQXFCLHdCQUF3QjtDQUM5QztBQVNEOztHQUVHO0FBQ0gscUJBQWEsa0JBQWtCO0lBQzdCLE9BQU8sQ0FBQyxPQUFPLENBQXlCO0lBRWpDLFNBQVMsQ0FBQyxTQUFTLEVBQUUsZUFBZSxFQUFFLFFBQVEsRUFBRSxNQUFNLEVBQUUsU0FBUyxFQUFFLE1BQU0sRUFBRSxLQUFLLEVBQUUsTUFBTSxRQUU5RjtJQUVNLGNBQWMsSUFBSSxNQUFNLENBd0I5QjtJQUVNLDJCQUEyQixDQUFDLE1BQU0sU0FBSSxHQUFHLE1BQU0sQ0FjckQ7Q0FDRiJ9

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

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

package/dest/mem_pools/tx_pool_v2/tx_pool_bench_metrics.js

@@ -0,0 +1,70 @@
+/**
+ * Metrics types for tx pool benchmarks.
+ */ export var TxPoolOperation = /*#__PURE__*/ function(TxPoolOperation) {
+    TxPoolOperation["ADD_PENDING_TXS"] = "addPendingTxs";
+    TxPoolOperation["CAN_ADD_PENDING_TX"] = "canAddPendingTx";
+    TxPoolOperation["GET_PENDING_TX_HASHES"] = "getPendingTxHashes";
+    TxPoolOperation["GET_TX_BY_HASH"] = "getTxByHash";
+    TxPoolOperation["GET_TXS_BY_HASH"] = "getTxsByHash";
+    TxPoolOperation["HAS_TXS"] = "hasTxs";
+    TxPoolOperation["HANDLE_MINED_BLOCK"] = "handleMinedBlock";
+    TxPoolOperation["PREPARE_FOR_SLOT"] = "prepareForSlot";
+    TxPoolOperation["HANDLE_PRUNED_BLOCKS"] = "handlePrunedBlocks";
+    TxPoolOperation["GET_LOWEST_PRIORITY_PENDING"] = "getLowestPriorityPending";
+    TxPoolOperation["HYDRATE_FROM_DATABASE"] = "hydrateFromDatabase";
+    return TxPoolOperation;
+}({});
+/**
+ * Collects and formats tx pool benchmark metrics.
+ */ export class TxPoolBenchMetrics {
+    metrics = [];
+    addMetric(operation, poolSize, batchSize, value) {
+        this.metrics.push({
+            operation,
+            poolSize,
+            batchSize,
+            value
+        });
+    }
+    toPrettyString() {
+        let pretty = 'TxPool Benchmark Metrics:\n';
+        pretty += '='.repeat(60) + '\n';
+        // Group by operation
+        const byOperation = new Map();
+        for (const metric of this.metrics){
+            if (!byOperation.has(metric.operation)) {
+                byOperation.set(metric.operation, []);
+            }
+            byOperation.get(metric.operation).push(metric);
+        }
+        for (const [operation, opMetrics] of byOperation){
+            pretty += `\n${operation}:\n`;
+            for (const metric of opMetrics){
+                const poolSizeStr = metric.poolSize > 0 ? `pool=${metric.poolSize}` : '';
+                const batchSizeStr = metric.batchSize > 0 ? `batch=${metric.batchSize}` : '';
+                const params = [
+                    poolSizeStr,
+                    batchSizeStr
+                ].filter(Boolean).join(', ');
+                pretty += `  ${params ? `(${params})` : ''}: ${metric.value.toFixed(3)} ms\n`;
+            }
+        }
+        return pretty;
+    }
+    toGithubActionBenchmarkJSON(indent = 2) {
+        const data = this.metrics.map((metric)=>{
+            const poolSizeStr = metric.poolSize > 0 ? `${metric.poolSize} txs in pool` : '';
+            const batchSizeStr = metric.batchSize > 0 ? `batch of ${metric.batchSize}` : '';
+            const params = [
+                poolSizeStr,
+                batchSizeStr
+            ].filter(Boolean).join('/');
+            return {
+                name: `TxPool/${metric.operation}${params ? `/${params}` : ''}`,
+                value: metric.value,
+                unit: 'ms'
+            };
+        });
+        return JSON.stringify(data, null, indent);
+    }
+}

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

@@ -0,0 +1,99 @@
+import { SlotNumber } from '@aztec/foundation/branded-types';
+import type { L2BlockId } from '@aztec/stdlib/block';
+import { type TxMetaData, type TxState } 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 declare class TxPoolIndices {
+    #private;
+    /**
+     * 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: TxMetaData): TxState;
+    getMetadata(txHash: string): TxMetaData | undefined;
+    has(txHash: string): boolean;
+    isEmpty(): boolean;
+    getTxCount(): number;
+    /**
+     * Iterates pending transaction hashes in priority order.
+     * @param order - 'desc' for highest priority first, 'asc' for lowest priority first
+     */
+    iteratePendingByPriority(order: 'asc' | 'desc'): Generator<string>;
+    /** Iterates all metadata entries */
+    iterateMetadata(): Generator<[string, TxMetaData]>;
+    /** Adds a new pending transaction to all indices */
+    addPending(meta: TxMetaData): void;
+    /** Adds a new protected transaction (not added to pending indices) */
+    addProtected(meta: TxMetaData, slot: SlotNumber): void;
+    /** Adds a new mined transaction (not added to pending indices) */
+    addMined(meta: TxMetaData): void;
+    /** Marks an existing transaction as mined and removes from pending indices */
+    markAsMined(meta: TxMetaData, blockId: L2BlockId): void;
+    /** Clears the mined status from a transaction */
+    markAsUnmined(meta: TxMetaData): void;
+    /**
+     * Updates protection status for an existing transaction.
+     * Removes from pending indices if transitioning from pending to protected.
+     */
+    updateProtection(txHash: string, slotNumber: SlotNumber): void;
+    /** Sets protection for a txHash that may not have metadata yet */
+    setProtection(txHash: string, slotNumber: SlotNumber): void;
+    /** Gets the protection slot for a txHash, if protected */
+    getProtectionSlot(txHash: string): SlotNumber | undefined;
+    /** Removes protection from tx hashes */
+    clearProtection(txHashes: string[]): void;
+    /** Removes a transaction from all indices */
+    remove(txHash: string): void;
+    /** Removes a transaction from pending indices only (not metadata) */
+    removeFromPendingIndices(meta: TxMetaData): void;
+    /** Adds a transaction to pending indices (used during conflict resolution) */
+    addToPendingIndices(meta: TxMetaData): void;
+    /** Gets all pending transactions for a given fee payer */
+    getFeePayerPendingTxs(feePayer: string): TxMetaData[];
+    /** Gets the count of pending transactions */
+    getPendingTxCount(): number;
+    /** Gets the lowest priority pending transaction hashes (up to limit) */
+    getLowestPriorityPending(limit: number): string[];
+    /** Gets the lowest priority pending transaction */
+    getLowestPriorityPendingTx(): TxMetaData | undefined;
+    /** Gets all pending transactions */
+    getPendingTxs(): TxMetaData[];
+    /** Gets all fee payers with pending transactions */
+    getPendingFeePayers(): string[];
+    /** Gets the txHash that uses a given nullifier (pending txs only) */
+    getTxHashByNullifier(nullifier: string): string | undefined;
+    /** Gets txHashes for a fee payer */
+    getTxHashesByFeePayer(feePayer: string): Set<string> | undefined;
+    /** Finds all transactions mined in blocks after the given block number */
+    findTxsMinedAfter(blockNumber: number): TxMetaData[];
+    /** Finds tx hashes mined at or before the given block number */
+    findTxsMinedAtOrBefore(blockNumber: number): string[];
+    /** Finds protected tx hashes from slots earlier than the given slot number */
+    findExpiredProtectedTxs(slotNumber: SlotNumber): string[];
+    /** Filters out transactions that are currently protected */
+    filterUnprotected(txs: TxMetaData[]): TxMetaData[];
+    /** Filters to transactions that have metadata and are not mined */
+    filterRestorable(txHashes: string[]): TxMetaData[];
+    /** Counts transactions by state */
+    countTxs(): {
+        pending: number;
+        protected: number;
+        mined: number;
+    };
+    /** Gets all mined transactions with their block IDs */
+    getMinedTxs(): [string, L2BlockId][];
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidHhfcG9vbF9pbmRpY2VzLmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi9zcmMvbWVtX3Bvb2xzL3R4X3Bvb2xfdjIvdHhfcG9vbF9pbmRpY2VzLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sRUFBRSxVQUFVLEVBQUUsTUFBTSxpQ0FBaUMsQ0FBQztBQUM3RCxPQUFPLEtBQUssRUFBRSxTQUFTLEVBQUUsTUFBTSxxQkFBcUIsQ0FBQztBQUVyRCxPQUFPLEVBQUUsS0FBSyxVQUFVLEVBQUUsS0FBSyxPQUFPLEVBQTZCLE1BQU0sa0JBQWtCLENBQUM7QUFFNUY7Ozs7Ozs7Ozs7O0dBV0c7QUFDSCxxQkFBYSxhQUFhOztJQWdCeEI7Ozs7OztPQU1HO0lBQ0gsVUFBVSxDQUFDLElBQUksRUFBRSxVQUFVLEdBQUcsT0FBTyxDQVFwQztJQUVELFdBQVcsQ0FBQyxNQUFNLEVBQUUsTUFBTSxHQUFHLFVBQVUsR0FBRyxTQUFTLENBRWxEO0lBRUQsR0FBRyxDQUFDLE1BQU0sRUFBRSxNQUFNLEdBQUcsT0FBTyxDQUUzQjtJQUVELE9BQU8sSUFBSSxPQUFPLENBRWpCO0lBRUQsVUFBVSxJQUFJLE1BQU0sQ0FFbkI7SUFNRDs7O09BR0c7SUFDRix3QkFBd0IsQ0FBQyxLQUFLLEVBQUUsS0FBSyxHQUFHLE1BQU0sR0FBRyxTQUFTLENBQUMsTUFBTSxDQUFDLENBZWxFO0lBRUQsb0NBQW9DO0lBQ25DLGVBQWUsSUFBSSxTQUFTLENBQUMsQ0FBQyxNQUFNLEVBQUUsVUFBVSxDQUFDLENBQUMsQ0FFbEQ7SUFNRCxvREFBb0Q7SUFDcEQsVUFBVSxDQUFDLElBQUksRUFBRSxVQUFVLEdBQUcsSUFBSSxDQUdqQztJQUVELHNFQUFzRTtJQUN0RSxZQUFZLENBQUMsSUFBSSxFQUFFLFVBQVUsRUFBRSxJQUFJLEVBQUUsVUFBVSxHQUFHLElBQUksQ0FHckQ7SUFFRCxrRUFBa0U7SUFDbEUsUUFBUSxDQUFDLElBQUksRUFBRSxVQUFVLEdB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

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

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

package/dest/mem_pools/tx_pool_v2/tx_pool_indices.js

@@ -0,0 +1,332 @@
+import { compareFee, compareTxHash } 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 txHashes grouped by priority fee */ #pendingByPriority = new Map();
+    /** 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) {
+        // Use compareFee from tx_metadata, swap args for descending order
+        const feeCompareFn = order === 'desc' ? (a, b)=>compareFee(b, a) : compareFee;
+        const hashCompareFn = order === 'desc' ? (a, b)=>compareTxHash(b, a) : compareTxHash;
+        const sortedFees = [
+            ...this.#pendingByPriority.keys()
+        ].sort(feeCompareFn);
+        for (const fee of sortedFees){
+            const hashesAtFee = this.#pendingByPriority.get(fee);
+            // Use compareTxHash from tx_metadata, swap args for descending order
+            const sortedHashes = [
+                ...hashesAtFee
+            ].sort(hashCompareFn);
+            for (const hash of sortedHashes){
+                yield hash;
+            }
+        }
+    }
+    /** 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);
+    }
+    /** 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() {
+        let count = 0;
+        for (const hashes of this.#pendingByPriority.values()){
+            count += hashes.size;
+        }
+        return count;
+    }
+    /** 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 hashSet of this.#pendingByPriority.values()){
+            for (const txHash of hashSet){
+                const meta = this.#metadata.get(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;
+    }
+    /** 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 */ 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
+        };
+    }
+    /** 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);
+        // 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);
+            }
+        }
+    }
+}