@aztec/p2p 0.0.1-commit.9ef841308 → 0.0.1-commit.a89ec08

package/src/config.ts

@@ -11,6 +11,7 @@ import {
   secretStringConfigHelper,
 } from '@aztec/foundation/config';
 import { Fr } from '@aztec/foundation/curves/bn254';
+import { type DataStoreConfig, dataConfigMappings } from '@aztec/kv-store/config';
 import { FunctionSelector } from '@aztec/stdlib/abi/function-selector';
 import { AztecAddress } from '@aztec/stdlib/aztec-address';
 import {
@@ -20,7 +21,6 @@ import {
   chainConfigMappings,
   sharedSequencerConfigMappings,
 } from '@aztec/stdlib/config';
-import { type DataStoreConfig, dataConfigMappings } from '@aztec/stdlib/kv-store';
 
 import {
   type BatchTxRequesterConfig,
@@ -70,9 +70,6 @@ export interface P2PConfig
   /** The frequency in which to check for new peers. */
   peerCheckIntervalMS: number;
 
-  /** How long to ban a peer after it fails MAX_DIAL_ATTEMPTS dials. */
-  peerFailedBanTimeMs: number;
-
   /** Size of queue of L2 blocks to store. */
   l2QueueSize: number;
 
@@ -189,7 +186,10 @@ export interface P2PConfig
   /** Whether transactions are disabled for this node. This means transactions will be rejected at the RPC and P2P layers. */
   disableTransactions: boolean;
 
-  /** The probability that a transaction is discarded (0 = disabled). - For testing purposes only */
+  /** True to simulate discarding transactions. - For testing purposes only*/
+  dropTransactions: boolean;
+
+  /** The probability that a transaction is discarded. - For testing purposes only */
   dropTransactionsProbability: number;
 
   /** Whether to delete transactions from the pool after a reorg instead of moving them back to pending. */
@@ -266,11 +266,6 @@ export const p2pConfigMappings: ConfigMappingsType<P2PConfig> = {
     description: 'The frequency in which to check for new peers.',
     ...numberConfigHelper(30_000),
   },
-  peerFailedBanTimeMs: {
-    env: 'P2P_PEER_FAILED_BAN_TIME_MS',
-    description: 'How long to ban a peer after it fails maximum dial attempts.',
-    ...numberConfigHelper(5 * 60 * 1000),
-  },
   l2QueueSize: {
     env: 'P2P_L2_QUEUE_SIZE',
     description: 'Size of queue of L2 blocks to store.',
@@ -474,6 +469,11 @@ export const p2pConfigMappings: ConfigMappingsType<P2PConfig> = {
     description: 'Number of auth attempts to allow before peer is banned. Number is inclusive',
     ...numberConfigHelper(3),
   },
+  dropTransactions: {
+    env: 'P2P_DROP_TX',
+    description: 'True to simulate discarding transactions. - For testing purposes only',
+    ...booleanConfigHelper(false),
+  },
   dropTransactionsProbability: {
     env: 'P2P_DROP_TX_CHANCE',
     description: 'The probability that a transaction is discarded (0 - 1). - For testing purposes only',

package/src/index.ts

@@ -6,6 +6,7 @@ export * from './client/index.js';
 export * from './enr/index.js';
 export * from './config.js';
 export * from './mem_pools/attestation_pool/index.js';
+export * from './mem_pools/tx_pool/index.js';
 export * from './mem_pools/tx_pool_v2/index.js';
 export * from './msg_validators/index.js';
 export * from './services/index.js';

package/src/mem_pools/attestation_pool/attestation_pool.ts

@@ -26,10 +26,10 @@ export type TryAddResult = {
   count: number;
 };
 
-export const MAX_CHECKPOINT_PROPOSALS_PER_SLOT = 2;
-export const MAX_BLOCK_PROPOSALS_PER_POSITION = 2;
+export const MAX_CHECKPOINT_PROPOSALS_PER_SLOT = 5;
+export const MAX_BLOCK_PROPOSALS_PER_POSITION = 3;
 /** Maximum attestations a single signer can make per slot before being rejected. */
-export const MAX_ATTESTATIONS_PER_SLOT_AND_SIGNER = 2;
+export const MAX_ATTESTATIONS_PER_SLOT_AND_SIGNER = 3;
 
 /** Public API interface for attestation pools. Used for typing mocks and test implementations. */
 export type AttestationPoolApi = Pick<
@@ -359,10 +359,11 @@ export class AttestationPool {
         }
 
         const address = sender.toString();
-        const ownKey = this.getAttestationKey(slotNumber, proposalId, address);
 
-        await this.checkpointAttestations.set(ownKey, attestation.toBuffer());
-        this.metrics.trackMempoolItemAdded(ownKey);
+        await this.checkpointAttestations.set(
+          this.getAttestationKey(slotNumber, proposalId, address),
+          attestation.toBuffer(),
+        );
 
         this.log.debug(`Added own checkpoint attestation for slot ${slotNumber} from ${address}`, {
           signature: attestation.signature.toString(),
@@ -428,7 +429,6 @@ export class AttestationPool {
       const attestationEndKey = new Fr(oldestSlot).toString();
       for await (const key of this.checkpointAttestations.keysAsync({ end: attestationEndKey })) {
         await this.checkpointAttestations.delete(key);
-        this.metrics.trackMempoolItemRemoved(key);
         numberOfAttestations++;
       }
 
@@ -526,7 +526,6 @@ export class AttestationPool {
 
       // Add the attestation
       await this.checkpointAttestations.set(key, attestation.toBuffer());
-      this.metrics.trackMempoolItemAdded(key);
 
       // Track this attestation in the per-signer-per-slot index for duplicate detection
       const slotSignerKey = this.getSlotSignerKey(slotNumber, signerAddress);

package/src/mem_pools/attestation_pool/attestation_pool_test_suite.ts

@@ -446,12 +446,12 @@ export function describeAttestationPool(getAttestationPool: () => AttestationPoo
         const result2 = await ap.tryAddBlockProposal(proposal2);
         expect(result2.count).toBe(2);
 
-        // Third proposal for same position should be rejected (cap is 2)
+        // Add a third proposal for same position
         const proposal3 = await mockBlockProposalWithIndex(signers[2], slotNumber, indexWithinCheckpoint);
         const result3 = await ap.tryAddBlockProposal(proposal3);
 
-        expect(result3.added).toBe(false);
-        expect(result3.count).toBe(2);
+        expect(result3.added).toBe(true);
+        expect(result3.count).toBe(3);
       });
 
       it('should return added=false when exceeding capacity', async () => {
@@ -666,12 +666,12 @@ export function describeAttestationPool(getAttestationPool: () => AttestationPoo
         const result2 = await ap.tryAddCheckpointProposal(proposal2);
         expect(result2.count).toBe(2);
 
-        // Third proposal for same slot should be rejected (cap is 2)
+        // Add a third proposal for same slot
         const proposal3 = await mockCheckpointProposalCoreForPool(signers[2], slotNumber);
         const result3 = await ap.tryAddCheckpointProposal(proposal3);
 
-        expect(result3.added).toBe(false);
-        expect(result3.count).toBe(2);
+        expect(result3.added).toBe(true);
+        expect(result3.count).toBe(3);
       });
 
       it('should not count attestations as proposals for duplicate detection', async () => {

package/src/mem_pools/index.ts

@@ -1,3 +1,6 @@
 export { AttestationPool, type AttestationPoolApi } from './attestation_pool/attestation_pool.js';
 export { type MemPools } from './interface.js';
+// Old TxPool exports - kept temporarily for external consumers
+export { type TxPool } from './tx_pool/tx_pool.js';
+// New TxPoolV2 exports
 export { type TxPoolV2, type TxPoolV2Config, type TxPoolV2Events, type AddTxsResult } from './tx_pool_v2/index.js';

package/src/mem_pools/instrumentation.ts

@@ -73,7 +73,7 @@ export class PoolInstrumentation<PoolObject extends Gossipable> {
   private defaultAttributes;
   private meter: Meter;
 
-  private mempoolItemAddedTimestamp: Map<bigint | string, number> = new Map<bigint | string, number>();
+  private txAddedTimestamp: Map<bigint, number> = new Map<bigint, number>();
 
   constructor(
     telemetry: TelemetryClient,
@@ -114,26 +114,22 @@ export class PoolInstrumentation<PoolObject extends Gossipable> {
   }
 
   public transactionsAdded(transactions: Tx[]) {
-    transactions.forEach(tx => this.trackMempoolItemAdded(tx.txHash.toBigInt()));
-  }
-
-  public transactionsRemoved(hashes: Iterable<bigint> | Iterable<string>) {
-    for (const hash of hashes) {
-      this.trackMempoolItemRemoved(BigInt(hash));
+    const timestamp = Date.now();
+    for (const transaction of transactions) {
+      this.txAddedTimestamp.set(transaction.txHash.toBigInt(), timestamp);
     }
   }
 
-  public trackMempoolItemAdded(key: bigint | string): void {
-    this.mempoolItemAddedTimestamp.set(key, Date.now());
-  }
-
-  public trackMempoolItemRemoved(key: bigint | string): void {
+  public transactionsRemoved(hashes: Iterable<bigint> | Iterable<string>) {
     const timestamp = Date.now();
-    const addedAt = this.mempoolItemAddedTimestamp.get(key);
-    if (addedAt !== undefined) {
-      this.mempoolItemAddedTimestamp.delete(key);
-      if (addedAt < timestamp) {
-        this.minedDelay.record(timestamp - addedAt);
+    for (const hash of hashes) {
+      const key = BigInt(hash);
+      const addedAt = this.txAddedTimestamp.get(key);
+      if (addedAt !== undefined) {
+        this.txAddedTimestamp.delete(key);
+        if (addedAt < timestamp) {
+          this.minedDelay.record(timestamp - addedAt);
+        }
       }
     }
   }

package/src/mem_pools/tx_pool/README.md

@@ -0,0 +1,270 @@
+# Transaction Pool (Mempool)
+
+This module implements the transaction pool (mempool) for the Aztec P2P network. The mempool holds unconfirmed transactions awaiting inclusion in a block.
+
+## Overview
+
+The transaction pool serves as a staging area for transactions before they are included in blocks. It manages the lifecycle of transactions from initial submission through mining, handling duplicates, priority ordering, and eviction of invalid or low-priority transactions.
+
+## Interface: `TxPool`
+
+The [`TxPool`](tx_pool.ts) interface defines the contract that all transaction pool implementations must fulfill:
+
+### Transaction Lifecycle
+
+The lifecycle of transactions in the pool is summarised in the following table:
+
+| State | Meaning | Possible Future States |
+| --- | --- | --- |
+| Pending | Available to be added to a block, can be evicted | Protected, Mined, Soft Deleted |
+| Protected | Added to a proposal, must not be evicted | Mined, Pending |
+| Mined | Confirmed as added to a block | Soft Deleted, Pending |
+| Soft Deleted | Awaiting full deletion once state has been finalised on L1 | Pending, Deleted |
+| Deleted | Removed from the pool | N/A |
+
+**Note on why Soft Delete:**
+Mined transactions are soft-deleted rather than permanently removed to support:
+1. Reorg handling — If a chain reorganization occurs, soft-deleted transactions are still available in the mempool
+2. Slash condition detection — The epoch prune watcher needs access to transactions from pruned epochs to correctly identify data withholding slash conditions. Without soft-delete, transactions invalidated by reorgs (e.g., built on removed blocks) would be lost, causing false positives for data withholding violations.
+
+Mined transactions are permanently deleted via `cleanupDeletedMinedTxs()` once their original block is finalized on L1, ensuring theyremain available during the uncertainty window.
+Alternatively, mined transactions can be permanently deleted immediately by passing the `permanent: true` option to `deleteTxs()`.
+
+#### Transaction Lifecycle Methods
+
+| Method | Description |
+|--------|-------------|
+| `addTxs(txs, opts?)` | Adds transactions to the pool. Duplicates and nullifier conflicts are handled. Returns count of newly added txs. |
+| `deleteTxs(txHashes, opts?)` | Removes transactions from the pool. Supports soft-delete for mined txs. |
+| `markAsMined(txHashes, blockHeader)` | Marks transactions as included in a block. |
+| `markMinedAsPending(txHashes, blockNumber)` | Reverts mined transactions to pending (used during reorgs). |
+| `getArchivedTxByHash(txHash)` | Retrieves archived (historical) transactions. |
+| `getTxStatus(txHash)` | Returns status: `'pending'`, `'mined'`, `'deleted'`, or `undefined`. |
+
+### Transaction Fetching
+
+| Method | Description |
+|--------|-------------|
+| `hasTx(txHash)` / `hasTxs(txHashes)` | Checks if transaction(s) exist in the pool. |
+| `getTxByHash(txHash)` | Retrieves a transaction by its hash. |
+| `getTxsByHash(txHashes)` | Batch retrieval of transactions by hash. |
+| `getAllTxs()` / `getAllTxHashes()` | Returns all transactions or their hashes. |
+| `getPendingTxHashes()` | Returns pending tx hashes **sorted by priority** (highest first). |
+| `getPendingTxCount()` | Returns count of pending transactions. |
+| `getMinedTxHashes()` | Returns mined tx hashes with their block numbers. |
+
+### Pool Management
+
+| Method | Description |
+|--------|-------------|
+| `updateConfig(config)` | Updates pool configuration (max size, archive limit). |
+| `markTxsAsNonEvictable(txHashes)` | Protects transactions from eviction. |
+| `clearNonEvictableTxs()` | Clears non-evictable flag from all transactions. |
+| `cleanupDeletedMinedTxs(blockNumber)` | Permanently removes soft-deleted txs from blocks ≤ blockNumber. |
+| `isEmpty()` | Checks if the pool has no transactions. |
+
+### Events
+
+The pool emits a `txs-added` event when new transactions are successfully added, allowing subscribers to react to pool changes.
+
+## `AztecKVTxPool`
+
+The [`AztecKVTxPool`](aztec_kv_tx_pool.ts) is the production-grade implementation backed by a persistent key-value store. It provides:
+
+- **Persistent storage** via `AztecAsyncKVStore`
+- **Multiple indexes** for efficient queries
+- **Automatic eviction** of invalid and low-priority transactions
+- **Transaction archival** for historical lookups
+- **Soft-delete semantics** for mined transactions
+
+#### Storage Structure
+
+The pool maintains several KV maps and indexes:
+
+| Store | Purpose |
+|-------|---------|
+| `#txs` | Primary storage: tx hash → serialized tx buffer |
+| `#minedTxHashToBlock` | Index of mined txs: tx hash → block number |
+| `#pendingTxPriorityToHash` | Priority-ordered index of pending txs |
+| `#deletedMinedTxHashes` | Soft-deleted mined txs: tx hash → original block number |
+| `#blockToDeletedMinedTxHash` | Reverse index for cleanup: block → deleted tx hashes |
+| `#txHashToHistoricalBlockHeaderHash` | Anchor block reference for each tx |
+| `#historicalHeaderToTxHash` | Index from historical block → tx hashes |
+| `#feePayerToTxHash` | Index from fee payer address → tx hashes |
+| `#pendingNullifierToTxHash` | Index from nullifier → tx hash |
+| `#archivedTxs` | Archived transactions for historical lookup |
+
+#### In-Memory Caches
+
+| Cache | Purpose |
+|-------|---------|
+| `#pendingTxs` | Hydrated pending transactions for fast access |
+| `#nonEvictableTxs` | Set of tx hashes protected from eviction |
+
+## Transaction Priority
+
+Transactions are prioritized based on their **total priority fees** (see [`priority.ts`](priority.ts)):
+
+```typescript
+priorityFee = maxPriorityFeesPerGas.feePerDaGas + maxPriorityFeesPerGas.feePerL2Gas
+```
+
+The priority is stored as a hex string derived from a 32-byte buffer representation of the fee amount, enabling lexicographic ordering in the KV store. Pending transactions are returned in **descending priority order** (highest fees first).
+
+## Transaction Lifecycle in AztecKVTxPool
+
+### 1. Adding Transactions
+
+When `addTxs()` is called:
+
+1. Check for duplicates (skip if tx already exists)
+2. Check for nullifier conflicts (see Nullifier Deduplication below)
+3. Store the serialized tx in `#txs`
+4. Index the tx by its anchor block hash
+5. If not already mined, add to pending indexes:
+   - Priority-to-hash index (for ordering)
+   - Historical header index (for reorg handling)
+   - Fee payer index (for balance validation)
+   - Nullifier-to-tx-hash index (for conflict detection)
+6. Record metrics
+7. Trigger eviction rules for `TXS_ADDED` event
+8. Emit `txs-added` event
+
+### 2. Marking as Mined
+
+When a block is finalized, `markAsMined()`:
+
+1. Move tx from pending to mined status
+2. If previously soft-deleted, restore to mined status
+3. Trigger eviction rules for `BLOCK_MINED` event
+
+### 3. Handling Reorgs
+
+When blocks are pruned, `markMinedAsPending()`:
+
+1. Remove tx from mined index
+2. Rehydrate pending indexes
+3. Trigger eviction rules for `CHAIN_PRUNED` event
+
+### 4. Deleting Transactions
+
+The `deleteTxs()` method handles two cases:
+
+- **Pending transactions**: Permanently deleted (transactions and all indexes to the transaction)
+- **Mined transactions**: Soft-deleted by default (moved to `#deletedMinedTxHashes`), with option for permanent deletion
+
+Soft-deleted mined transactions are retained for potential future reference and can be permanently cleaned up later via `cleanupDeletedMinedTxs()`.
+
+### Nullifier Deduplication
+
+The pool prevents nullifier spam attacks by ensuring only one pending transaction can reference each unique nullifier. When an incoming transaction shares nullifiers with existing pending transactions:
+
+- **Higher fee wins**: If the incoming tx has a higher priority fee than ALL conflicting txs, those conflicting txs are replaced
+- **Existing tx wins on tie**: If any conflicting tx has an equal or higher fee, the incoming tx is rejected
+- **Partial overlap counts**: Even a single shared nullifier triggers conflict resolution
+
+This is enforced at entry time via the `#pendingNullifierToTxHash` index, which maps each nullifier to the tx hash that references it. The index is maintained atomically with tx additions and removals.
+
+## Eviction System
+
+The eviction system automatically removes invalid or low-priority transactions based on configurable rules. See the [`eviction/`](eviction/) subdirectory for implementation details.
+
+### Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                      EvictionManager                            │
+│  Orchestrates eviction rules based on pool events               │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐  │
+│  │EvictionRule #1  │  │EvictionRule #2  │  │EvictionRule #N  │  │
+│  └─────────────────┘  └─────────────────┘  └─────────────────┘  │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+                    ┌─────────────────┐
+                    │ TxPoolOperations│
+                    │   (interface)   │
+                    └─────────────────┘
+```
+
+The [`EvictionManager`](eviction/eviction_manager.ts) coordinates eviction by:
+
+1. Registering multiple `EvictionRule` implementations
+2. Calling each rule when tx pool events occur
+3. Propagating configuration updates to all rules
+
+### Eviction Events
+
+| Event | Trigger | Purpose |
+|-------|---------|---------|
+| `TXS_ADDED` | New transactions added | Enforce pool size limits |
+| `BLOCK_MINED` | Block finalized | Remove invalidated transactions |
+| `CHAIN_PRUNED` | Chain reorganization | Remove txs referencing pruned blocks and re-evaluate fee payer balances |
+
+### Eviction Rules
+
+#### 1. `InvalidTxsAfterMiningRule`
+
+**Triggers on:** `BLOCK_MINED`
+
+Evicts transactions that become invalid after a block is mined:
+
+- Duplicate nullifiers: Txs with nullifiers already included in the mined block
+- Expired transactions: Txs with `expirationTimestamp` ≤ mined block timestamp
+
+#### 2. `InvalidTxsAfterReorgRule`
+
+**Triggers on:** `CHAIN_PRUNED`
+
+Evicts transactions that reference blocks no longer in the canonical chain:
+
+- Checks each pending tx's anchor block hash against the archive tree
+- Removes txs whose anchor blocks are not found (pruned)
+
+#### 3. `FeePayerBalanceEvictionRule`
+
+**Triggers on:** `TXS_ADDED`, `BLOCK_MINED`, `CHAIN_PRUNED`
+
+Evicts low-priority transactions when a fee payer's pending fee limits exceed their Fee Juice balance:
+
+- Evaluates transactions in priority order so higher-priority claims can fund lower-priority spends
+- Accounts for self-funding claims made during setup
+- Removes evictable txs that do not fit within the running balance
+
+#### 4. `LowPriorityEvictionRule`
+
+**Triggers on:** `TXS_ADDED`
+
+Enforces maximum pool size by evicting lowest-priority (by fee) transactions:
+
+- Configured via `maxPendingTxCount` option (0 = disabled)
+- Uses `getLowestPriorityEvictable()` to find txs to evict
+
+### Non-Evictable Transactions
+
+Transactions can be marked as non-evictable via `markTxsAsNonEvictable()`. This protects them from all eviction rules, typically used during block building to ensure transactions being processed aren't evicted mid-operation. The flag is cleared after block processing via `clearNonEvictableTxs()`.
+The `clearNonEvictableTxs` is called upon getting new L2 block.
+
+## Configuration
+
+The pool accepts configuration via `TxPoolOptions`:
+
+```typescript
+type TxPoolOptions = {
+  maxPendingTxCount?: number;  // Max pending txs (0 = unlimited)
+  archivedTxLimit?: number;    // Number of archived txs to retain
+};
+```
+
+Configuration can be updated at runtime via `updateConfig()`.
+
+## Telemetry
+
+The pool integrates with the telemetry system to report:
+
+- Transaction counts (pending vs mined)
+- Transaction sizes
+- Store size estimates